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

OSFlagPend() 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" */
                  :
                  :
              }
          }

µC/OS-III Documentation