Versions Compared

Old Version 1

changes.mady.by.user Former user

Saved on

compared with

New Version Current

changes.mady.by.user WES Admin

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

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. Anchor999963999963 Arguments Anchor999964999964

Files

os.h/os_flag.c

Prototype

Code Block
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 Anchor999965999965

is a pointer to the event flag group.

...

flags Anchor999967999967

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).

Anchor999968999968timeout Anchor999969999969

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.

...

999970999970opt Anchor999971999971

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

...

classWebWorks_Indent_2

...

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)

...

...

classWebWorks_Indent_1

...

OS_OPT_PEND_FLAG_CLR_ANY

...

classWebWorks_Indent_2

...

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)

...

classWebWorks_Indent_1

...

OS_OPT_PEND_FLAG_SET_ALL

...

classWebWorks_Indent_2

...

...

Check all bits in flags to be set (1)

...

classWebWorks_Indent_1

...

OS_OPT_PEND_FLAG_SET_ANY

...

classWebWorks_Indent_2

...

Check any bit in flags to be set (1)

...

classWebWorks_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.

Anchor999986999986p_ts Anchor999988999988

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;

...

999997999997p_err Anchor999998999998

is a pointer to an error code and can be:

...

classWebWorks_Indent_1

...

...

OS_ERR_NONE

...

classWebWorks_Indent_2

...

No error.

...

classWebWorks_Indent_1

...

OS_ERR_OBJ_DEL

If the event group was deleted.

OS_ERR_OBJ_PTR_NULL

...

classWebWorks_Indent_2

...

If OS_CFG_ARG_CHK_EN is set to

...

DEF_ENABLED in os_cfg.h: if p_grp is a NULL pointer.

...

...

classWebWorks_Indent_1

...

OS_ERR_OBJ_TYPE

...

classWebWorks_Indent_2

...

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.

...

...

classWebWorks_Indent_1

...

OS_ERR_OPT_INVALID

...

classWebWorks_Indent_2

...

If OS_CFG_ARG_CHK_EN is set to

...

DEF_ENABLED in os_cfg.h: the caller specified an invalid option.

...

classWebWorks_Indent_1

...

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

...

classWebWorks_Indent_2

...

The wait on the flags was aborted by another task that called OSFlagPendAbort().

...

...

OS_ERR_PEND_ISR

...

classWebWorks_Indent_2

...

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.

...

...

classWebWorks_Indent_1

...

OS_ERR

...

_

...

classWebWorks_Indent_1

...

PEND_WOULD_BLOCK

...

classWebWorks_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.

...

classWebWorks_Indent_1

...

classWebWorks_Indent_2

...

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

...

1000018The flag(s) that cause the task to be ready, 0 if either if either none of the flags are ready, or indicate an error occurred. Anchor10511521051152

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

...

  1. The event flag group must be created before it is used.

...

...

Example Usage

...

Code Block

...

#define #define 
   0x01
          #define  ENGINE_OIL_TEMP_OK
0x02 #define ENGINE_START 0x04  
   0x02
          #define  ENGINE_START         0x04
           
          OS_FLAG_GRP
EngineStatus;   void Task (void *p_arg) { OS_ERR err; OS_FLAGS value; CPU_TS ts;    
  EngineStatus;
           
          void Task (void *p_arg)
          {
              OS_ERR    err;
              OS_FLAGS  value;
              CPU_TS    ts;
           
           
              (void)&p_arg;
while 

              while (DEF_ON)
{ value = OSFlagPend(&EngineStatus,
 {
                  value = OSFlagPend(&EngineStatus,
                                     ENGINE_OIL_PRES_OK   + ENGINE_OIL_TEMP_OK,

                                     OS_FLAG_WAIT_SET_ALL + OS_FLAG_CONSUME,
10,

                                     10,
                                     OS_OPT_PEND_BLOCKING,
&ts, &err); /* Check “err” */ : : } }tr

                                     &ts,
                                     &err);
                  /* Check "err" */
                  :
                  :
              }
          }
HTML Table
summary
classCode_Listing
Table Row (tr)
Table Cell (td)
rowspan23
Anchor
10511561051156
titleOSFlagPend() example usage
          #define  ENGINE_OIL_PRES_OK
0x01
Anchor
10511571051157
Anchor
10511581051158
Anchor
10511591051159
Anchor
10511601051160
Anchor
10511611051161
Anchor
10511621051162
Anchor
10511631051163
Anchor
10511641051164
Anchor
10511651051165
Anchor
10511661051166
Anchor
10511671051167
Anchor
10511681051168
Anchor
10511691051169
Anchor
10511701051170
Anchor
10511711051171
Anchor
10511721051172
Anchor
10511731051173
Anchor
10511741051174
Anchor
10511751051175
Anchor
10511761051176
Anchor
10511771051177
Anchor
10511781051178
Anchor
10511791051179
Anchor
10511801051180
Anchor
10511811051181
Anchor
10511821051182
Table Row (tr)
Table Row (tr)
Table Row (tr)
Table Row (tr)
Table Row (tr)
Table Row (tr)
Table Row (tr)
Table Row (tr)
Table Row (tr)
Table Row (tr)
Table Row (tr)
Table Row (tr)
Table Row (tr)
Table Row (tr)
Table Row (tr)
Table Row (tr)
Table Row (tr)
Table Row (tr)
Table Row (tr)
Table Row (tr)
Table Row (tr)