Timer

Files
file	rkhtmr.h
	Specifies the interface of software timer services.

Data Structures
struct	RKH_TMR_T
	Defines the data structure used to maintain information that allows the timer-handling facility to update and expire software timers. More...
struct	RKHTmEvt
	It defines a time event that occurs at a specific duration. More...

Macros
#define	RKH_TMR_INIT(t_, e_, th_)    rkh_tmr_init_((t_), (e_), (th_))
	Initializes the previously allocated timer structure RKH_TMR_T. More...
#define	RKH_TMR_ONESHOT(t, sma, itick)    rkh_tmr_start(t, sma, itick, 0)
	Start a timer as one-shot timer. More...
#define	RKH_TMR_PERIODIC(t, sma, itick, per)    rkh_tmr_start((t), (sma), (itick), (per))
	Start a timer as periodic timer. More...

Functions
void	rkh_tmr_start (RKH_TMR_T *t, const struct RKH_SMA_T *sma, RKH_TNT_T itick, RKH_TNT_T per)
	Start a timer. More...
rbool_t	rkh_tmr_stop (RKH_TMR_T *t)
	Stops a running timer. More...
void	rkh_tmr_init (void)
	Initializes the timer module. More...
void	rkh_tmr_get_info (RKH_TMR_T *t, RKH_TINFO_T *info)
	Retrieves performance information for a particular software timer. More...
void	rkh_tmr_clear_info (RKH_TMR_T *t)
	Clear performance information for a particular software timer. More...

Detailed Description

Macro Definition Documentation

RKH_TMR_INIT

#define RKH_TMR_INIT	(		t_,
			e_,
			th_
	)		rkh_tmr_init_((t_), (e_), (th_))

Initializes the previously allocated timer structure RKH_TMR_T.

A timer is declared with the RKH_TMR_T data type and is defined with the RKH_TMR_INIT() service. The timer is initialized in a non-active state (stopped). In this case, a subsequent start service call is necessary to get the timer actually started. The following listing creates an application timer that executes "my_timer_hook" and send the event signal "TOUT" to "pwr" SMA after 100 timer-ticks.

Parameters

[in]	t_	pointer to previously allocated timer structure. Any software module intending to install a software timer must first allocate a timer structure RKH_TMR_T.
[in]	e_	event to be directly posted (using the FIFO policy) into the event queue of the target agreed state machine application at the timer expiration.
[in]	th_	hook function to be called at the timer expiration. This argument is optional, thus it could be declared as NULL or eliminated in compile-time with RKH_CFG_TMR_HOOK_EN.

Note

See RKH_TMR_T structure for more information.

Usage

#define SYNC_TIME    RKH_TIME_MS(100)
...
static RKHTmEvt tmSync;
...
void
powerOn(ActiveObject *const me)
{
    RKH_SET_STATIC_EVENT(&tmSync, Sync);
    RKH_TMR_INIT(&tmSync.tmr, 
                 RKH_UPCAST(RKH_EVT_T, &tmSync), 
                 NULL);
    RKH_TMR_ONESHOT(&tmSync.tmr, 
                    RKH_UPCAST(RKH_SMA_T, me), 
                    SYNC_TIME);
}

Definition at line 143 of file rkhtmr.h.

RKH_TMR_ONESHOT

#define RKH_TMR_ONESHOT	(		t,
			sma,
			itick
	)		rkh_tmr_start(t, sma, itick, 0)

Start a timer as one-shot timer.

This operation installs a previously created timer into the timer-handling facility. The timer begins running at the completion of this operation. The timer won't be re-started automatically. The following listing creates an application timer that executes "my_timer_hook" and send the event signal "TOUT" to "pwr" SMA after 100 timer-ticks.

Parameters

[in]	t	pointer to previously created timer structure.
[in]	sma	state machine application (SMA) that receives the timer event.
[in]	itick	number of ticks for timer expiration.

Usage

#define SYNC_TIME    RKH_TIME_MS(100)
...
static RKHTmEvt tmSync;
...
void
powerOn(ActiveObject *const me)
{
    RKH_SET_STATIC_EVENT(&tmSync, Sync);
    RKH_TMR_INIT(&tmSync.tmr, 
                 RKH_UPCAST(RKH_EVT_T, &tmSync), 
                 NULL);
    RKH_TMR_ONESHOT(&tmSync.tmr, 
                    RKH_UPCAST(RKH_SMA_T, me), 
                    SYNC_TIME);
}

Definition at line 187 of file rkhtmr.h.

RKH_TMR_PERIODIC

#define RKH_TMR_PERIODIC	(		t,
			sma,
			itick,
			per
	)		rkh_tmr_start((t), (sma), (itick), (per))

Start a timer as periodic timer.

This operation installs a previously created timer into the timer-handling facility. The timer begins running at the completion of this operation. Once the timeout will expire the timer will be re-started (re-triggered) again automatically. The following listing creates an application timer that executes "my_timer_hook" and send the event signal "TOUT" to "pwr" SMA after 100 timer-ticks initially and then after every 25 timer-ticks.

Parameters

[in]	t	pointer to previously created timer structure.
[in]	sma	state machine application (SMA) that receives the timer event.
[in]	itick	number initial of ticks for timer expiration.
[in]	per	number of ticks for all timer expirations after the first (expiration period). A zero for this parameter makes the timer a one-shot timer, otherwise, for periodic timers, any value in range.

Usage

#define TKEY_TIME       RKH_TIME_MS(100)
#define TKEYSTART_TIME  RKH_TIME_MS(300)
...
static RKHTmEvt tKey;
...
void
close(PowerMonitor *const me)
{
    RKH_SET_STATIC_EVENT(&tKey, evKey);
    RKH_TMR_INIT(&tKey.tmr, 
                 RKH_UPCAST(RKH_EVT_T, &tKey), 
                 NULL);
    RKH_TMR_PERIODIC(&tKey.tmr, 
                     RKH_UPCAST(RKH_SMA_T, me), 
                     TKEYSTART_TIME,
                     TKEY_TIME);
}

Definition at line 234 of file rkhtmr.h.

Function Documentation

rkh_tmr_start()

void rkh_tmr_start	(	RKH_TMR_T *	t,
		const struct RKH_SMA_T *	sma,
		RKH_TNT_T	itick,
		RKH_TNT_T	per
	)

Start a timer.

This operation installs a previously created timer into the timer-handling facility. The timer begins running at the completion of this operation.

Parameters

[in]	t	pointer to previously created timer structure.
[in]	sma	state machine application (SMA) that receives the timer event.
[in]	itick	number of ticks for timer expiration.
[in]	per	number of ticks for all timer expirations after the first (expiration period). A zero for this parameter makes the timer an one-shot timer, otherwise, for periodic timers, any value in range.

rkh_tmr_stop()

rbool_t rkh_tmr_stop

(

RKH_TMR_T *

t

)

Stops a running timer.

This operation stops a timer by removing the currently running timer from the timer-handling facility. If the timer is already stopped, this service has no effect.

Parameters

[in]

t

pointer to previously created timer structure.

Returns

'true' if the timer was running. The 'false' return is only possible for one-shot timers that have been automatically stopped upon expiration. In this case the 'false' return means that the time event has already been posted and should be expected in the active object's state machine.

rkh_tmr_init()

void rkh_tmr_init

(

void

)

Initializes the timer module.

Note

It should be invoked before using any timer.

rkh_tmr_get_info()

void rkh_tmr_get_info	(	RKH_TMR_T *	t,
		RKH_TINFO_T *	info
	)

Retrieves performance information for a particular software timer.

The user application must allocate an RKH_TINFO_T data structure used to receive data. The performance information is available during run-time for each of the RKH services. This can be useful in determining whether the application is performing properly, as well as helping to optimize the application. This information provides a "snapshot" a particular instant in time, i.e., when the service is invoked.

Parameters

[in]	t	pointer to previously created timer structure.
[in]	info	pointer to the buffer into which the performance information will be copied by reference.

Note

See RKH_TINFO_T structure for more information. This function is optional, thus it could be eliminated in compile-time with RKH_CFG_TMR_GET_INFO_EN.

rkh_tmr_clear_info()

void rkh_tmr_clear_info

(

RKH_TMR_T *

t

)

Clear performance information for a particular software timer.

Parameters

[in]

t

pointer to previously created timer structure.

Note

See RKH_TINFO_T structure for more information. This function is optional, thus it could be eliminated in compile-time with RKH_CFG_TMR_GET_INFO_EN.