OSTmrSet

Description

OSTmrSet() allows the user to change the period, delay and callback parameters of an already existing timer. For more information, see OSTmrCreate().

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,
                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 and that the timer has already been initialized by OSTmrCreate().

dly

specifies the delay (specified in timer tick units) used by the timer. 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.

period

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.

p_callback

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.

p_callback_arg

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.

p_err

a pointer to an error code and can be any of the following:

OS_ERR_NONE

The timer was configured as expected.

OS_ERR_OBJ_TYPE

If OS_CFG_OBJ_TYPE_CHK_EN is set to DEF_ENABLED in os_cfg.h: ‘p_tmr” is not pointing to a timer.

OS_ERR_OS_NOT_RUNNING

If OS_CFG_INVALID_OS_CALLS_CHK_EN is set to DEF_ENABLED in os_cfg.h: if µC/OS-III is not running yet.

OS_ERR_TMR_INVALID

If OS_CFG_ARG_CHK_EN is set to DEF_ENABLED in os_cfg.h: if p_tmr is a NULL pointer or possess an invalid 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: This function is called from an ISR, which is not allowed.

Returned Values

None

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.

Example Usage

          OS_TMR    CloseDoorTmr;
           
           
          void Task (void *p_arg)
          {
              OS_ERR    err;
           
           
              (void)&p_arg;
              while (DEF_ON) {
                  OSTmrSet(&CloseDoorTmr,          /* p_tmr          */
                            10,                    /* dly            */
                            100,                   /* period         */
                            DoorCloseFnct,         /* p_callback     */
                            0,                     /* p_callback_arg */
                           &err);                  /* p_err          */
                  /* Check "err" */
                  :
                  :
              }
          }
 
           
          void  DoorCloseFnct (OS_TMR  *p_tmr,
                               void    *p_arg)
          {
              /* Close the door! */
          }