<p>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.<br/>
While event flags are not something unknown in other operating systems, their peculiar implementation in ChibiOS/RT requires a more in depth explanation.<br/>
Lets start with the events related terminology:</p>
<ul>
<li><b>Event Source</b>, an <code><aclass="el"href="struct_event_source.html"title="Event Source structure.">EventSource</a></code> is a system object that can be <em>broadcasted</em> asynchronously in response of a system event, as example, when the CAN driver receives a packet from the CAN bus it <em>broadcasts</em> an event source in order to inform the registered threads that a packet has just arrived.</li>
<li><b>Broadcast</b>, the operation performed on an event source in order to inform the <em>registered</em> threads that an event just occurred. Broadcasting can happened both in interrupt handlers and in threads.</li>
<li><b>Event Listener</b>, a system object that associates a <code><aclass="el"href="struct_thread.html"title="Structure representing a thread.">Thread</a></code> object to an event source. The process of associating a <code><aclass="el"href="struct_thread.html"title="Structure representing a thread.">Thread</a></code> to an <code><aclass="el"href="struct_event_source.html"title="Event Source structure.">EventSource</a></code> using an <code><aclass="el"href="struct_event_listener.html"title="Event Listener structure.">EventListener</a></code> is called <em>registration</em>.</li>
<li><b>Registration</b>, action performed by a thread in order to be informed of events from a specific event source. Of course a thread can be <em>registered</em> on more than one event source by using multiple <code><aclass="el"href="struct_event_listener.html"title="Event Listener structure.">EventListener</a></code> objects. Threads can also <em>unregister</em> from an event source.</li>
<li><b>Pend</b>, each thread has a mask of <em>pending</em> events. The <em>broadcast</em> operation <em>pends</em> an event mask on all the <em>registered</em> threads.</li>
<li><b>Wait</b>, synchronous operation performed by a thread in order to <em>wait</em> a specific combination of events. The API offers a variety of <em>wait</em> functions, please refer to the events API documentation.</li>
</ul>
<p>Note that events are asynchronously generated, as example in an interrupt handler, but are synchronously served.</p>
<h2>Events related data structures</h2>
<p>The following diagram explains the relationship between an event source, its list of event listeners and the <em>registered</em> threads. </p>
<p> Note that each event listener has a different bit mask to be <em>pended</em> on its associated thread when the event source is <em>broadcasted</em>, this means that each thread can define its own event identifiers independently. A <em>broadcast</em> operation can also <em>pend</em> more than one bit on the <em>registered</em> threads.<br/>
The threads have a variety of <em>wait</em> primitives, they can <em>wait</em> for one or more event flags to become <em>pending</em>, and can also specify AND/OR conditions, as example a thread can <em>wait</em> for any event to become <em>pending</em> or <em>wait</em> for all the specified events to become <em>pending</em>.<br/>
The field <code>p_epending</code> is the mask of the currently pending events, the field <code>p_ewmask</code> is the mask of the events the thread is interested on in that moment (AND or OR condition depending on the invoked <em>wait</em> API).</p>
<h2>Use Scenarios</h2>
<p>Events are best used when one of more of the following conditions are required:</p>
<ul>
<li>Having to wait on multiple conditions, Events are the only mechanism that easily allow that.</li>
<li>Synchronous response to one or more asynchronous events.</li>
<li>Single threaded applications working in a event driver environment (but events are not limited to single threaded applications).</li>
Generated on Sun Nov 28 2010 14:09:55 for ChibiOS/RT by <ahref="http://www.doxygen.org/index.html"><imgsrc="doxygen.png"alt="doxygen"align="middle"border="0"></a> 1.7.1</small></address>