Event flag groups: utility services and data structures

March 19, 2018

Colin Walls-March 19, 2018

Data Structures

Event flag groups utilize one or two data structures – both in RAM – which, like other Nucleus SE objects, are tables, included and dimensioned according to the number of groups configured and options selected.

I strongly recommend that application code does not access these data structures directly, but uses the provided API functions. This avoids incompatibility with future versions of Nucleus SE and unwanted side-effects and simplifies porting of an application to Nucleus RTOS. The details of data structures are included here to facilitate easier understanding of the working of the service call code and for debugging.

RAM Data

These data structures are:

NUSE_Event_Group_Data[] – This is an array of type U8, with one entry for each configured event flag group and is where the event flag data is stored.

NUSE_Event_Group_Blocking_Count[] – This type U8 array contains the counts of how many tasks are blocked on each event flag group. This array only exists if blocking API call support is enabled.

These data structures are all initialized to zeros by NUSE_Init_Event_Group() when Nucleus SE starts up. A future article will provide a full description of Nucleus SE start-up procedures.

Here are the definitions of these data structures in nuse_init.c file:

    RAM U8 NUSE_Event_Group_Blocking_Count[NUSE_EVENT_GROUP_NUMBER];

ROM Data

There are no ROM data structures associated with event flag groups.

Event Flag Group Data Footprint

Like all kernel objects in Nucleus SE, the amount of data memory required for event flag groups is readily predictable.

The ROM data footprint for all the event flag groups in an application is 0.

The RAM data footprint (in bytes) for all the event flag groups in an application, when blocking API calls is enabled, is simply: NUSE_EVENT_GROUP_NUMBER * 2.

Otherwise it is just NUSE_EVENT_GROUP_NUMBER.

Unimplemented API Calls

Three event flag group API calls found in Nucleus RTOS are not implemented in Nucleus SE:

Create Event Flag Group

This API call creates an event flag group. It is not needed with Nucleus SE, as event flag groups are created statically.

Service call prototype:

STATUS NU_Create_Event_Group(NU_EVENT_GROUP *group, CHAR *name);


group – pointer to a user-supplied event flag group control block; this will be used as a “handle” for the event flag group in other API calls

name – pointers to a 7-character, null-terminated name for the event flag group


NU_SUCCESS – indicates successful completion of the service

NU_INVALID_GROUP – indicates the event flag group control block pointer is NULL or already in use

Delete Event Flag Group

This API call deletes a previously created event flag group. It is not needed with Nucleus SE, as event flag groups are created statically and cannot be deleted.

Service call prototype:

STATUS NU_Delete_Event_Group(NU_EVENT_GROUP *group);


group - pointer to partition event flag group control block


NU_SUCCESS – indicates successful completion of the service

NU_INVALID_GROUP – indicates the event flag group pointer is invalid

Event Flag Group Pointers

This API call builds a sequential list of pointers to all event flag groups in the system. It is not needed with Nucleus SE, as event flag groups are identified by a simple index, not a pointer, and it would be redundant.

Service call prototype:

UNSIGNED NU_Event_Group_Pointers(NU_EVENT_GROUP *pointer_list,
UNSIGNED maximum_pointers);


pointer_list – pointer to an array of NU_EVENT_GROUP pointers; this array will be filled with pointers to established event flag groups in the system

maximum_pointers – the maximum number of pointers to place in the array


The number of NU_EVENT_GROUP pointers placed into the array

Compatibility with Nucleus RTOS

With all aspects of Nucleus SE, it was my goal to maintain as high a level of applications code compatibility with Nucleus RTOS as possible. Event flag groups are no exception and, from a user’s perspective, they are implemented in much the same way as in Nucleus RTOS. There are areas of incompatibility, which have come about where I determined that such an incompatibility would be acceptable, given that the resulting code is easier to understand, or, more likely, could be made more memory efficient. Otherwise, Nucleus RTOS API calls may be almost directly mapped onto Nucleus SE calls. A future article will include further information on using Nucleus SE for users of Nucleus RTOS.

Object Identifiers

In Nucleus RTOS, all objects are described by a data structure – a control block – which has a specific data type. A pointer to this control block serves as an identifier for the event flag group. In Nucleus SE, I decided that a different approach was needed for memory efficiency, and all kernel objects are described by a number of tables in RAM and/or ROM. The size of these tables is determined by the number of each object type that is configured. The identifier for a specific object is simply an index into those tables. So, I have defined NUSE_EVENT_GROUP as being equivalent to U8; a variable – not a pointer – of this type then serves as the event flag group identifier. This is a small incompatibility, which is easily handled if code is ported to or from Nucleus RTOS. Object identifiers are normally just stored and passed around and not operated upon in any way.

Nucleus RTOS also supports naming of event flag groups. These names are only used for target-based debug facilities. I omitted them from Nucleus SE to save memory.

Number of Flags in a Group

In Nucleus RTOS, an event flag groups contain 32 flags; in Nucleus SE I reduced this to eight, as this is likely to be sufficient for simpler applications and saves RAM. Nucleus SE could be modified quite readily, if larger event flag groups were required.

Consume Flags Option

In Nucleus RTOS, there is an option to clear (consume) event flags when they are retrieved. I chose to omit this from Nucleus SE for simplicity, as the actual consume (deletion) of flags takes place when all the blocked tasks have received their retrieved flags; this would have been difficult to implement. The retrieving task can always clear the event flags by means of a further API call, if required.

Unimplemented API Calls

Nucleus RTOS supports seven service calls to work with event flag groups. Of these, three are not implemented in Nucleus SE. Details of these and of the decision to omit them was outlined above.

The next RTOS Revealed article will look at semaphores.

Colin Walls has over thirty years experience in the electronics industry, largely dedicated to embedded software. A frequent presenter at conferences and seminars and author of numerous technical articles and two books on embedded software, Colin is an embedded software technologist with Mentor Embedded [the Mentor Graphics Embedded Software Division], and is based in the UK. His regular blog is located at: He may be reached by email at

< Previous
Page 2 of 2
Next >

Loading comments...