OSTimeDly

Description

Allows a task to delay itself for an integral number of clock ticks. The delay can either be relative (delay from current time), periodic (delay occurs at fixed intervals) or absolute (delay until we reach some time).

In relative mode, rescheduling always occurs when the number of clock ticks is greater than zero. A delay of 0 means that the task is not delayed, and OSTimeDly() returns immediately to the caller.

In periodic mode, you must specify a non-zero period otherwise the function returns immediately with an appropriate error code. The period is specified in “ticks”.

In absolute mode, rescheduling always occurs since all delay values are valid.

The actual delay time depends on the tick rate (see OS_CFG_TICK_RATE_HZ if os_cfg_app.h).

Files

os.h/os_time.c

Prototype

void  OSTimeDly (OS_TICK   dly,
                 OS_OPT    opt,
                 OS_ERR   *p_err)

Arguments

dly

is the desired delay expressed in number of clock ticks. Depending on the value of the opt field, delays can be relative or absolute.

A relative delay means that the delay is started from the “current time + dly”.

A periodic delay means the period (in number of ticks). µC/OS-III saves the current time + dly in .TickCtrPrev so the next time OSTimeDly() is called, we use .TickDlyPrev + dly.

An absolute delay means that the task will wake up when OSTickCtr reaches the value specified by dly.

opt

is used to indicate whether the delay is absolute or relative:

OS_OPT_TIME_DLY

Specifies a relative delay.

OS_OPT_TIME_TIMEOUT

Same as OS_OPT_TIME_DLY.

OS_OPT_TIME_PERIODIC

Specifies periodic mode.

OS_OPT_TIME_MATCH

Specifies that the task will wake up when OSTickCtr reaches the value specified by dly

p_err

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

OS_ERR_NONE

If the call was successful, and the task has returned from the desired delay.

OS_ERR_OPT_INVALID

If OS_CFG_ARG_CHK_EN is set to DEF_ENABLED in os_cfg.h: if a valid option is not specified.

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_SCHED_LOCKED

If the scheduler is locked.

OS_ERR_TIME_DLY_ISR

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

OS_ERR_TIME_ZERO_DLY

If specifying a delay of 0 when the option was set to OS_OPT_TIME_DLY. Note that a value of 0 is valid when setting the option to OS_OPT_TIME_MATCH.

Returned Value

None

Required Configuration

None

Callers

Application.

Notes/Warnings

None

Example Usage

          void TaskX (void *p_arg)
          {
            OS_ERR  err;
           
           
            while (DEF_ON) {
              :
              :
              OSTimeDly(10,
                        OS_OPT_TIME_PERIODIC,
                        &err);
              /* Check "err" */
              :
              :
            }
          }