124 lines
5.9 KiB
Plaintext
124 lines
5.9 KiB
Plaintext
/*
|
|
ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio.
|
|
|
|
This file is part of ChibiOS/RT.
|
|
|
|
ChibiOS/RT is free software; you can redistribute it and/or modify
|
|
it under the terms of the GNU General Public License as published by
|
|
the Free Software Foundation; either version 3 of the License, or
|
|
(at your option) any later version.
|
|
|
|
ChibiOS/RT is distributed in the hope that it will be useful,
|
|
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
GNU General Public License for more details.
|
|
|
|
You should have received a copy of the GNU General Public License
|
|
along with this program. If not, see <http://www.gnu.org/licenses/>.
|
|
*/
|
|
|
|
/**
|
|
* @page article_events 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.<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:
|
|
* - <b>Event Source</b>, an @p EventSource is a system object that can be
|
|
* @a broadcasted asynchronously in response of a system event, as example,
|
|
* when the CAN driver receives a packet from the CAN bus it @a broadcasts
|
|
* an event source in order to inform the registered threads that a packet
|
|
* has just arrived.
|
|
* - <b>Broadcast</b>, the operation performed on an event source in order
|
|
* to inform the @a registered threads that an event just occurred.
|
|
* Broadcasting can happened both in interrupt handlers and in threads.
|
|
* - <b>Event Listener</b>, a system object that associates a @p Thread object
|
|
* to an event source. The process of associating a @p Thread to an
|
|
* @p EventSource using an @p EventListener is called @a registration.
|
|
* - <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
|
|
* @a registered on more than one event source by using multiple
|
|
* @p EventListener objects. Threads can also @a unregister from an event
|
|
* source.
|
|
* - <b>Pend</b>, each thread has a mask of @a pending events. The @a broadcast
|
|
* operation @a pends an event mask on all the @a registered threads.
|
|
* - <b>Wait</b>, synchronous operation performed by a thread in order to
|
|
* @a wait a specific combination of events. The API offers a variety of
|
|
* @a 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.
|
|
*
|
|
* <h2>Events related data structures</h2>
|
|
* The following diagram explains the relationship between an event source,
|
|
* its list of event listeners and the @a registered threads.
|
|
* @dot
|
|
digraph example {
|
|
rankdir="LR";
|
|
|
|
node [shape=rectangle, fontname=Helvetica, fontsize=8,
|
|
fixedsize="true", width="1.0", height="0.5"];
|
|
edge [fontname=Helvetica, fontsize=8, sep=3.0];
|
|
|
|
es [shape=record, label="EventSource | es_next", style="bold"];
|
|
|
|
subgraph cluster_0 {
|
|
fontname=Helvetica;
|
|
label = "Listeners List";
|
|
color = blue;
|
|
node [shape=record, fontname=Helvetica, fontsize=8,
|
|
fixedsize="true", width="1.5", height="1.0"];
|
|
el4 [label="EventListener 4 | el_mask: 0x0001 | el_listener | el_next"];
|
|
el3 [label="EventListener 3 | el_mask: 0x0C00 | el_listener | el_next"];
|
|
el2 [label="EventListener 2 | el_mask: 0x0001 | el_listener | el_next"];
|
|
el1 [label="EventListener 1 | el_mask: 0x0004 | el_listener | el_next"];
|
|
el1 -> el2 -> el3 -> el4 [label=" el_next", constraint=false];
|
|
}
|
|
|
|
subgraph cluster_1 {
|
|
fontname=Helvetica;
|
|
label = "Registered Threads";
|
|
color = blue;
|
|
node [shape=record, fontname=Helvetica, fontsize=8,
|
|
fixedsize="true", width="1.5", height="0.8"];
|
|
t1 [label="Thread 1 | p_epending:0x0000 | p_ewmask:0xFFFF"];
|
|
t2 [label="Thread 2 | p_epending:0x000F | p_ewmask:0x0C01"];
|
|
t3 [label="Thread 3 | p_epending:0x0008 | p_ewmask:0x0001"];
|
|
t4 [label="Thread 4 | p_epending:0x0000 | p_ewmask:0xFFFF"];
|
|
}
|
|
|
|
es -> el1 [label=" es_next"];
|
|
el4 -> es [label=" el_next"];
|
|
el1 -> t1 [label="el_listener"];
|
|
el2 -> t2 [label="el_listener"];
|
|
el3 -> t3 [label="el_listener"];
|
|
el4 -> t4 [label="el_listener"];
|
|
}
|
|
* @enddot
|
|
* Note that each event listener has a different bit mask to be @a pended on
|
|
* its associated thread when the event source is @a broadcasted, this means
|
|
* that each thread can define its own event identifiers independently. A
|
|
* @a broadcast operation can also @a pend more than one bit on the
|
|
* @a registered threads.<br>
|
|
* The threads have a variety of @a wait primitives, they can @a wait for one
|
|
* or more event flags to become @a pending, and can also specify AND/OR
|
|
* conditions, as example a thread can @a wait for any event to become
|
|
* @a pending or @a wait for all the specified events to become @a pending.<br>
|
|
* The field @p p_epending is the mask of the currently pending events,
|
|
* the field @p p_ewmask is the mask of the events the thread is interested
|
|
* on in that moment (AND or OR condition depending on the invoked
|
|
* @a wait API).
|
|
*
|
|
* <h2>Use Scenarios</h2>
|
|
* 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).
|
|
* .
|
|
*/
|