git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1960 35acf78f-673a-0410-8e92-d51de3d6d3f4

2 files changed, 124 insertions, 0 deletions

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 <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 @w 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).

+ * .

+ */