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

17 files changed, 242 insertions, 28 deletions

diff --git a/os/kernel/src/chcond.c b/os/kernel/src/chcond.c
index 33ffe98b1..c450b0c32 100644
--- a/os/kernel/src/chcond.c
+++ b/os/kernel/src/chcond.c
@@ -26,6 +26,15 @@
  * @brief   Condition Variables code.

  *

  * @addtogroup condvars Condition Variables

+ * @details This module implements the Condition Variables mechanism. Condition

+ *          variables are an extensions to the Mutex subsystem and cannot

+ *          work alone.

+ *          <h2>Operation mode</h2>

+ *          The condition variable is a synchronization object meant to be

+ *          used inside a zone protected by a @p Mutex. Mutexes and CondVars

+ *          together can implement a Monitor construct.<br>

+ *          In order to use the Condition Variables APIs the @p CH_USE_CONDVARS

+ *          option must be enabled in @p chconf.h.

  * @{

  */

 

@@ -107,10 +116,11 @@ void chCondBroadcastI(CondVar *cp) {
 

 /**

  * @brief   Waits on the condition variable releasing the mutex lock.

- * @details Releases the mutex, waits on the condition variable, and finally

- *          acquires the mutex again. This is done atomically.

- * @note    The thread MUST already have locked the mutex when calling

- *          @p chCondWait().

+ * @details Releases the currently owned mutex, waits on the condition

+ *          variable, and finally acquires the mutex again. All the sequence

+ *          is performed atomically.

+ * @note    The invoking thread <b>must</b> have at least one owned mutex on

+ *          entry.

  *

  * @param[in] cp        pointer to the @p CondVar structure

  * @return              The wakep mode.

@@ -128,10 +138,11 @@ msg_t chCondWait(CondVar *cp) {
 

 /**

  * @brief   Waits on the condition variable releasing the mutex lock.

- * @details Releases the mutex, waits on the condition variable, and finally

- *          acquires the mutex again. This is done atomically.

- * @note    The thread MUST already have locked the mutex when calling

- *          @p chCondWaitS().

+ * @details Releases the currently owned mutex, waits on the condition

+ *          variable, and finally acquires the mutex again. All the sequence

+ *          is performed atomically.

+ * @note    The invoking thread <b>must</b> have at least one owned mutex on

+ *          entry.

  *

  * @param[in] cp        pointer to the @p CondVar structure

  * @return              The wakep mode.

@@ -160,10 +171,13 @@ msg_t chCondWaitS(CondVar *cp) {
 #if CH_USE_CONDVARS_TIMEOUT

 /**

  * @brief   Waits on the condition variable releasing the mutex lock.

- * @details Releases the mutex, waits on the condition variable, and finally

- *          acquires the mutex again. This is done atomically.

- * @note    The thread MUST already have locked the mutex when calling

- *          @p chCondWaitTimeout().

+ * @details Releases the currently owned mutex, waits on the condition

+ *          variable, and finally acquires the mutex again. All the sequence

+ *          is performed atomically.

+ * @note    The invoking thread <b>must</b> have at least one owned mutex on

+ *          entry.

+ * @note    Exiting the function because a timeout does not re-acquire the

+ *          mutex, the mutex ownership is lost.

  *

  * @param[in] cp        pointer to the @p CondVar structure

  * @param[in] time      the number of ticks before the operation timeouts,

@@ -188,10 +202,13 @@ msg_t chCondWaitTimeout(CondVar *cp, systime_t time) {
 

 /**

  * @brief   Waits on the condition variable releasing the mutex lock.

- * @details Releases the mutex, waits on the condition variable, and finally

- *          acquires the mutex again. This is done atomically.

- * @note    The thread MUST already have locked the mutex when calling

- *          @p chCondWaitTimeoutS().

+ * @details Releases the currently owned mutex, waits on the condition

+ *          variable, and finally acquires the mutex again. All the sequence

+ *          is performed atomically.

+ * @note    The invoking thread <b>must</b> have at least one owned mutex on

+ *          entry.

+ * @note    Exiting the function because a timeout does not re-acquire the

+ *          mutex, the mutex ownership is lost.

  *

  * @param[in] cp        pointer to the @p CondVar structure

  * @param[in] time      the number of ticks before the operation timeouts,

@@ -218,7 +235,8 @@ msg_t chCondWaitTimeoutS(CondVar *cp, systime_t time) {
   currp->p_u.wtobjp = cp;

   prio_insert(currp, &cp->c_queue);

   msg = chSchGoSleepTimeoutS(THD_STATE_WTCOND, time);

-  chMtxLockS(mp);

+  if (msg != RDY_TIMEOUT)

+    chMtxLockS(mp);

   return msg;

 }

 #endif /* CH_USE_CONDVARS_TIMEOUT */

diff --git a/os/kernel/src/chdebug.c b/os/kernel/src/chdebug.c
index 969718082..462f2559e 100644
--- a/os/kernel/src/chdebug.c
+++ b/os/kernel/src/chdebug.c
@@ -22,6 +22,11 @@
  * @brief   ChibiOS/RT Debug code.

  *

  * @addtogroup debug

+ * @details Debug APIs and services:

+ *          - Trace buffer.

+ *          - Parameters check.

+ *          - Kernel assertions.

+ *          .

  * @{

  */

 

diff --git a/os/kernel/src/chevents.c b/os/kernel/src/chevents.c
index 898b2c0bb..6a0ed1755 100644
--- a/os/kernel/src/chevents.c
+++ b/os/kernel/src/chevents.c
@@ -22,6 +22,33 @@
  * @brief   Events code.

  *

  * @addtogroup events

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

+ *          <h2>Operation mode</h2>

+ *          Each thread has a mask of pending event flags inside its @p 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 an events mask.<br>

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

+ *          each thread can be listening on an unlimited number of

+ *          them.<br><br>

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

+ *          enabled in @p chconf.h.

  * @{

  */

 #include "ch.h"

diff --git a/os/kernel/src/chheap.c b/os/kernel/src/chheap.c
index ce8ce385b..ede326b59 100644
--- a/os/kernel/src/chheap.c
+++ b/os/kernel/src/chheap.c
@@ -22,6 +22,18 @@
  * @brief   Heaps code.

  *

  * @addtogroup heaps

+ * @details Heap Allocator related APIs.

+ *          <h2>Operation mode</h2>

+ *          The heap allocator implements a first-fit strategy and its APIs

+ *          are functionally equivalent to the usual @p malloc() and @p free()

+ *          library functions. The main difference is that the OS heap APIs

+ *          are guaranteed to be thread safe.<br>

+ *          By enabling the @p CH_USE_MALLOC_HEAP option the heap manager

+ *          will use the runtime-provided @p malloc() and @p free() as

+ *          backend for the heap APIs instead of the system provided

+ *          allocator.<br>

+ *          In order to use the heap APIs the @p CH_USE_HEAP option must

+ *          be enabled in @p chconf.h.

  * @{

  */

 

diff --git a/os/kernel/src/chlists.c b/os/kernel/src/chlists.c
index f722f94cb..2d973e771 100644
--- a/os/kernel/src/chlists.c
+++ b/os/kernel/src/chlists.c
@@ -20,11 +20,11 @@
 /**

  * @file    chlists.c

  * @brief   Thread queues/lists code.

- * @note    All the functions present in this module, while public, are not

- *          an OS API and should not be directly used in the user applications

- *          code.

  *

  * @addtogroup internals

+ * @details All the functions present in this module, while public, are not

+ *          an OS API and should not be directly used in the user applications

+ *          code.

  * @{

  */

 #include "ch.h"

diff --git a/os/kernel/src/chmboxes.c b/os/kernel/src/chmboxes.c
index 3811fc5da..ce4ecae67 100644
--- a/os/kernel/src/chmboxes.c
+++ b/os/kernel/src/chmboxes.c
@@ -22,6 +22,30 @@
  * @brief   Mailboxes code.

  *

  * @addtogroup mailboxes

+ * @details Asynchronous messages.

+ *          <h2>Operation mode</h2>

+ *          A mailbox is an asynchronous communication mechanism.<br>

+ *          The following operations are possible on a mailbox:

+ *          - <b>Post</b>: Posts a message on the mailbox in FIFO order.

+ *          - <b>Post Ahead</b>: Posts a message on the mailbox with urgent

+ *            priority.

+ *          - <b>Fetch</b>: A message is fetched from the mailbox and removed

+ *            from the queue.

+ *          - <b>Reset</b>: The mailbox is emptied and all the stored messages

+ *            are lost.

+ *          .

+ *          A message is a variable of type msg_t that is guaranteed to have

+ *          the same size of and be compatible with (data) pointers (anyway an

+ *          explicit cast is needed).

+ *          If larger messages need to be exchanged then a pointer to a

+ *          structure can be posted in the mailbox but the posting side has

+ *          no predefined way to know when the message has been processed. A

+ *          possible approach is to allocate memory (from a memory pool as

+ *          example) from the posting side and free it on the fetching side.

+ *          Another approach is to set a "done" flag into the structure pointed

+ *          by the message.<br>

+ *          In order to use the mailboxes APIs the @p CH_USE_MAILBOXES option

+ *          must be enabled in @p chconf.h.

  * @{

  */

 

diff --git a/os/kernel/src/chmemcore.c b/os/kernel/src/chmemcore.c
index 435120a33..d0c657a48 100644
--- a/os/kernel/src/chmemcore.c
+++ b/os/kernel/src/chmemcore.c
@@ -22,6 +22,22 @@
  * @brief   Core memory manager code.

  *

  * @addtogroup memcore

+ * @details Core Memory Manager related APIs and services.

+ *          <h2>Operation mode</h2>

+ *          The core memory manager is a simplified allocator that only allows

+ *          to allocate memory blocks without the possibility to free them.<br>

+ *          This allocator is meant as a memory blocks provider for the other

+ *          allocators such as:

+ *          - C-Runtime allocator (through a compiler specific adapter module).

+ *          - Heap allocator (see @ref heaps).

+ *          - Memory pools allocator (see @ref pools).

+ *          .

+ *          By having a centralized memory provider the various allocators can

+ *          coexist and share the main memory.<br>

+ *          This allocator, alone, is also useful for very simple applications

+ *          that just require a simple way to get memory blocks.<br>

+ *          In order to use the core memory manager APIs the @p CH_USE_MEMCORE

+ *          option must be enabled in @p chconf.h.

  * @{

  */

 

diff --git a/os/kernel/src/chmempools.c b/os/kernel/src/chmempools.c
index f79e20353..31e4682fb 100644
--- a/os/kernel/src/chmempools.c
+++ b/os/kernel/src/chmempools.c
@@ -22,6 +22,13 @@
  * @brief   Memory Pools code.

  *

  * @addtogroup pools

+ * @details Memory Pools related APIs and services.

+ *          <h2>Operation mode</h2>

+ *          The Memory Pools APIs allow to allocate/free fixed size objects in

+ *          <b>constant time</b> and reliably without memory fragmentation

+ *          problems.<br>

+ *          In order to use the memory pools APIs the @p CH_USE_MEMPOOLS option

+ *          must be enabled in @p chconf.h.

  * @{

  */

 

diff --git a/os/kernel/src/chmsg.c b/os/kernel/src/chmsg.c
index 1e89aa0a3..96bf61452 100644
--- a/os/kernel/src/chmsg.c
+++ b/os/kernel/src/chmsg.c
@@ -22,6 +22,22 @@
  * @brief   Messages code.

  *

  * @addtogroup messages

+ * @details Synchronous inter-thread messages APIs and services.

+ *          <h2>Operation Mode</h2>

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

+ *          threads can both act as message servers and/or message clients,

+ *          the mechanism allows data to be carried in both directions. Note

+ *          that messages are not copied between the client and server threads

+ *          but just a pointer passed so the exchange is very time

+ *          efficient.<br>

+ *          Messages are usually processed in FIFO order but it is possible to

+ *          process them in priority order by enabling the

+ *          @p CH_USE_MESSAGES_PRIORITY option in @p chconf.h.<br>

+ *          Applications do not need to allocate buffers for synchronous

+ *          message queues, the mechanism just requires two extra pointers in

+ *          the @p Thread structure (the message queue header).<br>

+ *          In order to use the Messages APIs the @p CH_USE_MESSAGES option

+ *          must be enabled in @p chconf.h.

  * @{

  */

 

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.

  * @{

  */

 

diff --git a/os/kernel/src/chqueues.c b/os/kernel/src/chqueues.c
index 2f8d1b569..acc7494c2 100644
--- a/os/kernel/src/chqueues.c
+++ b/os/kernel/src/chqueues.c
@@ -22,6 +22,23 @@
  * @brief   I/O Queues code.

  *

  * @addtogroup io_queues

+ * @details ChibiOS/RT queues are mostly used in serial-like device drivers.

+ *          The device drivers are usually designed to have a lower side

+ *          (lower driver, it is usually an interrupt service routine) and an

+ *          upper side (upper driver, accessed by the application threads).<br>

+ *          There are several kind of queues:<br>

+ *          - <b>Input queue</b>, unidirectional queue where the writer is the

+ *            lower side and the reader is the upper side.

+ *          - <b>Output queue</b>, unidirectional queue where the writer is the

+ *            upper side and the reader is the lower side.

+ *          - <b>Full duplex queue</b>, bidirectional queue. Full duplex queues

+ *            are implemented by pairing an input queue and an output queue

+ *            together.

+ *          .

+ *          In order to use the I/O queues the @p CH_USE_QUEUES option must

+ *          be enabled in @p chconf.h.<br>

+ *          I/O queues are usually used as an implementation layer for the I/O

+ *          channels interface, also see @ref io_channels.

  * @{

  */

 

diff --git a/os/kernel/src/chregistry.c b/os/kernel/src/chregistry.c
index 8d4ffa4e8..4dca52534 100644
--- a/os/kernel/src/chregistry.c
+++ b/os/kernel/src/chregistry.c
@@ -22,6 +22,9 @@
  * @brief   Threads registry code.

  *

  * @addtogroup registry

+ * @details Threads Registry related APIs and services.<br>

+ *          In order to use the threads registry the @p CH_USE_REGISTRY option

+ *          must be enabled in @p chconf.h.

  * @{

  */

 #include "ch.h"

diff --git a/os/kernel/src/chschd.c b/os/kernel/src/chschd.c
index 023c35d41..9bf34d43a 100644
--- a/os/kernel/src/chschd.c
+++ b/os/kernel/src/chschd.c
@@ -21,8 +21,7 @@
  * @file    chschd.c

  * @brief   Scheduler code.

  *

- * @defgroup scheduler Scheduler

- * @ingroup base

+ * @addtogroup scheduler

  * @details This module provides the default portable scheduler code,

  *          scheduler functions can be individually captured by the port

  *          layer in order to provide architecture optimized equivalents.

diff --git a/os/kernel/src/chsem.c b/os/kernel/src/chsem.c
index 9de6571d8..439412d7c 100644
--- a/os/kernel/src/chsem.c
+++ b/os/kernel/src/chsem.c
@@ -22,6 +22,28 @@
  * @brief   Semaphores code.

  *

  * @addtogroup semaphores

+ * @details Semaphores and threads synchronization.

+ *

+ *          <h2>Operation mode</h2>

+ *          A semaphore is a threads synchronization object, some operations

+ *          are defined on semaphores:

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

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

+ *            becomes negative the thread is queued in the semaphore and

+ *            suspended.

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

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

+ *          .

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

+ *          (note that mutexes are recommended for this kind of use) but also

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

+ *          Semaphores usually use a FIFO queuing strategy but it is possible

+ *          to make them order threads by priority by enabling

+ *          @p CH_USE_SEMAPHORES_PRIORITY in @p chconf.h.<br>

+ *          In order to use the Semaphores APIs the @p CH_USE_SEMAPHORES

+ *          option must be enabled in @p chconf.h.

  * @{

  */

 

diff --git a/os/kernel/src/chsys.c b/os/kernel/src/chsys.c
index 2003f690b..eeed4a998 100644
--- a/os/kernel/src/chsys.c
+++ b/os/kernel/src/chsys.c
@@ -22,6 +22,13 @@
  * @brief   System related code.

  *

  * @addtogroup system

+ * @details System related APIs and services:

+ *          - Initialization.

+ *          - Locks.

+ *          - Interrupt Handling.

+ *          - Power Management.

+ *          - Abnormal Termination.

+ *          .

  * @{

  */

 

diff --git a/os/kernel/src/chthreads.c b/os/kernel/src/chthreads.c
index a2745b94c..3ba5702f5 100644
--- a/os/kernel/src/chthreads.c
+++ b/os/kernel/src/chthreads.c
@@ -21,12 +21,15 @@
  * @file    chthreads.c

  * @brief   Threads code.

  *

- * @defgroup threads Threads

- * @ingroup base

- * @details This module contains all the threads related APIs, creation,

- *          termination, synchronization, delay etc. Dynamic variants of

- *          the base static API are also included.

- *

+ * @addtogroup threads

+ * @details This module contains all the threads related APIs and services:

+ *          - Creation.

+ *          - Termination.

+ *          - Synchronization.

+ *          - Delays.

+ *          - References.

+ *          .

+ *          Dynamic variants of the base static API are also included.

  * @{

  */

 

diff --git a/os/kernel/src/chvt.c b/os/kernel/src/chvt.c
index b48e7f4f4..8be1926ca 100644
--- a/os/kernel/src/chvt.c
+++ b/os/kernel/src/chvt.c
@@ -22,6 +22,7 @@
  * @brief   Time and Virtual Timers related code.

  *

  * @addtogroup time

+ * @details Time and Virtual Timers related APIs and services.

  * @{

  */