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

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

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.

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

os/kernel/src/chregistry.c

@@ -22,13 +22,21 @@
  * @brief   Threads registry code.
  *
  * @addtogroup registry
- * @details Threads Registry related APIs and services.<br>
+ * @details Threads Registry related APIs and services.
- *          The threads Threads Registry is a double linked list that holds
+ *
- *          all the active threads in the system.<br>
+ *          <h2>Operation mode</h2>
- *          The registry is meant to be mainly a debug feature, as example
+ *          The Threads Registry is a double linked list that holds all the
- *          through the registry a debugger can enumerate the active threads
+ *          active threads in the system.<br>
- *          in any given moment or the shell can print the active threads and
+ *          Operations defined for the registry:
- *          their state.<br>
+ *          - <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

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
+ *          Semaphores are a flexible synchronization primitive, ChibiOS/RT
- *          are defined on semaphores:
+ *          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
+ *          Semaphores can be used as guards for mutual exclusion zones
- *          (note that mutexes are recommended for this kind of use) but also
+ *          (note that mutexes are recommended for this kind of use) but
- *          have other uses, queues guards and counters as example.<br>
+ *          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>

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:
+ * @details Threads related APIs and services.
- *          - Creation.
+ *
- *          - Termination.
+ *          <h2>Operation mode</h2>
- *          - Synchronization.
+ *          A thread is an abstraction of an independent instructions flow.
- *          - Delays.
+ *          In ChibiOS/RT a thread is represented by a "C" function owning
- *          - References.
+ *          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.
  * @{
  */
 

readme.txt

@@ -57,8 +57,8 @@
 *****************************************************************************
 
 *** 1.5.4 ***
-- FIX: Fixed missing memory recovery on reference release in chRegNextThread()
+- FIX: Fixed missing memory recovery on thread reference release in
-  (bug 2971878).
+  chRegNextThread() (bug 2971878).
 - FIX: Fixed wrong thread state macro in STM32/spi_lld.c (bug 2968142).
 - NEW: The port layer now can "capture" the implementation of individual
   scheduler API functions in order to provide architecture-optimized
@@ -71,15 +71,17 @@
 - NEW: Added RIDE7 project files to the STM32 demo under a ./ride7
   subdirectory, this should make things easier for RIDE7 users. The normal
   makefile is still available of course.
-- NEW: New article in the documentation. Fixed an orphaned page (STM8 port).
+- NEW: New article in the documentation.
 - NEW: Documentation improvements, now the description goes on top of each
   page, doxygen defaulted it in the middle, not exactly the best for
-  readability. Improved many descriptions of the various subsystems.
+  readability. Improved many descriptions of the various subsystems. Fixed
+  a misplaced page (STM8 port).
 - OPT: Optimization on the interface between scheduler and port layer, now
   the kernel is even smaller and the context switch performance improved
   quite a bit on all the supported architectures.
 - OPT: Simplified the implementation of chSchYieldS() and made it a macro.
-  The previous implementation was probably overkill and took too much space.
+  The previous implementation was probably overkill and took too much space
+  even if a bit faster.
 - CHANGE: Exiting from a chCondWaitTimeout() because a timeout now does not
   re-acquire the mutex, ownership is lost.
 - CHANGE: The module documentation has been moved from the kernel.dox file