OSFlagPend()
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)
File |
Called from |
Code enabled by |
os_flag.c |
Task only |
OS_CFG_FLAG_EN |
OSFlagPend() allows the task to 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.
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:
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:
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.
Notes/Warnings
The event flag group must be created before it is used.
Example
#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” */ : : } } |