path: root/docs/ch.txt

/**
 * @mainpage ChibiOS/RT
 * @author Giovanni Di Sirio (gdisirio@users.sourceforge.net).
 * @section Chibi Chibi ?
 * 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>.
 * @section ch_features Features
 * <ul>
 * <li>Free software, GPL3 licensed.</li>
 * <li>Designed for realtime applications.</li>
 * <li>Easily portable.</li>
 * <li>Mixed programming model:</li>
 *   <ul>
 *   <li>Synchronous, using semaphores/mutexes and/or messages.</li>
 *   <li>Asynchronous, using event sources.</li>
 *   <li>Mix of the above models, multiple threads listening to multiple event
 *       sources while serving message queues.</li>
 *   </ul>
 * <li>PC simulator target included, the development can be done on the PC
 *     using MinGW or VS.
 *     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 and VS demos available and ready to go, use them as templates for
 *     your application.</li>
 * <li>Preemptive scheduling.</li>
 * <li>128 priority levels.</li>
 * <li>Multiple threads at the same priorily level allowed.</li>
 * <li>Round robin scheduling for threads at the same priority level.</li>
 * <li>Unlimited number of threads.</li>
 * <li>Unlimited number of virtual timers.</li>
 * <li>Unlimited number of semaphores.</li>
 * <li>Unlimited number of mutexes.</li>
 * <li>Unlimited number of event sources.</li>
 * <li>Unlimited number of messages in queue.</li>
 * <li>Unlimited number of I/O queues.</li>
 * <li>No static setup at compile time, there is no need to configure a maximum
 *     number of all the above resources.</li>
 * <li>No *need* for a memory allocator, all the kernel structures are static
 *     and declaratively allocated.</li>
 * <li>Threads, Semaphores, Event Sources, Virtual Timers creation/deletion at
 *     runtime.</li>
 * <li>Optional, thread safe, Heap Allocator subsystem.</li>
 * <li>Optional, thread safe, Memory Pools Allocator subsystem.</li>
 * <li>Blocking and non blocking I/O channels with timeout and events generation
 *     capability.</li>
 * <li>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.</li>
 * <li>Small memory footprint, unused subsystems can be excluded by the
 *     memory image.</li>
 * <li>Almost totally written in C with little ASM code required for ports.</li>
 * </ul>
 *
 * ChibiOS/RT architecture:<br><br>
 * @subpage Concepts
 */

/**
 * @page Concepts Concepts
 * @{
 * @section naming Naming Conventions
 * ChibiOS/RT APIs are all named following this convention:
 * \a ch\<group\>\<action\>\<suffix\>().
 * The possible groups are: \a Sys, \a Sch, \a VT, \a Thd, \a Sem, \a Mtx,
 * \a Evt, \a Msg, \a IQ, \a OQ, \a HQ,\a FDD, \a HDD, \a Dbg.
 * The suffix is not present for normal APIs but can be one of
 * the following: "I" for APIs meant to be invoked within the system mutex 
 * zone, "S" for APIs only useable from within the system mutex zone but not
 * from interrupt handlers.<br>
 * The APIs without suffix can be invoked only from the user code outsize the
 * system mutex zone and not from interrupt handlers unless differently
 * specified.<br>
 * Examples: \p chThdCreate(), \p chSemSignalI(), \p chIQGetTimeout().
 *
 * @section scheduling Scheduling
 * The strategy is very simple the currently ready thread with the highest
 * priority is executed. If more than one thread with equal priority are
 * eligible for execution then they are executed in a round-robin way, the
 * CPU time slice constant is configurable. The ready list is a double linked
 * list of threads ordered by priority.
 * @image html readylist.png
 * Note that the currently running thread is not in the ready list, the list
 * only contains the threads ready to be executed but still actually waiting.
 *
 * @section states Threads States Diagram
 * The image shows how threads can change their state in ChibiOS/RT.<br>
 * @image html states.png
 *
 * @section warea Thread Working Area
 * Each thread has its own stack, a Thread structure and a registers dump
 * structure. All the structures are allocated into a "Thread working area",
 * a thread private heap, usually allocated in a char array declared in your
 * code, there is not a central threads table or list, this means you can
 * have as many threads you want as long you have enough available RAM
 * memory. The threads do not use any memory outside the allocated working
 * area.<br>
 * @image html workspace.png
 * <br>
 * Note that the registers dump is only present when the Thread is not
 * running, the context switching is done by pushing the registers on the
 * stack of the switched-out thread and popping the registers of the
 * switched-in thread from its stack.
 *
 * @section sysmutex System Mutex Zone
 * It is the code within the OS that cannot be preempted, this code is
 * everything between the \p chSysLock() and \p chSysUnlock() API calls.
 * The implementation of the APIs in most cases just enables/disables the
 * interrupts. Of course the code in the system mutex zone must be as short
 * and efficient possible as it affects the RT performance of the whole
 * system. The worst case response time is affected by the longest code
 * path in the system mutex zone or interrupt handler.
 * @code
 * // User code, not critical, preemption possible.
 * chSysLock();
 * ...
 * // System critical code, preemption delayed.
 * ...
 * chSysUnlock();
 * // User code, preemption possible again.
 * @endcode
 * Applications usually do not need to put code into the system mutex zone
 * unless you are implementing device drivers or special synchronization
 * primitives, everything else can be implemented by using semaphores,
 * mutexes, messages or events.
 */
/** @} */

/**
 * @defgroup Ports Ports
 * @{
 * This section describes the technical details for the various supported
 * ChibiOS/RT ports.
 */
/** @} */

/**
 * @defgroup ARM7 ARM7TDMI
 * @{
 * <p>
 * The ARM7 port makes some assumptions on the application code organization:
 * <ul>
 * <li>The \p main() function is invoked in system mode.</li>
 * <li>Each thread has a private user/system stack, the system has a single
 *     interrupt stack where all the interrupts are processed.</li>
 * <li>The threads are started in system mode.</li>
 * <li>The threads code can run in system mode or user mode, however the
 *     code running in user mode cannot invoke the ChibiOS/RT APIs directly
 *     because privileged instructions are used inside.<br>
 *     The kernel APIs can be eventually invoked by using a SWI entry point
 *     that handles the switch in system mode and the return in user mode.</li>
 * <li>Other modes are not preempt-able because the system code assumes the
 *     threads running in system mode. When running in supervisor or other
 *     modes make sure that the interrupts are globally disabled.</li>
 * <li>Interrupts nesting is not supported in the ARM7 code because their
 *     implementation, even if possible, is not really efficient in this
 *     architecture.</li>
 * <li>FIQ sources can preempt the kernel (by design) so it is not possible to
 *     invoke the kernel APIs from inside a FIQ handler.</li>
 * </ul>
 * </p>
 * <p>
 * The ARM7 port is shared by multiple demos targeted to various implementations:
 * </p>
 * @ingroup Ports
 */
/** @} */

/**
 * @defgroup LPC214x LPC214x Support
 * @{
 * <p>
 * The LPC214x support includes:
 * <ul>
 * <li>VIC support code.</li>
 * <li>Buffered, interrupt driven, serial driver.</li>
 * <li>SSP driver.</li>
 * <li>A MMC/SD demo driver.</li>
 * <li>A buzzer demo driver.</li>
 * <li>A minimal demo, useful as project template.</li>
 * <li>A demo supporting the kernel test suite.</li>
 * <li>A C++ demo supporting the kernel test suite.</li>
 * </ul>
 * </p>
 * @ingroup ARM7
 */
/** @} */

/**
 * @defgroup AT91SAM7X AT91SAM7X Support
 * @{
 * <p>
 * The AT91SAM7X support includes:
 * <ul>
 * <li>Buffered, interrupt driven, serial driver.</li>
 * <li>A demo supporting the kernel test suite.</li>
 * </ul>
 * </p>
 * @ingroup ARM7
 */
/** @} */

/**
 * @defgroup ARMCM3 ARM Cortex-M3
 * @{
 * <p>
 * The ARM Cortex-M3 port is organized as follow:
 * </p>
 * <ul>
 * <li>The \p main() function is invoked in thread-privileged mode.</li>
 * <li>Each thread has a private process stack, the system has a single main
 *     stack where all the interrupts and exceptions are processed.</li>
 * <li>Only the 4 MSb of the priority level are used, the 4 LSb are assumed
 *     to be zero.</li>
 * <li>The threads are started in thread-privileged mode with BASEPRI level
 *     0x00 (disabled).</li>
 * <li>The kernel raises its BASEPRI level to 0x10 in order to protect the
 *     system mutex zones. Note that exceptions with level 0x00 can preempt
 *     the kernel, such exception handlers cannot invoke kernel APIs directly.</li>
 * <li>Interrupt nesting and the other advanced NVIC features are supported.</li>
 * <li>The SVC instruction and vector, with parameter #0,  is internally used
 *     for commanded context switching.<br>
 *     It is possible to share the SVC handler at the cost of slower context
 *     switching.</li>
 * <li>The PendSV vector is internally used for preemption context switching.</li>
 * </ul>
 * @ingroup Ports
 */
/** @} */

/**
 * @defgroup STM32F103 STM32F103 Support
 * @{
 * <p>
 * The STM32F103 support includes:
 * <ul>
 * <li>Buffered, interrupt driven, serial driver.</li>
 * <li>A demo supporting the kernel test suite.</li>
 * </ul>
 * </p>
 * @ingroup ARMCM3
 */
/** @} */

/**
 * @defgroup AVR MegaAVR
 * @{
 * <p>
 * Notes about the AVR port:
 * </p>
 * <ul>
 * <li>The AVR does not have a dedicated interrupt stack, make sure to reserve
 *     enough stack space for interrupts in each thread stack. This can be done
 *     by modifying the \p INT_REQUIRED_STACK macro into \p ports/AVR/chcore.h.</li>
 * </ul>
 * @ingroup Ports
 */
/** @} */

/**
 * @defgroup MSP430 MSP430
 * @{
 * <p>
 * Notes about the MSP430 port:
 * </p>
 * <ul>
 * <li>In the current version the MSP430 port is still untested.</li>
 * <li>The MSP430 does not have a dedicated interrupt stack, make sure to reserve
 *     enough stack space for interrupts in each thread stack. This can be done
 *     by modifying the \p INT_REQUIRED_STACK macro into \p ports/MSP430/chcore.h.</li>
 * </ul>
 * @ingroup Ports
 */
/** @} */

/**
 * @defgroup Kernel Kernel
 * @{
 */
/** @} */

/**
 * @defgroup Config Configuration
 * @{
 * In \p chconf.h are defined the required subsystems for your application.
 * @ingroup Kernel
 * @file chconf.h ChibiOS/RT configuration file.
 */
/** @} */

/**
 * @defgroup Core Core
 * @{
 * Non portable code.
 * @ingroup Kernel
 * @file chcore.c Non portable code.
 */
/** @} */

/**
 * @defgroup Initialization Initialization
 * @{
 * Initialization APIs and procedures.
 * @ingroup Kernel
 * @file ch.h ChibiOS/RT main include file, it includes everything else.
 * @file chinit.c ChibiOS/RT Initialization code.
 */
/** @} */

/**
 * @defgroup Debug Debug
 * @{
 * Debug APIs and procedures.
 * @ingroup Kernel
 * @file debug.h Debug macros and structures.
 * @file chdebug.c ChibiOS/RT Debug code.
 */
/** @} */

/**
 * @defgroup Scheduler Scheduler
 * @{
 * ChibiOS/RT scheduler.
 * @ingroup Kernel
 * @file chschd.c Scheduler code.
 * @file scheduler.h Scheduler macros and structures.
 */
/** @} */

/**
 * @defgroup ThreadLists Thread Lists and Queues
 * @{
 * ChibiOS/RT thread lists and queues utilities.
 * @ingroup Kernel
 * @file chlists.c Lists and queues code.
 * @file lists.h Lists and queues macros and structures.
 */
/** @} */

/**
 * @defgroup Threads Threads
 * @{
 * Threads creation and termination APIs.
 * @file threads.h Threads structures, macros and functions.
 * @file chthreads.c Threads code.
 */
/** @} */

/**
 * @defgroup Time Time and Virtual Timers
 * @{
 * Time and Virtual Timers related APIs.
 * @file include/vt.h Time macros and structures.
 * @file chvt.c Time functions.
 */
/** @} */

/**
 * @defgroup Heap Heap
 * @{
 * Heap Allocator related APIs.
 * <b>Operation mode</b><br><br>
 * 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.
 * @file include/heap.h Heap macros and structures.
 * @file chheap.c Heap functions.
 */
/** @} */

/**
 * @defgroup MemoryPools Memory Pools
 * @{
 * Memory Pools related APIs.
 * <b>Operation mode</b><br><br>
 * 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.
 * @file include/mempools.h Memory Pools macros and structures.
 * @file chmempools.c Memory Pools functions.
 */
/** @} */

/**
 * @defgroup Semaphores Semaphores
 * @{
 * Semaphores and threads synchronization.
 * <b>Operation mode</b><br><br>
 * A semaphore is a threads synchronization object, some operations
 * are defined on semaphores:<br>
 * <ul>
 *   <li><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.
 *   </li>
 *   <li><b>Wait</b>: The semaphore counter is decreased and if the result
 *     becomes negative the thread is queued in the semaphore and suspended.
 *   </li>
 *   <li><b>Reset</b>: The semaphore counter is reset to a non-negative value
 *     and all the threads in the queue are released.
 *   </li>
 * </ul>
 * Semaphores can be used as guards for mutual exclusion code zones but
 * also have other uses, queues guards and counters as example.<br>
 * In order to use the Semaphores APIs the \p CH_USE_SEMAPHORES
 * option must be specified in \p chconf.h.<br><br>
 * @file semaphores.h Semaphores macros and structures.
 * @file chsem.c Semaphores code.
 */
/** @} */

/**
 * @defgroup Mutexes Mutexes
 * @{
 * Mutexes and threads synchronization.
 * <b>Operation mode</b><br><br>
 * A mutex is a threads synchronization object, some operations are defined
 * on mutexes:<br>
 * <ul>
 *   <li><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.
 *   </li>
 *   <li><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.
 *   </li>
 * </ul>
 * In order to use the Event APIs the \p CH_USE_MUTEXES option must be
 * specified in \p chconf.h.<br>
 *
 * <b>Constraints</b><br><br>
 * 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.
 *
 * <b>The priority inversion problem</b><br><br>
 * 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.
 * @file mutexes.h Mutexes macros and structures.
 * @file chmtx.c Mutexes functions.
 */
/** @} */

/**
 * @defgroup Events Events
 * @{
 * Event Sources and Event Listeners.<br>
 * <b>Operation mode</b><br><br>
 * 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 the \p chEvtWait()
 * 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 the \p chEvtWait().<br>
 * In order to use the Event APIs the \p CH_USE_EVENTS option must be
 * specified in \p chconf.h.
 * @file events.h Events macros and structures.
 * @file chevents.c Events functions.
 */
/** @} */

/**
 * @defgroup Messages Messages
 * @{
 * Synchronous Messages.<br>
 * <b>Operation Mode</b><br><br>
 * 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 carryed in both directions. Data is not copyed 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.
 * @file messages.h	Messages macros and structures.
 * @file chmsg.c Messages functions.
 */
/** @} */

/**
 * @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>
 * <ul>
 * <li><b>Input queue</b>, monodirectional queue where the writer is the
 *     lower side and the reader is the upper side.</li>
 * <li><b>Output queue</b>, monodirectional queue where the writer is the
 *     upper side and the reader is the lower side.</li>
 * <li><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.
 * <li><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.
 * </ul>
 * 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.
 * @file queues.h I/O Queues macros and structures.
 * @file chqueues.c I/O Queues code.
 */
/** @} */

/**
 * @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.
 * @file serial.h Serial Drivers macros and structures.
 * @file chserial.c Serial Drivers code.
 */
/** @} */

/**
 * @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.
 * @file ch.hpp C++ wrapper classes and definitions.
 * @file ch.cpp C++ wrapper code.
 */
/** @} */