Kernel Event Flag API#

OSFlagCreate()#

Description#

This function is called to create an event flag group.

Files#

os.h/os_flag.c

Prototype#

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

Arguments#

p_grp

Pointer to the event flag group to create. Your application is responsible for allocating storage for the flag group.

p_name

The name of the event flag group.

flags

Contains the initial value to store in the event flag group (typically 0).

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_OS_ILLEGAL_RUN_TIME

Returned Value#

None.

Notes / Warnings#

None.

OSFlagDel()#

Description#

This function deletes an event flag group and readies all tasks pending on the event flag group.

Files#

os.h/os_flag.c

Prototype#

OS_OBJ_QTY  OSFlagDel (OS_FLAG_GRP  *p_grp,
                       OS_OPT        opt,
                       RTOS_ERR     *p_err)

Arguments#

p_grp

Pointer to the event flag group.

opt

Determines delete options as follows:

  • OS_OPT_DEL_NO_PEND Deletes the event flag group ONLY if no task is pending.

  • OS_OPT_DEL_ALWAYS Deletes the event flag group even if tasks are waiting. In this case, all the pending tasks will be made ready.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_OS_ILLEGAL_RUN_TIME

  • RTOS_ERR_OS_TASK_WAITING

Returned Value#

  • == 0 If no tasks were waiting on the event flag group, or upon error.

  • > 0 If one or more tasks waiting on the event flag group are now ready and informed.

Notes / Warnings#

  1. Use this function with care. Tasks that would normally expect the presence of the event flag group MUST check the return code of OSFlagPost() and OSFlagPend().

OSFlagPend()#

Description#

This function is called to wait for a combination of bits to be set in an event flag group. Your application can wait for either ANY bit to be set or ALL bits to be set.

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,
                      RTOS_ERR     *p_err)

Arguments#

p_grp

Pointer to the event flag group.

flags

Bit pattern that indicates which bit(s) (i.e., flags) to wait for. The bits you want are specified by setting the corresponding bits in 'flags' (e.g., if your application waits for bits 0 and 1, then the 'flags' would contain 0x03).

timeout

Optional timeout (in clock ticks) that your task will wait for the desired bit combination. If you specify 0, the task will wait forever at the specified event flag group, or until a message arrives.

opt

Specifies whether you want ALL bits to be set or ANY of the bits to be set. You can specify the 'ONE' of the following arguments:

  • OS_OPT_PEND_FLAG_CLR_ALL Wait for ALL bits in 'flags' to be clear. (0)

  • OS_OPT_PEND_FLAG_CLR_ANY Wait for ANY bit in 'flags' to be clear. (0)

  • OS_OPT_PEND_FLAG_SET_ALL Wait for ALL bits in 'flags' to be set. 1.

  • OS_OPT_PEND_FLAG_SET_ANY Wait for ANY bit in 'flags' to be set. 1.

You can 'ADD' OS_OPT_PEND_FLAG_CONSUME if you want the event flag to be 'consumed' by the call. For example, to wait for any flag in a group AND clear the flags that are present, set 'wait_opt' to:

OS_OPT_PEND_FLAG_SET_ANY + OS_OPT_PEND_FLAG_CONSUME

You can also 'ADD' the type of pend with 'ONE' of the two options:

  • OS_OPT_PEND_BLOCKING Task will block if flags are not available.

  • OS_OPT_PEND_NON_BLOCKING Task will NOT block if flags are not available.

p_ts

Pointer to a variable that receives the timestamp of when the event flag group was posted, aborted, or deleted. If you pass a NULL pointer (i.e. (CPU_TS *)0) then you will not get the timestamp. In other words, passing a NULL pointer is valid and indicates that you don't need the timestamp.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_ERR_WOULD_BLOCK

  • RTOS_ERR_OS_SCHED_LOCKED

  • RTOS_ERR_ABORT

  • RTOS_ERR_TIMEOUT

Returned Value#

The flags in the event flag group that made the task ready or, 0 if a timeout or an error occurred.

Notes / Warnings#

None.

OSFlagPendAbort()#

Description#

This function aborts and prepares any tasks currently waiting on an event flag group. Rather than posting to the event flag group with OSFlagPost(), you should use this function to fault-abort the wait on the event flag group.

Files#

os.h/os_flag.c

Prototype#

OS_OBJ_QTY  OSFlagPendAbort (OS_FLAG_GRP  *p_grp,
                             OS_OPT        opt,
                             RTOS_ERR     *p_err)

Arguments#

p_grp

Pointer to the event flag group.

opt

Determines the type of ABORT performed:

  • OS_OPT_PEND_ABORT_1 ABORT wait for a single task (HPT) waiting on the event flag.

  • OS_OPT_PEND_ABORT_ALL ABORT wait for ALL tasks that are waiting on the event flag.

  • OS_OPT_POST_NO_SCHED Do not call the scheduler.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_NONE_WAITING

Returned Value#

  • == 0 If no tasks were waiting on the event flag group, or upon error.

  • > 0 If one or more tasks waiting on the event flag group are now ready and informed.

Notes / Warnings#

None.

OSFlagPendGetFlagsRdy()#

Description#

This function is called to obtain the flags that caused the task to be ready. In other words, this function allows you to reveal "Who done it!"

Files#

os.h/os_flag.c

Prototype#

OS_FLAGS  OSFlagPendGetFlagsRdy (RTOS_ERR  *p_err)

Arguments#

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

Returned Value#

The flags that caused the task to be ready.

Notes / Warnings#

None.

OSFlagPost()#

Description#

This function is called to set or clear some bits in an event flag group. The bits to set or clear are specified by a 'bit mask'.

Files#

os.h/os_flag.c

Prototype#

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

Arguments#

p_grp

Pointer to the event flag group.

flags

If 'opt' (see below) is OS_OPT_POST_FLAG_SET, each bit set in 'flags' will be SET to the corresponding bit in the event flag group. For example, to set bits 0, 4, and 5, you would set 'flags' to:

0x31 (note, bit 0 is least significant bit)

  • If 'opt' (see below) is OS_OPT_POST_FLAG_CLR, each bit 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 (note, bit 0 is least significant bit)

opt

Indicates whether the flags will be Set or Cleared :

  • OS_OPT_POST_FLAG_SET Set.

  • OS_OPT_POST_FLAG_CLR Cleared.

You can also 'ADD' OS_OPT_POST_NO_SCHED to prevent the scheduler from being called.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

Returned Value#

The new value of the event flags bits that are still set.

Notes / Warnings#

  1. The execution time of this function depends on the number of tasks waiting on the event flag group.