Documentation improvements.

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

1 files changed, 0 insertions, 407 deletions

diff --git a/docs/ch.txt b/docs/ch.txt
deleted file mode 100644
index 58a96870d..000000000
--- a/docs/ch.txt
+++ /dev/null
@@ -1,407 +0,0 @@
-/*

-    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

- */

-/** @} */

-