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
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.The total delay (in ticks) must not exceed the maximum acceptable value that an
OS_TICK
variable can hold. TypicallyOS_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" */ : : } }