diff options
Diffstat (limited to 'docs/src/events.dox')
| -rw-r--r-- | docs/src/events.dox | 124 |
1 files changed, 0 insertions, 124 deletions
diff --git a/docs/src/events.dox b/docs/src/events.dox deleted file mode 100644 index 27de187e4..000000000 --- a/docs/src/events.dox +++ /dev/null @@ -1,124 +0,0 @@ -/*
- 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
- * 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.
- * - <b>Broadcast</b>, 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.
- * - <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 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
- * registered on more than one event source by using multiple
- * @p EventListener objects. Threads can also unregister from an event
- * source.
- * - <b>Pending Events</b>, event flags waiting to be served by a thread.
- * - <b>Add</b>, the broadcast operation adds (logical or) an events
- * mask to all the registered threads.
- * - <b>Wait</b>, 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.
- *
- * <h2>Events related data structures</h2>
- * The following diagram explains the relationship between an event source,
- * its list of event listeners and the 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 added 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 add more than one bit on the
- * registered threads.<br>
- * The threads have a variety of wait primitives, they can wait for one
- * or more event flags, and can also specify AND/OR conditions, as example
- * a thread can wait for any of the specified events or wait for all the
- * specified events.<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
- * 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).
- * .
- */
|