Page Comparison

...

Description

OSTmrCreate() allows the user to create a software timer. The timer can be configured to run continuously (opt set to  set to OS_TMR_OPT_PERIODIC), or only once (opt set to  set to OS_TMR_OPT_ONE_SHOT). When the timer counts down to to 0 (from the value specified in 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.

Anchor10824751082475The timer is created in the “stop” mode and therefore the user user must call  call OSTmrStart() to  to actually start the timer. If configuring the timer for ONE-SHOT mode, and the timer expires, you need to call call OSTmrStart() to  to retrigger the timer, call call OSTmrDel() to  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. Anchor

10824791082479 Image Removed Anchor10824801082480Image Added

PERIODIC MODE (see “opt”“opt”) – – dly >  > 0, period >  > 0

Anchor10824841082484 Image Removed Anchor10824851082485Image Added

PERIODIC MODE (see “opt”“opt”) – “dly == 0, period > 0

Anchor10824891082489 Image Removed Anchor10824901082490Image Added

ONE-SHOT MODE (see “opt”“opt”) – – dly >  > 0, period == 0 Anchor10824911082491 Arguments Anchor10824921082492 p_tmr Anchor10824931082493

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,
                   OS_ERR               *p_err)

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;

Anchor10824951082495p_name Anchor10824961082496

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.

...

10824971082497dly Anchor10824981082498

specifies the initial delay (specified in timer tick units) used by the timer (see drawing above). 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 timeout to wait before the timer enters periodic mode. The units of this time depends on how often the user will call OSTmrSignal() (see OSTimeTick()). If OSTmrSignal() is called every 1/10 of a second (i.e., OS_CFG_TMR_TASK_RATE_HZ set to 10), dly specifies the number of 1/10 of a second before the delay expires.

...

1082499period Anchor10825001082500

specifies the period repeated by the timer if configured for PERIODIC mode. You would set the

...

“period” to 0 when using ONE-SHOT mode. The units of time depend on how often OSTmrSignal() is called. If OSTmrSignal() is called every 1/10 of a second (i.e., OS_CFG_TMR_TASK_RATE_HZ set to 10), the period specifies the number of 1/10 of a second before the timer repeats.

...

optanchor13259131325913

is used to specify whether the timer is to be ONE-SHOT or PERIODIC:

...

OS_OPT_TMR_ONE_SHOT specifiesONE-SHOT mode
OS_OPT_TMR_PERIODIC specifiesPERIODIC mode

...

10825061082506p_callbackanchor10825071082507

is a pointer to a function that will execute when the timer expires (ONE-SHOT mode), or every time the period expires (PERIODIC mode). A NULL pointer indicates that no action is to be performed upon timer expiration. The callback function must be declared as follows:

...

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

...

...

When called, the callback will be passed the pointer to the timer as well as an argument (p_callback_arg), which can be used to indicate to the callback what to do. Note that the user is allowed to call all of the timer related functions (i.e., OSTmrCreate(), OSTmrDel(), OSTmrStateGet(), OSTmrRemainGet(), OSTmrStart(), and OSTmrStop()) from the callback function.

...

Do not make blocking calls within callback functions.

...

10825121082512p_callback_arg Anchor10825131082513

is an argument passed to the callback function when the timer expires (ONE-SHOT mode), or every time the period expires (PERIODIC mode). The pointer is declared as a

...

“void *” so it can point to any data.

Anchor10825141082514p_err Anchor10825151082515

is a pointer to a variable that contains an error code returned by this function.

...

...

OS_ERR_NONE

...

...

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

...

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

...

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.

...

...

...

OS_ERR_TMR_INVALID_PERIOD

...

...

If OS_CFG_ARG_CHK_EN is set to

...

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_TMR_ISR

...

...

If OS_CFG_CALLED_FROM_ISR_CHK_EN set

...

to DEF_ENABLED in os_cfg.h: if calling this function from an ISR.

...

Returned Values

...

...

...

Anchor10825301082530 Returned Values Anchor10825311082531 None. Anchor10825321082532 Notes/Warnings Anchor10825331082533None.

Required Configuration

OS_CFG_TMR_EN must be enabled in os_cfg.h. Refer to µC-OS-III Configuration Manual.

Callers

Application.

Notes/Warnings

1. Do not call this function from an ISR.

...

1. The timer is not started when it is created. To start the timer, simply call OSTmrStart().

...

...

1. Do not make blocking calls within callback functions.

...

1. Keep callback functions as short as possible.

...

Example Usage

...

...

              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! */
          }

          OS_TMR  CloseDoorTmr;
           
           
          void Task (void *p_arg)
          {
              OS_ERR   err;
           
           
              (void)&p_arg;