OSFlagPend
Description
Wait for a combination of conditions or events (i.e. bits) to be set (or cleared) in an event flag group. The application can wait for any condition to be set or cleared, or for all conditions to be set or cleared. If the events that the calling task desires are not available, the calling task is blocked (optional) until the desired conditions or events are satisfied, the specified timeout expires, the event flag is deleted, or the pend is aborted by another task.
Files
os.h/os_flag.c
Prototype
OS_FLAGS OSFlagPend (OS_FLAG_GRP *p_grp,
OS_FLAGS flags,
OS_TICK timeout,
OS_OPT opt,
CPU_TS *p_ts,
OS_ERR *p_err)
Arguments
p_grp
is a pointer to the event flag group.
flags
is a bit pattern indicating which bit(s) (i.e., flags) to check. The bits wanted are specified by setting the corresponding bits in flags. If the application wants to wait for bits 0 and 1 to be set, specify 0x03. The same applies if you’d want to wait for the same 2 bits to be cleared (you’d still specify which bits by passing 0x03).
timeout
allows the task to resume execution if the desired flag(s) is (are) not received from the event flag group within the specified number of clock ticks. A timeout value of 0 indicates that the task wants to wait forever for the flag(s). The timeout value is not synchronized with the clock tick. The timeout count begins decrementing on the next clock tick, which could potentially occur immediately.
opt
specifies whether all bits are to be set/cleared or any of the bits are to be set/cleared. Here are the options:
OS_OPT_PEND_FLAG_CLR_ALL
If OS_CFG_FLAG_MODE_CLR_EN is set to DEF_ENABLED in os_cfg.h, check all bits in flags to be clear (0)
OS_OPT_PEND_FLAG_CLR_ANY
If OS_CFG_FLAG_MODE_CLR_EN is set to DEF_ENABLED in os_cfg.h, check any bit in flags to be clear (0)
OS_OPT_PEND_FLAG_SET_ALL
Check all bits in flags to be set (1)
OS_OPT_PEND_FLAG_SET_ANY
Check any bit in flags to be set (1)
The caller may also specify whether the flags are consumed by “adding” OS_OPT_PEND_FLAG_CONSUME to the opt argument. For example, to wait for any flag in a group and then clear the flags that satisfy the condition, you would set opt to:
OS_OPT_PEND_FLAG_SET_ANY + OS_OPT_PEND_FLAG_CONSUME
Finally, you can specify whether you want the caller to block if the flag(s) are available or not. You would then “add” the following options:
OS_OPT_PEND_BLOCKING
OS_OPT_PEND_NON_BLOCKING
Note that the timeout argument should be set to 0 when specifying OS_OPT_PEND_NON_BLOCKING, since the timeout value is irrelevant using this option. Having a non-zero value could simply confuse the reader of your code.
p_ts
is a pointer to a timestamp indicating when the flags were posted, the pend was aborted, or the event flag group was deleted. Passing a NULL pointer (i.e., (CPU_TS *)0) indicates that the caller does not desire the timestamp. In other words, passing a NULL pointer is valid, and indicates that the caller does not need the timestamp.
A timestamp is useful when the task desires to know when the event flag group was posted or how long it took for the task to resume after the event flag group was posted. In the latter case, the user must call OS_TS_GET() and compute the difference between the current value of the timestamp and *p_ts, as shown:
delta = OS_TS_GET() - *p_ts;
p_err
is a pointer to an error code and can be:
OS_ERR_NONE
No error.
OS_ERR_OBJ_DEL
If the event group was deleted.
OS_ERR_OBJ_PTR_NULL
If OS_CFG_ARG_CHK_EN is set to DEF_ENABLED in os_cfg.h: if p_grp is a NULL pointer.
OS_ERR_OBJ_TYPE
If OS_CFG_OBJ_TYPE_CHK_EN is set to DEF_ENABLED in os_cfg.h: p_grp is not pointing to an event flag group.
OS_ERR_OPT_INVALID
If OS_CFG_ARG_CHK_EN is set to DEF_ENABLED in os_cfg.h: the caller specified an invalid option.
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_PEND_ABORT
The wait on the flags was aborted by another task that called OSFlagPendAbort().
OS_ERR_PEND_ISR
If OS_CFG_CALLED_FROM_ISR_CHK_EN set to DEF_ENABLED in os_cfg.h: An attempt was made to call OSFlagPend() from an ISR, which is not allowed.
OS_ERR_PEND_WOULD_BLOCK
If specifying non-blocking but the flags were not available and the call would block if the caller had specified OS_OPT_PEND_BLOCKING.
OS_ERR_SCHED_LOCKED
When calling this function while the scheduler was locked.
OS_ERR_STATUS_INVALID
If the pend status has an invalid value.
OS_ERR_TIMEOUT
The flags are not available within the specified amount of time.
Returned Values
The flag(s) that cause the task to be ready, 0 if either none of the flags are ready, or indicate an error occurred.
Required Configuration
OS_CFG_FLAG_EN must be enabled, and optionally OS_CFG_FLAG_MODE_CLR_EN, in os_cfg.h. Refer to µC-OS-III Configuration Manual.
Callers
Application.
Notes/Warnings
- The event flag group must be created before it is used.
Example Usage
#define ENGINE_OIL_PRES_OK 0x01
#define ENGINE_OIL_TEMP_OK 0x02
#define ENGINE_START 0x04
OS_FLAG_GRP EngineStatus;
void Task (void *p_arg)
{
OS_ERR err;
OS_FLAGS value;
CPU_TS ts;
(void)&p_arg;
while (DEF_ON) {
value = OSFlagPend(&EngineStatus,
ENGINE_OIL_PRES_OK + ENGINE_OIL_TEMP_OK,
OS_FLAG_WAIT_SET_ALL + OS_FLAG_CONSUME,
10,
OS_OPT_PEND_BLOCKING,
&ts,
&err);
/* Check "err" */
:
:
}
}