/**
* @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.
* - 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.
* 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.
*
* Related pages
* - @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\\\().
* 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:
* - None, APIs without any suffix can be invoked only from the user
* code in the Normal state unless differently specified. See
* @ref system_states.
* - "I", I-Class APIs are invokable only from the I-Locked or
* S-Locked states. See @ref system_states.
* - "S", S-Class APIs are invokable only from the S-Locked
* 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:
* - Regular Interrupts. 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.
* - Fast Interrupts. 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.
* 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.
* - Non Maskable Interrupts. 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:
* - Initialization. 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.
* - Normal. All the interrupt sources are enabled and the system APIs
* are accessible, threads are running.
* - Suspended. 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.
* - Disabled. 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.
* - Sleep. 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.
* - S-Locked. Kernel locked and regular interrupt sources disabled.
* Fast interrupt sources are enabled. S-Class and I-Class APIs are
* invokable in this state.
* - I-Locked. Kernel locked and regular interrupt sources disabled.
* I-Class APIs are invokable from this state.
* - Serving Regular Interrupt. 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.
* - Serving Fast Interrupt. System APIs are not accessible.
* - Serving Non-Maskable Interrupt. System APIs are not accessible.
* - Halted. All interrupt sources are disabled and system stopped into
* an infinite loop. This state can be reached if the debug mode is activated
* and an error is detected or after explicitly invoking
* @p chSysHalt().
*
* Note that the above state are just Logical States 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.
* @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.
* @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.
* 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.
* @image html workspace.png
*
* 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.
* 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.
* @file include/heap.h Heap macros and structures.
* @file chheap.c Heap functions.
*/
/** @} */
/**
* @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.
* @file include/mempools.h Memory Pools macros and structures.
* @file chmempools.c Memory Pools functions.
*/
/** @} */
/**
* @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 but
* also have other uses, queues guards and counters as example.
* In order to use the Semaphores APIs the @p CH_USE_SEMAPHORES
* option must be specified in @p chconf.h.
* @file semaphores.h Semaphores macros and structures.
* @file chsem.c Semaphores code.
*/
/** @} */
/**
* @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.
* @file mutexes.h Mutexes macros and structures.
* @file chmtx.c Mutexes functions.
*/
/** @} */
/**
* @defgroup CondVars Conditional Variables
* @{
* Conditional 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 Conditional Variables APIs the @p CH_USE_CONDVARS
* option must be specified in @p chconf.h.
* @file condvars.h Conditional Variables macros and structures.
* @file chcond.c Conditional Variables code.
*/
/** @} */
/**
* @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.
* @file events.h Events macros and structures.
* @file chevents.c Events functions.
*/
/** @} */
/**
* @defgroup Messages Messages
* @{
* Synchronous inter-thread Messages.
* Operation Mode
* 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.
* @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).
* 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.
* @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.
* 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.
* @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.
* 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 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.
*/
/** @} */