tinySA/docs/ch.txt

/**
 * @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.
 * - Designed for realtime applications.
 * - Easily portable.
 * - Mixed programming model:
 *   - Synchronous, using semaphores/mutexes/condvars and/or messages.
 *   - Asynchronous, using event sources.
 *   - Mix of the above models, multiple threads listening to multiple event
 *     sources while serving message queues.
 *   - 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.
 * - Preemptive scheduling.
 * - 128 priority levels.
 * - Multiple threads at the same priority level allowed.
 * - Round robin scheduling for threads at the same priority level.
 * - Unlimited number of threads.
 * - Unlimited number of virtual timers.
 * - Unlimited number of semaphores.
 * - Unlimited number of mutexes.
 * - Unlimited number of condvars.
 * - Unlimited number of event sources.
 * - Unlimited number of messages in queue.
 * - Unlimited number of I/O queues.
 * - No static setup at compile time, there is no need to configure a maximum
 *   number of all the above resources.
 * - No *need* for a memory allocator, all the kernel structures are static
 *   and declaratively allocated.
 * - Threads, Semaphores, Event Sources, Virtual Timers creation/deletion at
 *   runtime.
 * - 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.
 * - Small memory footprint, unused subsystems can be excluded by the
 *   memory image.
 * - Almost totally written in C with little ASM code required for ports.
 *
 * <h2>Related pages</h2>
 * - @subpage Concepts
 * - @subpage Articles
 */

/**
 * @page Concepts Concepts
 * @{
 * @brief ChibiOS/RT Concepts and Architecture
 * @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 Cond, @a Evt, @a Msg, @a IQ, @a OQ, @a HQ, @a FDD, @a HDD, @a Dbg,
 * @a Heap, @a Pool.
 *
 * @section api_suffixes API Names Suffixes
 * The suffix is not present for normal APIs but can be one of
 * the following:
 * - <b>None</b>, APIs without any suffix can be invoked only from the user
 *   code in the <b>Normal</b> state unless differently specified. See
 *   @ref system_states.
 * - <b>"I"</b>, I-Class APIs are invokable only from the <b>I-Locked</b> or
 *   <b>S-Locked</b> states. See @ref system_states.
 * - <b>"S"</b>, S-Class APIs are invokable only from the <b>S-Locked</b>
 *   state. See @ref system_states.
 * Examples: @p chThdCreateStatic(), @p chSemSignalI(), @p chIQGetTimeout().
 *
 * @section interrupt_classes Interrupt Classes
 * In ChibiOS/RT there are three logical interrupt classes:
 * - <b>Regular Interrupts</b>. Maskable interrupt sources that cannot
 *   preempt the kernel code and are thus able to invoke operating system APIs
 *   from within their handlers. The interrupt handlers belonging to this class
 *   must be written following some rules. See the @ref System APIs group.
 * - <b>Fast Interrupts</b>. Maskable interrupt sources with the ability
 *   to preempt the kernel code and thus have a lower latency. Such sources are
 *   not supported on all the architectures.<br>
 *   Fast interrupts are not allowed to invoke any operating system API from
 *   within their handlers. Fast interrupt sources may however pend a lower
 *   priority regular interrupt where access to the operating system is
 *   possible.
 * - <b>Non Maskable Interrupts</b>. Non maskable interrupt sources are
 *   totally out of the operating system control and have the lowest latency.
 *   Such sources are not supported on all the architectures.
 *
 * The mapping of the above logical classes into physical interrupts priorities
 * is, of course, port dependent. See the documentation of the various ports
 * for details.
 *
 * @section system_states System States
 * When using ChibiOS/RT the system can be in one of the following logical
 * operating states:
 * - <b>Initialization</b>. When the system is in this state all the maskable
 *   interrupt sources are disabled. In this state it is not possible to use
 *   any system API except @p chSysInit(). This state is entered after a
 *   physical reset.
 * - <b>Normal</b>. All the interrupt sources are enabled and the system APIs
 *   are accessible, threads are running.
 * - <b>Suspended</b>. In this state the fast interrupt sources are enabled but
 *   the regular interrupt sources are not. In this state it is not possible
 *   to use any system API except @p chSysDisable() or @p chSysEnable() in
 *   order to change state.
 * - <b>Disabled</b>. When the system is in this state both the maskable
 *   regular and fast interrupt sources are disabled. In this state it is not
 *   possible to use any system API except @p chSysSuspend() or
 *   @p chSysEnable() in order to change state.
 * - <b>Sleep</b>. Architecture-dependent low power mode, the idle thread
 *   goes in this state and waits for interrupts, after servicing the interrupt
 *   the Normal state is restored and the scheduler has a chance to reschedule.
 * - <b>S-Locked</b>. Kernel locked and regular interrupt sources disabled.
 *   Fast interrupt sources are enabled. S-Class and I-Class APIs are
 *   invokable in this state.
 * - <b>I-Locked</b>. Kernel locked and regular interrupt sources disabled.
 *   I-Class APIs are invokable from this state.
 * - <b>Serving Regular Interrupt</b>. No system APIs are accessible but it is
 *   possible to switch to the I-Locked state using @p chSysLockI() and then
 *   invoke any I-Class API. Interrupt handlers can be preemptable on some
 *   architectures thus is important to switch to I-Locked state before
 *   invoking system APIs.
 * - <b>Serving Fast Interrupt</b>. System APIs are not accessible.
 * - <b>Serving Non-Maskable Interrupt</b>. System APIs are not accessible.
 * - <b>Halted</b>. All interrupt sources are disabled and system stopped into
 *   an infinite loop. This state can be reached if the debug mode is activated
 *   <b>and</b> an error is detected <b>or</b> after explicitly invoking
 *   @p chSysHalt().
 *
 * Note that the above state are just <b>Logical States</b> that may have no
 * real associated machine state on some architectures. The following diagram
 * shows the possible transitions between the states:
 *
 * @dot
  digraph example {
      rankdir="LR";
      node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true", width="0.75", height="0.75"];
      init [label="Initialization", style="bold"];
      norm [label="Normal", shape=doublecircle];
      susp [label="Suspended"];
      disab [label="Disabled"];
      slock [label="S-Locked"];
      ilock [label="I-Locked"];
      slock [label="S-Locked"];
      sleep [label="Sleep"];
      sri [label="SRI"];
      sfi [label="SFI"];
      init -> norm [label="chSysInit()", fontname=Helvetica, fontsize=8];
      norm -> slock [label="chSysLock()", fontname=Helvetica, fontsize=8, constraint=false];
      slock -> norm [label="chSysUnlock()", fontname=Helvetica, fontsize=8];
      norm -> susp [label="chSysSuspend()", fontname=Helvetica, fontsize=8];
      susp -> disab [label="chSysDisable()", fontname=Helvetica, fontsize=8];
      norm -> disab [label="chSysDisable()", fontname=Helvetica, fontsize=8];
      susp -> norm [label="chSysEnable()", fontname=Helvetica, fontsize=8];
      disab -> norm [label="chSysEnable()", fontname=Helvetica, fontsize=8];
      slock -> ilock [dir="both", label="Context Switch", fontname=Helvetica, fontsize=8];
      norm -> sri [style="dotted", label="Regular IRQ", fontname=Helvetica, fontsize=8];
      norm -> sfi [style="dotted", label="Fast IRQ", fontname=Helvetica, fontsize=8];
      susp -> sfi [style="dotted", label="Fast IRQ", fontname=Helvetica, fontsize=8];
      sri -> norm [label="Regular IRQ return", fontname=Helvetica, fontsize=8];
      sfi -> norm [label="Fast IRQ return", fontname=Helvetica, fontsize=8];
      sfi -> susp [label="Fast IRQ return", fontname=Helvetica, fontsize=8];
      sri -> ilock [label="chSysLockI()", fontname=Helvetica, fontsize=8, constraint=false];
      ilock -> sri [label="chSysUnlockI()", fontname=Helvetica, fontsize=8];
      norm -> sleep [label="Idle Thread", fontname=Helvetica, fontsize=8];
      sleep -> sri [style="dotted", label="Regular IRQ", fontname=Helvetica, fontsize=8];
      sleep -> sfi [style="dotted", label="Fast IRQ", fontname=Helvetica, fontsize=8];
  }
 * @enddot
 * Note, the Halted and SNMI states can be reached from any state and are not
 * shown for simplicity.
 *
 * @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.<br><br>
 * @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 thread_states Threads States
 * The image shows how threads can change their state in ChibiOS/RT.<br>
 * @image html states.png
 *
 * @section priority Priority Levels
 * Priorities in ChibiOS/RT are a contiguous numerical range but the initial
 * and final values are not enforced.<br>
 * The following table describes the various priority boundaries (from lowest
 *   to highest):
 * - @p IDLEPRIO, this is the lowest priority level and is reserved for the
 *   idle thread, no other threads should share this priority level. This is
 *   the lowest numerical value of the priorities space.
 * - @p LOWPRIO, the lowest priority level that can be assigned to an user
 *   thread.
 * - @p NORMALPRIO, this is the central priority level for user threads. It is
 *   advisable to assign priorities to threads as values relative to
 *   @p NORMALPRIO, as example NORMALPRIO-1 or NORMALPRIO+4, this ensures the
 *   portability of code should the numerical range change in future
 *   implementations.
 * - @p HIGHPRIO, the highest priority level that can be assigned to an user
 *   thread.
 * - @p ABSPRO, absolute maximum software priority level, it can be higher than
 *   @p HIGHPRIO but the numerical values above @p HIGHPRIO up to @p ABSPRIO
 *   (inclusive) are reserved. This is the highest numerical value of the
 *   priorities space.
 *
 * @section warea Thread Working Area
 * Each thread has its own stack, a Thread structure and some preemption
 * areas. All the structures are allocated into a "Thread working area",
 * a thread private heap, usually allocated in an array declared in your
 * code. Threads do not use any memory outside the allocated working area
 * except when accessing static shared data.<br><br>
 * @image html workspace.png
 * <br>
 * Note that the preemption area is only present when the thread is not
 * running (switched out), 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.
 * The preemption area can be divided in up to three structures:
 * - External context.
 * - Interrupt stack.
 * - Internal context.
 *
 * See the @ref Core documentation for details, the area may change on
 * the various ports and some structures may not be present (or be zero-sized).
 */
/** @} */

/**
 * @page Articles Articles
 * @{
 * @brief ChibiOS/RT Articles and Code Examples
 *
 * - @subpage article_atomic
 * - @subpage article_saveram
 * - @subpage article_interrupts
 */
/** @} */

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

/**
 * @defgroup Kernel Kernel
 * @{
 * @file ch.h ChibiOS/RT main include file, it includes everything else.
 */
/** @} */

/**
 * @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 Generic Port Code Templates
 * @{
 * Non portable code templates.
 * @ingroup Kernel
 * @file src/templates/chcore.c Non portable code template file.
 * @file src/templates/chcore.h Non portable macros and structures template file.
 */
/** @} */

/**
 * @defgroup Types Types
 * @{
 * System types and macros.
 * @ingroup Kernel
 * @file templates/chtypes.h System types and code modifiers.
 */
/** @} */

/**
 * @defgroup System System Management
 * @{
 * Initialization, Locks, Interrupt Handling, Power Management, Abnormal
 * Termination.
 * @ingroup Kernel
 * @file sys.h System related macros and structures.
 * @file chsys.c System related code.
 */
/** @} */

/**
 * @defgroup Inline Inline
 * @{
 * System inline-able code.
 * @ingroup Kernel
 * @file inline.h Inline versions of some critical system routines.
 */
/** @} */

/**
 * @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.
 * <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.
 * @file include/heap.h Heap macros and structures.
 * @file chheap.c Heap functions.
 */
/** @} */

/**
 * @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.
 * @file include/mempools.h Memory Pools macros and structures.
 * @file chmempools.c Memory Pools functions.
 */
/** @} */

/**
 * @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 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.
 * <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.
 * @file mutexes.h Mutexes macros and structures.
 * @file chmtx.c Mutexes functions.
 */
/** @} */

/**
 * @defgroup CondVars Conditional Variables
 * @{
 * Conditional 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 Conditional Variables APIs the @p CH_USE_CONDVARS
 * option must be specified in @p chconf.h.<br><br>
 * @file condvars.h Conditional Variables macros and structures.
 * @file chcond.c Conditional Variables code.
 */
/** @} */

/**
 * @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.
 * @file events.h Events macros and structures.
 * @file chevents.c Events functions.
 */
/** @} */

/**
 * @defgroup Messages Messages
 * @{
 * Synchronous inter-thread Messages.
 * <h2>Operation Mode</h2>
 * 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.
 * @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>
 * - <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.
 * @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 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 application.
 */
/** @} */

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

/**
 * @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
 * @file evtimer.c Events Generator Timer code.
 * @file evtimer.h Events Generator Timer structures and macros.
 */
/** @} */