/* ChibiOS/RT - Copyright (C) 2006-2007 Giovanni Di Sirio. This file is part of ChibiOS/RT. ChibiOS/RT is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version. ChibiOS/RT is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program. If not, see . */ /** * @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. Stable releases include a exception clause * to the GPL. * - Designed for realtime applications. * - Easily portable. * - Preemptive scheduling. * - 128 priority levels. Multiple threads at the same priority level allowed. * - Round robin scheduling for threads at the same priority level. * - Offers threads, virtual timers, semaphores, mutexes, condvars, * event flags, messages, mailboxes, I/O queues. * - No static setup at compile time, there is no need to configure a maximum * number of all the above objects. * - 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. * - No *need* for a memory allocator, all the kernel structures are static * and declaratively allocated. * - 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. * - Almost totally written in C with little ASM code required for ports. * . *

Related pages

* - @subpage lic_faq * - @subpage goals * - @subpage concepts * - @subpage articles * - @subpage testsuite * . */ /** * @page testsuite Test Suite *

Description

* Most of the ChibiOS/RT demos link a set of software modules (test suite) in * order to verify the proper working of the kernel, the port and the demo * itself.
* Each Test Module performs a series of tests on a specified subsystem or * subsystems and can report a failure/success status and/or a performance * index as the test suite output.
* The test suite is usually activated in the demo applications by pressing a * button on the target board, see the readme into the various demos * directories. The test suite output is usually sent through a serial port and * can be examined by using a terminal emulator program. * *

Test Modules

* - @subpage test_threads * - @subpage test_dynamic * - @subpage test_msg * - @subpage test_sem * - @subpage test_mtx * - @subpage test_events * - @subpage test_mbox * - @subpage test_queues * - @subpage test_serial * - @subpage test_heap * - @subpage test_pools * - @subpage test_benchmarks * . */ /** * @defgroup Ports Ports * This section describes the technical details for the various supported * ChibiOS/RT ports. */ /** * @defgroup Kernel Kernel * Kernel related subsystems, */ /** * @defgroup Config Configuration * In @p chconf.h are defined the required subsystems for your application. * @ingroup Kernel */ /** * @defgroup Core Port Code Templates * Non portable code templates. The function and the macros defined under this * section are the non portable part of the kernel. * @note The port code is not an API, the applications should not invoke it * directly, use the equivalent system API instead. * @ingroup Kernel */ /** * @defgroup Types Types * System types and macros. * @ingroup Kernel */ /** * @defgroup System System Management * Initialization, Locks, Interrupt Handling, Power Management, Abnormal * Termination. * @ingroup Kernel */ /** * @defgroup Debug Debug Support * Debug APIs and procedures. * @ingroup Kernel */ /** * @defgroup Scheduler Low Level Scheduler * ChibiOS/RT scheduler APIs and macros. * @ingroup Kernel */ /** * @defgroup ThreadLists Thread Lists and Queues * ChibiOS/RT thread lists and queues utilities. * @ingroup Kernel */ /** * @defgroup Threads Threads * Threads related APIs. * @ingroup Kernel */ /** * @defgroup Time Time and Virtual Timers * Time and Virtual Timers related APIs. * @ingroup Kernel */ /** * @defgroup Synchronization Synchronization * Synchronization services. */ /** * @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 (note that * mutexes are recommended for this kind of use) but also have other uses, * queues guards and counters as example.
* Semaphores usually use FIFO queues but it is possible to make them * order threads by priority by specifying CH_USE_SEMAPHORES_PRIORITY in * @p chconf.h.
* In order to use the Semaphores APIs the @p CH_USE_SEMAPHORES * option must be specified in @p chconf.h.

* @ingroup Synchronization */ /** * @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 an efficient * implementation of 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. * @ingroup Synchronization */ /** * @defgroup CondVars Condition Variables * Condition 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 Condition Variables APIs the @p CH_USE_CONDVARS * option must be specified in @p chconf.h.

* @ingroup Synchronization */ /** * @defgroup Events Event Flags * @brief Event Flags, Event Sources and Event Listeners. *

Operation mode

* Each thread has a mask of pending event flags inside its Thread structure. * Several operations are defined: * - Wait, the invoking thread goes to sleep until a certain AND/OR * combination of event flags becomes pending. * - Clear, a mask of event flags is cleared from the pending events * mask, the cleared event flags mask is returned (only the flags that were actually pending and then cleared). * - Signal, an event mask is directly ORed to the mask of the signaled * thread. * - Broadcast, each thread registered on an Event Source is signaled * with the event flags specified in its Event Listener. * - Dispatch, an events mask is scanned and for each bit set to one * an associated handler function is invoked. Bit masks are scanned from bit * zero upward. * . * An Event Source is a special object that can be "broadcasted" by a thread or * an interrupt service routine. Broadcasting an Event Source has the effect * that all the threads registered on the Event Source will be signaled with * and events mask.
* An unlimited number of Event Sources can exists in a system and each * thread can listen on an unlimited number of them.

* In order to use the Event APIs the @p CH_USE_EVENTS option must be * specified in @p chconf.h. * @ingroup Synchronization */ /** * @defgroup Messages Synchronous Messages * Synchronous inter-thread messages. *

Operation Mode

* Synchronous 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. * @ingroup Synchronization */ /** * @defgroup Mailboxes Mailboxes * Asynchronous messages. *

Operation mode

* A mailbox is an asynchronous communication mechanism.
* The following operations are possible on a mailbox: * - Post: Posts a message on the mailbox in FIFO order. * - Post Ahead: Posts a message on the mailbox with high priority. * - Fetch: A message is fetched from the mailbox and removed from * the queue. * - Reset: The mailbox is emptied and all the stored messages lost. * . * A message is a variable of type msg_t that is guaranteed to have the * same size of and be compatible with pointers (an explicit cast is needed). * If larger messages need to be exchanged then a pointer to a structure can * be posted in the mailbox but the posting side has no predefined way to * know when the message has been processed. A possible approach is to * allocate memory (from a memory pool as example) from the posting side and * free it on the fetching side. Another approach is to set a "done" flag into * the structure pointed by the message. * @ingroup Synchronization */ /** * @defgroup Memory Memory Management * Memory Management services. */ /** * @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. * @ingroup Memory */ /** * @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. * @ingroup Memory */ /** * @defgroup IO I/O Support * @brief I/O related services. * @details This section contains the I/O related services. Note that no * specific drivers are documented here, all the listed modules are abstract * interfaces or kernel APIs that the device drivers should implement/use.
* The use of common I/O interfaces allow for a certain degree of portability * for the ChibiOS/RT application among very different MCUs. */ /** * @defgroup PAL I/O Ports Abstraction Layer (PAL) * @brief I/O Ports Abstraction Layer * @details This module defines an abstract interface for digital I/O ports. * Note that most I/O ports functions are just macros. The macros * have default software implementations that can be redefined in a * @ref PAL_LLD if the target hardware supports special features like, as * example, atomic bit set/reset/masking. Please refer to the ports specific * documentation for details.
* The @ref PAL has the advantage to make the access to the I/O ports platform * independent and still be optimized for the specific architectures.
* Note that the @ref PAL_LLD may also offer non standard macro and functions * in order to support specific features but, of course, the use of such * interfaces would not be portable. Such interfaces shall be marked with * the architecture name inside the function names. * *

Implementation Rules

* In implementing an @ref PAL_LLD there are some rules/behaviors that * should be respected. * *

Writing on input pads

* The behavior is not specified but there are implementations better than * others, this is the list of possible implementations, preferred options * are on top: * -# The written value is not actually output but latched, should the pads * be reprogrammed as outputs the value would be in effect. * -# The write operation is ignored. * -# The write operation has side effects, as example disabling/enabling * pull up/down resistors or changing the pad direction. This scenario is * discouraged, please try to avoid this scenario. * . *

Reading from output pads

* The behavior is not specified but there are implementations better than * others, this is the list of possible implementations, preferred options * are on top: * -# The actual pads states are read (not the output latch). * -# The output latch value is read (regardless of the actual pads states). * -# Unspecified, please try to avoid this scenario. * . *

Writing unused or unimplemented port bits

* The behavior is not specified. * *

Reading from unused or unimplemented port bits

* The behavior is not specified. * *

Reading or writing on pins associated to other functionalities

* The behavior is not specified. * *

Usage

* The use of I/O ports requires the inclusion of the header file @p pal.h, * this file is not automatically included @p ch.h like the other header * files. * * @ingroup IO */ /** * @defgroup PAL_LLD PAL Low Level Driver * @brief @ref PAL low level driver template. * @details This file is a template for an I/O port low level driver. This * file implements the physical layer of an I/O port driver. * * @ingroup PAL */ /** * @defgroup Channels Abstract I/O Channels * @brief Abstract I/O Channels. * @details This module defines an abstract interface for I/O channels. Note * that no code is present, I/O channels are just abstract classes-like * structures, you should look at the systems as to a set of abstract C++ * classes (even if written in C). Specific device drivers can use/extend * the interfaces and implement them.
* This system has the advantage to make the access to channels * independent from the implementation logic. As example, an I/O channel * interface can hide the access to a serial driver, to a networking socket * and so on. * * @ingroup IO */ /** * @defgroup IOQueues I/O Queues * @brief I/O queues. * @details 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. * - 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.
* * @ingroup IO */ /** * @defgroup Serial Serial Drivers * @brief Generic Serial Drivers. * @details This module implements a generic full duplex serial driver. The * driver implements a @p FullDuplexDriver interface and uses I/O Queues for * communication between the upper and the lower driver. Event flags are used * to notify the application about incoming data, outgoing 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. * * @ingroup IO */ /** * @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 applications. */ /** * @defgroup CPlusPlusLibrary C++ Wrapper * @brief C++ wrapper module. * @details This module allows to use the ChibiOS/RT functionalities * from C++ as classes and objects rather the traditional "C" APIs. * * @ingroup utilities_library */ /** * @defgroup event_timer Periodic Events Timer * @brief Periodic Event 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 */