path: root/docs/ch.txt

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