From 1d222307d4b60222ac1f3e619549ecd672a1e710 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Mon, 2 Mar 2009 15:42:19 +0000 Subject: Documentation improvements. git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@807 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/ch.txt | 407 ------------------------------------------------------------ 1 file changed, 407 deletions(-) delete mode 100644 docs/ch.txt (limited to 'docs/ch.txt') 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 . -*/ - -/** - * @mainpage ChibiOS/RT - * @author Giovanni Di Sirio (gdisirio@users.sourceforge.net). - * - *

Chibi ?

- * 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 (ちびOS/RT) @endhtmlonly - * means small Real Time Operating System. - * Source Wikipedia. - * - *

Features

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

Related pages

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

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. - */ -/** @} */ - -/** - * @defgroup MemoryPools 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. - */ -/** @} */ - -/** - * @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.

- */ -/** @} */ - -/** - * @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 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. - */ -/** @} */ - -/** - * @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.

- */ -/** @} */ - -/** - * @defgroup Events Events - * @{ - * Event Sources and Event Listeners. - *

Operation mode

- * 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.
- * An unlimited number of Event Sources can exists in a system and each - * thread can listen on an unlimited number of them.
- * 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().
- * 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. - *

Operation Mode

- * 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.
- * 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. - */ -/** @} */ - -/** - * @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. - */ -/** @} */ - -/** - * @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).
- * 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. - * - Half duplex queue, 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. - * - 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.
- * 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.
- * In order to use the serial full duplex driver the - * @p CH_USE_SERIAL_FULLDUPLEX option must be specified in @p chconf.h.
- * 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. - *

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 - * @{ - * 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 - */ -/** @} */ - -- cgit v1.2.3