Timer

This GOAL core module provides functionalities for:

hard timers with an operating system (Figure 18),
hard timers without an operating system (Figure 19) and
soft timers (Figure 20).

Hard timers are high prioritized and handled interrupt-controlled or operating system-specific. Soft timers are low prioritized and handled loop-controlled. Both kinds of timer base on platform-specific timers. The value range of the timers depends on the platform-specific timer configuration. The standard GOAL system requires a minimal time period of 1 ms.
The accesses to the GOAL timers are protected by the GOAL locking mechanism.

Figure: typical case for hard timer with operating system

Figure: typical case for hard timer without operating system

Figure: soft timer handling

The timers can be used as:

single shot timer or
periodic timer

The timer type can be configured by function goal_timerSetup().

GOAL files:
- goal_timer.[h,c], goal_timer_cli.c
example:
- not available

Callback functions

There are the following callback functions to connect the timer with other functionality:

Table: cbTimerFunc()

Prototype	void cbTimerFunc(void *pArg)
Description	This callback function is always called if the current time stamp is captured.
Parameter	pArg	specific arguments used by the callback function
Return values	none
Category	Mandatory
Registration	during runtime via function goal_timerSetup`()`

Table: cbStopTimerFunc()

Prototype	void cbStopTimerFunc(void *pArg)
Description	This function is called once if the timer is stopped.
Parameter	pArg	specific arguments used by the callback function
Return values	none
Category	optional If a callback function is not available, GOAL deletes the timer.
Registration	during runtime via function goal_timerStopCb()

Platform API

GOAL requires the following indication function to manage a platform-specific timer as base for GOAL timers:

Table: goal_targetTimerInit()

Prototype	GOAL_STATUS_T goal_targetTimerInit(void)
Description	This indication function initializes a platform-specific timer and is called in stage GOAL_STAGE_TIMER_PRE in the state GOAL_FSA_INIT_GOAL.
Parameters	none
Return values	GOAL return status, see Chapter: GOAL status
Category	mandatory
Condition	none

Table: goal_targetTimerCreate()

Prototype	GOAL_STATUS_T goal_targetTimerCreate(GOAL_TIMER_T *pTmr)
Description	This indication function creates a platform-specific timer for a GOAL hard timer.
Parameters	pTmr	handle for the GOAL hard timer
Return values	GOAL return status, see Chapter: GOAL status
Category	mandatory for GOAL hard timers
Condition	none

Table: goal_targetTimerDelete()

Prototype	GOAL_STATUS_T goal_targetTimerDelete(GOAL_TIMER_T *pTmr)
Description	This indication function deletes a platform-specific timer for a GOAL hard timer.
Parameters	pTmr	handle for the GOAL hard timer
Return values	GOAL return status, see Chapter: GOAL status
Category	mandatory for GOAL hard timers
Condition	none

Table: goal_targetTimerStart()

Prototype	GOAL_STATUS_T goal_targetTimerStart(GOAL_TIMER_T *pTmr)
Description	This indication function starts a platform-specific timer for a GOAL hard timer.
Parameters	pTmr	handle for the GOAL hard timer
Return values	GOAL return status, see Chapter: GOAL status
Category	mandatory for GOAL hard timers
Condition	none

Table: goal_targetTimerStop()

Prototype	GOAL_STATUS_T goal_targetTimerStop(GOAL_TIMER_T *pTmr)
Description	This indication function stops a platform-specific timer for a GOAL hard timer.
Parameters	pTmr	handle for the GOAL hard timer
Return values	GOAL return status, see Chapter: GOAL status
Category	mandatory for GOAL hard timers
Condition	none

Command line interface

Command	time current
Description	Prints the current timestamp of the GOAL system to the command line interface.
Parameter	none

Implementation guidelines

Use a periodic soft timer and start the timer immediately

Create a handle for the timer:

GOAL_TIMER_T *pSoftTimer;
Create a soft timer of low priority in state GOAL_FSA_INIT:

goal_timerCreate(&pSoftTimer, GOAL_TIMER_LOW);
The soft timer shall be triggered every 1000 ms periodically and shall be started immediately. The timer is configured as follow:

goal_timerSetup(pSoftTimer, GOAL_TIMER_PERIODIC, 1000, cbTimerFunc, NULL, GOAL_TRUE);
The callback function is called if the timer is expired again and again.
Stop the timer without calling a callback function after it is expired the next time:
Delete the timer:

Use a single soft timer and start the timer in the application

Create a handle for the timer:
Create a soft timer of low priority in state GOAL_FSA_INIT:
The soft timer shall be triggered only once after 1000 ms and shall be started by the application. The timer is configured as follow:
Start the timer in the application:
Stop the timer without calling a callback function:
Delete the timer:

Stop hard timer with callback function

Create a handle for the timer:
Create a hard timer of high priority in state GOAL_FSA_INIT:
The hard timer shall be triggered every 1000 ms periodically and shall be started immediately. The timer is configured as follow:
The callback function is called if the timer is expired again and again.
Stop the timer with calling a callback function:
Delete the timer:

1 Callback functions
2 Platform API
3 Command line interface
4 Implementation guidelines