From c7b1157dc9f3ae577d592ab3207a84e64140eabe Mon Sep 17 00:00:00 2001 From: gdisirio Date: Sun, 30 Aug 2009 07:17:22 +0000 Subject: [PATCH] git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1134 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/Doxyfile | 1 + docs/src/main.dox | 38 ----- os/kernel/kernel.dox | 320 +++++++++++++++++++++++++++++++++++++++++ os/ports/ports.dox | 25 ++++ os/various/ch.cpp | 2 +- os/various/ch.hpp | 2 +- os/various/various.dox | 49 +++++++ 7 files changed, 397 insertions(+), 40 deletions(-) create mode 100644 os/kernel/kernel.dox create mode 100644 os/ports/ports.dox create mode 100644 os/various/various.dox diff --git a/docs/Doxyfile b/docs/Doxyfile index 800c83ca1..f9019353a 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -578,6 +578,7 @@ INPUT = ../docs/src \ ../os/kernel/include \ ../os/kernel/src \ ../os/kernel/templates \ + ../os/ports \ ../os/ports/GCC/ARM7 \ ../os/ports/GCC/ARM7/crt0.s \ ../os/ports/GCC/ARM7/chcoreasm.s \ diff --git a/docs/src/main.dox b/docs/src/main.dox index 58e1b4e6a..59cb75e2c 100644 --- a/docs/src/main.dox +++ b/docs/src/main.dox @@ -94,12 +94,6 @@ * . */ -/** - * @defgroup Ports Ports - * This section describes the technical details for the various supported - * ChibiOS/RT ports. - */ - /** * @defgroup IO I/O Support * @brief I/O related services. @@ -217,35 +211,3 @@ * * @ingroup SERIAL */ - -/** - * @defgroup utilities_library Utilities Library - * @brief Utilities Library. - * @details This is a collection of useful library code that is not part of - * the base kernel services. - *

Notes

- * The library code does not follow the same naming convention of the - * system APIs in order to make very clear that it is not "core" code.
- * The main difference is that library code is not formally tested in the - * test suite but through usage in the various demo applications. - */ - -/** - * @defgroup CPlusPlusLibrary C++ Wrapper - * @brief C++ wrapper module. - * @details This module allows to use the ChibiOS/RT functionalities - * from C++ as classes and objects rather the traditional "C" APIs. - * - * @ingroup utilities_library - */ - -/** - * @defgroup event_timer Periodic Events Timer - * @brief Periodic Event Timer. - * @details This timer generates an event at regular intervals. The - * listening threads can use the event to perform time related activities. - * Multiple threads can listen to the same timer. - * - * @ingroup utilities_library - */ - 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 diff --git a/os/ports/ports.dox b/os/ports/ports.dox new file mode 100644 index 000000000..5fd3caa95 --- /dev/null +++ b/os/ports/ports.dox @@ -0,0 +1,25 @@ +/* + 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 ports Ports + * This section describes the technical details of the various supported + * ChibiOS/RT ports. + */ + diff --git a/os/various/ch.cpp b/os/various/ch.cpp index 6e338630e..6efb38f7b 100644 --- a/os/various/ch.cpp +++ b/os/various/ch.cpp @@ -19,7 +19,7 @@ /** * @file ch.cpp * @brief C++ wrapper code. - * @addtogroup CPlusPlusLibrary + * @addtogroup cpp_library * @{ */ diff --git a/os/various/ch.hpp b/os/various/ch.hpp index b13e8db6d..f0055a174 100644 --- a/os/various/ch.hpp +++ b/os/various/ch.hpp @@ -20,7 +20,7 @@ /** * @file ch.hpp * @brief C++ wrapper classes and definitions. - * @addtogroup CPlusPlusLibrary + * @addtogroup cpp_library * @{ */ diff --git a/os/various/various.dox b/os/various/various.dox new file mode 100644 index 000000000..63872e2de --- /dev/null +++ b/os/various/various.dox @@ -0,0 +1,49 @@ +/* + 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 utilities_library Utilities Library + * @brief Utilities Library. + * @details This is a collection of useful library code that is not part of + * the base kernel services. + *

Notes

+ * The library code does not follow the same naming convention of the + * system APIs in order to make very clear that it is not "core" code.
+ * The main difference is that library code is not formally tested in the + * test suite but through usage in the various demo applications. + */ + +/** + * @defgroup cpp_library C++ Wrapper + * @brief C++ wrapper module. + * @details This module allows to use the ChibiOS/RT functionalities + * from C++ as classes and objects rather the traditional "C" APIs. + * + * @ingroup utilities_library + */ + +/** + * @defgroup event_timer Periodic Events Timer + * @brief Periodic Event Timer. + * @details This timer generates an event at regular intervals. The + * listening threads can use the event to perform time related activities. + * Multiple threads can listen to the same timer. + * + * @ingroup utilities_library + */