Event Flag Groups in Nucleus SE: An Introductory Guide to Configuration and API Usage

View the RTOS Revealed series

Event flag groups provide a lightweight, flexible mechanism for inter-task communication in Nucleus SE, akin to signals but with richer functionality.

Using Event Flags

In Nucleus SE, event flags are configured at build time. A maximum of 16 groups can be defined. If none are configured, the RTOS omits all related data structures and API code.

Configuring Event Flag Groups

Number of Event Flag Groups

Configuration is driven by #define directives in nuse_config.h. The key macro NUSE_EVENT_GROUP_NUMBER sets how many groups the application will use (default 0). Values above 16 or negative values trigger a compile‑time #error generated by nuse_config_check.h.

Setting a non‑zero value activates the event‑flag subsystem: data structures are allocated and API enables are considered.

API Enables

Each service call has an enable macro in nuse_config.h:

NUSE_EVENT_GROUP_SET
NUSE_EVENT_GROUP_RETRIEVE
NUSE_EVENT_GROUP_INFORMATION
NUSE_EVENT_GROUP_COUNT

By default all are FALSE, disabling the corresponding functions. To use an API, set the desired macros to TRUE. A mismatch (enabling an API while NUSE_EVENT_GROUP_NUMBER is 0) causes a compile‑time error, except for NUSE_Event_Group_Count(), which is always available.

Example excerpt from the default nuse_config.h:

#define NUSE_EVENT_GROUP_NUMBER              0 /* Number of event groups – 0‑16 */
#define NUSE_EVENT_GROUP_SET                  FALSE /* Service call enabler */
#define NUSE_EVENT_GROUP_RETRIEVE             FALSE /* Service call enabler */
#define NUSE_EVENT_GROUP_INFORMATION          FALSE /* Service call enabler */
#define NUSE_EVENT_GROUP_COUNT                FALSE /* Service call enabler */

If your code references an API that was not enabled, the linker will emit an error because the implementation was omitted.

Event Flag Service Calls

Nucleus SE offers seven service calls related to event flags, though only four are implemented:

• NUSE_Event_Group_Set() – set or clear flags.
• NUSE_Event_Group_Retrieve() – read current flag state.
• NUSE_Event_Group_Information() – query a group’s status.
• NUSE_Event_Group_Count() – obtain the number of configured groups.
• Creation, deletion, and enumeration of groups are not implemented in SE.

There is no dedicated reset function; a group can be reset to all zeros using NUSE_Event_Group_Set() with an OR operation on a zero flag mask.

Set and Retrieve Operations

Because event flags are bits, they are best expressed as binary values. Nucleus SE ships nuse_binary.h, which defines macros like b01010101 for every 8‑bit pattern.

Setting Event Flags

Both RTOS and SE expose similar APIs. The RTOS prototype is:

STATUS NU_Set_Events(NU_EVENT_GROUP *group, UNSIGNED event_flags, OPTION operation);

Parameters:

• group – pointer to the event‑flag control block.
• event_flags – bitmask of flags to manipulate.
• operation – NU_OR (set) or NU_AND (clear).

Return values:

• NU_SUCCESS
• NU_INVALID_GROUP
• NU_INVALID_OPERATION

The SE equivalent is:

STATUS NUSE_Event_Group_Set(NUSE_EVENT_GROUP group, U8 event_flags, OPTION operation);

Parameters and return codes mirror the RTOS version, with NUSE_SUCCESS, NUSE_INVALID_GROUP, and NUSE_INVALID_OPERATION.

Implementation Highlights

The core routine checks operation and applies the mask:

NUSE_CS_Enter();
if (operation == NUSE_OR) {
    NUSE_Event_Group_Data[group] |= event_flags;
} else { /* NUSE_AND */
    NUSE_Event_Group_Data[group] &= event_flags;
}

When blocking is enabled (NUSE_BLOCKING_ENABLE), the function iterates over all tasks, wakes any that are suspended on this group, and updates the blocking counter. Afterward, a reschedule may occur if a priority scheduler is active.

Suspended tasks resume once the flag state changes, allowing them to evaluate their wait conditions.

Continue to page two >>