git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@643 35acf78f-673a-0410-8e92-d51de3d6d3f4
This commit is contained in:
gdisirio
parent
f8b4fca89a
commit
0810f1daac
|
|
@ -18,7 +18,7 @@ FULL_PATH_NAMES = NO
|
|||
STRIP_FROM_PATH = "C:/Documents and Settings/Administrator/"
|
||||
STRIP_FROM_INC_PATH =
|
||||
SHORT_NAMES = NO
|
||||
JAVADOC_AUTOBRIEF = YES
|
||||
JAVADOC_AUTOBRIEF = NO
|
||||
QT_AUTOBRIEF = NO
|
||||
MULTILINE_CPP_IS_BRIEF = NO
|
||||
INHERIT_DOCS = NO
|
||||
|
|
@ -84,7 +84,7 @@ WARN_LOGFILE =
|
|||
#---------------------------------------------------------------------------
|
||||
# configuration options related to the input files
|
||||
#---------------------------------------------------------------------------
|
||||
INPUT = ../src/include ../src/templates ../src ../docs/ch.txt ../src/lib ../ports/ARM7 ../ports/ARM7-AT91SAM7X/port.dox ../ports/ARM7-LPC214x/port.dox ../ports/ARMCM3 ../ports/ARMCM3-STM32F103/port.dox ../ports/MSP430 ../ports/AVR
|
||||
INPUT = ../src/include ../src/templates ../src ../docs/ch.txt ../docs/src ../src/lib ../ports/ARM7 ../ports/ARM7-AT91SAM7X/port.dox ../ports/ARM7-LPC214x/port.dox ../ports/ARMCM3 ../ports/ARMCM3-STM32F103/port.dox ../ports/MSP430 ../ports/AVR
|
||||
INPUT_ENCODING = UTF-8
|
||||
FILE_PATTERNS = *.c *.cc *.cxx *.cpp *.c++ *.d *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx *.hpp *.h++ *.idl *.odl *.cs *.php *.php3 *.inc *.m *.mm *.dox *.py *.ddf
|
||||
RECURSIVE = YES
|
||||
|
|
|
|||
181
docs/ch.txt
181
docs/ch.txt
|
|
@ -7,59 +7,57 @@
|
|||
* 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/condvars 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
|
||||
* - Free software, GPL3 licensed.
|
||||
* - Designed for realtime applications.
|
||||
* - Easily portable.
|
||||
* - Mixed programming model:
|
||||
* - Synchronous, using semaphores/mutexes/condvars and/or messages.
|
||||
* - Asynchronous, using event sources.
|
||||
* - Mix of the above models, multiple threads listening to multiple event
|
||||
* sources while serving message queues.
|
||||
* - 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.</li>
|
||||
* <li>Preemptive scheduling.</li>
|
||||
* <li>128 priority levels.</li>
|
||||
* <li>Multiple threads at the same priority level allowed.</li>
|
||||
* <li>Round robin scheduling for threads at the same priority level.</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 condvars.</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.</li>
|
||||
* <li>Threads, Semaphores, Event Sources, Virtual Timers creation/deletion at
|
||||
* runtime.</li>
|
||||
* <li>Optional, thread safe, Heap Allocator subsystem.</li>
|
||||
* <li>Optional, thread safe, Memory Pools Allocator subsystem.</li>
|
||||
* <li>Blocking and non blocking I/O channels with timeout and events generation
|
||||
* capability.</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>
|
||||
* MinGW demo available.
|
||||
* - Preemptive scheduling.
|
||||
* - 128 priority levels.
|
||||
* - Multiple threads at the same priority level allowed.
|
||||
* - Round robin scheduling for threads at the same priority level.
|
||||
* - Unlimited number of threads.
|
||||
* - Unlimited number of virtual timers.
|
||||
* - Unlimited number of semaphores.
|
||||
* - Unlimited number of mutexes.
|
||||
* - Unlimited number of condvars.
|
||||
* - Unlimited number of event sources.
|
||||
* - Unlimited number of messages in queue.
|
||||
* - Unlimited number of I/O queues.
|
||||
* - No static setup at compile time, there is no need to configure a maximum
|
||||
* number of all the above resources.
|
||||
* - No *need* for a memory allocator, all the kernel structures are static
|
||||
* and declaratively allocated.
|
||||
* - Threads, Semaphores, Event Sources, Virtual Timers creation/deletion at
|
||||
* runtime.
|
||||
* - 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.
|
||||
* - Small memory footprint, unused subsystems can be excluded by the
|
||||
* memory image.
|
||||
* - Almost totally written in C with little ASM code required for ports.
|
||||
*
|
||||
* ChibiOS/RT architecture:<br><br>
|
||||
* @subpage Concepts
|
||||
* Related pages:
|
||||
* - @subpage Concepts
|
||||
* - @subpage Articles
|
||||
*/
|
||||
|
||||
/**
|
||||
* @page Concepts Concepts
|
||||
* @{
|
||||
* @brief ChibiOS/RT Concepts and Architecture
|
||||
* @section naming Naming Conventions
|
||||
* ChibiOS/RT APIs are all named following this convention:
|
||||
* @a ch\<group\>\<action\>\<suffix\>().
|
||||
|
|
@ -236,6 +234,16 @@
|
|||
*/
|
||||
/** @} */
|
||||
|
||||
/**
|
||||
* @page Articles Articles
|
||||
* @{
|
||||
* @brief ChibiOS/RT Articles and Code Examples
|
||||
*
|
||||
* - @subpage article_atomic
|
||||
* - @subpage article_saveram
|
||||
*/
|
||||
/** @} */
|
||||
|
||||
/**
|
||||
* @defgroup Ports Ports
|
||||
* @{
|
||||
|
|
@ -351,7 +359,7 @@
|
|||
* @defgroup Heap Heap
|
||||
* @{
|
||||
* Heap Allocator related APIs.
|
||||
* <b>Operation mode</b><br><br>
|
||||
* <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>
|
||||
|
|
@ -369,7 +377,7 @@
|
|||
* @defgroup MemoryPools Memory Pools
|
||||
* @{
|
||||
* Memory Pools related APIs.
|
||||
* <b>Operation mode</b><br><br>
|
||||
* <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
|
||||
|
|
@ -383,21 +391,16 @@
|
|||
* @defgroup Semaphores Semaphores
|
||||
* @{
|
||||
* Semaphores and threads synchronization.
|
||||
* <b>Operation mode</b><br><br>
|
||||
* <h2>Operation mode</h2>
|
||||
* 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>
|
||||
* 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 but
|
||||
* also have other uses, queues guards and counters as example.<br>
|
||||
* In order to use the Semaphores APIs the @p CH_USE_SEMAPHORES
|
||||
|
|
@ -411,30 +414,26 @@
|
|||
* @defgroup Mutexes Mutexes
|
||||
* @{
|
||||
* Mutexes and threads synchronization.
|
||||
* <b>Operation mode</b><br><br>
|
||||
* <h2>Operation mode</h2>
|
||||
* 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>
|
||||
* 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>
|
||||
*
|
||||
* <b>Constraints</b><br><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 the priority
|
||||
* inheritance mechanism.
|
||||
*
|
||||
* <b>The priority inversion problem</b><br><br>
|
||||
* <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,
|
||||
|
|
@ -451,7 +450,7 @@
|
|||
* @defgroup CondVars Conditional Variables
|
||||
* @{
|
||||
* Conditional Variables and threads synchronization.
|
||||
* <b>Operation mode</b><br><br>
|
||||
* <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>
|
||||
|
|
@ -465,8 +464,8 @@
|
|||
/**
|
||||
* @defgroup Events Events
|
||||
* @{
|
||||
* Event Sources and Event Listeners.<br>
|
||||
* <b>Operation mode</b><br><br>
|
||||
* Event Sources and Event Listeners.
|
||||
* <h2>Operation mode</h2>
|
||||
* 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
|
||||
|
|
@ -488,8 +487,8 @@
|
|||
/**
|
||||
* @defgroup Messages Messages
|
||||
* @{
|
||||
* Synchronous Messages.<br>
|
||||
* <b>Operation Mode</b><br><br>
|
||||
* Synchronous inter-thread Messages.
|
||||
* <h2>Operation Mode</h2>
|
||||
* 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
|
||||
|
|
@ -517,19 +516,17 @@
|
|||
* 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>, unidirectional queue where the writer is the
|
||||
* lower side and the reader is the upper side.</li>
|
||||
* <li><b>Output queue</b>, unidirectional 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>
|
||||
* - <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>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.
|
||||
* - <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>
|
||||
* In order to use the half duplex queues the @p CH_USE_QUEUES_HALFDUPLEX
|
||||
|
|
|
|||
|
|
@ -0,0 +1,50 @@
|
|||
/**
|
||||
* @page article_atomic Invoking multiple primitives as a single atomic operation
|
||||
* @{
|
||||
* It is often necessary to invoke multiple operations involving a
|
||||
* reschedulation as a single atomic operation.<br>
|
||||
* ChibiOS/RT already implements APIs that perform complex operations, as
|
||||
* example the API @p chSemSignalWait() performs two operations atomically.<br>
|
||||
* If more complex operations are required in your application then it is
|
||||
* possible to build macro-operations, see the following example:
|
||||
* @code
|
||||
chSysLock();
|
||||
|
||||
chSemSignalI(&sem1);
|
||||
chSemSignalI(&sem2);
|
||||
if (tp != NULL) {
|
||||
chThdResumeI(tp);
|
||||
tp = NULL;
|
||||
}
|
||||
chSchRescheduleS();
|
||||
|
||||
chSysUnlock();
|
||||
* @endcode
|
||||
* The above example performs a signal operation on two semaphores, optionally
|
||||
* resumes a thread, and performs a final reschedulation. The three operations
|
||||
* are performed atomically.<br>
|
||||
* An hypotetical @p chSemSignalSignalWait() operation could be implemented as
|
||||
* follow:
|
||||
* @code
|
||||
chSysLock();
|
||||
|
||||
chSemSignalI(&sem1);
|
||||
chSemSignalI(&sem2);
|
||||
/*
|
||||
* The "if" is required because the chSemWaitS() does not always internally
|
||||
* reschedule.
|
||||
*/
|
||||
if (chSemGetCounter(&sem3) <= 0)
|
||||
chSemWaitS(&Sem3);
|
||||
else {
|
||||
chSemFastWaitS(&sem3);
|
||||
chSchRescheduleS();
|
||||
}
|
||||
|
||||
chSysUnlock();
|
||||
* @endcode
|
||||
* In general multiple I-Class APIs can be included and the block is terminated
|
||||
* by an S-Class API that performs a reschedulation. Optionally a
|
||||
* @p chSchRescheduleS() is present at the very end of the block.
|
||||
*/
|
||||
/** @} */
|
||||
|
|
@ -0,0 +1,66 @@
|
|||
/**
|
||||
* @page article_saveram Saving RAM by declaring thread functions "noreturn"
|
||||
* @{
|
||||
* One of the problems, when writing embedded multi-threaded applications,
|
||||
* is that the thread functions do save the registers in the function
|
||||
* entry code even if the system does not require it, exiting such
|
||||
* a function would terminate the thread so there is no need to preserve
|
||||
* the register values. This can waste tens of bytes for each thread.<br>
|
||||
* Consider the following code:
|
||||
* @code
|
||||
#include <ch.h>
|
||||
|
||||
static WORKING_AREA(waMyThread, 64);
|
||||
|
||||
static t_msg MyThread(void *arg) {
|
||||
|
||||
while (!chThdShoudTerminate()) {
|
||||
/* Do thread inner work */
|
||||
}
|
||||
return 1;
|
||||
}
|
||||
|
||||
main() {
|
||||
chSysInit();
|
||||
...
|
||||
chThdCreate(NORMALPRIO, 0, waMyThread, sizeof(waMyThread), MyThread, NULL);
|
||||
...
|
||||
chSysPause();
|
||||
}
|
||||
* @endcode
|
||||
* The resulting ASM code for the thread function would be something like this:
|
||||
* @code
|
||||
MyThread:
|
||||
stmfd sp!, {r4, r5, r6, lr}
|
||||
...
|
||||
ldmfd sp!, {r4, r5, r6, pc}
|
||||
* @endcode
|
||||
* Being that function a thread there is no need to save those registers, in
|
||||
* embedded applications often the RAM is a scarce resource. That space can be
|
||||
* saved by modifying the code as follow, using some advanced GCC extensions:
|
||||
* @code
|
||||
#include <ch.h>
|
||||
|
||||
static BYTE8 waMyThread[UserStackSize(64)];
|
||||
|
||||
__attribute__((noreturn)) void MyThread(void *arg) {
|
||||
|
||||
while (!chThdShoudTerminate()) {
|
||||
/* Do thread inner work */
|
||||
}
|
||||
chThdExit(1);
|
||||
}
|
||||
|
||||
main() {
|
||||
chSysInit();
|
||||
...
|
||||
chThdCreate(NORMALPRIO, 0, waMyThread, sizeof(waMyThread), (t_tfunc)MyThread, NULL);
|
||||
...
|
||||
chSysPause();
|
||||
}
|
||||
* @endcode
|
||||
* This will make GCC believe that the function cannot return and there is no
|
||||
* need to save registers. The code will be a bit less readable and less
|
||||
* portable on other compilers however.
|
||||
*/
|
||||
/** @} */
|
||||
|
|
@ -84,6 +84,8 @@ CH_IRQ_HANDLER void SysTickVector(void) {
|
|||
|
||||
/**
|
||||
* The SVC vector is used for commanded context switch.
|
||||
* @param otp the thread to be switched out
|
||||
* @param ntp the thread to be switched it
|
||||
*/
|
||||
/** @cond never */
|
||||
__attribute__((naked))
|
||||
|
|
|
|||
|
|
@ -85,6 +85,8 @@ Win32-MinGW - ChibiOS/RT simulator and demo into a WIN32 process,
|
|||
- Introduced the concept of interrupt classes, see the documentation.
|
||||
- Introduced the concept of system states, see the documentation.
|
||||
- Huge improvements to the ports documentation.
|
||||
- Articles and notes previously in the wiki now merged in the general
|
||||
documentation, the wiki entries are obsolete and will be removed.
|
||||
|
||||
*** 1.0.0rc2 ***
|
||||
- FIX: Removed unused variable "retaddr" from the Cortex-M3 port.
|
||||
|
|
|
|||
Loading…
Reference in New Issue