Hooks

The hook functions allows to bsp/port developer to extend the functionality of the framework. More...

Macros
#define	RKH_TIM_TICK(_sender)   rkh_tmr_tick(_sender)
	Invoke the system clock tick processing rkh_tmr_tick(). More...

Functions
void	rkh_hook_dispatch (RKH_SMA_T *me, RKH_EVT_T *e)
	When dispatching an event to a SMA the dispatch hook function will be executed. More...
void	rkh_hook_signal (RKH_EVT_T *e)
	When the producer of an event directly posts the event to the event queue of the consumer SMA the rkh_hook_signal() will optionally called. More...
void	rkh_hook_timeout (const void *t)
	If a timer expires the rkh_hook_timeout() function is called just before the assigned event is directly posted into the state machine application queue. More...
void	rkh_hook_start (void)
	This hook function is called just before the RKH takes over control of the application. More...
void	rkh_hook_exit (void)
	This hook function is called just before the RKH returns to the underlying OS/RTOS. Usually, the rkh_hook_exit() is useful when executing clean-up code upon SMA terminate or framework exit. More...
void	rkh_hook_idle (void)
	An idle hook function will only get executed (with interrupts LOCKED) when there are no SMAs of higher priority that are ready to run. More...
void	rkh_hook_timetick (void)
	This function is called by rkh_tmr_tick(), which is assumed to be called from an ISR. rkh_hook_timetick() is called at the very beginning of rkh_tmr_tick(), to give priority to user or port-specific code when the tick interrupt occurs. More...
void	rkh_hook_putTrcEvt (void)
	This function is called from rkh_trc_end() function, at the end of that, to allow to the application to extend the functionality of RKH, giving the port developer the opportunity to add code that will be called when is put a trace event into the stream buffer.

Detailed Description

The hook functions allows to bsp/port developer to extend the functionality of the framework.

A RKH port cannot and should not define all the functions that it calls, because this would render the port too inflexible. The functions that RKH calls but doesn't actually implement are referred to as callback or hook functions. All these functions in RKH are easily indentifiable by the "_hook_" key word used in the function name, rkh_hook_dispatch(), rkh_hook_signal(), rkh_hook_timeout(), rkh_hook_start(), rkh_hook_exit(), and rkh_hook_idle(). Please, see RKH_CFG_HOOK_DISPATCH_EN, RKH_CFG_HOOK_SIGNAL_EN, RKH_CFG_HOOK_TIMEOUT_EN, RKH_CFG_HOOK_START_EN, and RKH_CFG_HOOK_EXIT_EN options from the rkhcfg.h.

Macro Definition Documentation

RKH_TIM_TICK

#define RKH_TIM_TICK

(

_sender

)

rkh_tmr_tick(_sender)

Invoke the system clock tick processing rkh_tmr_tick().

This macro is the recommended way of invoke the clock tick processing, because it provides the vital information for software tracing and avoids any overhead when the tracing is disabled.

Parameters

[in]

_sender

pointer to the sender object. Typically RKH_TIM_TICK() will be called from an interrupt, in which case it would create a unique object just to unambiguously identify the ISR as the sender of the time events.

See also

rkh_tmr_tick().

Definition at line 89 of file rkhtmr.h.

Function Documentation

rkh_hook_dispatch()

void rkh_hook_dispatch	(	RKH_SMA_T *	me,
		RKH_EVT_T *	e
	)

When dispatching an event to a SMA the dispatch hook function will be executed.

Parameters

[in]	me	pointer to previously created state machine application.
[in]	e	pointer to arrived event.

Note

The dispatch hook will only get called if RKH_CFG_HOOK_DISPATCH_EN is set to 1 within rkhcfg.h file. When this is set the application must provide the hook function.

rkh_hook_signal()

void rkh_hook_signal

(

RKH_EVT_T *

e

)

When the producer of an event directly posts the event to the event queue of the consumer SMA the rkh_hook_signal() will optionally called.

Parameters

[in]

e

pointer to arrived event.

Note

The signal hook will only get called if RKH_CFG_HOOK_SIGNAL_EN is set to 1 within rkhcfg.h file. When this is set the application must provide the hook function.

rkh_hook_timeout()

void rkh_hook_timeout

(

const void *

t

)

If a timer expires the rkh_hook_timeout() function is called just before the assigned event is directly posted into the state machine application queue.

Parameters

[in]

t

pointer to previously allocated timer structure. A cast to RKH_TMR_T data type must be internally implemented to get the appropiated timer control block.

Note

The timeout hook will only get called if RKH_CFG_HOOK_TIMEOUT_EN is set to 1 within rkhcfg.h file. When this is set the application must provide the hook function.

rkh_hook_start()

void rkh_hook_start

(

void

)

This hook function is called just before the RKH takes over control of the application.

Note

The start hook will only get called if RKH_CFG_HOOK_START_EN is set to 1 within rkhcfg.h file. When this is set the application must provide the hook function.

rkh_hook_exit()

void rkh_hook_exit

(

void

)

This hook function is called just before the RKH returns to the underlying OS/RTOS. Usually, the rkh_hook_exit() is useful when executing clean-up code upon SMA terminate or framework exit.

Note

The exit hook will only get called if RKH_CFG_HOOK_EXIT_EN is set to 1 within rkhcfg.h file. When this is set the application must provide the hook function.

rkh_hook_idle()

void rkh_hook_idle

(

void

)

An idle hook function will only get executed (with interrupts LOCKED) when there are no SMAs of higher priority that are ready to run.

This makes the idle hook function an ideal place to put the processor into a low power state - providing an automatic power saving whenever there is no processing to be performed.

Note

The rkh_hook_idle() callback is called with interrupts locked, because the determination of the idle condition might change by any interrupt posting an event. This function must internally unlock interrupts, ideally atomically with putting the CPU to the power-saving mode.

Usage

void
rkh_hook_idle( void )       // NOTE: entered with interrupts DISABLED
{
    RKH_ENA_INTERRUPT();    // must at least enable interrupts
    ...
}

rkh_hook_timetick()

void rkh_hook_timetick

(

void

)

This function is called by rkh_tmr_tick(), which is assumed to be called from an ISR. rkh_hook_timetick() is called at the very beginning of rkh_tmr_tick(), to give priority to user or port-specific code when the tick interrupt occurs.

Usually, this hook allows to the application to extend the functionality of RKH, giving the port developer the opportunity to add code that will be called by rkh_tmr_tick(). Frequently, the rkh_hook_timetick() is called from the tick ISR and must not make any blocking calls and must execute as quickly as possible.

Note

The time tick hook will only get called if RKH_CFG_HOOK_TIMETICK_EN is set to 1 within rkhcfg.h file. When this is set the application must provide the hook function.