事件标志组(API - Event Flags)

事件标志组(API - Event Flags)

必须同时满足两个及以上事件才触发某种动作

Required Configuration

OS_CFG_FLAG_EN must be enabled in os_cfg.h. Refer to uC-OS-III Configuration Manual.

Description

Creates and initialize an event flag group. µC/OS-III allows the user to create an unlimited

number of event flag groups (limited only by the amount of RAM in the system).

Files

os.h/os_flag.c

Prototype

void OSFlagCreate (OS_FLAG_GRP *p_grp,
 CPU_CHAR *p_name,
 OS_FLAGS flags,
 OS_ERR *p_err)

Arguments

p_grp

This is a pointer to an event flag group that must be allocated in the application. The user

will need to declare a “global” variable as shown, and pass a pointer to this variable to

OSFlagCreate():

OS_FLAG_GRP MyEventFlag;

p_name

This is a pointer to an ASCII string used for the name of the event flag group. The name

can be displayed by debuggers or by µC/Probe.

flags

This contains the initial value of the flags to store in the event flag group. Typically, you

would set all flags to 0 events correspond to set bits and all 1s if events correspond to

cleared bits.

p_err

This is a pointer to a variable that is used to hold an error code. The error code can be one

of the following:

OS_ERR_NONE

If the call is successful and the event flag group has been created.

OS_ERR_CREATE_ISR

If OS_CFG_CALLED_FROM_ISR_CHK_EN set to DEF_ENABLED in os_cfg.h: If attempting to

create an event flag group from an ISR, w is not allowed.

OS_ERR_ILLEGAL_CREATE_RUN_TIME

If OS_SAFETY_CRITICAL_IEC61508 is defined: you called this after calling OSStart()

and thus you are no longer allowed to create additional kernel objects.

OSFlagPost

Description

Sets or clears event flag bits. The bits set or cleared are specified in a bit mask (i.e., the flags

argument). OSFlagPost() readies each task that has its desired bits satisfied by this call. The

caller can set or clear bits that are already set or cleared.

Files

os.h/os_flag.c

Prototype

OS_FLAGS OSFlagPost (OS_FLAG_GRP *p_grp,
 OS_FLAGS flags,
 OS_OPT opt,
 OS_ERR *p_err)

Arguments

p_grp

is a pointer to the event flag group.

flags

specifies which bits to be set or cleared. If opt is OS_OPT_POST_FLAG_SET, each bit that is

set in flags will set the corresponding bit in the event flag group. For example to set bits

0, 4, and 5, you would set flags to 0x31 (note that bit 0 is the least significant bit). If opt

is OS_OPT_POST_FLAG_CLR, each bit that is set in flags will clear the corresponding bit in

the event flag group. For example to clear bits 0, 4, and 5, you would specify flags as

0x31 (again, bit 0 is the least significant bit).

opt

indicates whether the flags are set (OS_OPT_POST_FLAG_SET) or cleared (

OS_OPT_POST_FLAG_CLR).

The caller may also “add” OS_OPT_POST_NO_SCHED so that µC/OS-III will not call the

scheduler after the post.

p_err

is a pointer to an error code and can be:

OS_ERR_NONE

the call is successful.

OS_ERR_INT_Q_FULL

If OS_CFG_ISR_POST_DEFERRED_EN is to DEF_ENABLED in os_cfg.h: If the deferred

interrupt post queue is full.

OS_ERR_OBJ_PTR_NULL

If OS_CFG_ARG_CHK_EN is set to DEF_ENABLED in os_cfg.h: if the caller passed a NULL

pointer.

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

Check all bits in flags to be clear (0)

OS_OPT_PEND_FLAG_CLR_ANY

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.