事件标志组(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.