/*
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 .
*/
/**
* @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.
* 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 @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.
* - Broadcast, 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.
* - Event Listener, 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.
* - Registration, 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.
* - Pend, each thread has a mask of @a pending events. The @a broadcast
* operation @a pends an event mask on all the @a registered threads.
* - Wait, 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.
*
* Events related data structures
* 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.
* 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.
* 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).
*
* 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).
* .
*/
#n91'>91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
|