diff options
| -rw-r--r-- | os/kernel/src/chevents.c | 2 | ||||
| -rw-r--r-- | os/kernel/src/chmboxes.c | 2 | ||||
| -rw-r--r-- | os/kernel/src/chmtx.c | 2 | ||||
| -rw-r--r-- | os/kernel/src/chregistry.c | 22 | ||||
| -rw-r--r-- | os/kernel/src/chsem.c | 21 | ||||
| -rw-r--r-- | os/kernel/src/chthreads.c | 36 | ||||
| -rw-r--r-- | readme.txt | 12 |
7 files changed, 69 insertions, 28 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.
* @{
*/
diff --git a/readme.txt b/readme.txt index bb47971e9..5026e1ac5 100644 --- a/readme.txt +++ b/readme.txt @@ -57,8 +57,8 @@ *****************************************************************************
*** 1.5.4 ***
-- FIX: Fixed missing memory recovery on reference release in chRegNextThread()
- (bug 2971878).
+- FIX: Fixed missing memory recovery on thread reference release in
+ 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
|