From ad3d21e81592481539a56e93234f5bf1fa2c0504 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Tue, 16 Mar 2010 19:36:21 +0000 Subject: 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 --- os/kernel/include/ch.h | 1 + os/kernel/include/chioch.h | 8 ++ os/kernel/include/chstreams.h | 8 ++ os/kernel/kernel.dox | 219 ++++-------------------------------------- os/kernel/src/chcond.c | 52 ++++++---- os/kernel/src/chdebug.c | 5 + os/kernel/src/chevents.c | 27 ++++++ os/kernel/src/chheap.c | 12 +++ os/kernel/src/chlists.c | 6 +- os/kernel/src/chmboxes.c | 24 +++++ os/kernel/src/chmemcore.c | 16 +++ os/kernel/src/chmempools.c | 7 ++ os/kernel/src/chmsg.c | 16 +++ os/kernel/src/chmtx.c | 37 +++++++ os/kernel/src/chqueues.c | 17 ++++ os/kernel/src/chregistry.c | 3 + os/kernel/src/chschd.c | 3 +- os/kernel/src/chsem.c | 22 +++++ os/kernel/src/chsys.c | 7 ++ os/kernel/src/chthreads.c | 15 +-- os/kernel/src/chvt.c | 1 + os/kernel/templates/chconf.h | 1 + os/kernel/templates/chcore.c | 1 + os/kernel/templates/chtypes.h | 1 + 24 files changed, 279 insertions(+), 230 deletions(-) (limited to 'os/kernel') diff --git a/os/kernel/include/ch.h b/os/kernel/include/ch.h index 31845855d..800fc2699 100644 --- a/os/kernel/include/ch.h +++ b/os/kernel/include/ch.h @@ -24,6 +24,7 @@ * only kernel header you usually want to include in your application. * * @addtogroup kernel_info + * @details Kernel related info. * @{ */ diff --git a/os/kernel/include/chioch.h b/os/kernel/include/chioch.h index c63dadc0e..f8a1f4f98 100644 --- a/os/kernel/include/chioch.h +++ b/os/kernel/include/chioch.h @@ -24,6 +24,14 @@ * I/O resources in a standardized way. * * @addtogroup io_channels + * @details This module defines an abstract interface for I/O channels by + * extending the @p BaseSequentialStream interface. Note that no code + * is present, I/O channels are just abstract interface like + * structures, you should look at the systems as to a set of abstract + * C++ classes (even if written in C). Specific device drivers can + * use/extend the interface and implement them.
+ * This system has the advantage to make the access to channels + * independent from the implementation logic. * @{ */ diff --git a/os/kernel/include/chstreams.h b/os/kernel/include/chstreams.h index 7b55ca539..4681ac331 100644 --- a/os/kernel/include/chstreams.h +++ b/os/kernel/include/chstreams.h @@ -24,6 +24,14 @@ * data streams in a standardized way. * * @addtogroup data_streams + * @details This module define an abstract interface for generic data streams. + * Note that no code is present, streams are just abstract interfaces + * like structures, you should look at the systems as to a set of + * abstract C++ classes (even if written in C). This system has the + * advantage to make the access to streams independent from the + * implementation logic.
+ * The stream interface can be used as base class for high level + * object types such as files, sockets, serial ports, pipes etc. * @{ */ diff --git a/os/kernel/kernel.dox b/os/kernel/kernel.dox index b55d53d49..0cbcd17af 100644 --- a/os/kernel/kernel.dox +++ b/os/kernel/kernel.dox @@ -19,332 +19,147 @@ /** * @defgroup kernel Kernel - * The kernel is the portable part of ChibiOS/RT, this section documents the - * various kernel subsystems. + * @details The kernel is the portable part of ChibiOS/RT, this section + * documents the various kernel subsystems. */ /** * @defgroup kernel_info Version Numbers and Identification - * Kernel related info. * @ingroup kernel */ /** * @defgroup config Configuration - * Kernel related settings and hooks. * @ingroup kernel */ /** * @defgroup types Types - * System types and macros. * @ingroup kernel */ /** * @defgroup base Base Kernel Services - * Base kernel services, the base subsystems are always included in the - * OS builds. + * @details Base kernel services, the base subsystems are always included in + * the OS builds. * @ingroup kernel */ /** * @defgroup system System Management - * Initialization, Locks, Interrupt Handling, Power Management, Abnormal - * Termination. + * @ingroup base + */ + +/** + * @defgroup scheduler Scheduler + * @ingroup base + */ + +/** + * @defgroup threads Threads * @ingroup base */ /** * @defgroup time Time and Virtual Timers - * Time and Virtual Timers related APIs. * @ingroup base */ /** * @defgroup synchronization Synchronization - * Synchronization services. + * @details Synchronization services. * @ingroup kernel */ /** * @defgroup semaphores Semaphores - * Semaphores and threads synchronization. - *

Operation mode

- * A semaphore is a threads synchronization object, some operations - * are defined on 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. - * - Wait: The semaphore counter is decreased and if the result - * becomes negative the thread is queued in the semaphore and suspended. - * - 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 usually use FIFO queues but it is possible to make them - * order threads by priority by specifying @p CH_USE_SEMAPHORES_PRIORITY in - * @p chconf.h.
- * In order to use the Semaphores APIs the @p CH_USE_SEMAPHORES - * option must be specified in @p chconf.h.

* @ingroup synchronization */ /** * @defgroup mutexes Mutexes - * Mutexes and threads synchronization. - *

Operation mode

- * A mutex is a threads synchronization object, some operations are defined - * on mutexes: - * - Lock: The mutex is checked, if the mutex is not owned by some - * other thread then it is locked else the current thread is queued on the - * mutex in a list ordered by priority. - * - Unlock: 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 Event APIs the @p CH_USE_MUTEXES option must be - * specified in @p chconf.h.
- * - *

Constraints

- * 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 taken from an internal stack of owned mutexes. - * This both improves the performance and is required by an efficient - * implementation of the priority inheritance mechanism. - * - *

The priority inversion problem

- * The mutexes in ChibiOS/RT implements the full priority - * inheritance mechanism in order handle the priority inversion problem.
- * 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. * @ingroup synchronization */ /** * @defgroup condvars Condition Variables - * Condition Variables and threads synchronization. - *

Operation mode

- * 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.
- * In order to use the Condition Variables APIs the @p CH_USE_CONDVARS - * option must be specified in @p chconf.h.

* @ingroup synchronization */ /** * @defgroup events Event Flags - * @brief Event Flags, Event Sources and Event Listeners. - *

Operation mode

- * Each thread has a mask of pending event flags inside its Thread structure. - * Several operations are defined: - * - 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 events - * mask, the cleared event flags mask is returned (only the flags that were - actually pending and then cleared). - * - Signal, an event mask is directly ORed to the mask of the signaled - * thread. - * - Broadcast, each thread registered on an Event Source is signaled - * with the event flags specified in its Event Listener. - * - Dispatch, 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 - * and events mask.
- * An unlimited number of Event Sources can exists in a system and each - * thread can listen on an unlimited number of them.

- * In order to use the Event APIs the @p CH_USE_EVENTS option must be - * specified in @p chconf.h. * @ingroup synchronization */ /** * @defgroup messages Synchronous Messages - * Synchronous inter-thread messages. - *

Operation Mode

- * Synchronous messages are an easy to use and fast IPC mechanism, threads - * can both serve messages and send messages to other threads, the mechanism - * allows data to be carried in both directions. Data is not copied between - * the client and server threads but just a pointer passed so the exchange - * is very time efficient.
- * Messages are usually processed in FIFO order but it is possible to process - * them in priority order by specifying CH_USE_MESSAGES_PRIORITY - * in @p chconf.h.
- * Threads do not need to allocate space for message queues, the mechanism - * just requires two extra pointers in the @p Thread structure (the message - * queue header).
- * In order to use the Messages APIs the @p CH_USE_MESSAGES option must be - * specified in @p chconf.h. * @ingroup synchronization */ /** * @defgroup mailboxes Mailboxes - * Asynchronous messages. - *

Operation mode

- * A mailbox is an asynchronous communication mechanism.
- * The following operations are possible on a mailbox: - * - Post: Posts a message on the mailbox in FIFO order. - * - Post Ahead: Posts a message on the mailbox with high priority. - * - Fetch: A message is fetched from the mailbox and removed from - * the queue. - * - Reset: The mailbox is emptied and all the stored messages lost. - * . - * A message is a variable of type msg_t that is guaranteed to have the - * same size of and be compatible with pointers (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. * @ingroup synchronization */ /** * @defgroup memory Memory Management - * Memory Management services. + * @details Memory Management services. * @ingroup kernel */ /** * @defgroup memcore Core Memory Manager - * Core Memory Manager related APIs. - *

Operation mode

- * The core memory manager is a simplified allocator that only allows to - * allocate memory blocks without the possibility to free them.
- * This allocator is meant as a memory blocks provider for the other - * allocators such as: - * - C-Runtime allocator. - * - 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.
- * This allocator, alone, is also useful for very simple applications that - * just require a simple way to get memory blocks.
- * In order to use the core memory manager APIs the @p CH_USE_MEMCORE option - * must be specified in @p chconf.h. * @ingroup memory */ /** * @defgroup heaps Heaps - * Heap Allocator related APIs. - *

Operation mode

- * The heap allocator implements a first-fit strategy and its APIs are - * functionally equivalent to the usual @p malloc() and @p free(). The main - * difference is that the heap APIs are thread safe.
- * 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.
- * In order to use the heap APIs the @p CH_USE_HEAP option must be specified - * in @p chconf.h. * @ingroup memory */ /** * @defgroup pools Memory Pools - * Memory Pools related APIs. - *

Operation mode

- * The Memory Pools APIs allow to allocate/free fixed size objects in - * constant time and reliably without memory fragmentation problems.
- * In order to use the Time APIs the @p CH_USE_MEMPOOLS option must be - * specified in @p chconf.h. * @ingroup memory */ /** * @defgroup io_support I/O Support - * I/O related services. + * @details I/O related services. * @ingroup kernel */ /** * @defgroup data_streams Data Streams - * @brief Abstract Data Streams. - * @details This module define an abstract interface for generic data streams. - * Note that no code is present, streams are just abstract classes-like - * structures, you should look at the systems as to a set of abstract C++ - * classes (even if written in C). This system has the advantage to make the - * access to streams independent from the implementation logic.
- * The stream interface can be used as base class for high level object types - * such as files, sockets, serial ports, pipes etc. - * * @ingroup io_support */ /** * @defgroup io_channels I/O Channels - * @brief Abstract I/O Channels. - * @details This module defines an abstract interface for I/O channels by - * extending the @p BaseSequentialStream interface. Note that no code is - * present, I/O channels are just abstract classes-like structures, - * you should look at the systems as to a set of abstract C++ classes - * (even if written in C). Specific device drivers can use/extend the - * interface and implement them.
- * This system has the advantage to make the access to channels - * independent from the implementation logic. - * * @ingroup io_support */ /** * @defgroup io_queues I/O Queues - * @brief I/O queues. - * @details ChibiOS/RT supports several kinds of queues. The 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).
- * There are several kind of queues:
- * - Input queue, unidirectional queue where the writer is the - * lower side and the reader is the upper side. - * - Output queue, unidirectional queue where the writer is the - * upper side and the reader is the lower side. - * - Full duplex queue, bidirectional queue where read and write - * operations can happen at the same time. 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 specified in @p chconf.h.
- * I/O queues are usually used as an implementation layer for the I/O channels - * interface. - * * @ingroup io_support */ /** * @defgroup registry Registry - * Threads Registry related APIs. * @ingroup kernel */ /** * @defgroup debug Debug - * Debug APIs and procedures. * @ingroup kernel */ /** * @defgroup core Port Templates - * Non portable code templates. * @ingroup kernel */ /** * @defgroup internals Internals - * Internal details, not APIs. * @ingroup kernel */ 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. + *

Operation mode

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

Operation mode

+ * Each thread has a mask of pending event flags inside its @p Thread + * structure. + * Several operations are defined: + * - 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 + * events mask, the cleared event flags mask is returned (only the + * flags that were actually pending and then cleared). + * - Signal, an event mask is directly ORed to the mask of the + * signaled thread. + * - Broadcast, each thread registered on an Event Source is + * signaled with the event flags specified in its Event Listener. + * - Dispatch, 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.
+ * An unlimited number of Event Sources can exists in a system and + * each thread can be listening on an unlimited number of + * them.

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

Operation mode

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

Operation mode

+ * A mailbox is an asynchronous communication mechanism.
+ * The following operations are possible on a mailbox: + * - Post: Posts a message on the mailbox in FIFO order. + * - Post Ahead: Posts a message on the mailbox with urgent + * priority. + * - Fetch: A message is fetched from the mailbox and removed + * from the queue. + * - Reset: 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.
+ * 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. + *

Operation mode

+ * The core memory manager is a simplified allocator that only allows + * to allocate memory blocks without the possibility to free them.
+ * 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.
+ * This allocator, alone, is also useful for very simple applications + * that just require a simple way to get memory blocks.
+ * 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. + *

Operation mode

+ * The Memory Pools APIs allow to allocate/free fixed size objects in + * constant time and reliably without memory fragmentation + * problems.
+ * 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. + *

Operation Mode

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

Operation mode

+ * 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: + * - 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 + * priority. + * - Unlock: 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. + *

Constraints

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

The priority inversion problem

+ * The mutexes in ChibiOS/RT implements the full priority + * inheritance mechanism in order handle the priority inversion + * problem.
+ * 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).
+ * There are several kind of queues:
+ * - Input queue, unidirectional queue where the writer is the + * lower side and the reader is the upper side. + * - Output queue, unidirectional queue where the writer is the + * upper side and the reader is the lower side. + * - Full duplex queue, 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.
+ * 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.
+ * 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. + * + *

Operation mode

+ * A semaphore is a threads synchronization object, some operations + * are defined on 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. + * - Wait: The semaphore counter is decreased and if the result + * becomes negative the thread is queued in the semaphore and + * suspended. + * - 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 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.
+ * 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. * @{ */ diff --git a/os/kernel/templates/chconf.h b/os/kernel/templates/chconf.h index 02d38baf4..046d28300 100644 --- a/os/kernel/templates/chconf.h +++ b/os/kernel/templates/chconf.h @@ -24,6 +24,7 @@ * contains the application specific kernel settings. * * @addtogroup config + * @details Kernel related settings and hooks. * @{ */ diff --git a/os/kernel/templates/chcore.c b/os/kernel/templates/chcore.c index 0d4f8c3a1..d7956171c 100644 --- a/os/kernel/templates/chcore.c +++ b/os/kernel/templates/chcore.c @@ -26,6 +26,7 @@ * advantage in doing so, as example because performance concerns. * * @addtogroup core + * @details Non portable code templates. * @{ */ diff --git a/os/kernel/templates/chtypes.h b/os/kernel/templates/chtypes.h index 5c771e999..e54c55100 100644 --- a/os/kernel/templates/chtypes.h +++ b/os/kernel/templates/chtypes.h @@ -26,6 +26,7 @@ * doing so. * * @addtogroup types + * @details System types and macros. * @{ */ -- cgit v1.2.3