15.2. Background

15.2.1. Event Sets

An event flag is used by a task (or ISR) to inform another task of the occurrence of a significant situation. Thirty-two event flags are associated with each task. A collection of one or more event flags is referred to as an event set. The data type rtems_event_set is used to manage event sets.

The application developer should remember the following key characteristics of event operations when utilizing the event manager:

  • Events provide a simple synchronization facility.

  • Events are aimed at tasks.

  • Tasks can wait on more than one event simultaneously.

  • Events are independent of one another.

  • Events do not hold or transport data.

  • Events are not queued. In other words, if an event is sent more than once to a task before being received, the second and subsequent send operations to that same task have no effect.

An event set is posted when it is directed (or sent) to a task. A pending event is an event that has been posted but not received. An event condition is used to specify the event set which the task desires to receive and the algorithm which will be used to determine when the request is satisfied. An event condition is satisfied based upon one of two algorithms which are selected by the user. The RTEMS_EVENT_ANY algorithm states that an event condition is satisfied when at least a single requested event is posted. The RTEMS_EVENT_ALL algorithm states that an event condition is satisfied when every requested event is posted.

15.2.2. Building an Event Set or Condition

An event set or condition is built by a bitwise OR of the desired events. The set of valid events is RTEMS_EVENT_0 through RTEMS_EVENT_31. If an event is not explicitly specified in the set or condition, then it is not present. Events are specifically designed to be mutually exclusive, therefore bitwise OR and addition operations are equivalent as long as each event appears exactly once in the event set list.

For example, when sending the event set consisting of RTEMS_EVENT_6, RTEMS_EVENT_15, and RTEMS_EVENT_31, the event parameter to the rtems_event_send directive should be RTEMS_EVENT_6 | RTEMS_EVENT_15 | RTEMS_EVENT_31.

15.2.3. Building an EVENT_RECEIVE Option Set

In general, an option is built by a bitwise OR of the desired option components. The set of valid options for the rtems_event_receive directive are listed in the following table:

RTEMS_WAIT

task will wait for event (default)

RTEMS_NO_WAIT

task should not wait

RTEMS_EVENT_ALL

return after all events (default)

RTEMS_EVENT_ANY

return after any events

Option values are specifically designed to be mutually exclusive, therefore bitwise OR and addition operations are equivalent as long as each option appears exactly once in the component list. An option listed as a default is not required to appear in the option list, although it is a good programming practice to specify default options. If all defaults are desired, the option RTEMS_DEFAULT_OPTIONS should be specified on this call.

This example demonstrates the option parameter needed to poll for all events in a particular event condition to arrive. The option parameter passed to the rtems_event_receive directive should be either RTEMS_EVENT_ALL | RTEMS_NO_WAIT or RTEMS_NO_WAIT. The option parameter can be set to RTEMS_NO_WAIT because RTEMS_EVENT_ALL is the default condition for rtems_event_receive.