Kernel Timer API#

• OSTmrCreate()

• OSTmrDel()

• OSTmrRemainGet()

• OSTmrSet()

• OSTmrStart()

• OSTmrStateGet()

• OSTmrStop()

OSTmrCreate()#

Description#

Called by your application code to create a timer.

Files#

os.h/os_tmr.c

Prototype#

void  OSTmrCreate (OS_TMR               *p_tmr,
                   CPU_CHAR             *p_name,
                   OS_TICK               dly,
                   OS_TICK               period,
                   OS_OPT                opt,
                   OS_TMR_CALLBACK_PTR   p_callback,
                   void                 *p_callback_arg,
                   RTOS_ERR             *p_err)

Arguments#

p_tmr

Pointer to the timer to create. Your application is responsible for allocating storage for the timer.

p_name

Pointer to an ASCII string that names the timer (useful for debugging)

dly

Initial delay.

• If the timer is configured for ONE-SHOT mode, this is the timeout used.

• If the timer is configured for PERIODIC mode, this is the first timeout to wait for before the timer starts entering periodic mode.

period

The 'period' being repeated for the timer. If you specified 'OS_OPT_TMR_PERIODIC' as an option, when the timer expires, it will automatically restart with the same period.

opt

Specifies either:

• OS_OPT_TMR_ONE_SHOT The timer counts down only once.

• OS_OPT_TMR_PERIODIC The timer counts down and then reloads itself.

p_callback

Pointer to a callback function that will be called when the timer expires. The callback function must be declared as follows:

void MyCallback (OS_TMR p_tmr, void p_arg);

p_callback_arg

Pointer to an argument that is passed to the callback function when it is called.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

• RTOS_ERR_NONE

• RTOS_ERR_OS_ILLEGAL_RUN_TIME

Returned Value#

None.

Notes / Warnings#

1. This function only creates the timer. In other words, the timer is not started when created. To start the timer, call OSTmrStart().

OSTmrDel()#

Description#

Called by your application code to delete a timer.

Files#

os.h/os_tmr.c

Prototype#

CPU_BOOLEAN  OSTmrDel (OS_TMR    *p_tmr,
                       RTOS_ERR  *p_err)

Arguments#

p_tmr

Pointer to the timer to stop and delete.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

• RTOS_ERR_NONE

• RTOS_ERR_OS_ILLEGAL_RUN_TIME

• RTOS_ERR_NOT_INIT

Returned Value#

• == DEF_TRUE If the timer was deleted.

• == DEF_FALSE If the timer was not deleted or upon an error.

Notes / Warnings#

None.

OSTmrRemainGet()#

Description#

Called to get the number of ticks before a timer times out.

Files#

os.h/os_tmr.c

Prototype#

OS_TICK  OSTmrRemainGet (OS_TMR    *p_tmr,
                         RTOS_ERR  *p_err)

Arguments#

p_tmr

Pointer to the timer to obtain the remaining time from.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

• RTOS_ERR_NONE

• RTOS_ERR_NOT_INIT

Returned Value#

The time remaining for the timer to expire. The time represents 'timer' increments. In other words, if OS_TmrTask() is signaled every 1/10 of a second, the returned value represents the number of 1/10 of a second remaining before the timer expires.

Notes / Warnings#

None.

OSTmrSet()#

Description#

Called by your application code to set a timer.

Files#

os.h/os_tmr.c

Prototype#

void  OSTmrSet (OS_TMR               *p_tmr,
                OS_TICK               dly,
                OS_TICK               period,
                OS_TMR_CALLBACK_PTR   p_callback,
                void                 *p_callback_arg,
                RTOS_ERR             *p_err)

Arguments#

p_tmr

Pointer to the timer to set.

dly

Initial delay. If the timer is configured for ONE-SHOT mode, this is the timeout used. If the timer is configured for PERIODIC mode, this is the first timeout to wait for before the timer starts entering periodic mode.

period

The 'period' being repeated for the timer. If you specified 'OS_OPT_TMR_PERIODIC' as an option, when the timer expires, it will automatically restart with the same period.

p_callback

Pointer to a callback function that will be called when the timer expires. The callback function must be declared as follows:

void MyCallback (OS_TMR *p_tmr, void *p_arg);

p_callback_arg

Pointer to an argument that is passed to the callback function when it is called.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

• RTOS_ERR_NONE

Returned Value#

None.

Notes / Warnings#

1. This function can be called on a running timer. The change to the delay and period will only take effect after the current period or delay has passed. Change to the callback will take effect immediately.

OSTmrStart()#

Description#

Called by your application code to start a timer.

Files#

os.h/os_tmr.c

Prototype#

CPU_BOOLEAN  OSTmrStart (OS_TMR    *p_tmr,
                         RTOS_ERR  *p_err)

Arguments#

p_tmr

Pointer to the timer to start.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

• RTOS_ERR_NONE

• RTOS_ERR_NOT_INIT

Returned Value#

• DEF_TRUE If the timer was started.

• DEF_FALSE If the timer was not started or upon an error.

Notes / Warnings#

1. When starting/restarting a timer, regardless if it is in PERIODIC or ONE-SHOT mode, the timer is linked to the timer list with the OS_OPT_LINK_DLY option. This option sets the initial expiration time for the timer. For timers in PERIODIC mode, subsequent expiration times are handled by the OS_TmrTask().

OSTmrStateGet()#

Description#

Called to determine what state the timer is in:

Files#

os.h/os_tmr.c

Prototype#

OS_STATE  OSTmrStateGet (OS_TMR    *p_tmr,
                         RTOS_ERR  *p_err)

Arguments#

p_tmr

Pointer to the timer.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

• RTOS_ERR_NONE

Returned Value#

The current state of the timer (see description).

Notes / Warnings#

None.

OSTmrStop()#

Description#

Called by your application code to stop a timer.

Files#

os.h/os_tmr.c

Prototype#

CPU_BOOLEAN  OSTmrStop (OS_TMR    *p_tmr,
                        OS_OPT     opt,
                        void      *p_callback_arg,
                        RTOS_ERR  *p_err)

Arguments#

p_tmr

Pointer to the timer to stop.

opt

Allows you to specify an option to this functions which can be:

• OS_OPT_TMR_NONE Stop the timer.

• OS_OPT_TMR_CALLBACK Stop the timer and execute the callback function, pass it the callback argument specified when the timer was created.

• OS_OPT_TMR_CALLBACK_ARG Stop the timer and execute the callback specified in THIS function call.

p_callback_arg

Pointer to a 'new' callback argument that can be passed to the callback function instead of the timer's callback argument. In other words, use 'callback_arg' passed in THIS function INSTEAD of p_tmr->OSTmrCallbackArg

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

• RTOS_ERR_NONE

• RTOS_ERR_NOT_INIT

• RTOS_ERR_INVALID_ARG

• RTOS_ERR_INVALID_STATE

Returned Value#

• DEF_TRUE If we stop the timer (if the timer is already stopped, it returns as DEF_TRUE).

• DEF_FALSE If the timer is not stopped.

Notes / Warnings#

None.