().
* 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, \a Heap, \a Pool.
* 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.
* 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.
* Examples: \p chThdCreateStatic(), \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.
* @image html states.png
*
* @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 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.
* @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).
*
* @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
* @{
*
* The ARM7 port supports 3 modes:
*
*
* - Pure ARM mode, this is the preferred mode for code speed. The code size
* is larger however. This mode is enabled when all the modules are compiled
* in ARM mode, see the Makefiles.
* - Pure THUMB mode, this is the preferred mode for code size. In this mode
* the execution speed is slower than the ARM mode. This mode is enabled
* when all the modules are compiled in THUMB mode, see the Makefiles.
* - Interworking mode, when in the sistem there are ARM modules mixed with
* THUMB modules then the interworking compiler option is enabled. This is
* usually the slowest mode and the code size is not as good as in pure
* THUMB mode.
*
*
* The ARM7 port makes some assumptions on the application code organization:
*
* - The \p main() function is invoked in system mode.
* - Each thread has a private user/system stack, the system has a single
* interrupt stack where all the interrupts are processed.
* - The threads are started in system mode.
* - 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.
* 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.
* - 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.
* - Interrupts nesting is not supported in the ARM7 code because their
* implementation, even if possible, is not really efficient in this
* architecture.
* - FIQ sources can preempt the kernel (by design) so it is not possible to
* invoke the kernel APIs from inside a FIQ handler. FIQ handlers are not
* affected by the kernel activity so there is not added jitter.
* - Interrupt handlers do not save function-saved registers so you need to
* make sure your code saves them or does not use them (this happens
* because in the ARM7 port all the OS interrupt handlers are declared
* naked).
* Function-trashed registers (R0-R3,R12,LR,SR) are saved/restored by the
* system macros \p chSysIRQEnterI() and \p chSysIRQExitI().
* The easiest way to ensure this is to just invoke a function from within
* the interrupt handler, the function code will save all the required
* registers.
* Example:
* @code
* __attribute__((naked, weak))
* void irq_handler(void) {
* chSysIRQEnterI();
*
* serve_interrupt();
*
* VICVectAddr = 0; // This is LPC214x-specific.
* chSysIRQExitI();
* }
* @endcode
* This is not a bug but an implementation choice, this solution allows to
* have interrupt handlers compiled in thumb mode without have to use an
* interworking mode (the mode switch is hidden in the macros), this
* greatly improves code efficiency and size. You can look at the serial
* driver for real examples of interrupt handlers.
*
*
* @ingroup Ports
*/
/** @} */
/**
* @defgroup ARM7CONF Configuration Options
* @{
*
* The ARM7 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 practice this value is the stack space used by the chSchDoReschedule()
* stack frame.
* This value can be affected by a variety of external things like compiler
* version, compiler options, kernel settings (speed/size) and so on.
* The default for this value is @p 0x10 which should be a safe value, you
* can trim this down by defining the macro externally. This would save
* some valuable RAM space for each thread present in the system.
* The default value is set into ./ports/ARM7/chcore.h.
*
*
* @ingroup ARM7
*/
/** @} */
/**
* @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
* @{
*/
/** @} */
/**
* @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.
* @file chcore.h Non portable macros and structures.
*/
/** @} */
/**
* @defgroup Types Types
* @{
* System types and macros.
* @ingroup Kernel
* @file chtypes.h System types and code modifiers.
*/
/** @} */
/**
* @defgroup Inline Inline
* @{
* System inline-able code.
* @ingroup Kernel
* @file inline.h Inline versions of some critical system routines.
*/
/** @} */
/**
* @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.
* 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, monodirectional queue where the writer is the
* lower side and the reader is the upper side.
* - Output queue, monodirectional 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.
*/
/** @} */