OSTimeDlyHMSM

Description

Allows a task to delay itself for a user-specified period that is specified in hours, minutes, seconds, and milliseconds. This format is more convenient and natural than simply specifying ticks as in OSTimeDly(). Rescheduling always occurs when at least one of the parameters is non-zero. The delay is relative from the time this function is called.

µC/OS-III allows the user to specify nearly any value when indicating that this function is not to be strict about the values being passed (opt == OS_OPT_TIME_HMSM_NON_STRICT). This is a useful feature, for example, to delay a task for thousands of milliseconds.

Files

os.h/os_time.c

Prototype

void  OSTimeDlyHMSM (CPU_INT16U   hours,
                     CPU_INT16U   minutes,
                     CPU_INT16U   seconds,
                     CPU_INT32U   milli,
                     OS_OPT       opt,
                     OS_ERR      *p_err)

Arguments

hours

is the number of hours the task is delayed. Depending on the opt value, the valid range is 0..99 (OS_OPT_TIME_HMSM_STRICT), or 0..999 (OS_OPT_TIME_HMSM_NON_STRICT). Please note that it not recommended to delay a task for many hours because feedback from the task will not be available for such a long period of time.

minutes

is the number of minutes the task is delayed. The valid range of values is 0 to 59 (OS_OPT_TIME_HMSM_STRICT), or 0..9,999 (OS_OPT_TIME_HMSM_NON_STRICT). Please note that it not recommended to delay a task for tens to hundreds of minutes because feedback from the task will not be available for such a long period of time.

seconds

is the number of seconds the task is delayed. The valid range of values is 0 to 59 (OS_OPT_TIME_HMSM_STRICT), or 0..65,535 (OS_OPT_TIME_HMSM_NON_STRICT).

milli

is the number of milliseconds the task is delayed. The valid range of values is 0 to 999 (OS_OPT_TIME_HMSM_STRICT), or 0..4,294,967,295 (OS_OPT_TIME_HMSM_NON_STRICT). Note that the resolution of this argument is in multiples of the tick rate. For instance, if the tick rate is set to 100Hz, a delay of 4 ms results in no delay because the delay is rounded to the nearest tick. Thus, a delay of 15 ms actually results in a delay of 20 ms.

opt

is the desired mode and can be either:

OS_OPT_TIME_HMSM_STRICT

(see above)

OS_OPT_TIME_HMSM_NON_STRICT

(see above)

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 hours, minutes, seconds and milli.

p_err

is a pointer to a variable that contains 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_INVALID_HOURS

If OS_CFG_ARG_CHK_EN is set to DEF_ENABLED in os_cfg.h: if not specifying a valid value for hours.

OS_ERR_TIME_INVALID_MINUTES

If OS_CFG_ARG_CHK_EN is set to DEF_ENABLED in os_cfg.h: if not specifying a valid value for minutes.

OS_ERR_TIME_INVALID_SECONDS

If OS_CFG_ARG_CHK_EN is set to DEF_ENABLED in os_cfg.h: if not specifying a valid value for seconds.

OS_ERR_TIME_INVALID_MILLISECONDS

If OS_CFG_ARG_CHK_EN is set to DEF_ENABLED in os_cfg.h: if not specifying a valid value for milliseconds.

OS_ERR_TIME_ZERO_DLY

If specifying a delay of 0 because all the time arguments are 0.

Returned Value

None

Required Configuration

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

Callers

Application.

Notes/Warnings

1. Note that OSTimeDlyHMSM(0,0,0,0,OS_OPT_TIME_HMSM_???,&err) (i.e., hours, minutes, seconds, milliseconds are 0) results in no delay, and the function returns to the caller.

2. The total delay (in ticks) must not exceed the maximum acceptable value that an OS_TICK variable can hold. Typically OS_TICK is a 32-bit value.

Example Usage

          void TaskX (void *p_arg)
          {
              OS_ERR  err;
           
           
              while (DEF_ON) {
                  :
                  :
                  OSTimeDlyHMSM(0,
                                0,
                                1,
                                0,
                                OS_OPT_TIME_HMSM_STRICT,
                                &err);              /* Delay task for 1 second */
                  /* Check "err" */
                  :
                  :
              }
          }