Description
OSTmrCreate() allows the user to create a software timer. The timer can be configured to run continuously (opt set to OS_TMR_OPT_PERIODIC), or only once (opt set to OS_TMR_OPT_ONE_SHOT). When the timer counts down to 0 (from the value specified in period), an optional “callback” function can be executed. The callback can be used to signal a task that the timer expired, or perform any other function. However, it is recommended to keep the callback function as short as possible.
The timer is created in the “stop” mode and therefore the user must call OSTmrStart() to actually start the timer. If configuring the timer for ONE-SHOT mode, and the timer expires, you need to call OSTmrStart() to retrigger the timer, call OSTmrDel() to delete the timer if it is not necessary to retrigger it, or not use the timer anymore. Note: you can use the callback function to delete the timer if using the ONE-SHOT mode.
PERIODIC MODE (see “opt”) – dly > 0, period > 0
PERIODIC MODE (see “opt”) – “dly == 0, period > 0
ONE-SHOT MODE (see “opt”) – dly > 0, period == 0
Files
os.h/os_tmr.c
Prototype
| Code Block |
|---|
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, |
...
OS_ERR *p_err |
...
File | Called from | Code enabled by |
|---|---|---|
| Task only |
|
...
) |
...
The timer is created in the “stop” mode and therefore the user must call OSTmrStart() to actually start the timer. If configuring the timer for ONE-SHOT mode, and the timer expires, you need to call OSTmrStart() to retrigger the timer, call OSTmrDel() to delete the timer if it is not necessary to retrigger it, or not use the timer anymore. Note: you can use the callback function to delete the timer if using the ONE-SHOT mode.
PERIODIC MODE (see “opt”) – dly > 0, period > 0
PERIODIC MODE (see “opt”) – “dly == 0, period > 0
ONE-SHOT MODE (see “opt”) – dly > 0, period == 0
Arguments
p_tmr
is a pointer to the timer-control block of the desired timer. It is assumed that storage for the timer will be allocated in the application. In other words, you should declare a “global” variable as follows, and pass a pointer to this variable to OSTmrCreate():
OS_TMR MyTmr MyTmr;
p_name
is a pointer to an ASCII string (NUL terminated) used to assign a name to the timer. The name can be displayed by debuggers or µC/Probe.
...
If the call was successful.
OS_ERR_ILLEGAL_CREATE_RUN_TIME
If OS_SAFETY_CRITICAL_IEC61508 is defined: you called this after calling OSStart() and thus you are no longer allowed to create additional kernel objects.
OS_ERR_OBJ_PTR_NULL
If OS_CFG_ARG_CHK_EN is set to 1 DEF_ENABLED in os_cfg.h: if p_tmr is a NULL pointer.
OS_ERR_OPT_INVALID
If OS_CFG_ARG_CHK_EN is set to DEF_ENABLED in os_cfg.h: if not specifying a valid option.
OS_ERR_TMR_INVALID_CALLBACK
If OS_CFG_ARG_CHK_EN is set to DEF_ENABLED in os_cfg.h: if p_callback is a NULL pointer.
OS_ERR_TMR_INVALID_DLY
If OS_CFG_ARG_CHK_EN is set to 1 in DEF_ENABLED in os_cfg.h: if specifying an invalid delay in ONE-SHOT mode. In other words, it is not allowed to delay for 0 in ONE-SHOT mode.
...
If OS_CFG_ARG_CHK_EN is set to 1 in DEF_ENABLED in os_cfg.h: if specifying an invalid period in PERIODIC mode. It is not allowed to have a 0 period in PERIODIC.
OS_ERR_OPT_INVALID
If OS_CFG_ARG_CHK_EN is set to 1 in os_cfg.h: if not specifying a valid options.
OS_ERR_TMR_ISR
If OS_CFG_CALLED_FROM_ISR_CHK_EN set to 1 in to DEF_ENABLED in os_cfg.h: if calling this function from an ISR.
Returned Values
None.
Required Configuration
OS_
...
CFG_
...
If OS_SAFETY_CRITICAL_IEC61508 is defined: you called this after calling OSSafetyCriticalStart() and thus you are no longer allowed to create additional kernel objects.
Returned Values
NoneTMR_EN must be enabled in os_cfg.h. Refer to µC-OS-III Configuration Manual.
Callers
Application.
Notes/Warnings
- Do not call this function from an ISR.
- The timer is not started when it is created. To start the timer, simply call
OSTmrStart(). - Do not make blocking calls within callback functions.
- Keep callback functions as short as possible.
Example Usage
| Code Block | ||
|---|---|---|
| ||
OS_TMR CloseDoorTmr;
void Task (void *p_arg)
{
OS_ERR err;
(void)&p_arg;
while (DEF_ON) {
OSTmrCreate(&CloseDoorTmr, /* p_tmr */
"Door close", /* p_name */
10, /* dly */
100, /* period */
OS_OPT_TMR_PERIODIC, /* opt */
DoorCloseFnct, /* p_callback */
0, /* p_callback_arg */
&err); /* p_err */
/* Check "err" */
:
:
}
}
void DoorCloseFnct (OS_TMR *p_tmr,
void *p_arg)
{
/* Close the door! */
} |