From 29d727356b71e0706a7069e41e70e1d5e885f4d3 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Fri, 28 May 2010 13:43:00 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1960 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/src/articles.dox | 1 + docs/src/events.dox | 123 ++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 124 insertions(+) create mode 100644 docs/src/events.dox (limited to 'docs/src') diff --git a/docs/src/articles.dox b/docs/src/articles.dox index 42d1606ae..c34e34d43 100644 --- a/docs/src/articles.dox +++ b/docs/src/articles.dox @@ -40,6 +40,7 @@ * Articles and guides about ChibiOS/RT. * - @subpage article_integrationguide * - @subpage article_portguide + * - @subpage article_events * - @subpage article_debug * - @subpage article_stacks * - @subpage article_roundrobin diff --git a/docs/src/events.dox b/docs/src/events.dox new file mode 100644 index 000000000..22e4afec7 --- /dev/null +++ b/docs/src/events.dox @@ -0,0 +1,123 @@ +/* + 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 @w 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). + * . + */ -- cgit v1.2.3