507 lines
19 KiB
Plaintext
507 lines
19 KiB
Plaintext
/**
|
|
* @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 (<span class="t_nihongo_kanji" xml:lang="ja" lang="ja">ちび</span>OS/RT) \endhtmlonly
|
|
* means small Real Time Operating System.
|
|
* Source <a href="http://en.wikipedia.org/wiki/Chibi" target="_blank">Wikipedia</a>.
|
|
* @section ch_features Features
|
|
* <ul>
|
|
* <li>Free software, GPL3 licensed.</li>
|
|
* <li>Designed for realtime applications.</li>
|
|
* <li>Easily portable.</li>
|
|
* <li>Mixed programming model:</li>
|
|
* <ul>
|
|
* <li>Synchronous, using semaphores/mutexes and/or messages.</li>
|
|
* <li>Asynchronous, using event sources.</li>
|
|
* <li>Mix of the above models, multiple threads listening to multiple event
|
|
* sources while serving message queues.</li>
|
|
* </ul>
|
|
* <li>PC simulator target included, the development can be done on the PC
|
|
* using MinGW or VS.
|
|
* 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 and VS demos available and ready to go, use them as templates for
|
|
* your application.</li>
|
|
* <li>Unlimited number of threads.</li>
|
|
* <li>Unlimited number of virtual timers.</li>
|
|
* <li>Unlimited number of semaphores.</li>
|
|
* <li>Unlimited number of mutexes.</li>
|
|
* <li>Unlimited number of event sources.</li>
|
|
* <li>Unlimited number of messages in queue.</li>
|
|
* <li>Unlimited number of I/O queues.</li>
|
|
* <li>No static setup at compile time, there is no need to configure a maximum
|
|
* number of all the above resources.</li>
|
|
* <li>No *need* for a memory allocator, all the kernel structures are static
|
|
* and declaratively allocated. A memory allocator can be used in your
|
|
* application but it is not required by the ChibiOS/RT itself.</li>
|
|
* <li>Threads, Semaphores, Event Sources, Virtual Timers creation/deletion at
|
|
* runtime.</li>
|
|
* <li>Blocking and non blocking I/O channels with timeout and events generation
|
|
* capability.</li>
|
|
* <li>Pre-emptive scheduling.</li>
|
|
* <li>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.</li>
|
|
* <li>Small memory footprint, unused subsystems can be excluded by the
|
|
* memory image.</li>
|
|
* <li>Almost totally written in C with little ASM code required for ports.</li>
|
|
* </ul>
|
|
*
|
|
* ChibiOS/RT architecture:<br><br>
|
|
* @subpage Concepts
|
|
*/
|
|
|
|
/**
|
|
* @page Concepts Concepts
|
|
* @{
|
|
* @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 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.<br>
|
|
* 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.<br>
|
|
* @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.<br>
|
|
* @image html workspace.png
|
|
* <br>
|
|
* 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
|
|
* @{
|
|
* <p>
|
|
* The ARM7 port makes some assumptions on the application code organization:
|
|
* <ul>
|
|
* <li>The \p main() function is invoked in system mode and with interrupts
|
|
* disabled.</li>
|
|
* <li>Each thread has a private user/system stack, the system has a single
|
|
* interrupt stack where all the interrupts are processed.</li>
|
|
* <li>The threads are started in system mode.</li>
|
|
* <li>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.<br>
|
|
* 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.</li>
|
|
* <li>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.</li>
|
|
* <li>Interrupts nesting is not supported in the ARM7 code because their
|
|
* implementation, even if possible, is not really efficient in this
|
|
* architecture.</li>
|
|
* <li>FIQ sources can preempt the kernel (by design) so it is not possible to
|
|
* invoke the kernel APIs from inside a FIQ handler.</li>
|
|
* </ul>
|
|
* </p>
|
|
* <p>
|
|
* The ARM7 port is shared by multiple demos targeted to various implementations:
|
|
* </p>
|
|
* @ingroup Ports
|
|
*/
|
|
/** @} */
|
|
|
|
/**
|
|
* @defgroup LPC214x LPC214x Support
|
|
* @{
|
|
* <p>
|
|
* The LPC214x support includes:
|
|
* <ul>
|
|
* <li>VIC support code.</li>
|
|
* <li>Buffered, interrupt driven, serial driver.</li>
|
|
* <li>SSP driver.</li>
|
|
* <li>A MMC/SD demo driver.</li>
|
|
* <li>A buzzer demo driver.</li>
|
|
* <li>A minimal demo, useful as project template.</li>
|
|
* <li>A demo supporting the kernel test suite.</li>
|
|
* <li>A C++ demo supporting the kernel test suite.</li>
|
|
* </ul>
|
|
* </p>
|
|
* @ingroup ARM7
|
|
*/
|
|
/** @} */
|
|
|
|
/**
|
|
* @defgroup AT91SAM7X AT91SAM7X Support
|
|
* @{
|
|
* <p>
|
|
* The AT91SAM7X support includes:
|
|
* <ul>
|
|
* <li>Buffered, interrupt driven, serial driver.</li>
|
|
* <li>A demo supporting the kernel test suite.</li>
|
|
* </ul>
|
|
* </p>
|
|
* @ingroup ARM7
|
|
*/
|
|
/** @} */
|
|
|
|
/**
|
|
* @defgroup ARMCM3 ARM Cortex-M3
|
|
* @{
|
|
* <p>
|
|
* The ARM Cortex-M3 port is organized as follow:
|
|
* </p>
|
|
* <ul>
|
|
* <li>The \p main() function is invoked in thread-privileged mode.</li>
|
|
* <li>Each thread has a private process stack, the system has a single main
|
|
* stack where all the interrupts and exceptions are processed.</li>
|
|
* <li>Only the 4 MSb of the priority level are used, the 4 LSb are assumed
|
|
* to be zero.</li>
|
|
* <li>The threads are started in thread-privileged mode with BASEPRI level
|
|
* 0x00 (disabled).</li>
|
|
* <li>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.</li>
|
|
* <li>Interrupt nesting and the other advanced NVIC features are supported.</li>
|
|
* <li>The SVC instruction and vector, with parameter #0, is internally used
|
|
* for commanded context switching.<br>
|
|
* It is possible to share the SVC handler at the cost of slower context
|
|
* switching.</li>
|
|
* <li>The PendSV vector is internally used for preemption context switching.</li>
|
|
* </ul>
|
|
* @ingroup Ports
|
|
*/
|
|
/** @} */
|
|
|
|
/**
|
|
* @defgroup AVR MegaAVR
|
|
* @{
|
|
* <p>
|
|
* Notes about the AVR port:
|
|
* </p>
|
|
* <ul>
|
|
* <li>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.</li>
|
|
* </ul>
|
|
* @ingroup Ports
|
|
*/
|
|
/** @} */
|
|
|
|
/**
|
|
* @defgroup MSP430 MSP430
|
|
* @{
|
|
* <p>
|
|
* Notes about the MSP430 port:
|
|
* </p>
|
|
* <ul>
|
|
* <li>In the current version the MSP430 port is still untested.</li>
|
|
* <li>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.</li>
|
|
* </ul>
|
|
* @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.
|
|
* <b>Operation mode</b><br><br>
|
|
* A semaphore is a threads synchronization object, some operations
|
|
* are defined on semaphores:<br>
|
|
* <ul>
|
|
* <li><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.
|
|
* </li>
|
|
* <li><b>Wait</b>: The semaphore counter is decreased and if the result
|
|
* becomes negative the thread is queued in the semaphore and suspended.
|
|
* </li>
|
|
* <li><b>Reset</b>: The semaphore counter is reset to a non-negative value
|
|
* and all the threads in the queue are released.
|
|
* </li>
|
|
* </ul>
|
|
* 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.
|
|
* <b>Operation mode</b><br><br>
|
|
* A mutex is a threads synchronization object, some operations are defined
|
|
* on mutexes:<br>
|
|
* <ul>
|
|
* <li><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.
|
|
* </li>
|
|
* <li><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.
|
|
* </li>
|
|
* </ul>
|
|
* In order to use the Event APIs the \p CH_USE_MUTEXES option must be
|
|
* specified in \p chconf.h.<br>
|
|
*
|
|
* <b>Constraints</b><br><br>
|
|
* 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.
|
|
*
|
|
* <b>The priority inversion problem</b><br><br>
|
|
* 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 Events Events
|
|
* @{
|
|
* Event Sources and Event Listeners.<br>
|
|
* <b>Operation mode</b><br><br>
|
|
* 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 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().<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 Messages.<br>
|
|
* <b>Operation Mode</b><br><br>
|
|
* 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.<br>
|
|
* 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.<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>
|
|
* <ul>
|
|
* <li><b>Input queue</b>, monodirectional queue where the writer is the
|
|
* lower side and the reader is the upper side.</li>
|
|
* <li><b>Output queue</b>, monodirectional queue where the writer is the
|
|
* upper side and the reader is the lower side.</li>
|
|
* <li><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.
|
|
* <li><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.
|
|
* </ul>
|
|
* 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.
|
|
*/
|
|
/** @} */
|