git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@809 35acf78f-673a-0410-8e92-d51de3d6d3f4

1 files changed, 407 insertions, 0 deletions

diff --git a/docs/src/main.dox b/docs/src/main.dox
new file mode 100644
index 000000000..58a96870d
--- /dev/null
+++ b/docs/src/main.dox
@@ -0,0 +1,407 @@
+/*

+    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 <http://www.gnu.org/licenses/>.

+*/

+

+/**

+ * @mainpage ChibiOS/RT

+ * @author Giovanni Di Sirio (gdisirio@users.sourceforge.net).

+ *

+ * <h2>Chibi ?</h2>

+ * I didn't want a serious name for this project. It is the Japanese word for

+ * small as in small child. So ChibiOS/RT

+ * @htmlonly (<span class="t_nihongo_kanji" xml:lang="ja" lang="ja">&#12385;&#12403;</span>OS/RT) @endhtmlonly

+ * means small Real Time Operating System.

+ * Source <a href="http://en.wikipedia.org/wiki/Chibi" target="_blank">Wikipedia</a>.

+ *

+ * <h2>Features</h2>

+ * - Free software, GPL3 licensed. Stable releases include a exception clause

+ *   to the GPL.

+ * - Designed for realtime applications.

+ * - Easily portable.

+ * - Preemptive scheduling.

+ * - 128 priority levels. Multiple threads at the same priority level allowed.

+ * - Round robin scheduling for threads at the same priority level.

+ * - Offers threads, virtual timers, semaphores, mutexes, condvars,

+ *   event flags, messages, I/O queues.

+ * - No static setup at compile time, there is no need to configure a maximum

+ *   number of all the above objects.

+ * - PC simulator target included, the development can be done on the PC

+ *   using MinGW.<br>

+ *   Timers, I/O channels and other HW resources are simulated in a

+ *   Win32 process and the application code does not need to be aware of it.

+ *   MinGW demo available.

+ * - No *need* for a memory allocator, all the kernel structures are static

+ *   and declaratively allocated.

+ * - Optional, thread safe, Heap Allocator subsystem.

+ * - Optional, thread safe, Memory Pools Allocator subsystem.

+ * - Blocking and non blocking I/O channels with timeout and events generation

+ *   capability.

+ * - Minimal system requirements: about 8KiB ROM with all options enabled and

+ *   speed optimizations on. The size can shrink under 2KiB by disabling the

+ *   the unused subsystems and optimizing for size.

+ * - Almost totally written in C with little ASM code required for ports.

+ * .

+ * <h2>Related pages</h2>

+ * - @subpage lic_faq

+ * - @subpage goals

+ * - @subpage concepts

+ * - @subpage articles

+ * .

+ */

+

+/**

+ * @defgroup Ports Ports

+ * @{

+ * This section describes the technical details for the various supported

+ * ChibiOS/RT ports.

+ */

+/** @} */

+

+/**

+ * @defgroup Kernel Kernel

+ * @{

+ */

+/** @} */

+

+/**

+ * @defgroup Config Configuration

+ * @{

+ * In @p chconf.h are defined the required subsystems for your application.

+ * @ingroup Kernel

+ */

+/** @} */

+

+/**

+ * @defgroup Core Generic Port Code Templates

+ * @{

+ * Non portable code templates.

+ * @ingroup Kernel

+ */

+/** @} */

+

+/**

+ * @defgroup Types Types

+ * @{

+ * System types and macros.

+ * @ingroup Kernel

+ */

+/** @} */

+

+/**

+ * @defgroup System System Management

+ * @{

+ * Initialization, Locks, Interrupt Handling, Power Management, Abnormal

+ * Termination.

+ * @ingroup Kernel

+ */

+/** @} */

+

+/**

+ * @defgroup Inline Inline

+ * @{

+ * System inline-able code.

+ * @ingroup Kernel

+ */

+/** @} */

+

+/**

+ * @defgroup Debug Debug

+ * @{

+ * Debug APIs and procedures.

+ * @ingroup Kernel

+ */

+/** @} */

+

+/**

+ * @defgroup Scheduler Scheduler

+ * @{

+ * ChibiOS/RT scheduler.

+ * @ingroup Kernel

+ */

+/** @} */

+

+/**

+ * @defgroup ThreadLists Thread Lists and Queues

+ * @{

+ * ChibiOS/RT thread lists and queues utilities.

+ * @ingroup Kernel

+ */

+/** @} */

+

+/**

+ * @defgroup Threads Threads

+ * @{

+ * Threads creation and termination APIs.

+ */

+/** @} */

+

+/**

+ * @defgroup Time Time and Virtual Timers

+ * @{

+ * Time and Virtual Timers related APIs.

+ */

+/** @} */

+

+/**

+ * @defgroup Heap Heap

+ * @{

+ * Heap Allocator related APIs.

+ * <h2>Operation mode</h2>

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

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

+ * In order to use the heap APIs the @p CH_USE_HEAP option must be specified

+ * in @p chconf.h.

+ */

+/** @} */

+

+/**

+ * @defgroup MemoryPools Memory Pools

+ * @{

+ * Memory Pools related APIs.

+ * <h2>Operation mode</h2>

+ * The Memory Pools APIs allow to allocate/free fixed size objects in

+ * <b>constant time</b> and reliably without memory fragmentation problems.<br>

+ * In order to use the Time APIs the @p CH_USE_MEMPOOLS option must be

+ * specified in @p chconf.h.

+ */

+/** @} */

+

+/**

+ * @defgroup Semaphores Semaphores

+ * @{

+ * Semaphores and threads synchronization.

+ * <h2>Operation mode</h2>

+ * A semaphore is a threads synchronization object, some operations

+ * are defined on semaphores:

+ * - <b>Signal</b>: The semaphore counter is increased and if the result

+ *   is non-positive then a waiting thread is removed from the semaphore

+ *   queue and made ready for execution.

+ * - <b>Wait</b>: The semaphore counter is decreased and if the result

+ *   becomes negative the thread is queued in the semaphore and suspended.

+ * - <b>Reset</b>: The semaphore counter is reset to a non-negative value

+ *   and all the threads in the queue are released.

+ * .

+ * Semaphores can be used as guards for mutual exclusion code zones (note that

+ * mutexes are recommended for this kind of use) but also have other uses,

+ * queues guards and counters as example.<br>

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

+ * In order to use the Semaphores APIs the @p CH_USE_SEMAPHORES

+ * option must be specified in @p chconf.h.<br><br>

+ */

+/** @} */

+

+/**

+ * @defgroup Mutexes Mutexes

+ * @{

+ * Mutexes and threads synchronization.

+ * <h2>Operation mode</h2>

+ * A mutex is a threads synchronization object, some operations are defined

+ * on mutexes:

+ * - <b>Lock</b>: 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.

+ * - <b>Unlock</b>: 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.<br>

+ *

+ * <h2>Constraints</h2>

+ * 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 the priority

+ * inheritance mechanism.

+ *

+ * <h2>The priority inversion problem</h2>

+ * The mutexes in ChibiOS/RT implements the <b>full</b> priority

+ * inheritance mechanism in order handle the priority inversion problem.<br>

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

+ */

+/** @} */

+

+/**

+ * @defgroup CondVars Condition Variables

+ * @{

+ * Condition Variables and threads synchronization.

+ * <h2>Operation mode</h2>

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

+ * In order to use the Condition Variables APIs the @p CH_USE_CONDVARS

+ * option must be specified in @p chconf.h.<br><br>

+ */

+/** @} */

+

+/**

+ * @defgroup Events Events

+ * @{

+ * Event Sources and Event Listeners.

+ * <h2>Operation mode</h2>

+ * An Event Source is a special object that can be signaled by a thread or

+ * an interrupt service routine. Signaling an Event Source has the effect

+ * that all the threads registered on the Event Source will receive

+ * and serve the event.<br>

+ * An unlimited number of Event Sources can exists in a system and each

+ * thread can listen on an unlimited number of them.<br>

+ * Note that the events can be asynchronously generated but are synchronously

+ * served, a thread can serve event by calling a @p chEvtWaitXXX()

+ * API. If an event is generated while a listening thread is not ready to

+ * serve it then the event becomes "pending" and will be served as soon the

+ * thread invokes a @p chEvtWaitXXX().<br>

+ * In order to use the Event APIs the @p CH_USE_EVENTS option must be

+ * specified in @p chconf.h.

+ */

+/** @} */

+

+/**

+ * @defgroup Messages Synchronous Messages

+ * @{

+ * Synchronous inter-thread messages.

+ * <h2>Operation Mode</h2>

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

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

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

+ * In order to use the Messages APIs the @p CH_USE_MESSAGES option must be

+ * specified in @p chconf.h.

+ */

+/** @} */

+

+/**

+ * @defgroup Mailboxes Mailboxes

+ * @{

+ * Asynchronous messages.

+ * <h2>Operation mode</h2>

+ * A mailbox is an asynchronous communication mechanism.<br>

+ * The following operations are possible on a mailbox:

+ * - <b>Post</b>: Posts a message on the mailbox in FIFO order.

+ * - <b>Post Ahead</b>: Posts a message on the mailbox with high priority.

+ * - <b>Fetch</b>: A message is fetched from the mailbox and removed from

+ *   the queue.

+ * - <b>Reset</b>: 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.

+ */

+/** @} */

+

+/**

+ * @defgroup IOQueues I/O Queues

+ * @{

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

+ * There are several kind of queues:<br>

+ * - <b>Input queue</b>, unidirectional queue where the writer is the

+ *   lower side and the reader is the upper side.

+ * - <b>Output queue</b>, unidirectional queue where the writer is the

+ *   upper side and the reader is the lower side.

+ * - <b>Half duplex queue</b>, bidirectional queue where the buffer is shared

+ *   between a receive and a transmit queues. This means that concurrent

+ *   buffered input and output operations are not possible, this is perfectly

+ *   acceptable for a lot of applications however, as example an RS485 driver.

+ * - <b>Full duplex queue</b>, 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.<br>

+ * In order to use the half duplex queues the @p CH_USE_QUEUES_HALFDUPLEX

+ * option must be specified in @p chconf.h.

+ */

+/** @} */

+

+/**

+ * @defgroup Serial Serial Drivers

+ * @{

+ * This module implements a generic full duplex serial driver and a generic

+ * half duplex serial driver. It uses the I/O Queues for communication between

+ * the upper and the lower driver and events to notify the application about

+ * incoming data, outcoming data and other I/O events.

+ * The  module also contains functions that make the implementation of the

+ * interrupt service routines much easier.<br>

+ * In order to use the serial full duplex driver the

+ * @p CH_USE_SERIAL_FULLDUPLEX option must be specified in @p chconf.h.<br>

+ * In order to use the serial half duplex driver the

+ * @p CH_USE_SERIAL_HALFDUPLEX option must be specified in @p chconf.h.

+ */

+/** @} */

+

+/**

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

+ * <h2>Notes</h2>

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

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

+ * @{

+ * C++ wrapper module. 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 Events Generator Timer

+ * @{

+ * @brief Event Generator 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

+ */

+/** @} */

+