/** * @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 (ちびOS/RT) \endhtmlonly * means small Real Time Operating System. * Source Wikipedia. * @section ch_features Features * * * ChibiOS/RT architecture:

* @subpage Concepts */ /** * @page Concepts Concepts * @{ * @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. * The suffix is not present for normal APIs but can be one of * the following: * - "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. * * The APIs without suffix can be invoked only from the user code in the Normal * state unless differently specified.
* Examples: @p chThdCreateStatic(), @p chSemSignalI(), @p chIQGetTimeout(). * * @section interrupts 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). */ /** @} */ /** * @defgroup Ports Ports * @{ * This section describes the technical details for the various supported * ChibiOS/RT ports. */ /** @} */ /** * @defgroup LPC214x LPC214x Support * @{ *

* The LPC214x support includes: *

    *
  • VIC support code.
  • *
  • Buffered, interrupt driven, serial driver.
  • *
  • SSP driver.
  • *
  • A MMC/SD demo driver.
  • *
  • A buzzer demo driver.
  • *
  • A minimal demo, useful as project template.
  • *
  • A demo supporting the kernel test suite.
  • *
  • A C++ demo supporting the kernel test suite.
  • *
*

* @ingroup ARM7 */ /** @} */ /** * @defgroup AT91SAM7X AT91SAM7X Support * @{ *

* The AT91SAM7X support includes: *

    *
  • Buffered, interrupt driven, serial driver.
  • *
  • EMAC driver with MII support.
  • *
  • A demo supporting the kernel test suite.
  • *
  • A Web server demo using the uIP TCP/IP stack.
  • *
*

* @ingroup ARM7 */ /** @} */ /** * @defgroup ARMCM3 ARM Cortex-M3 * @{ *

* The ARM Cortex-M3 port is organized as follow: *

*
    *
  • The @p main() function is invoked in thread-privileged mode.
  • *
  • Each thread has a private process stack, the system has a single main * stack where all the interrupts and exceptions are processed.
  • *
  • Only the 4 MSb of the priority level are used, the 4 LSb are assumed * to be zero.
  • *
  • The threads are started in thread-privileged mode with BASEPRI level * 0x00 (disabled).
  • *
  • 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. * It is possible to modify the priority levels by editing the * ./ports/ARMCM3/chcore.h file.
  • *
  • Interrupt nesting and the other advanced NVIC features are supported.
  • *
  • The SVC instruction and vector, with parameter #0, is internally used * for commanded context switching.
    * It is possible to share the SVC handler at the cost of slower context * switching.
  • *
  • The PendSV vector is internally used for preemption context switching.
  • *
* @ingroup Ports */ /** @} */ /** * @defgroup ARMCM3CONF Configuration Options * @{ *

* The ARMCM3 port allows some architecture-specific configurations settings * that can be specified externally, as example on the compiler command line: *

    *
  • @p INT_REQUIRED_STACK, this value represent the amount of stack space used * by an interrupt handler between the @p extctx and @p intctx * structures.
    * In the current implementation this value is guaranteed to be zero so * there is no need to modify this value unless changes are done at the * interrupts handling code.
  • *
  • @p BASEPRI_USER, this is the @p BASEPRI value for the user threads. The * default value is @p 0 (disabled).
    * Usually there is no need to change this value, please refer to the * Cortex-M3 technical reference manual for a detailed description.
  • *
  • @p BASEPRI_KERNEL, this is the @p BASEPRI value for the kernel lock code. * The default value is 0x10.
    * Code running at higher priority levels must not invoke any OS API.
    * Usually there is no need to change this value, please refer to the * Cortex-M3 technical reference manual for a detailed description.
  • *
  • @p ENABLE_WFI_IDLE, if set to @p 1 enables the use of the @p wfi * instruction from within the idle loop. This is defaulted to 0 because * it can create problems with some debuggers. Setting this option to 1 * reduces the system power requirements.
  • *
*

* @ingroup ARMCM3 */ /** @} */ /** * @defgroup STM32F103 STM32F103 Support * @{ *

* The STM32F103 support includes: *

    *
  • Buffered, interrupt driven, serial driver.
  • *
  • A demo supporting the kernel test suite.
  • *
*

* @ingroup ARMCM3 */ /** @} */ /** * @defgroup AVR MegaAVR * @{ *

* Notes about the AVR port: *

*
    *
  • 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 * ./ports/AVR/chcore.h.
  • *
* @ingroup Ports */ /** @} */ /** * @defgroup AVRCONF Configuration Options * @{ *

* The AVR port allows some architecture-specific configurations settings * that can be specified externally, as example on the compiler command line: *

    *
  • @p INT_REQUIRED_STACK, this value represent the amount of stack space * used by the interrupt handlers.
    * The default for this value is @p 32, this space is allocated for each * thread so be careful in order to not waste precious RAM space.
    * The default value is set into ./ports/AVR/chcore.h.
  • *
*

* @ingroup AVR */ /** @} */ /** * @defgroup MSP430 MSP430 * @{ *

* Notes about the MSP430 port: *

*
    *
  • 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 * ./ports/MSP430/chcore.h.
  • *
* @ingroup Ports */ /** @} */ /** * @defgroup MSP430CONF Configuration Options * @{ *

* The MSP430 port allows some architecture-specific configurations settings * that can be specified externally, as example on the compiler command line: *

    *
  • @p INT_REQUIRED_STACK, this value represent the amount of stack space * used by the interrupt handlers.
    * The default for this value is @p 32, this space is allocated for each * thread so be careful in order to not waste precious RAM space.
    * The default value is set into ./ports/MSP430/chcore.h.
  • *
*

* @ingroup MSP430 */ /** @} */ /** * @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 Core * @{ * Non portable code. * @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 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 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.
* 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 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. */ /** @} */