From 7ae3e3227ee895c3ed5ac3358411b07276c7838e Mon Sep 17 00:00:00 2001 From: gdisirio Date: Wed, 17 Mar 2010 16:24:43 +0000 Subject: [PATCH] git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1748 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- os/kernel/src/chevents.c | 2 +- os/kernel/src/chmboxes.c | 2 +- os/kernel/src/chmtx.c | 2 +- os/kernel/src/chregistry.c | 22 +++++++++++++++------- os/kernel/src/chsem.c | 21 +++++++++++++++------ os/kernel/src/chthreads.c | 36 +++++++++++++++++++++++++++++------- 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 @@ *

Operation mode

* Each thread has a mask of pending event flags inside its @p Thread * structure. - * Several operations are defined: + * Operations defined for event flags: * - Wait, the invoking thread goes to sleep until a certain * AND/OR combination of event flags becomes pending. * - Clear, 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. *

Operation mode

* A mailbox is an asynchronous communication mechanism.
- * The following operations are possible on a mailbox: + * Operations defined for mailboxes: * - Post: Posts a message on the mailbox in FIFO order. * - Post Ahead: 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: * - Lock: 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.
- * The threads Threads Registry is a double linked list that holds - * all the active threads in the system.
- * 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.
+ * @details Threads Registry related APIs and services. + * + *

Operation mode

+ * The Threads Registry is a double linked list that holds all the + * active threads in the system.
+ * Operations defined for the registry: + * - First, returns the first, in creation order, active thread + * in the system. + * - Next, 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.
* 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. * *

Operation mode

- * 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.
+ * Operations defined for semaphores: * - Signal: 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 @@ * - Reset: 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.
+ * 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.
* 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.
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. + * + *

Operation mode

+ * 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.
+ * Operations defined for threads: + * - Init, a thread is prepared and put in the suspended + * state. + * - Create, a thread is started on the specified thread + * function. This operation is available in multiple variants, + * both static and dynamic. + * - Exit, 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. + * - Wait, a thread waits for the termination of another + * thread and retrieves its return value. + * - Resume, a thread created in suspended state is started. + * - Sleep, the execution of a thread is suspended for the + * specified amount of time or the specified future absolute time + * is reached. + * - SetPriority, a thread changes its own priority level. + * - Yield, 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