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

1 files changed, 51 insertions, 22 deletions

diff --git a/docs/ch.txt b/docs/ch.txt
index 02152047b..993f77102 100644
--- a/docs/ch.txt
+++ b/docs/ch.txt
@@ -13,7 +13,7 @@
  * <li>Easily portable.</li>

  * <li>Mixed programming model:</li>

  *   <ul>

- *   <li>Synchronous, using semaphores and/or messages.</li>

+ *   <li>Synchronous, using semaphores/mutexes and/or messages.</li>

  *   <li>Asynchronous, using event sources.</li>

  *   <li>Mix of the above models, multiple threads listening to multiple event

  *       sources while serving message queues.</li>

@@ -27,6 +27,7 @@
  * <li>Unlimited number of threads.</li>

  * <li>Unlimited number of virtual timers.</li>

  * <li>Unlimited number of semaphores.</li>

+ * <li>Unlimited number of mutexes.</li>

  * <li>Unlimited number of event sources.</li>

  * <li>Unlimited number of messages in queue.</li>

  * <li>Unlimited number of I/O queues.</li>

@@ -211,39 +212,67 @@
  * A semaphore is a threads synchronization object, some operations

  * are defined on semaphores:<br>

  * <ul>

- * <li><b>Signal</b>: The semaphore counter is increased and if the result

+ *   <li><b>Signal</b>: The semaphore counter is increased and if the result

  *     is non-positive then a waiting thread is removed from the semaphore

- *     queue and made ready for execution.</li>

- * <li><b>Wait</b>: The semaphore counter is decreased and if the result

+ *     queue and made ready for execution.

+ *   </li>

+ *   <li><b>Wait</b>: The semaphore counter is decreased and if the result

  *     becomes negative the thread is queued in the semaphore and suspended.

- *     </li>

- * <li><b>Reset</b>: The semaphore counter is reset to a non-negative value

- *     and all the threads in the queue are released.</li>

+ *   </li>

+ *   <li><b>Reset</b>: The semaphore counter is reset to a non-negative value

+ *     and all the threads in the queue are released.

+ *   </li>

  * </ul>

- * Semaphores are mainly used as guards for mutual exclusion code zones but

+ * Semaphores can be used as guards for mutual exclusion code zones but

  * also have other uses, queues guards and counters as example.<br>

  * In order to use the Semaphores APIs the \p CH_USE_SEMAPHORES

  * option must be specified in \p chconf.h.<br><br>

- * <b>Realtime Semaphores</b><br><br>

- * The RT Semaphores work exactly like normal semaphores except that the

- * thread gaining access to a mutex zone receives a priority boost, the

- * priority is increased by \p MEPRIO and becomes higher than any thread that

- * does not have the boost, note that all the boosted threads still keep their

- * relative priorities.<br>

- * Another difference is that the threads are queued by priority when trying

- * to acquire RT semaphores, normal semaphores use a FIFO strategy.<br>

- * The reason of this mechanism is to make the threads leave very critical

- * guarded zones in a predictable time. Use this mechanism if your application

- * has very strong realtime requirements.<br>

- * In order to use the RT Semaphores APIs the \p CH_USE_RT_SEMAPHORES

- * option must be specified in \p chconf.h.<br>

- * This mechanism is <b>experimental</b>.

  * @file semaphores.h Semaphores macros and structures.

  * @file chsem.c Semaphores code.

  */

 /** @} */

 

 /**

+ * @defgroup Mutexes Mutexes

+ * @{

+ * Mutexes and threads synchronization.

+ * <b>Operation mode</b><br><br>

+ * A mutex is a threads synchronization object, some operations are defined

+ * on mutexes:<br>

+ * <ul>

+ *   <li><b>Lock</b>: The mutex is checked, if the mutex is not owned by some

+ *     other thread then it is locked else the current thread is queued on the

+ *     mutex in a list ordered by priority.

+ *   </li>

+ *   <li><b>Unlock</b>: The mutex is released by the owner and the highest

+ *     priority thread waiting in the queue, if any, is resumed and made owner

+ *     of the mutex.

+ *   </li>

+ * </ul>

+ * In order to use the Event APIs the \p CH_USE_MUTEXES option must be

+ * specified in \p chconf.h.<br><br>

+ *

+ * <b>Constraints</b><br><br>

+ * In ChibiOS/RT the Unlock operations are always performed in Lock-reverse

+ * order. The Unlock API does not even have a parameter, the mutex to unlock

+ * is taken from an internal stack of owned mutexes.

+ * This both improves the performance and is required by the priority

+ * inheritance mechanism.

+ *

+ * <b>The priority inversion problem</b><br><br>

+ * The mutexes in ChibiOS/RT implements the <b>full recursive<b> priority

+ * inheritance mechanism in order handle the priority inversion problem.<br>

+ * When a thread is queued on a mutex, any thread, directly or indirectly,

+ * holding the mutex gains the same priority of the waiting thread (if their

+ * priority was not already equal or higher). The mechanism works with any

+ * number of nested mutexes and any number of involved threads. The algorithm

+ * complexity (worst case) is N with N equal to the number of nested mutexes.

+ * @file mutexes.h Mutexes macros and structures.

+ * @file chmtx.c Mutexes functions.

+ */

+/** @} */

+

+/**

  * @defgroup Events Events

  * @{

  * Event Sources and Event Listeners.<br>