...
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 |
| Task only |
|
...
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.Anchor
Arguments
...
p_grpanchor
is a pointer to the event flag group.
Anchor
flagsanchoris 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).
Anchor
timeoutallows 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.
...
optspecifies whether all bits are to be set/cleared or any of the bits are to be set/cleared. Here are the options:
...
| class | WebWorks_Indent_1 |
|---|
...
OS_OPT_PEND_FLAG_CLR_ALL
...
| class | WebWorks_Indent_2 |
|---|
...
Check all bits in flags to be clear (0)
...
...
| class | WebWorks_Indent_1 |
|---|
...
OS_OPT_PEND_FLAG_CLR_ANY
...
| class | WebWorks_Indent_2 |
|---|
...
Check any bit in flags to be clear (0)
...
...
OS_OPT_PEND_FLAG_SET_ALL
...
| class | WebWorks_Indent_2 |
|---|
...
...
Check all bits in flags to be set (1)
...
| class | WebWorks_Indent_1 |
|---|
...
...
OS_OPT_PEND_FLAG_SET_ANY
...
...
| class | WebWorks_Indent_2 |
|---|
...
Check any bit in flags to be set (1)
...
| class | WebWorks_Indent_2 |
|---|
...
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_tsis 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_erris a pointer to an error code and can be:
...
...
OS_ERR_NONE
...
...
No error.
...
| class | WebWorks_Indent_1 |
|---|
...
OS_ERR_OBJ_PTR_NULL
...
| class | WebWorks_Indent_2 |
|---|
...
if OS_CFG_ARG_CHK_EN is set to 1 in os_cfg.h: if p_grp is a NULL pointer.
...
| class | WebWorks_Indent_1 |
|---|
...
OS_ERR_OBJ_TYPE
...
...
if OS_CFG_OBJ_TYPE_CHK_EN is set to 1 in os_cfg.h: p_grp is not pointing to an event flag group.
...
| class | WebWorks_Indent_1 |
|---|
...
OS_ERR_OPT_INVALID
...
...
| class | WebWorks_Indent_2 |
|---|
...
if OS_CFG_ARG_CHK_EN is set to 1 in os_cfg.h: the caller specified an invalid option.
...
| class | WebWorks_Indent_1 |
|---|
...
OS_ERR_PEND_ABORT
...
...
| class | WebWorks_Indent_2 |
|---|
...
the wait on the flags was aborted by another task that called OSFlagPendAbort().
...
| class | WebWorks_Indent_1 |
|---|
...
OS_ERR_PEND_ISR
...
| class | WebWorks_Indent_2 |
|---|
...
...
if OS_CFG_CALLED_FROM_ISR_CHK_EN set to 1 in os_cfg.h: An attempt was made to call OSFlagPend() from an ISR, which is not allowed.
...
| class | WebWorks_Indent_1 |
|---|
...
OS_ERR_SCHED_LOCKED
...
| class | WebWorks_Indent_2 |
|---|
...
...
When calling this function while the scheduler was locked.
...
...
OS_ERR_PEND_WOULD_BLOCK
...
| class | WebWorks_Indent_2 |
|---|
...
if specifying non-blocking but the flags were not available and the call would block if the caller had specified OS_OPT_PEND_BLOCKING.
...
| class | WebWorks_Indent_1 |
|---|
...
...
OS_ERR_TIMEOUT
...
| class | WebWorks_Indent_2 |
|---|
...
the flags are not available within the specified amount of time.
...
Returned Values
...
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.Anchor
Example
...
| rowspan | 23 |
|---|
...