Improved event flags documentation.

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

1 files changed, 23 insertions, 13 deletions

diff --git a/docs/src/main.dox b/docs/src/main.dox
index 0013737df..e1852342e 100644
--- a/docs/src/main.dox
+++ b/docs/src/main.dox
@@ -272,20 +272,30 @@
  */

 

 /**

- * @defgroup Events Events

- * Event Sources and Event Listeners.

+ * @defgroup Events Event Flags

+ * @brief Event Flags, Event Sources and Event Listeners.

  * <h2>Operation mode</h2>

- * An Event Source is a special object that can be signaled by a thread or

- * an interrupt service routine. Signaling an Event Source has the effect

- * that all the threads registered on the Event Source will receive

- * and serve the event.<br>

+ * Each thread has a mask of pending event flags inside its Thread structure.

+ * Several operations are defined:

+ * - <b>Wait</b>, the invoking thread goes to sleep until a certain AND/OR

+ *   combination of event flags becomes pending.

+ * - <b>Clear</b>, a mask of event flags is cleared from the pending events

+ *   mask, the cleared event flags mask is returned (only the flags that were

+     actually pending and then cleared).

+ * - <b>Signal</b>, an event mask is directly ORed to the mask of the signaled

+ *   thread.

+ * - <b>Broadcast</b>, each thread registered on an Event Source is signaled

+ *   with the event flags specified in its Event Listener.

+ * - <b>Dispatch</b>, an events mask is scanned and for each bit set to one

+ *   an associated handler function is invoked. Bit masks are scanned from bit

+ *   zero upward.

+ * .

+ * An Event Source is a special object that can be "broadcasted" by a thread or

+ * an interrupt service routine. Broadcasting an Event Source has the effect

+ * that all the threads registered on the Event Source will be signaled with

+ * and events mask.<br>

  * An unlimited number of Event Sources can exists in a system and each

- * thread can listen on an unlimited number of them.<br>

- * Note that the events can be asynchronously generated but are synchronously

- * served, a thread can serve event by calling a @p chEvtWaitXXX()

- * API. If an event is generated while a listening thread is not ready to

- * serve it then the event becomes "pending" and will be served as soon the

- * thread invokes a @p chEvtWaitXXX().<br>

+ * thread can listen on an unlimited number of them.<br><br>

  * In order to use the Event APIs the @p CH_USE_EVENTS option must be

  * specified in @p chconf.h.

  * @ingroup Synchronization

@@ -295,7 +305,7 @@
  * @defgroup Messages Synchronous Messages

  * Synchronous inter-thread messages.

  * <h2>Operation Mode</h2>

- * Synchronoud messages are an easy to use and fast IPC mechanism, threads

+ * Synchronous messages are an easy to use and fast IPC mechanism, threads

  * can both serve messages and send messages to other threads, the mechanism

  * allows data to be carried in both directions. Data is not copied between

  * the client and server threads but just a pointer passed so the exchange