From c7b1157dc9f3ae577d592ab3207a84e64140eabe Mon Sep 17 00:00:00 2001 From: gdisirio Date: Sun, 30 Aug 2009 07:17:22 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1134 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- os/kernel/kernel.dox | 320 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 320 insertions(+) create mode 100644 os/kernel/kernel.dox (limited to 'os/kernel/kernel.dox') diff --git a/os/kernel/kernel.dox b/os/kernel/kernel.dox new file mode 100644 index 000000000..d2936fa14 --- /dev/null +++ b/os/kernel/kernel.dox @@ -0,0 +1,320 @@ +/* + ChibiOS/RT - Copyright (C) 2006-2007 Giovanni Di Sirio. + + This file is part of ChibiOS/RT. + + ChibiOS/RT is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 3 of the License, or + (at your option) any later version. + + ChibiOS/RT is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see . +*/ + +/** + * @defgroup kernel Kernel + * 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 settings and hooks. + * @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. + * @ingroup kernel + */ + +/** + * @defgroup system System Management + * Initialization, Locks, Interrupt Handling, Power Management, Abnormal + * Termination. + * @ingroup base + */ + +/** + * @defgroup time Time and Virtual Timers + * Time and Virtual Timers related APIs. + * @ingroup base + */ + +/** + * @defgroup scheduler Scheduler + * ChibiOS/RT scheduler APIs and macros. + * @ingroup base + */ + +/** + * @defgroup threads Threads + * Threads related APIs. + * @ingroup base + */ + +/** + * @defgroup synchronization Synchronization + * 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 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. + * @ingroup kernel + */ + +/** + * @defgroup heap Heap + * 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. + * @ingroup kernel + */ + +/** + * @defgroup io_channels I/O Abstract Channels + * @brief Abstract I/O Channels. + * @details This module defines an abstract interface for I/O channels. 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 interfaces and implement them.
+ * This system has the advantage to make the access to channels + * independent from the implementation logic. As example, an I/O channel + * interface can hide the access to a serial driver, to a networking socket + * and so on. + * + * @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.
+ * + * @ingroup io_support + */ + +/** + * @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 + */ + \ No newline at end of file -- cgit v1.2.3 From 34fd822f84d409fa649934251fae01994de7888b Mon Sep 17 00:00:00 2001 From: gdisirio Date: Sat, 17 Oct 2009 09:21:59 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1226 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- os/kernel/kernel.dox | 23 ++++++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) (limited to 'os/kernel/kernel.dox') diff --git a/os/kernel/kernel.dox b/os/kernel/kernel.dox index d2936fa14..bd8870279 100644 --- a/os/kernel/kernel.dox +++ b/os/kernel/kernel.dox @@ -230,7 +230,28 @@ */ /** - * @defgroup heap Heap + * @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). + * - @ref 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 -- cgit v1.2.3 From ca817db850a964f05e730952302fe60a4eb50fdb Mon Sep 17 00:00:00 2001 From: gdisirio Date: Sat, 17 Oct 2009 11:43:41 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1232 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- os/kernel/kernel.dox | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'os/kernel/kernel.dox') diff --git a/os/kernel/kernel.dox b/os/kernel/kernel.dox index bd8870279..720e71977 100644 --- a/os/kernel/kernel.dox +++ b/os/kernel/kernel.dox @@ -239,7 +239,7 @@ * allocators such as: * - C-Runtime allocator. * - Heap allocator (see @ref heaps). - * - @ref Memory pools allocator (see @ref pools). + * - Memory pools allocator (see @ref pools). * . * By having a centralized memory provider the various allocators can coexist * and share the main memory.
-- cgit v1.2.3 From 320a3f140e693a0d8647fd05ec6d2d4cb10c523a Mon Sep 17 00:00:00 2001 From: gdisirio Date: Wed, 30 Dec 2009 13:28:10 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1484 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- os/kernel/kernel.dox | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'os/kernel/kernel.dox') diff --git a/os/kernel/kernel.dox b/os/kernel/kernel.dox index 720e71977..0f544d04e 100644 --- a/os/kernel/kernel.dox +++ b/os/kernel/kernel.dox @@ -25,7 +25,7 @@ /** * @defgroup kernel_info Version Numbers and Identification - * Kernel related settings and hooks. + * Kernel related info. * @ingroup kernel */ @@ -97,7 +97,7 @@ * 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 CH_USE_SEMAPHORES_PRIORITY in + * 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.

-- cgit v1.2.3 From 855fe2391d07c5dab27129ad626541482fe8d782 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Tue, 5 Jan 2010 17:14:09 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1501 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- os/kernel/kernel.dox | 31 +++++++++++++++++++++++-------- 1 file changed, 23 insertions(+), 8 deletions(-) (limited to 'os/kernel/kernel.dox') diff --git a/os/kernel/kernel.dox b/os/kernel/kernel.dox index 0f544d04e..072be41ec 100644 --- a/os/kernel/kernel.dox +++ b/os/kernel/kernel.dox @@ -282,18 +282,31 @@ * @ingroup kernel */ +/** + * @defgroup data_streams Streams + * @brief 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 Abstract Channels * @brief Abstract I/O Channels. - * @details This module defines an abstract interface for I/O channels. 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 interfaces and implement them.
+ * @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. As example, an I/O channel - * interface can hide the access to a serial driver, to a networking socket - * and so on. + * independent from the implementation logic. * * @ingroup io_support */ @@ -317,6 +330,8 @@ * . * 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 */ -- cgit v1.2.3 From 157b6f9695e7f72f2d54b231c19cb4045710ed01 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Sun, 21 Feb 2010 07:24:53 +0000 Subject: Updated license dates. git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1646 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- os/kernel/kernel.dox | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'os/kernel/kernel.dox') diff --git a/os/kernel/kernel.dox b/os/kernel/kernel.dox index 072be41ec..e93ac8c5e 100644 --- a/os/kernel/kernel.dox +++ b/os/kernel/kernel.dox @@ -1,5 +1,5 @@ /* - ChibiOS/RT - Copyright (C) 2006-2007 Giovanni Di Sirio. + ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio. This file is part of ChibiOS/RT. @@ -353,4 +353,4 @@ * Internal details, not APIs. * @ingroup kernel */ - \ No newline at end of file + -- cgit v1.2.3 From 508b7bc93297fcb74af43b11b1435aa96add3c85 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Thu, 25 Feb 2010 16:48:00 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1675 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- os/kernel/kernel.dox | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) (limited to 'os/kernel/kernel.dox') diff --git a/os/kernel/kernel.dox b/os/kernel/kernel.dox index e93ac8c5e..5ca6005f6 100644 --- a/os/kernel/kernel.dox +++ b/os/kernel/kernel.dox @@ -283,8 +283,8 @@ */ /** - * @defgroup data_streams Streams - * @brief Streams. + * @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++ @@ -297,7 +297,7 @@ */ /** - * @defgroup io_channels I/O Abstract Channels + * @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 @@ -336,6 +336,12 @@ * @ingroup io_support */ +/** + * @defgroup registry Registry + * Threads Registry related APIs. + * @ingroup kernel + */ + /** * @defgroup debug Debug * Debug APIs and procedures. -- cgit v1.2.3 From 0eed163a696d4b6daab19fd8daf05b980058f5f3 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Tue, 16 Mar 2010 15:43:23 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1745 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- os/kernel/kernel.dox | 12 ------------ 1 file changed, 12 deletions(-) (limited to 'os/kernel/kernel.dox') diff --git a/os/kernel/kernel.dox b/os/kernel/kernel.dox index 5ca6005f6..b55d53d49 100644 --- a/os/kernel/kernel.dox +++ b/os/kernel/kernel.dox @@ -61,18 +61,6 @@ * @ingroup base */ -/** - * @defgroup scheduler Scheduler - * ChibiOS/RT scheduler APIs and macros. - * @ingroup base - */ - -/** - * @defgroup threads Threads - * Threads related APIs. - * @ingroup base - */ - /** * @defgroup synchronization Synchronization * Synchronization services. -- cgit v1.2.3 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/kernel.dox | 219 ++++----------------------------------------------- 1 file changed, 17 insertions(+), 202 deletions(-) (limited to 'os/kernel/kernel.dox') 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 */ -- cgit v1.2.3 From 62f4b7f471a4b1037468d382f927c5061e5fa9ed Mon Sep 17 00:00:00 2001 From: gdisirio Date: Thu, 24 Jun 2010 14:19:52 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@2036 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- os/kernel/kernel.dox | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) (limited to 'os/kernel/kernel.dox') diff --git a/os/kernel/kernel.dox b/os/kernel/kernel.dox index 0cbcd17af..d4206c882 100644 --- a/os/kernel/kernel.dox +++ b/os/kernel/kernel.dox @@ -72,7 +72,12 @@ */ /** - * @defgroup semaphores Semaphores + * @defgroup semaphores Counting Semaphores + * @ingroup synchronization + */ + +/** + * @defgroup binary_semaphores Binary Semaphores * @ingroup synchronization */ -- cgit v1.2.3 From 0672a430f7581bd6e325ab18e49346beb6b1bb9d Mon Sep 17 00:00:00 2001 From: gdisirio Date: Sat, 18 Sep 2010 10:28:03 +0000 Subject: Files related documentation fixes. git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@2182 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- os/kernel/kernel.dox | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) (limited to 'os/kernel/kernel.dox') diff --git a/os/kernel/kernel.dox b/os/kernel/kernel.dox index d4206c882..3ec1bfd8a 100644 --- a/os/kernel/kernel.dox +++ b/os/kernel/kernel.dox @@ -134,12 +134,17 @@ */ /** - * @defgroup data_streams Data Streams + * @defgroup data_streams Abstract Sequential Streams * @ingroup io_support */ /** - * @defgroup io_channels I/O Channels + * @defgroup data_files Abstract File Streams + * @ingroup io_support + */ + +/** + * @defgroup io_channels Abstract I/O Channels * @ingroup io_support */ -- cgit v1.2.3 From 1b56dd572e01e2460c149ac6835db7bdf175b305 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Sun, 3 Oct 2010 08:45:34 +0000 Subject: Documentation related fixes. git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@2225 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- os/kernel/kernel.dox | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) (limited to 'os/kernel/kernel.dox') diff --git a/os/kernel/kernel.dox b/os/kernel/kernel.dox index 3ec1bfd8a..b946d49e9 100644 --- a/os/kernel/kernel.dox +++ b/os/kernel/kernel.dox @@ -35,6 +35,8 @@ /** * @defgroup types Types + * @details The system types are defined into the port layer, please refer to + * the core port implementation section. * @ingroup kernel */ @@ -163,13 +165,8 @@ * @ingroup kernel */ -/** - * @defgroup core Port Templates - * @ingroup kernel - */ - /** * @defgroup internals Internals * @ingroup kernel */ - + \ No newline at end of file -- cgit v1.2.3 From e13c7933bcc08bf8609c2f6e61eabda5273cdb8a Mon Sep 17 00:00:00 2001 From: gdisirio Date: Sat, 13 Nov 2010 21:38:55 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@2361 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- os/kernel/kernel.dox | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'os/kernel/kernel.dox') diff --git a/os/kernel/kernel.dox b/os/kernel/kernel.dox index b946d49e9..2a9278620 100644 --- a/os/kernel/kernel.dox +++ b/os/kernel/kernel.dox @@ -129,6 +129,11 @@ * @ingroup memory */ +/** + * @defgroup dynamic_threads Dynamic Threads + * @ingroup memory + */ + /** * @defgroup io_support I/O Support * @details I/O related services. -- cgit v1.2.3 From e7e79a6ccb4f3e320b2b8b7bad1b14d65218641d Mon Sep 17 00:00:00 2001 From: gdisirio Date: Fri, 18 Mar 2011 18:38:08 +0000 Subject: License updated. git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@2827 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- os/kernel/kernel.dox | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'os/kernel/kernel.dox') diff --git a/os/kernel/kernel.dox b/os/kernel/kernel.dox index 2a9278620..b1fc4bc29 100644 --- a/os/kernel/kernel.dox +++ b/os/kernel/kernel.dox @@ -1,5 +1,6 @@ /* - ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio. + ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010, + 2011 Giovanni Di Sirio. This file is part of ChibiOS/RT. @@ -174,4 +175,4 @@ * @defgroup internals Internals * @ingroup kernel */ - \ No newline at end of file + -- cgit v1.2.3 From de5dcbba856524599a8f06d3a9bdbf1b01db44c2 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Sat, 21 Jan 2012 14:29:42 +0000 Subject: License text updated with new year. git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@3846 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- os/kernel/kernel.dox | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'os/kernel/kernel.dox') diff --git a/os/kernel/kernel.dox b/os/kernel/kernel.dox index b1fc4bc29..1c0f03f8c 100644 --- a/os/kernel/kernel.dox +++ b/os/kernel/kernel.dox @@ -1,6 +1,6 @@ /* ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010, - 2011 Giovanni Di Sirio. + 2011,2012 Giovanni Di Sirio. This file is part of ChibiOS/RT. -- cgit v1.2.3 From 8f8b7f2c69575736da9004c8dc45c770b0f08c48 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Tue, 8 May 2012 19:02:16 +0000 Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@4177 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- os/kernel/kernel.dox | 23 +++++++++-------------- 1 file changed, 9 insertions(+), 14 deletions(-) (limited to 'os/kernel/kernel.dox') diff --git a/os/kernel/kernel.dox b/os/kernel/kernel.dox index 1c0f03f8c..321194e92 100644 --- a/os/kernel/kernel.dox +++ b/os/kernel/kernel.dox @@ -109,6 +109,11 @@ * @ingroup synchronization */ +/** + * @defgroup io_queues I/O Queues + * @ingroup synchronization + */ + /** * @defgroup memory Memory Management * @details Memory Management services. @@ -136,29 +141,19 @@ */ /** - * @defgroup io_support I/O Support - * @details I/O related services. + * @defgroup streams Streams and Files + * @details Stream and Files interfaces. * @ingroup kernel */ /** * @defgroup data_streams Abstract Sequential Streams - * @ingroup io_support + * @ingroup streams */ /** * @defgroup data_files Abstract File Streams - * @ingroup io_support - */ - -/** - * @defgroup io_channels Abstract I/O Channels - * @ingroup io_support - */ - -/** - * @defgroup io_queues I/O Queues - * @ingroup io_support + * @ingroup streams */ /** -- cgit v1.2.3 From 184a71345c6a36a9a8664eda8fbcc3ea728267a8 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Sat, 2 Feb 2013 10:58:09 +0000 Subject: Updated license years. git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@5102 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- os/kernel/kernel.dox | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'os/kernel/kernel.dox') diff --git a/os/kernel/kernel.dox b/os/kernel/kernel.dox index 321194e92..05753a8f6 100644 --- a/os/kernel/kernel.dox +++ b/os/kernel/kernel.dox @@ -1,6 +1,6 @@ /* ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010, - 2011,2012 Giovanni Di Sirio. + 2011,2012,2013 Giovanni Di Sirio. This file is part of ChibiOS/RT. -- cgit v1.2.3