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

* The ARM7 port makes some assumptions on the application code organization: *

    *
  • The \p main() function is invoked in system mode and with interrupts * disabled.
    • *
  • 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.
    • *
*

*

* The ARM7 port is shared by multiple demos targeted to various implementations: *

* @ingroup Ports */ /** @} */ /** * @defgroup LPC214x LPC214x Support * @{ *

* The LPC214x support includes: *

    *
  • VIC support code.
    • *
  • Buffered, interrupt driver, 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 driver, serial driver.
    • *
  • A demo supporting the kernel test suite.
    • *
*

* @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.
    • *
  • 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 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 \p ports/AVR/chcore.h.
    • *
* @ingroup Ports */ /** @} */ /** * @defgroup MSP430 MSP430 * @{ *

* Notes about the MSP430 port: *

*
    *
  • In the current version the MSP430 port is still untested.
    • *
  • The MSP430 does not have a dedicated interrupt stack, make sure to reserve * enough stack space for interrupts in each thread stack. This can be done * by modifying the \p INT_REQUIRED_STACK macro into \p ports/MSP430/chcore.h.
    • *
* @ingroup Ports */ /** @} */ /** * @defgroup Kernel Kernel * @{ */ /** @} */ /** * @defgroup Config Configuration * @{ * In \p chconf.h are defined the required subsystems for your application. * @ingroup Kernel * @file chconf.h ChibiOS/RT configuration file. */ /** @} */ /** * @defgroup Core Core * @{ * Non portable code. * @ingroup Kernel * @file chcore.c Non portable code. */ /** @} */ /** * @defgroup Initialization Initialization * @{ * Initialization APIs and procedures. * @ingroup Kernel * @file ch.h ChibiOS/RT main include file, it includes everything else. * @file chinit.c ChibiOS/RT Initialization code. */ /** @} */ /** * @defgroup Debug Debug * @{ * Debug APIs and procedures. * @ingroup Kernel * @file debug.h Debug macros and structures. * @file chdebug.c ChibiOS/RT Debug code. */ /** @} */ /** * @defgroup Scheduler Scheduler * @{ * ChibiOS/RT scheduler. * @ingroup Kernel * @file chschd.c Scheduler code. * @file scheduler.h Scheduler macros and structures. */ /** @} */ /** * @defgroup Threads Threads * @{ * Threads creation and termination APIs. * @file threads.h Threads structures, macros and functions. * @file chthreads.c Threads code. */ /** @} */ /** * @defgroup VirtualTimers Virtual Timers * @{ * Virtual Timers APIs. * In order to use the Virtual Timers the \p CH_USE_VIRTUAL_TIMERS option * must be specified in \p chconf.h. * @file src/chdelta.c Virtual Timers code. * @file delta.h Virtual Timers macros and structures. */ /** @} */ /** * @defgroup Time Time * @{ * Time related APIs. * In order to use the Time APIs the \p CH_USE_SLEEP * option must be specified in \p chconf.h. * @file include/sleep.h Time macros and structures. * @file chsleep.c Time 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 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 the \p chEvtWait() * API. If an event is generated while a listening thread is not ready to * serve it then the event becomes "pending" and will be served as soon the * thread invokes the \p chEvtWait().
* 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 \p P_MSGBYPRIO when creating a server * thread, \p CH_USE_MESSAGES_PRIORITY must also be specified in \p chconf.h * in order to enable the feature.
* 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. */ /** @} */