IPC@CHIP® RTOS-PPC – API Documentation

Header image

Main page


RTX_ID RTX_NewTimerCB ( const char *  tag,
RTX_TIMER_CALLBACK  proc,
long  interval,
unsigned long  lParam 
)

The specified procedure proc will be called based on a timer.

You must call either the RTX_Start_Timer(), RTX_Timer_Delay() or RTX_Timer_Delay_RTI() API to get the kernel to start calling your new timer procedure.

Timers require the use of one general purpose kernel object, of which the system has a total of 500.

The timer callback procedure execute in User mode by default. A Supervisor mode timer callback can be created by applying the RTX_CB_SUPV_MODE macro to the callback vector passed in the proc argument to this API.

Important:
Timer procedures are executed in the top priority AMXK kernel task, so the timer user callback procedure should be as short as possible. Avoid calling time consuming functions. It is not legal to call any API which may block from a timer callback. The system is not protected against such a violation and to do so may cause the system to crash. The total stack space available is 4096 bytes, a few of which are used by the system on entry into the callback.
Fault Handling:
When an application program's timer callback execution triggers an exception (e.g. MMU fault or invalid opcode), how the system reacts depends on whether the callback was executing in User mode or Supervisor mode. When the timer callback was in User mode, the fault will cause this timer callback to be automatically removed from the system and system execution will then contine. If the timer callback was in Supervisor mode at the time of the fault, then this is a fatal error and further system operation is not expected. Although the Supervisor mode timer callbacks are slightly more time efficient than User mode callbacks, greater care in programming is required when using the Supervisor mode.
Example:
#include <clib.h>

static void MyTimerCb (RTX_ID timer_id, unsigned long lParam)
{
    // ToDo:  Add timer callback functionality here
}


// Example installation of Supervisor mode kernel timer callback.
void InstallTimerCallback(void)
{
    RTX_ID timerId = RTX_NewTimerCB( "STMR",
                     RTX_CB_SUPV_MODE(MyTimerCb, RTX_TIMER_CALLBACK),
                             1000,
                             0) ;
    RTX_Start_Timer(timerId) ;

}
Parameters:
tag Up to 4 character name to give timer. Nil terminator is optional.
proc Vector to timer procedure.
interval Timer interval in milliseconds. This value must be non-negative, and when multiplied by the RTI rate must not exceed 31 bits. Otherwise this API will either fail with return value zero or create a timer with an undesired interval (depending on the nature of the count overflow).
lParam Optional 32 bit parameter to pass to timer callback procedure proc.
Returns:
Timer ID (handle) on success, else zero on failure.
See also:
RTX_NewFineTimerCB()     RTX_Remove_Timer()
Compatibility:
This API is not compatible with the SC1x, SC2x and SC1x3 C-library. The legacy function RTX_Install_Timer() may be used when cross system source compatibility is required.
Since:
SC2x3 V1.00 - CLIB V1.00





Top of page | Main page

Copyright © 2017 Beck IPC GmbH
Generated on Thu Jan 26 16:21:37 2017 by Doxygen 1.6.1