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

6 files changed, 62 insertions, 23 deletions

diff --git a/os/kernel/src/chevents.c b/os/kernel/src/chevents.c
index 6a0ed1755..2bc145cac 100644
--- a/os/kernel/src/chevents.c
+++ b/os/kernel/src/chevents.c
@@ -26,7 +26,7 @@
  *          <h2>Operation mode</h2>

  *          Each thread has a mask of pending event flags inside its @p Thread

  *          structure.

- *          Several operations are defined:

+ *          Operations defined for event flags:

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

diff --git a/os/kernel/src/chmboxes.c b/os/kernel/src/chmboxes.c
index ce4ecae67..717246b88 100644
--- a/os/kernel/src/chmboxes.c
+++ b/os/kernel/src/chmboxes.c
@@ -25,7 +25,7 @@
  * @details Asynchronous messages.

  *          <h2>Operation mode</h2>

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

- *          The following operations are possible on a mailbox:

+ *          Operations defined for mailboxes:

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

diff --git a/os/kernel/src/chmtx.c b/os/kernel/src/chmtx.c
index cc179eb20..c3076163a 100644
--- a/os/kernel/src/chmtx.c
+++ b/os/kernel/src/chmtx.c
@@ -30,7 +30,7 @@
  *          - Not owned.

  *          - Owned by a thread.

  *          .

- *          Some operations are defined on mutexes:

+ *          Operations defined for 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

diff --git a/os/kernel/src/chregistry.c b/os/kernel/src/chregistry.c
index 5ed8ace2e..ad5cd7fc1 100644
--- a/os/kernel/src/chregistry.c
+++ b/os/kernel/src/chregistry.c
@@ -22,13 +22,21 @@
  * @brief   Threads registry code.

  *

  * @addtogroup registry

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

- *          The threads Threads Registry is a double linked list that holds

- *          all the active threads in the system.<br>

- *          The registry is meant to be mainly a debug feature, as example

- *          through the registry a debugger can enumerate the active threads

- *          in any given moment or the shell can print the active threads and

- *          their state.<br>

+ * @details Threads Registry related APIs and services.

+ *

+ *          <h2>Operation mode</h2>

+ *          The Threads Registry is a double linked list that holds all the

+ *          active threads in the system.<br>

+ *          Operations defined for the registry:

+ *          - <b>First</b>, returns the first, in creation order, active thread

+ *            in the system.

+ *          - <b>Next</b>, returns the next, in creation order, active thread

+ *            in the system.

+ *          .

+ *          The registry is meant to be mainly a debug feature, as example,

+ *          using the registry a debugger can enumerate the active threads

+ *          in any given moment or the shell can print the active threads

+ *          and their state.<br>

  *          Another possible use is for centralized threads memory management,

  *          terminating threads can pulse an event source and an event handler

  *          can perform a scansion of the registry in order to recover the

diff --git a/os/kernel/src/chsem.c b/os/kernel/src/chsem.c
index 439412d7c..2a86a14f6 100644
--- a/os/kernel/src/chsem.c
+++ b/os/kernel/src/chsem.c
@@ -22,11 +22,20 @@
  * @brief   Semaphores code.

  *

  * @addtogroup semaphores

- * @details Semaphores and threads synchronization.

+ * @details Semaphores related APIs and services.

  *

  *          <h2>Operation mode</h2>

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

- *          are defined on semaphores:

+ *          Semaphores are a flexible synchronization primitive, ChibiOS/RT

+ *          implements semaphores in their "counting semaphores" variant as

+ *          defined by Edsger Dijkstra plus several enhancements like:

+ *          - Wait operation with timeout.

+ *          - Reset operation.

+ *          - Atomic wait+signal operation.

+ *          - Return message from the wait operation (OK, RESET, TIMEOUT).

+ *          .

+ *          The binary semaphores variant can be easily implemented using

+ *          counting semaphores.<br>

+ *          Operations defined for 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.

@@ -36,9 +45,9 @@
  *          - <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 can be used as guards for mutual exclusion 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>

diff --git a/os/kernel/src/chthreads.c b/os/kernel/src/chthreads.c
index 3ba5702f5..3f2f88899 100644
--- a/os/kernel/src/chthreads.c
+++ b/os/kernel/src/chthreads.c
@@ -22,14 +22,36 @@
  * @brief   Threads code.

  *

  * @addtogroup threads

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

- *          - Creation.

- *          - Termination.

- *          - Synchronization.

- *          - Delays.

- *          - References.

+ * @details Threads related APIs and services.

+ *

+ *          <h2>Operation mode</h2>

+ *          A thread is an abstraction of an independent instructions flow.

+ *          In ChibiOS/RT a thread is represented by a "C" function owning

+ *          a processor context, state informations and a dedicated stack

+ *          area. In this scenario static variables are shared among all

+ *          threads while automatic variables are local to the thread.<br>

+ *          Operations defined for threads:

+ *          - <b>Init</b>, a thread is prepared and put in the suspended

+ *            state.

+ *          - <b>Create</b>, a thread is started on the specified thread

+ *            function. This operation is available in multiple variants,

+ *            both static and dynamic.

+ *          - <b>Exit</b>, a thread terminates by returning from its top

+ *            level function or invoking a specific API, the thread can

+ *            return a value that can be retrieved by other threads.

+ *          - <b>Wait</b>, a thread waits for the termination of another

+ *            thread and retrieves its return value.

+ *          - <b>Resume</b>, a thread created in suspended state is started.

+ *          - <b>Sleep</b>, the execution of a thread is suspended for the

+ *            specified amount of time or the specified future absolute time

+ *            is reached.

+ *          - <b>SetPriority</b>, a thread changes its own priority level.

+ *          - <b>Yield</b>, a thread voluntarily renounces to its time slot.

  *          .

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

+ *          The threads subsystem is implicitly included in kernel however

+ *          some of its part may be excluded by disabling them in @p chconf.h,

+ *          see the @p CH_USE_WAITEXIT and @p CH_USE_DYNAMIC configuration

+ *          options.

  * @{

  */