diff options
author | gdisirio <gdisirio@35acf78f-673a-0410-8e92-d51de3d6d3f4> | 2010-03-16 19:36:21 +0000 |
---|---|---|
committer | gdisirio <gdisirio@35acf78f-673a-0410-8e92-d51de3d6d3f4> | 2010-03-16 19:36:21 +0000 |
commit | ad3d21e81592481539a56e93234f5bf1fa2c0504 (patch) | |
tree | 0e78278235ac7c8324aa3c3a7e7b0193bbd30dc6 /os/kernel/src/chmtx.c | |
parent | 0eed163a696d4b6daab19fd8daf05b980058f5f3 (diff) | |
download | ChibiOS-ad3d21e81592481539a56e93234f5bf1fa2c0504.tar.gz ChibiOS-ad3d21e81592481539a56e93234f5bf1fa2c0504.tar.bz2 ChibiOS-ad3d21e81592481539a56e93234f5bf1fa2c0504.zip |
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
Diffstat (limited to 'os/kernel/src/chmtx.c')
-rw-r--r-- | os/kernel/src/chmtx.c | 37 |
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.
* @{
*/
|