490 lines
19 KiB
Plaintext
490 lines
19 KiB
Plaintext
/*
|
|
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 <http://www.gnu.org/licenses/>.
|
|
*/
|
|
|
|
/**
|
|
* @mainpage ChibiOS/RT
|
|
* @author Giovanni Di Sirio (gdisirio@users.sourceforge.net).
|
|
*
|
|
* <h2>Chibi ?</h2>
|
|
* 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 (<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>.
|
|
*
|
|
* <h2>Features</h2>
|
|
* - 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.<br>
|
|
* 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.
|
|
* .
|
|
* <h2>Related pages</h2>
|
|
* - @subpage lic_faq
|
|
* - @subpage goals
|
|
* - @subpage concepts
|
|
* - @subpage articles
|
|
* - @subpage testsuite
|
|
* .
|
|
*/
|
|
|
|
/**
|
|
* @page testsuite Test Suite
|
|
* <h2>Description</h2>
|
|
* 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.<br>
|
|
* 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.<br>
|
|
* 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.
|
|
*
|
|
* <h2>Test Modules</h2>
|
|
* - @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 Memory Memory Management
|
|
* Memory Management services.
|
|
*/
|
|
|
|
/**
|
|
* @defgroup Heap Heap
|
|
* Heap Allocator related APIs.
|
|
* <h2>Operation mode</h2>
|
|
* 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.<br>
|
|
* 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.<br>
|
|
* 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.
|
|
* <h2>Operation mode</h2>
|
|
* The Memory Pools APIs allow to allocate/free fixed size objects in
|
|
* <b>constant time</b> and reliably without memory fragmentation problems.<br>
|
|
* In order to use the Time APIs the @p CH_USE_MEMPOOLS option must be
|
|
* specified in @p chconf.h.
|
|
* @ingroup Memory
|
|
*/
|
|
|
|
/**
|
|
* @defgroup Synchronization Synchronization
|
|
* Synchronization services.
|
|
*/
|
|
|
|
/**
|
|
* @defgroup Semaphores Semaphores
|
|
* Semaphores and threads synchronization.
|
|
* <h2>Operation mode</h2>
|
|
* A semaphore is a threads synchronization object, some operations
|
|
* are defined on semaphores:
|
|
* - <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.
|
|
* - <b>Wait</b>: The semaphore counter is decreased and if the result
|
|
* becomes negative the thread is queued in the semaphore and suspended.
|
|
* - <b>Reset</b>: 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.<br>
|
|
* 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.<br>
|
|
* In order to use the Semaphores APIs the @p CH_USE_SEMAPHORES
|
|
* option must be specified in @p chconf.h.<br><br>
|
|
* @ingroup Synchronization
|
|
*/
|
|
|
|
/**
|
|
* @defgroup Mutexes Mutexes
|
|
* Mutexes and threads synchronization.
|
|
* <h2>Operation mode</h2>
|
|
* A mutex is a threads synchronization object, some operations are defined
|
|
* on mutexes:
|
|
* - <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.
|
|
* - <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.
|
|
* .
|
|
* In order to use the Event APIs the @p CH_USE_MUTEXES option must be
|
|
* specified in @p chconf.h.<br>
|
|
*
|
|
* <h2>Constraints</h2>
|
|
* 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.
|
|
*
|
|
* <h2>The priority inversion problem</h2>
|
|
* 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.
|
|
* @ingroup Synchronization
|
|
*/
|
|
|
|
/**
|
|
* @defgroup CondVars Condition Variables
|
|
* Condition Variables and threads synchronization.
|
|
* <h2>Operation mode</h2>
|
|
* 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.<br>
|
|
* In order to use the Condition Variables APIs the @p CH_USE_CONDVARS
|
|
* option must be specified in @p chconf.h.<br><br>
|
|
* @ingroup Synchronization
|
|
*/
|
|
|
|
/**
|
|
* @defgroup Events Event Flags
|
|
* @brief Event Flags, Event Sources and Event Listeners.
|
|
* <h2>Operation mode</h2>
|
|
* Each thread has a mask of pending event flags inside its Thread structure.
|
|
* Several operations are defined:
|
|
* - <b>Wait</b>, the invoking thread goes to sleep until a certain AND/OR
|
|
* combination of event flags becomes pending.
|
|
* - <b>Clear</b>, 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).
|
|
* - <b>Signal</b>, an event mask is directly ORed to the mask of the signaled
|
|
* thread.
|
|
* - <b>Broadcast</b>, each thread registered on an Event Source is signaled
|
|
* with the event flags specified in its Event Listener.
|
|
* - <b>Dispatch</b>, 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.<br>
|
|
* An unlimited number of Event Sources can exists in a system and each
|
|
* thread can listen on an unlimited number of them.<br><br>
|
|
* 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.
|
|
* <h2>Operation Mode</h2>
|
|
* 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.<br>
|
|
* 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.<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.
|
|
* @ingroup Synchronization
|
|
*/
|
|
|
|
/**
|
|
* @defgroup Mailboxes Mailboxes
|
|
* Asynchronous messages.
|
|
* <h2>Operation mode</h2>
|
|
* A mailbox is an asynchronous communication mechanism.<br>
|
|
* The following operations are possible on a mailbox:
|
|
* - <b>Post</b>: Posts a message on the mailbox in FIFO order.
|
|
* - <b>Post Ahead</b>: Posts a message on the mailbox with high priority.
|
|
* - <b>Fetch</b>: A message is fetched from the mailbox and removed from
|
|
* the queue.
|
|
* - <b>Reset</b>: 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 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.<br>
|
|
* The use of common I/O interfaces allow for a certain degree of portability
|
|
* for the ChibiOS/RT application among very different MCUs.
|
|
*/
|
|
|
|
/**
|
|
* @defgroup IOPorts Abstract I/O Ports
|
|
* @brief Abstract digital I/O ports.
|
|
* @details This module defines an abstract interface for digital I/O ports.
|
|
* Note that no code is present, I/O ports are just a set of macros that must
|
|
* be implemented by a low level I/O port driver.<br>
|
|
* Currently the I/O ports interface does not handle physical port programming
|
|
* like direction, pull up/down resistors etc. The interface only allows input
|
|
* and output operations but this may change in future releases.
|
|
* This system has the advantage to make the access to I/O ports platform
|
|
* independent from the implementation logic.
|
|
*
|
|
* <h2>Implementation Rules</h2>
|
|
* In implementing an I/O port low level driver there are some rules that
|
|
* should be respected.
|
|
*
|
|
* <h3>Write on input pads</h3>
|
|
* 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.
|
|
* .
|
|
* <h3>Read from output pads</h3>
|
|
* 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.
|
|
* .
|
|
* <h3>Writing unused or unimplemented port bits</h3>
|
|
* The behavior is not specified.
|
|
*
|
|
* <h3>Reading from unused or unimplemented port bits</h3>
|
|
* The behavior is not specified.
|
|
*
|
|
* <h3>Reading or writing on pins associated to other functionalities</h3>
|
|
* The behavior is not specified.
|
|
*
|
|
* @ingroup IO
|
|
*/
|
|
|
|
/**
|
|
* @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.<br>
|
|
* 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).<br>
|
|
* There are several kind of queues:<br>
|
|
* - <b>Input queue</b>, unidirectional queue where the writer is the
|
|
* lower side and the reader is the upper side.
|
|
* - <b>Output queue</b>, unidirectional queue where the writer is the
|
|
* upper side and the reader is the lower side.
|
|
* - <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.
|
|
* .
|
|
* In order to use the I/O queues the @p CH_USE_QUEUES option must
|
|
* be specified in @p chconf.h.<br>
|
|
*
|
|
* @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.<br>
|
|
* 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.
|
|
*
|
|
* @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.
|
|
* <h2>Notes</h2>
|
|
* 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.<br>
|
|
* 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
|
|
*/
|
|
|