Events Explained

Events are an important feature in ChibiOS/RT, most device drivers generate events in order to notify the application that something happened at the I/O level.
While event flags are not something unknown in other operating systems, their peculiar implementation in ChibiOS/RT requires a more in depth explanation.
Lets start with the events related terminology:

• Event Source, an EventSource is a system object that can be broadcasted asynchronously in response of a system event, as example, when the CAN driver receives a packet from the CAN bus it broadcasts an event source in order to inform the registered threads that a packet has just arrived.
• Broadcast, the operation performed on an event source in order to inform the registered threads that an event just occurred. Broadcasting can happened both in interrupt handlers and in threads.
• Event Listener, a system object that associates a Thread object to an event source. The process of associating a Thread to an EventSource using an EventListener is called registration.
• Registration, action performed by a thread in order to be informed of events from a specific event source. Of course a thread can be registered on more than one event source by using multiple EventListener objects. Threads can also unregister from an event source.
• Pend, each thread has a mask of pending events. The broadcast operation pends an event mask on all the registered threads.
• Wait, synchronous operation performed by a thread in order to wait a specific combination of events. The API offers a variety of wait functions, please refer to the events API documentation.

Note that events are asynchronously generated, as example in an interrupt handler, but are synchronously served.

Events related data structures

The following diagram explains the relationship between an event source, its list of event listeners and the registered threads.

Note that each event listener has a different bit mask to be pended on its associated thread when the event source is broadcasted, this means that each thread can define its own event identifiers independently. A broadcast operation can also pend more than one bit on the registered threads.
The threads have a variety of wait primitives, they can wait for one or more event flags to become pending, and can also specify AND/OR conditions, as example a thread can wait for any event to become pending or wait for all the specified events to become pending.
The field p_epending is the mask of the currently pending events, the field p_ewmask is the mask of the events the thread is interested on in that moment (AND or OR condition depending on the invoked wait API).

Use Scenarios

Events are best used when one of more of the following conditions are required:

• Having to wait on multiple conditions, Events are the only mechanism that easily allow that.
• Synchronous response to one or more asynchronous events.
• Single threaded applications working in a event driver environment (but events are not limited to single threaded applications).