Advertisement

Event flag groups: utility services and data structures

March 19, 2018

Colin Walls-March 19, 2018

This article continues the look at event flag groups.

Event Flag Group Utility Services

Nucleus RTOS has three API calls which provide utility functions associated with event flag groups: return information about a group, return number of event flag groups in the application and return pointers to all groups in the application. The first two of these are implemented in Nucleus SE.

Event Flag Group Information

This service call obtains a selection of information about an event flag group. The Nucleus SE implementation differs from Nucleus RTOS in that it returns less information, as object naming and suspend ordering are not supported and task suspend may not be enabled.

Nucleus RTOS API Call for Event Group Information

Service call prototype:

STATUS NU_Event_Group_Information(NU_EVENT_GROUP *group,
CHAR *name, UNSIGNED *even
t_flags, UNSIGNED *tasks_waiting,
NU_TASK **first_task);

Parameters:

group – pointer to the user-supplied event flag group control block

name - pointer to an 8-character destination area for the event flag group’s name; this includes space for the null terminator

event_flags – a pointer to a variable, which will receive the current value of the specified event flag group

tasks_waiting – a pointer to a variable which will receive the number of tasks suspended on this event flag group

first_task – a pointer to a variable of type NU_TASK which will receive a pointer to the first suspended task

Returns:

NU_SUCCESS – the call was completed successfully

NU_INVALID_GROUP – the event flag group pointer is not valid

Nucleus SE API Call for Event Group Information

This API call supports the key functionality of the Nucleus RTOS API.

Service call prototype:

STATUS NUSE_Event_Group_Information(NUSE_EVENT_GROUP group,
U8 *event_flags, U8 *tasks_waiting, NUSE_TASK *first_task);

Parameters:

group – the index of the event flag group about which information is being requested

event_flags – a pointer to a variable, which will receive the current value of the specified event flag group

tasks_waiting – a pointer to a variable which will receive the number of tasks suspended on this event flag group (nothing returned if task suspend is disabled)

first_task – a pointer to a variable of type NUSE_TASK which will receive the index of the first suspended task (nothing returned if task suspend is disabled)

Returns:

NUSE_SUCCESS – the call was completed successfully

NUSE_INVALID_GROUP – the event flag group index is not valid

Nucleus SE Implementation of Event Group Information

The implementation of this API call is quite straightforward:

*event_flags = NUSE_Event_Group_Data[group];
 
#if NUSE_BLOCKING_ENABLE
 
    *tasks_waiting = NUSE_Event_Group_Blocking_Count[group];
    if (NUSE_Event_Group_Blocking_Count[group] != 0)
    {
        U8 index;
 
        for (index=0; index<NUSE_TASK_NUMBER; index++)
        {
            if ((LONIB(NUSE_Task_Status[index]) ==
                 NUSE_EVENT_SUSPEND)
                && (HINIB(NUSE_Task_Status[index]) == group))
            {
                *first_task = index;
                break;
            }
        }
    }
    else
    {
        *first_task = 0;
    }
 
#else
 
    *tasks_waiting = 0;
    *first_task = 0;
 
#endif
 
return NUSE_SUCCESS;


The function returns the value of the event flag group. Then, if blocking API calls is enabled, the number of waiting tasks and the index of the first one are returned (otherwise these two parameters are set to 0).

Obtaining the Number of Event Flag Groups

This service call returns the number of event flag groups configured in the application. Whilst in Nucleus RTOS this will vary over time and the returned value will represent the current number of groups, in Nucleus SE the value returned is set at build time and cannot change.

Nucleus RTOS API Call for Event Flag Group Count

Service call prototype:

UNSIGNED NU_Established_Event_Groups(VOID);

Parameters:

None

Returns:

The current number of created event flag groups in the application

Nucleus SE API Call for Event Flag Group Count

This API call supports the key functionality of the Nucleus RTOS API.

Service call prototype:

U8 NUSE_Event_Group_Count(void);

Parameters:

None

Returns:

The number of configured event flag groups in the application

Nucleus SE Implementation of Event Flag Group Count

The implementation of this API call is almost trivially simple: the value of the #define symbol NUSE_EVENT_GROUP_NUMBER is returned.

Continue reading on page two >>

 

< Previous
Page 1 of 2
Next >

Loading comments...