Documentation reorganization. Moved the description from kernel.dox into the source code for ease of editing and reference.

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

1 files changed, 37 insertions, 0 deletions

diff --git a/os/kernel/src/chmtx.c b/os/kernel/src/chmtx.c
index 336df8a6e..cc179eb20 100644
--- a/os/kernel/src/chmtx.c
+++ b/os/kernel/src/chmtx.c
@@ -22,6 +22,43 @@
  * @brief   Mutexes code.

  *

  * @addtogroup mutexes

+ * @details Mutexes related APIs and services.

+ *

+ *          <h2>Operation mode</h2>

+ *          A mutex is a threads synchronization object that can be in two

+ *          distinct states:

+ *          - Not owned.

+ *          - Owned by a thread.

+ *          .

+ *          Some operations are defined on mutexes:

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

+ *            some other thread then it is associated to the locking thread

+ *            else the thread is queued on the mutex in a list ordered by

+ *            priority.

+ *          - <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.

+ *          .

+ *          In order to use the Mutexes APIs the @p CH_USE_MUTEXES option must

+ *          be enabled in @p chconf.h.

+ *          <h2>Constraints</h2>

+ *          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 selected from an internal, per-thread, stack

+ *          of owned mutexes. This both improves the performance and is

+ *          required for an efficient implementation of the priority

+ *          inheritance mechanism.

+ *

+ *          <h2>The priority inversion problem</h2>

+ *          The mutexes in ChibiOS/RT implements the <b>full</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.

  * @{

  */