deon/gnuk
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

import ChibiOS 2.0.8

Browse Source
This commit is contained in:
NIIBE Yutaka
2010-11-30 13:54:43 +09:00
parent 27543cfeca
commit c560d0ad0c
1982 changed files with 5318 additions and 4046 deletions
Download Patch File Download Diff File Expand all files Collapse all files

268
ChibiOS_2.0.8/docs/src/architecture.dox Normal file
View File

@@ -0,0 +1,268 @@
/*
ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 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/>.
---
A special exception to the GPL can be applied should you wish to distribute
a combined work that includes ChibiOS/RT, without being obliged to provide
the source code for any proprietary components. See the file exception.txt
for full details of how and when the exception can be applied.
*/
/**
* @page architecture Architecture
* @brief ChibiOS/RT General Architecture
* - @ref components
* - @ref dependencies
* - @ref kernel_arch
* - @ref hal_arch
* .
* @section components Components
* ChibiOS/RT is composed of several major components, each component can be
* composed of one of more subsystems. The main components are:
* - <b>Kernel</b>, this is the platform independent part of the OS kernel.
* - <b>HAL</b>, this component contains a set of abstract device drivers
* that offer a common I/O API to the application across all the support
* platforms. The HAL code is totally portable across platforms.
* - <b>Port</b>, this is the platform dependent part of the OS kernel. This
* component is responsible of the system startup, interrupts abstraction,
* lock/unlock primitives, context switch related structures and code.<br>
* The component usually contains very little code because the OS is very
* portable but the quality of the implementation of the Port component
* affects heavily the performance of the ported OS. It is probably the
* most critical part of the whole OS.
* - <b>Platform</b>, this component contains a set of device drivers
* implementations.
* - <b>Various</b>, a library of various extra components that do not belong
* to any particular component but can make life easier while developing an
* embedded application.
* .
* @section dependencies Dependencies
* The following diagram shows the relationships among the various components
* that compose the system:<br><br>
* @dot
digraph example {
node [shape=rectangle, fontname=Helvetica, fontsize=8,
fixedsize="true", width="1.0", height="0.25"];
edge [fontname=Helvetica, fontsize=8];
Application [label="Application"];
HAL [label="HAL"];
Platform [label="Platform"];
Kernel [label="Kernel"];
Port [label="Port"];
HW [label="Hardware", style="filled", width="3.0", height="0.3"];
Application -> Kernel;
Application -> HAL;
Application -> HW [label=" (not recommended)"];
HAL -> Platform;
HAL -> Kernel;
Platform -> Kernel;
Platform -> HW;
Kernel -> Port;
Port -> HW;
}
* @enddot
*
* @section kernel_arch Kernel Architecture
* The kernel itself is very modular and is composed of several subsystems,
* most subsystems are optional and can be switched of in the kernel
* configuration file @p chconf.h.<br>
* The current kernel subsystems are divided in five categories:
* - @ref base, this category contains the mandatory kernel
* subsystems:
* - @ref system, low level locks, initialization.
* - @ref time, virtual timers and time APIs.
* - @ref scheduler, scheduler APIs, all the higher level synchronization
* mechanism are implemented through this subsystem, it is very flexible
* but not recommended for direct use in user code.
* - @ref threads, thread-related APIs.
* .
* Base services diagram:<br><br>
* @dot
digraph example {
node [shape=rectangle, fontname=Helvetica, fontsize=8,
fixedsize="true", width="1.0", height="0.25"];
edge [fontname=Helvetica, fontsize=8];
Threads -> Scheduler;
Scheduler-> System;
Scheduler-> Timers;
System-> Timers;
}
* @enddot
* - @ref synchronization, this category contains the synchronization-related
* subsystems, each one of the provided mechanism can be configured out of
* the kernel if not needed.
* - @ref semaphores, counter semaphores subsystem.
* - @ref mutexes, mutexes subsystem with support to the priority inheritance
* algorithm (fully implemented, any depht).
* - @ref condvars, condition variables, together with mutexes the condition
* variables allow the implementation of monitor constructs.
* - @ref events, event sources and event flags with flexible support for
* and/or conditions and automatic dispatching to handler functions.
* - @ref messages, lightweight synchronous messages.
* - @ref mailboxes, asynchronous messages queues.
* .
* All the synchronization mechanisms are built on top of the Scheduler APIs
* except Mailboxes that are build on top of Semaphores and Condition
* Variables that implicitly refer to Mutexes:<br><br>
* @dot
digraph example {
node [shape=rectangle, fontname=Helvetica, fontsize=8,
fixedsize="true", width="1.0", height="0.25"];
edge [fontname=Helvetica, fontsize=8];
Semaphores -> Scheduler;
Mutexes -> Scheduler;
Condvars -> Scheduler;
Condvars -> Mutexes;
Events -> Scheduler;
Messages -> Scheduler;
Mailboxes -> Semaphores;
}
* @enddot
* - @ref memory, memory management, multiple non-alternative schemes are
* available:
* - @ref memcore, centralized core memory manager, this subsystems is used
* by the other allocators in order to get chunks of memory in a consistent
* way.
* - @ref heaps, central heap manager using a first fit strategy, it also
* allow the creation of multiple heaps in order to handle non uniform
* memory areas.
* - @ref pools, very fast fixed size objects allocator.
* - @ref threads (dynamic), usually threads are static objects in ChibiOS/RT
* but there is the option for dynamic threads management, please see the
* article @ref article_lifecycle.
* .
* The various allocators follow a precise hierarchy:<br><br>
* @dot
digraph example {
node [shape=rectangle, fontname=Helvetica, fontsize=8,
fixedsize="true", width="1.0", height="0.25"];
edge [fontname=Helvetica, fontsize=8];
Core [label="Core Allocator"];
Dynamic [label="Dynamic Threads"];
Heaps [label="Dynamic Heaps"];
Pools [label="Memory Pools"];
C [label="C-runtime"];
Dynamic -> Heaps;
Dynamic -> Pools;
Heaps -> Core;
Pools -> Core;
C -> Core;
}
* @enddot
* Please also see the article @ref article_manage_memory.
* - @ref io_support, the kernel also provides mechanisms and abstract data
* interfaces that can be used by non-kernel components, the HAL as example.
* - @ref data_streams, abstract streams interface.
* - @ref io_channels, abstract I/O channels that inherits from the abstract
* stream interface.
* - @ref io_queues, generic, byte wide, I/O queues APIs.
* .
* - @ref debug, debug services and APIs. The @ref registry susystem can be
* seen as part of the debug category even if it finds use in non-debug
* roles.
* .
* @section hal_arch HAL Architecture
* The HAL is a collection of abstract device drivers, it relies on the
* Platform component for the low level implementation on specific
* hardware.<br>
* The current internal HAL organization is the following:<br><br>
* @dot
digraph example {
rankdir="LR";
node [shape=rectangle, fontname=Helvetica, fontsize=8,
fixedsize="true", width="1.0", height="0.25"];
edge [fontname=Helvetica, fontsize=8];
subgraph cluster_HAL {
node [shape=rectangle, fontname=Helvetica, fontsize=8,
fixedsize="true", width="0.6", height="0.25"];
ADC [label="ADC"];
CAN [label="CAN"];
HAL [label="HAL"];
MAC [label="MAC"];
PAL [label="PAL"];
PWM [label="PWM"];
SER [label="SER"];
SPI [label="SPI"];
MMC_SD [label="MMC/SD"];
color = blue;
label = "HAL";
}
subgraph cluster_Platform {
node [shape=rectangle, fontname=Helvetica, fontsize=8,
fixedsize="true", width="0.6", height="0.25"];
ADC_LLD [label="ADC_LLD"];
CAN_LLD [label="CAN_LLD"];
HAL_LLD [label="HAL_LLD"];
MAC_LLD [label="MAC_LLD"];
PAL_LLD [label="PAL_LLD"];
PWM_LLD [label="PWM_LLD"];
SER_LLD [label="SER_LLD"];
SPI_LLD [label="SPI_LLD"];
color = blue;
label = "Platform";
}
node [shape=rectangle, fontname=Helvetica, fontsize=8,
fixedsize="true", width="1", height="0.5"];
edge [fontname=Helvetica, fontsize=8];
Application [label="Application"];
HW [label="Hardware", style="filled"];
ADC -> ADC_LLD;
CAN -> CAN_LLD;
HAL -> HAL_LLD;
MAC -> MAC_LLD;
PAL -> PAL_LLD;
PWM -> PWM_LLD;
SER -> SER_LLD;
SPI -> SPI_LLD;
MMC_SD -> SPI [constraint=false];
Application -> ADC;
Application -> CAN;
Application -> HAL;
Application -> MAC;
Application -> PAL;
Application -> PWM;
Application -> SER;
Application -> SPI;
Application -> MMC_SD;
ADC_LLD -> HW;
CAN_LLD -> HW;
HAL_LLD -> HW;
MAC_LLD -> HW;
PAL_LLD -> HW;
PWM_LLD -> HW;
SER_LLD -> HW;
SPI_LLD -> HW;
}
* @enddot
* <br>
* See @ref IO for details about the various HAL subsystems.
*/

73
ChibiOS_2.0.8/docs/src/articles.dox Normal file
View File

@@ -0,0 +1,73 @@
/*
ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 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/>.
---
A special exception to the GPL can be applied should you wish to distribute
a combined work that includes ChibiOS/RT, without being obliged to provide
the source code for any proprietary components. See the file exception.txt
for full details of how and when the exception can be applied.
*/
/**
* @page articles Articles and Code Samples
* ChibiOS/RT Articles and Code Samples:
* - @subpage page_general
* - @subpage page_kb
* - @subpage page_howtos
* .
*/
/**
* @page page_general General
* Articles and guides not necessarily related to ChibiOS/RT.
* - @subpage article_eclipse
* - @subpage article_eclipse2
* - @subpage article_jitter
* .
*/
/**
* @page page_kb Knowledge Base
* Articles and guides about ChibiOS/RT.
* - @subpage article_integrationguide
* - @subpage article_portguide
* - @subpage article_events
* - @subpage article_debug
* - @subpage article_stacks
* - @subpage article_roundrobin
* - @subpage article_lifecycle
* - @subpage article_mutual_exclusion
* - @subpage article_atomic
* - @subpage article_saveram
* - @subpage article_timing
* - @subpage article_design
* .
*/
/**
* @page page_howtos How To's
* Articles describing how to implement specific tasks using ChibiOS/RT.
* - @subpage article_create_thread
* - @subpage article_interrupts
* - @subpage article_wakeup
* - @subpage article_manage_memory
* - @subpage article_stop_os
* .
*/

64
ChibiOS_2.0.8/docs/src/atomic.dox Normal file
View File

@@ -0,0 +1,64 @@
/*
ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 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/>.
---
A special exception to the GPL can be applied should you wish to distribute
a combined work that includes ChibiOS/RT, without being obliged to provide
the source code for any proprietary components. See the file exception.txt
for full details of how and when the exception can be applied.
*/
/**
* @page article_atomic Invoking multiple primitives as a single atomic operation
* It is often necessary to invoke multiple operations involving a
* reschedule 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);
chMtxUnlockS();
chSchRescheduleS();
chSysUnlock();
* @endcode
* The above example performs a signal operation on two semaphores, unlocks the
* last acquired mutex and finally performs a reschedule. All the operations
* are performed atomically.<br>
* An hypothetical @p chSemSignalSignalWait() operation could be implemented as
* follow:
* @code
chSysLock();
chSemSignalI(&sem1);
chSemSignalI(&sem2);
chSemWaitS(&Sem3); /* May reschedule or not. */
chSchRescheduleS(); /* This one reschedules if necessary. */
chSysUnlock();
* @endcode
* In general multiple @ref I-Class and (non rescheduling) @ref S-Class APIs
* can be included and the block is terminated by a rescheduling @ref S-Class
* API. An extra @p chSchRescheduleS() can be present at the very end of the
* block, it only reschedules if a reschedule is still required.
*/

290
ChibiOS_2.0.8/docs/src/concepts.dox Normal file
View File

@@ -0,0 +1,290 @@
/*
ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 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/>.
---
A special exception to the GPL can be applied should you wish to distribute
a combined work that includes ChibiOS/RT, without being obliged to provide
the source code for any proprietary components. See the file exception.txt
for full details of how and when the exception can be applied.
*/
/**
* @page concepts Kernel Concepts
* @brief ChibiOS/RT Kernel Concepts
* - @ref naming
* - @ref api_suffixes
* - @ref interrupt_classes
* - @ref system_states
* - @ref scheduling
* - @ref thread_states
* - @ref priority
* - @ref warea
* .
* @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 Time, @a VT, @a Thd, @a Sem,
* @a Mtx, @a Cond, @a Evt, @a Msg, @a SequentialStream, @a IO, @a IQ, @a OQ,
* @a Dbg, @a Core, @a Heap, @a Pool.
*
* @section api_suffixes API Names Suffixes
* The suffix can be one of the following:
* - <b>None</b>, APIs without any suffix can be invoked only from the user
* code in the <b>Normal</b> state unless differently specified. See
* @ref system_states.
* - @anchor I-Class <b>"I"</b>, I-Class APIs are invokable only from the
* <b>I-Locked</b> or <b>S-Locked</b> states. See @ref system_states.
* - @anchor S-Class <b>"S"</b>, S-Class APIs are invokable only from the
* <b>S-Locked</b> state. See @ref system_states.
* .
* Examples: @p chThdCreateStatic(), @p chSemSignalI(), @p chIQGetTimeout().
*
* @section interrupt_classes Interrupt Classes
* In ChibiOS/RT there are three logical interrupt classes:
* - <b>Regular Interrupts</b>. Maskable interrupt sources that cannot
* preempt (small parts of) the kernel code and are thus able to invoke
* operating system APIs from within their handlers. The interrupt handlers
* belonging to this class must be written following some rules. See the
* @ref system APIs group and @ref article_interrupts.
* - <b>Fast Interrupts</b>. Maskable interrupt sources with the ability
* to preempt the kernel code and thus have a lower latency and are less
* subject to jitter, see @ref article_jitter. Such sources are not
* supported on all the architectures.<br>
* Fast interrupts are not allowed to invoke any operating system API from
* within their handlers. Fast interrupt sources may, however, pend a lower
* priority regular interrupt where access to the operating system is
* possible.
* - <b>Non Maskable Interrupts</b>. Non maskable interrupt sources are
* totally out of the operating system control and have the lowest latency.
* Such sources are not supported on all the architectures.
* .
* The mapping of the above logical classes into physical interrupts priorities
* is, of course, port dependent. See the documentation of the various ports
* for details.
*
* @section system_states System States
* When using ChibiOS/RT the system can be in one of the following logical
* operating states:
* - <b>Init</b>. When the system is in this state all the maskable
* interrupt sources are disabled. In this state it is not possible to use
* any system API except @p chSysInit(). This state is entered after a
* physical reset.
* - <b>Normal</b>. All the interrupt sources are enabled and the system APIs
* are accessible, threads are running.
* - <b>Suspended</b>. In this state the fast interrupt sources are enabled but
* the regular interrupt sources are not. In this state it is not possible
* to use any system API except @p chSysDisable() or @p chSysEnable() in
* order to change state.
* - <b>Disabled</b>. When the system is in this state both the maskable
* regular and fast interrupt sources are disabled. In this state it is not
* possible to use any system API except @p chSysSuspend() or
* @p chSysEnable() in order to change state.
* - <b>Sleep</b>. Architecture-dependent low power mode, the idle thread
* goes in this state and waits for interrupts, after servicing the interrupt
* the Normal state is restored and the scheduler has a chance to reschedule.
* - <b>S-Locked</b>. Kernel locked and regular interrupt sources disabled.
* Fast interrupt sources are enabled. @ref S-Class and @ref I-Class APIs are
* invokable in this state.
* - <b>I-Locked</b>. Kernel locked and regular interrupt sources disabled.
* @ref I-Class APIs are invokable from this state.
* - <b>Serving Regular Interrupt</b>. No system APIs are accessible but it is
* possible to switch to the I-Locked state using @p chSysLockFromIsr() and
* then invoke any @ref I-Class API. Interrupt handlers can be preemptable on
* some architectures thus is important to switch to I-Locked state before
* invoking system APIs.
* - <b>Serving Fast Interrupt</b>. System APIs are not accessible.
* - <b>Serving Non-Maskable Interrupt</b>. System APIs are not accessible.
* - <b>Halted</b>. All interrupt sources are disabled and system stopped into
* an infinite loop. This state can be reached if the debug mode is activated
* <b>and</b> an error is detected <b>or</b> after explicitly invoking
* @p chSysHalt().
* .
* Note that the above states are just <b>Logical States</b> that may have no
* real associated machine state on some architectures. The following diagram
* shows the possible transitions between the states:
*
* @dot
digraph example {
rankdir="LR";
node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true", width="0.75", height="0.75"];
edge [fontname=Helvetica, fontsize=8];
init [label="Init", style="bold"];
norm [label="Normal", shape=doublecircle];
susp [label="Suspended"];
disab [label="Disabled"];
slock [label="S-Locked"];
ilock [label="I-Locked"];
slock [label="S-Locked"];
sleep [label="Sleep"];
sri [label="SRI"];
init -> norm [label="chSysInit()"];
norm -> slock [label="chSysLock()", constraint=false];
slock -> norm [label="chSysUnlock()"];
norm -> susp [label="chSysSuspend()"];
susp -> disab [label="chSysDisable()"];
norm -> disab [label="chSysDisable()"];
susp -> norm [label="chSysEnable()"];
disab -> norm [label="chSysEnable()"];
slock -> ilock [label="Context Switch", dir="both"];
norm -> sri [label="Regular IRQ", style="dotted"];
sri -> norm [label="Regular IRQ return", fontname=Helvetica, fontsize=8];
sri -> ilock [label="chSysLockFromIsr()", constraint=false];
ilock -> sri [label="chSysUnlockFromIsr()", fontsize=8];
norm -> sleep [label="Idle Thread"];
sleep -> sri [label="Regular IRQ", style="dotted"];
}
* @enddot
* Note, the <b>SFI</b>, <b>Halted</b> and <b>SNMI</b> states were not shown
* because those are reachable from most states:
*
* @dot
digraph example {
rankdir="LR";
node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true", width="0.75", height="0.75"];
edge [fontname=Helvetica, fontsize=8];
any1 [label="Any State\nexcept *"];
any2 [label="Any State"];
sfi [label="SFI"];
halt [label="Halted"];
SNMI [label="SNMI"];
any1 -> sfi [style="dotted", label="Fast IRQ"];
sfi -> any1 [label="Fast IRQ return"];
any2 -> halt [label="chSysHalt()"];
any2 -> SNMI [label="Synchronous NMI"];
any2 -> SNMI [label="Asynchronous NMI", style="dotted"];
SNMI -> any2 [label="NMI return"];
halt -> SNMI [label="Asynchronous NMI", style="dotted"];
SNMI -> halt [label="NMI return"];
}
* @enddot
* @attention * except: <b>Init</b>, <b>Halt</b>, <b>SNMI</b>, <b>Disabled</b>.
*
* @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.<br><br>
* @dot
digraph example {
rankdir="LR";
node [shape=square, fontname=Helvetica, fontsize=8,
fixedsize="true", width="0.6", height="0.5"];
edge [fontname=Helvetica, fontsize=8];
subgraph cluster_running {
node [shape=square, fontname=Helvetica, fontsize=8,
fixedsize="true", width="0.6", height="0.5"];
currp [label="'currp'\npointer", style="bold"];
T4 [label="Tuser(4)\nprio=100"];
label = "Currently Running Thread";
penwidth = 0;
}
subgraph cluster_rlist {
node [shape=square, fontname=Helvetica, fontsize=8,
fixedsize="true", width="0.6", height="0.5"];
rh [label="ready list\nheader\nprio=0", style="bold"];
Ti [label="Tidle\nprio=1"];
Tm [label="Tmain\nprio=64"];
T1 [label="Tuser(1)\nprio=32"];
T2 [label="Tuser(2)\nprio=32"];
T3 [label="Tuser(3)\nprio=80"];
label = "Threads Ready for Execution";
penwidth = 0;
}
currp -> T4
rh -> Ti -> T1 -> T2 -> Tm -> T3 -> rh [label="p_next"];
rh -> T3 -> Tm -> T2 -> T1 -> Ti -> rh [label="p_prev"];
}
* @enddot
* <br>
* 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 thread_states Threads States
* The image shows how threads can change their state in ChibiOS/RT.<br>
* @dot
digraph example {
/*rankdir="LR";*/
node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true", width="0.75", height="0.75"];
edge [fontname=Helvetica, fontsize=8];
start [label="Start", style="bold"];
run [label="Running"];
ready [label="Ready"];
suspend [label="Suspended"];
sleep [label="Sleeping"];
stop [label="Stop", style="bold"];
start -> suspend [label="chThdInit()", constraint=false];
start -> run [label="chThdCreate()"];
start -> ready [label="chThdCreate()"];
run -> ready [label="Reschedule", dir="both"];
suspend -> run [label="chThdResume()"];
suspend -> ready [label="chThdResume()"];
run -> sleep [label="chSchGoSleepS()"];
sleep -> run [label="chSchWakepS()"];
sleep -> ready [label="chSchWakepS()"];
run -> stop [label="chThdExit()"];
}
* @enddot
*
* @section priority Priority Levels
* Priorities in ChibiOS/RT are a contiguous numerical range but the initial
* and final values are not enforced.<br>
* The following table describes the various priority boundaries (from lowest
* to highest):
* - @p IDLEPRIO, this is the lowest priority level and is reserved for the
* idle thread, no other threads should share this priority level. This is
* the lowest numerical value of the priorities space.
* - @p LOWPRIO, the lowest priority level that can be assigned to an user
* thread.
* - @p NORMALPRIO, this is the central priority level for user threads. It is
* advisable to assign priorities to threads as values relative to
* @p NORMALPRIO, as example NORMALPRIO-1 or NORMALPRIO+4, this ensures the
* portability of code should the numerical range change in future
* implementations.
* - @p HIGHPRIO, the highest priority level that can be assigned to an user
* thread.
* - @p ABSPRO, absolute maximum software priority level, it can be higher than
* @p HIGHPRIO but the numerical values above @p HIGHPRIO up to @p ABSPRIO
* (inclusive) are reserved. This is the highest numerical value of the
* priorities space.
* .
* @section warea Threads Working Area
* Each thread has its own stack, a Thread structure and some preemption
* areas. All the structures are allocated into a "Thread Working Area",
* a thread private heap, usually statically declared in your code.
* Threads do not use any memory outside the allocated working area
* except when accessing static shared data.<br><br>
* @image html workspace.png
* <br>
* Note that the preemption area is only present when the thread is not
* running (switched out), 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.
* The preemption area can be divided in up to three structures:
* - External Context.
* - Interrupt Stack.
* - Internal Context.
* .
* See the @ref core documentation for details, the area may change on
* the various ports and some structures may not be present (or be zero-sized).
*/

194
ChibiOS_2.0.8/docs/src/createthread.dox Normal file
View File

@@ -0,0 +1,194 @@
/*
ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 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/>.
---
A special exception to the GPL can be applied should you wish to distribute
a combined work that includes ChibiOS/RT, without being obliged to provide
the source code for any proprietary components. See the file exception.txt
for full details of how and when the exception can be applied.
*/
/**
* @page article_create_thread How to create a thread
* At the system startup there are already two active threads:
* - <b>Idle thread</b>. This thread has the lowest priority in the system so
* it runs only when the other threads in the system are sleeping. This
* threads usually switches the system in a low power mode and does nothing
* else.
* - <b>Main thread</b>. This thread executes your @p main() function at
* startup. The main thread is created at the @p NORMALPRIO level but it
* can change its own priority if required. It is from the main thread
* that the other threads are usually created.
* .
* There are two kind of threads in ChibiOS/RT:
* - <b>Static Threads</b>. This kind of threads are statically allocated in
* memory. The memory used by the thread cannot reused except for restarting
* the threads.
* - <b>Dynamic Threads</b>. Threads created by allocating memory from a memory
* heap or a memory pool.
* .
* <h2>Creating a static thread</h2>
* In order to create a static thread a working area must be declared using
* the macro @p WORKING_AREA as shown:
* @code
static WORKING_AREA(myThreadWorkingArea, 128);
* @endcode
* This macro reserves 128 bytes of stack for the thread and space for all
* the required thread related structures. The total size and the alignment
* problems are handled inside the macro, you only need to specify the pure
* stack size.<br>
* A thread can be started by invoking @p chThdCreateStatic() as shown in this
* example:
* @code
Thread *tp = chThdCreateStatic(myThreadWorkingArea,
sizeof(myThreadWorkingArea),
NORMALPRIO, /* Initial priority. */
myThread, /* Thread function. */
NULL); /* Thread parameter. */
* @endcode
* The variable tp receives the pointer to the thread object, it is taken
* by other APIs as parameter.<br>
* Now a complete example:
* @code
/*
* * My simple application.
*/
#include <ch.h>
/*
* * Working area for the LED flashing thread.
*/
static WORKING_AREA(myThreadWorkingArea, 128);
/*
* * LED flashing thread.
*/
static msg_t myThread(void *arg) {
while (TRUE) {
LED_ON();
chThdSleepMilliseconds(500);
LED_OFF();
chThdSleepMilliseconds(500);
}
}
int main(int argc, char *argv[]) {
/* Starting the flashing LEDs thread.*/
(void)chThdCreateStatic(myThreadWorkingArea, sizeof(myThreadWorkingArea),
NORMALPRIO, myThread, NULL);
.
.
.
}
* @endcode
* Note that the memory allocated to myThread() is statically defined and
* cannot be reused. Static threads are ideal for safety applications because
* there is no risk of a memory allocation failure because progressive heap
* fragmentation.
*
* <h2>Creating a dynamic thread using the heap allocator</h2>
* In order to create a thread from a memory heap is very easy:
* @code
Thread *tp = chThdCreateFromHeap(NULL, /* NULL = Default heap. */
THD_WA_SIZE(128),/* Stack size. */
NORMALPRIO, /* Initial priority. */
myThread, /* Thread function. */
NULL); /* Thread parameter. */
* @endcode
* The memory is allocated from the spawned heap and the thread is started.
* Note that the memory is not freed when the thread terminates but when the
* thread final status (its return value) is collected by the spawning thread.
* As example:
* @code
static msg_t myThread(void *arg) {
unsigned i = 10;
while (i > 0) {
LED_ON();
chThdSleepMilliseconds(500);
LED_OFF();
chThdSleepMilliseconds(500);
i--;
}
return (msg_t)i;
}
int main(int argc, char *argv[]) {
Thread *tp = chThdCreateFromHeap(NULL, THD_WA_SIZE(128), NORMALPRIO+1,
myThread, NULL);
if (tp == NULL)
chSysHalt(); /* Memory exausted. */
/* The main thread continues its normal execution.*/
.
.
/*
* * Now waits for the spawned thread to terminate (if it has not terminated
* * already) then gets the thread exit message (msg) and returns the
* * terminated thread memory to the heap (default system heap in this
* * example).
*/
msg_t msg = chThdWait(tp);
.
.
}
* @endcode
*
* <h2>Creating a dynamic thread using the heap allocator</h2>
* A pool is a collection of equally sized memory blocks, creating a thread from
* a memry pool is very similar to the previous example but the memory of
* terminated threads is returned to the memory pool rather than to a heap:
* @code
static msg_t myThread(void *arg) {
unsigned i = 10;
while (i > 0) {
LED_ON();
chThdSleepMilliseconds(500);
LED_OFF();
chThdSleepMilliseconds(500);
i--;
}
return (msg_t)i;
}
int main(int argc, char *argv[]) {
Thread *tp = chThdCreateFromMemoryPool(myPool, NORMALPRIO+1, myThread, NULL);
if (tp == NULL)
chSysHalt(); /* Pool empty. */
/* The main thread continues its normal execution.*/
.
.
/*
* * Now waits for the spawned thread to terminate (if it has not terminated
* * already) then gets the thread exit message (msg) and returns the
* * terminated thread memory to the original memory pool.
*/
msg_t msg = chThdWait(tp);
.
.
}
* @endcode
*/

104
ChibiOS_2.0.8/docs/src/credits.dox Normal file
View File

@@ -0,0 +1,104 @@
/*
ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 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/>.
---
A special exception to the GPL can be applied should you wish to distribute
a combined work that includes ChibiOS/RT, without being obliged to provide
the source code for any proprietary components. See the file exception.txt
for full details of how and when the exception can be applied.
*/
/**
* @page credits Copyright and Credits
* @brief Copyright and Credits
*
* <h2>Copyright Statement</h2>
@verbatim
ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 Giovanni Di Sirio.
@endverbatim
*
* <h2>Contributions and Copyright Assignment</h2>
* If you plan to contribute code to the ChibiOS/RT project then there is a
* requirement you should be aware of: contributing code for inclusion in
* the ChibiOS/RT <b>main line</b> requires assigning the copyright on the
* contributed code to me (Giovanni Di Sirio).<br>
* This may sound a bit strange but is pretty standard for this kind of
* projects, there are several reasons for this requirement:
* - ChibiOS/RT will probably also become a commercial product and it would
* not be possible to re-license the code without ownership. Note that the
* commercial product would not be a different or better product, just the
* same GPL product made available, on request, under a different license.
* The code will always be available to you under the current licensing
* terms.
* - Ownership is required when changing the licensing terms and this happens
* each time the project goes from development/unstable to stable and
* back because the addition/removal of the GPL linking exception.
* - It will be easier for the project adopters to have a single ownership
* point in case of licensing issues (both GPL or commercial).
* - Losing the ownership on the code could preclude me the opportunity to
* make this project a full time job as I hope.
* - I definitely don't want to have to sort out copyright related issues
* in the future so better be clear than sorry.
* .
* Note that contributions will always be welcome even without such copyright
* assignment, the difference is that the contributed code would not be
* merged into the main line, it will still made available as contributed
* code with the contributor(s) copyright notice intact.<br>
* Submissions of code with copyright notice should only happen through
* email, please do not commit code with copyright notices directly on
* the repository.<br>
* When submitting code please <b>state clearly your intention to keep the
* copyright</b> on your work by adding your own copyright notice within the
* source code and by clearly mentioning your intentions in the message. Code
* contributed without copyright notice will be considered donated.<br>
* If in doubt with licensing issues please don't hesitate to contact me
* in order to sort out any problem you may have.<br>
* Of course the copyright assignment does not mean you would not be
* recognized for your hard work, see the following section.
*
* <h2>Credits</h2>
* I want to thank all the people that directly or indirectly contributed
* to the project, I beg pardon if someone is missing:
* - <b>Adamo Reggiani</b>, working on the Fujitsu port.
* - <b>Alexander Kozaruk</b>, AT91SAM7S256 demo and description files for
* the Olimex SAM7-P256 board.
* - <b>Brian Weaver</b>, STM8 port, STM8 and STM32 testing and improvements.
* - <b>Egon Carusi</b>, STM32 port improvements, testing and bug fixes.
* - <b>Enrico Cavazza</b>, working on the Fujitsu port and a GUI subsystem.
* - <b>Eric Weddington</b>, because his work on WinAVR and helping me sorting
* out issues with the ChibiOS/RT license.
* - <b>Isidoro Orabona</b>, co-developer of the ChibiOS/RT grandfather back
* in 1988, it is a long long story involving a 6502 and a Z80...
* - <b>Jacek</b>, Ride7 demo for STM32 Primer.
* - <b>Leon Woestenberg</b>, CondVars idea and implementation, documentation
* improvements and a lot of other ideas, he also helped with the lwIP port
* (he is one of the developers of that project too).
* - <b>Leszek Bednarz</b>, H8S and ColdFire ports and drivers maintainer.
* - <b>Liam Staskawicz</b>, Posix simulator, AT91SAM7x and STM32 related
* contributions, general improvements, many bug fixes and excellent
* suggestions.
* - <b>Michael Fischer</b>, because the work on YAGARTO and the excellent
* feedback.
* - <b>Riccardo Scanu</b>, another long story, this time involving reverse
* engineering and giant robots...
* - <b>Vladimir</b>, first tested and fixed the AVR port, I don't know the
* surname but he has been the first contributor.
* - <b>Walter Goossens</b>, several fixes to the LPC21xx support.
* .
*/

145
ChibiOS_2.0.8/docs/src/debug.dox Normal file
View File

@@ -0,0 +1,145 @@
/*
ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 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/>.
---
A special exception to the GPL can be applied should you wish to distribute
a combined work that includes ChibiOS/RT, without being obliged to provide
the source code for any proprietary components. See the file exception.txt
for full details of how and when the exception can be applied.
*/
/**
* @page article_debug Debugging ChibiOS/RT applications
* ChibiOS/RT offers several mechanisms that can help in the debug phase of
* the development cycle.
*
* <h2>What this guide does not cover</h2>
* This guide assumes knowledge in following areas:
* - General knowledge of embedded development.
* - RTOS concepts.
* - Setup of your specific target hardware and toolchain.
* - Knowledge of your toolchain. The guide will explain what you need to do,
* not how it is done using you specific debugger, compiler, JTAG probe and
* target hardware.
* .
* <h2>Helpful debugging configuration settings</h2>
* There are several settings in your kernel configuration file
* (see @ref templates/chconf.h) that you may want to enable during
* debugging and in general during the whole development process.
* - @p CH_OPTIMIZE_SPEED=FALSE, this disables inlining into the kernel code
* and makes it easier to debug using your debugger, you may also want
* to reduce or disable compiler optimizations (-O0 using GCC).
* - @p CH_DBG_ENABLE_CHECKS=TRUE, this setting enables the checks on the
* API parameters, useful to understand if you are passing wrong parameters
* to the OS functions.
* - @p CH_DBG_ENABLE_ASSERTS=TRUE, this setting enables the OS internal
* consistency checks, this can trap several kind of errors in the user
* code (or in the kernel itself).
* - @p CH_DBG_ENABLE_STACK_CHECK=TRUE, this setting enables checks on
* threads stack overflow. Note that this option is not available in
* all ports, check your port documentation. If not supported then it
* is silently ignored, see also the article @ref article_stacks.
* - @p CH_DBG_FILL_THREADS=TRUE, this setting enables the threads workspace
* filling, this can help examining the stack usage from your debugger.
* .
* Note that all the failed checks lock the kernel into the @p port_halt()
* function. In order to assess what triggered the lock the global variable
* @p panic_msg must be inspected using the debugger, the variable is a
* pointer to an error message (a zero terminated string), the pointer may
* contain @p NULL if the lock was triggered by a stack overflow.
*
* <h2>Common errors and symptoms</h2>
* There are some common errors while using an RTOS, use the following
* table as a check list, if your problem is not a generic programming error
* then probably it is one of the following common RTOS/embedded related
* mistakes:
* - Insufficient stack allocated to one or more threads.<br>
* Common symptoms:
* - Target instability.
* - Target locked into the @p port_halt() function.
* - Target trapped into an exception handler (architecture dependent).
* - Target apparent self reset (not real resets usually).
* .
* - Insufficient stack allocated to the IRQ stack (in those architectures
* that have a separate IRQ stack, ARM as example).<br>
* Common symptoms:
* - Target instability.
* - Target trapped into an exception handler (architecture dependent).
* - Target apparent self reset (not real resets usually).
* .
* - Use of a non reentrant function from within an interrupt handler, as
* example most C runtime functions.<br>
* Common symptoms:
* - Target instability.
* - Unexpected application behavior.
* .
* - Missing use of a mutual exclusion mechanism to protect data
* (or non reentrant code) shared among multiple threads and/or
* threads and interrupt handlers, see also the article
* @ref article_mutual_exclusion.<br>
* Common symptoms:
* - Target instability.
* - Unexpected application behavior.
* .
* - Use of S-class or I-class APIs outside a proper lock state, see the
* @ref concepts article, specifically the @ref api_suffixes and
* @ref system_states sections.<br>
* Common symptoms:
* - Target instability.
* - Target trapped into an exception handler (architecture dependent).
* - Target apparent self reset (not real resets usually).
* .
* - Use of a non I-class API from an interrupt handler, see the
* @ref concepts article, specifically the @ref api_suffixes and
* @ref system_states sections.<br>
* Common symptoms:
* - Target instability.
* - Target trapped into an exception handler (architecture dependent).
* - Target apparent self reset (not real resets usually).
* .
* - Wrong threads priority assignment. One of the most critical things
* to do when designing an RTOS based application is to assign correct
* priorities to the threads in the system.<br>
* Common symptoms:
* - Excessive or unpredictable response times.
* - Threads that appear to be never executed (CPU intensive threads at
* higher priority).
* .
* .
* <h2>General suggestions</h2>
* For the less expert users, there are several things you may do in order
* to minimize the need for debugging:
* - Read carefully the documentation first.
* - Try to find a code examples for things are you going to do, good sources
* are: the documentation, the test code, under "./test" you will
* find examples for almost any API in the ChibiOS/RT kernel and most
* common RTOS related tasks, under "./testhal" there are examples
* regarding the various device drivers, the various demos contain
* good code samples too).
* - Start your application from an existing demo, add things one at a
* time and test often, if you add too many things at once then finding a
* small problem can become a debugging nightmare. Follow the cycle: think,
* implement, test, repeat.
* - If you are stuck for too much time then consider asking for advice.
* - Report bugs and problems, bugs can be fixed, problems can become new
* articles in the documentation (this and other documentation articles
* spawned from questions in the forum or in the tracker).
* - Never give up :-)
* .
*/

117
ChibiOS_2.0.8/docs/src/design.dox Normal file
View File

@@ -0,0 +1,117 @@
/*
ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 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/>.
---
A special exception to the GPL can be applied should you wish to distribute
a combined work that includes ChibiOS/RT, without being obliged to provide
the source code for any proprietary components. See the file exception.txt
for full details of how and when the exception can be applied.
*/
/**
* @page article_design Designing an embedded application
* ChibiOS/RT offers a variety of mechanisms and primitives, often it is
* better to focus on a single approach for the system design and use only
* part of the available subsystems.<br>
* When designing your application you may choose among several design
* alternatives:
* - @ref nothreads
* - @ref messpass
* - @ref thdshared
* - @ref thdmixed
* .
* @section nothreads Single threaded superloop
* Correct, single thread, it is not mandatory to use the multithreading
* features of the OS. You may choose to implements everything as a complex
* state machine handled in the main thread alone. In this scenario the OS
* still offers a variety of useful mechanisms:
* - Interrupt handling.
* - Virtual Timers, very useful in state machines in order to handle time
* triggered state transitions.
* - Power management.
* - Event Flags and/or Semaphores as communication mechanism between
* interrupt handlers and the main.
* - I/O queues.
* - Memory allocation.
* - System time.
* .
* In this configuration the kernel size is really minimal, everything else
* is disabled and takes no space. You always have the option to use more
* threads at a later time in order to perform separate tasks.
*
* @section messpass Message Passing
* In this scenario there are multiple threads in the system that never
* share data, everything is done by exchanging messages. Each thread
* represents a service, the other threads can request the service by sending
* a message.<br>
* In this scenario the following subsystems can be used:
* - Synchronous Messages.
* - Mailboxes (asynchronous message queues).
* .
* The advantage of this approach is to not have to deal with mutual exclusion,
* each functionality is encapsulated into a server thread that sequentially
* serves all the requests. As example, you can have the following scenario:
* - A buffers allocator server.
* - A disk driver server.
* - A file system server.
* - One or more client threads.
* .
* Example:
* <br><br>
* @dot
digraph example {
rankdir="RL";
node [shape=rectangle, fontname=Helvetica, fontsize=8, fixedsize="true",
width="1.2", height="0.75"];
edge [fontname=Helvetica, fontsize=8];
disk [label="Server Thread\nDisk Driver"];
buf [label="Server Thread\nBuffers Allocator"];
fs [label="Client&Server Thread\nFile System"];
cl1 [label="Client Thread"];
cl2 [label="Client Thread"];
cl3 [label="Client Thread"];
fs -> disk [label="I/O request", constraint=false];
disk -> fs [label="status", style="dotted", constraint=false];
fs -> buf [label="buffer request"];
buf -> fs [label="buffer", style="dotted"];
cl1 -> fs [label="FS transaction"];
fs -> cl1 [label="result", style="dotted"];
cl2 -> fs [label="FS transaction"];
fs -> cl2 [label="result", style="dotted"];
cl3 -> fs [label="FS transaction"];
fs -> cl3 [label="result", style="dotted"];
}
* @enddot
* <br><br>
* Note that the threads should not exchange complex messages but just
* pointers to data structures in order to optimize the performance.
* Also note that a thread can be both client and server at the same
* time, the FS service in the previous scenario as example.
*
* @section thdshared Threads sharing data
* This is the most common scenario, several threads have access to both their
* private data and shared data. Synchronization happens with one of the
* mechanisms described in the @ref article_mutual_exclusion article.<br>
*
* @section thdmixed Mixed
* All the above approaches can be freely mixed in a single application but
* usually I prefer to choose a way and consistently design the system around
* it. The OS is a toolbox that offers a lot of tools but you don't have
* to use them all necessarily.
*/

176
ChibiOS_2.0.8/docs/src/eclipse.dox Normal file
View File

@@ -0,0 +1,176 @@
/*
ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 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/>.
---
A special exception to the GPL can be applied should you wish to distribute
a combined work that includes ChibiOS/RT, without being obliged to provide
the source code for any proprietary components. See the file exception.txt
for full details of how and when the exception can be applied.
*/
/**
* @page article_eclipse Setting up a free embedded IDE
* @brief Free advanced embedded IDE for ChibiOS/RT.
* details This article will explain how to setup a free toolchain for use with
* ChibiOS/RT and general embedded development.<br>
* The guide is meant mainly for Windows users but notes about Linux and
* MAC OSX are present where the setup differs, mostly the toolchain is
* exactly the same.
*
* <h2>What this guide does not cover</h2>
* We will not enter in details of common system tasks like and not limited to:
* - Installing applications (unless a special procedure is required).
* - Creating desktop shortcuts.
* - Adding paths to the PATH variable.
* - Creating environment variables.
* - Any other normal PC usage task.
* - Use of the toolchain, the use is covered by the @ref article_eclipse2
* article.
* .
*
* <h2>Article Index</h2>
* - @ref required_components
* - @ref install_chibios
* - @ref install_compiler
* - @ref install_eclipse
* - @ref install_zylin
* - @ref install_openocd
* - @ref install_doxygen
* - @ref install_graphviz
* - @ref install_eclox
* .
*
* @section required_components Required Components
* The first thing to do is to download all the required components, beginners
* should avoid the optional components initially:
* - A JTAG probe supporting GDB and OpenOCD, a list of compatible devices is
* available on the <a href="http://openocd.berlios.de/web/" target="_blank">
* OpenOCD home page</a>, more exactly
* <a href="http://openocd.berlios.de/doc/html/Debug-Adapter-Hardware.html#Debug-Adapter-Hardware"
* target="_blank">here</a>.
* - <a href="https://sourceforge.net/projects/chibios/" target="_blank">
* ChibiOS/RT latest stable release</a>.
* - <a href="http://www.java.com/en/" target="_blank">Java runtime</a>, you
* probably already have this installed.
* - <a href="http://www.eclipse.org/downloads/" target="_blank">Eclipse IDE
* for C/C++ Developers</a>
* - <a href="http://www.yagarto.de/" target="_blank">YAGARTO ARM toolchain
* for Windows</a>, note that you need both the compiler and the tools (make
* and binutils).
* - Zylin plugin for on-board debugging, see @ref install_zylin section.
* - OpenOCD binaries for Windows, YAGARTO does not provide those anymore but
* you can download them from <a href="http://www.freddiechopin.info/"
* target="_blank">here</a>. Linux users can try
* <a href="http://home.comcast.net/~mcatudal/" target="_blank">here</a>.
* - <b>Optional</b>, <a href="http://www.stack.nl/~dimitri/doxygen/"
* target="_blank">MinGW compiler</a>, needed if you want to compile, debug
* and run the simulator from within Eclipse. Linux users do not need this
* one because all Linux distributions include the native GCC.
* - <b>Optional</b>, <a href="http://www.stack.nl/~dimitri/doxygen/"
* target="_blank">Doxygen</a>, it is only required if you want to
* generate documentation from source files.
* - <b>Optional</b>, <a href="http://www.graphviz.org/" target="_blank">
* Graphwiz</a>, it is only required if you want to generate diagrams
* within documentation from source files.
* - <b>Optional</b>, <a href="http://home.gna.org/eclox/" target="_blank">
* Eclox</a>, it is only required if you want to generate documentation
* from source files from within Eclipse.
* .
*
* @section install_chibios ChibiOS/RT Installation
* Just unzip it into a directory in your home folder, Windows users may
* consider c:@\projects@\chibios. It is strongly suggested to not put version
* numbers into the ChibiOS/RT directory name because Eclipse workspaces
* have absolute paths inside and you don't want to setup everything again
* each time a new ChibiOS/RT version is released, use plain "chibios".
*
* @section install_compiler GCC ARM Compiler Installation
* Simply follow the YAGARTO installation guide. Linux/MACOS users have several
* other options:
* - Download the latest CodeSourcery free Linux package.
* - Build it yourself, Liam recommended a build script
* <a href="http://github.com/esden/summon-arm-toolchain" target="_blank">
* here</a>, it looks interesting.
* .
* Make sure that the compiler binaries directory is listed in the PATH
* variable or Eclipse would not be able to locate it.
*
* @section install_eclipse Eclipse Installation
* Eclipse is distributed into a compressed archive, there is no installation
* procedure:
* - Verify if you have Java installed, if not install the runtime. You may
* verify this using the command: "java -version". Make sure you have at
* least version 1.6.
* - Create an eclipse directory in your home and unpack the archive there.
* Windows users may unpack it into c:@\program files@\eclipse.
* - Create a desktop shortcut or other way to launch the Eclipse executable
* easily.
* - Launch Eclipse.
* - Eclipse will ask you a directory for its initial workspace, make it point
* to the ChibiOS/RT root directory (you may have as many workspaces you
* want, keep this for later), make sure to select the check box or it will
* ask you again each time.
* <br><br>
* @image html tool001.jpg
* <br>
* - Now you should see the welcome screen, close it and you will be in the
* normal C/C++ perspective.
* - Unselect "Project->Build Automatically" unless you like insanity.
* - Disable the "usage collector" in
* "Window->Preferences->Usage_Data_Collector" by unselecting "Enable
* capture".
* - If you are behind a proxy or firewall (corporate users usually are)
* configure the correct parameters in
* "Window->Preferences->General->Network_Connections".
* - Let Eclipse auto update to the latest version "Help->Check_for_Updates".
* .
*
* @section install_zylin Zylin Plugin Installation
* Eclipse requires an hardware debugger component in order to perform on board
* execution and debug.
* - Open Eclipse, then "Help->Install_New_Software...".
* - Press the "Add..." button and put http://opensource.zylin.com/zylincdt
* into the location field, then press OK. The Zylin plugin will appear in the
* available plugins view, select and install it.
* <br><br>
* @image html tool002.jpg
* .
*
* @section install_openocd OpenOCD Installation
* Windows users just have to use the installer. Linux user should follow the
* normal installation procedure for deb or rpm packages, of course it is also
* possible to build it from the source code.
*
* @section install_doxygen Doxygen Installation
* Just use the installer, Linux users probably have Doxygen already available
* from the repositories. Make sure that the Doxygen binaries directory
* is listed in the PATH variable or Eclipse would not be able to locate it.
*
* @section install_graphviz Graphviz Installation
* Just use the installer, Linux users probably have Graphviz already available
* from the repositories. Make sure that the Graphviz binaries directory
* is listed in the PATH variable or Doxygen would not be able to locate it.
*
* @section install_eclox Eclox Installation
* Use the same installation steps used for the Zylin plugin except use
* http://download.gna.org/eclox/update as URL. Install "Eclox" not "Eclox
* Hot".
* After installing Eclox you will be able to compile Doxygen documentation
* using the button with the blue @@ inside.
*/

256
ChibiOS_2.0.8/docs/src/eclipse2.dox Normal file
View File

@@ -0,0 +1,256 @@
/*
ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 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/>.
---
A special exception to the GPL can be applied should you wish to distribute
a combined work that includes ChibiOS/RT, without being obliged to provide
the source code for any proprietary components. See the file exception.txt
for full details of how and when the exception can be applied.
*/
/**
* @page article_eclipse2 Embedded development using Eclipse
* @brief Compiling and debugging ChibiOS/RT applications using Eclipse.
* @details This article will explain how to use an Eclipse based toolchain
* (see @ref article_eclipse) to develop ChibiOS/RT based applications.
* This guide will allow you to:
* - Importing ChibiOS/RT demos into the Eclipse environment.
* - Edit and reformat your source code.
* - Compile and examine errors and warnings.
* - Upload your program on the target board.
* - Debug your code on the target board both in high level language and
* assembler.
* - Develop embedded applications with or without ChibiOS/RT.
* .
*
* <h2>What this guide does not cover</h2>
* This guide assumes knowledge in following areas:
* - OpenOCD setup is not covered by this guide because the setup changes
* depending on the JTAG probe used, the target MCU and also the target
* board. The guide will show the setup for a specific JTAG probe and a
* specific target, a valuable source for the OpenOCD setup is the
* <a href="http://forum.sparkfun.com/viewforum.php?f=18" target="_blank">
* dedicated forum</a>, most questions you may have about OpenOCD have
* most likely already been answered there.
* - Hardware setup.
* .
* In general this guide is not a replacement for the Eclipse, GCC, Make,
* binutils, newlib, GDB, OpenOCD user manuals, the guide simply aims to
* give you a faster start.
*
* <h2>Article Index</h2>
* - @ref eclipse2_requirements
* - @ref eclipse2_importing
* - @ref eclipse2_creating
* - @ref eclipse2_compiling
* - @ref eclipse2_configuring
* - @ref eclipse2_configuring_gdb
* - @ref eclipse2_configuring_openocd
* .
* - @ref eclipse2_debugging
* - @ref eclipse2_debugging_start
* - @ref eclipse2_debugging_stop
* .
* .
*
* @section eclipse2_requirements Required Components
* This guide requires:
* - An Eclipse/GCC/OpenOCD based toolchain, as example the one described in
* the article @ref article_eclipse.
* - An Olimex ARM-USB-OCD JTAG probe, this guide applies to any other ARM
* JTAG probe as long it is supported by OpenOCD.
* - An Olimex STM32-P103 target board, this guide applies to any other ARM
* target except for the OpenOCD setup part.
* - A terminal emulator for capturing the board serial output, Windows users
* may use Hyper Terminal, Linux and MAC OS-X users may use
* <a href="http://cutecom.sourceforge.net/" target="_blank">CuteCom</a>.
* All ChibiOS/RT demos generate on the serial port a test report when a
* button on the target board is pressed, other demos may activate a command
* shell on the serial port, in both cases a terminal emulator is required.
* .
*
* @section eclipse2_importing Importing existing ChibiOS/RT demos into Eclipse
* The first step is to import a project into the Eclipse environment.
* ChibiOS/RT demos do not include Eclipse project files but just a normal
* Makefile. Eclipse is able to import a Makefile project and create
* its own project file so this is not a problem. This is how it is done:
* - Open you Eclipse environment and select the workspace created into the
* ChibiOS/RT project directory.
* - From within Eclipse select "File->New->C_Project", a dialog box will show.
* - Select "Makefile_project->Empty_Project" in the "Project type:" box.
* - Select "-- Other Toolchain --" in the "Toolchains:" box.
* - Unselect the "Use default location" check box.
* - Select the demo directory using the "Browse..." button. Something like
* "C:\Projects\ChibiOS-RT\demos\ARMCM3-STM32F103-GCC" will appear in the
* "Location:" box.
* - In the project name box put the same name of the directory containing
* the demo, ARMCM3-STM32F103-GCC in this example.
* <br><br>
* @image html eclipse003.jpg
* <br>
* - Press the "Finish" button and the project will be created and shown in
* the "Project Explorer".
* - Right click on the imported project and select "Index->Rebuild", this
* will make Eclipse build its internal symbols database.
* - Repeat the above steps for each ChibiOS/RT demo you want to import in
* Eclipse, all the demos that have a makefile can be imported.
* .
*
* @section eclipse2_creating Creating a new ChibiOS/RT application
* If you want to create a new application it is recommended that you create
* a Makefile project first then you can import it into eclipse using the above
* procedure. Makefile projects have the advantage that can be compiled
* everywhere even without Eclipse. Creation steps:
* - Create your own development directory under the ChibiOS/RT installation
* directory, as example "chibios/myprojects".
* - Copy an existing demo, of course choose a demo using your same target,
* under the new directory and rename it, as example
* "chibios/myprojects/myapplication".
* - Customize the Makefile if needed, usually you just need to do this if
* your application is composed by more than one source file. You may also
* want to remove the ChibiOS/RT test code from your application.
* - Once your makefile is ready, import the project under the Eclipse
* workspace using the procedure described in @ref eclipse2_importing.
* .
*
* @section eclipse2_compiling Compiling and Cleaning applications
* Once imported, an application can be compiled by using the "Build All" in
* the toolbar or by right clicking on the project and selecting "Build
* Project". In order to clean a project (removing all the temporary and binary
* files) right click on the project and select "Clean Project".
* <br><br>
* @image html eclipse004.jpg
* <br>
* The compilation result is visible as a complete log in the "Console" window,
* the detail of all errors an warnings is available in the "Problems" window.
* <br><br>
* @image html eclipse005.jpg
* <br>
* The build process produces the binary files specified in the Makefile, all
* the ChibiOS/RT demos produce binary files named ch.elf, ch.bin and/or
* ch.hex. The image must be loaded on the target board in order to execute
* it. The build process usually creates also some other useful files
* containing details about the built application (usually named ch.map and
* ch.dmp).
*
* @section eclipse2_configuring Preparing for Debug
* In order to debug your application a debug configuration must be created.
* The configuration instructs GDB (the source debugger used by Eclipse) on
* how to load the image, load the symbols and place the initial breakpoint
* in the make function. Note that GDB performs its function by connecting
* to a "GDB server", the DGB server implements the low level communication
* with the target device through the JTAG probe. In our scenario the GDB
* server functionality is performed by OpenOCD, this mean that OpenOCD must
* be running while performing a debug session within Eclipse.
*
* @subsection eclipse2_configuring_gdb Creating a GDB Debug Configuration
* A target specific debug configuration is required in order to:
* - Establish a connection with the GDB server.
* - Stop and reset the target.
* - Upload the binary code in Flash or RAM.
* - Set an initial breakpoint in the main function.
* - Start the target (which will immediately stop on the breakpoint).
* .
* The first thing to do is to open the "Debug Configurations..." dialog:
* <br><br>
* @image html eclipse006.jpg
* <br>
* The configuration dialog will appear, we must create a native Zylin
* configuration:
* <br><br>
* @image html eclipse007.jpg
* <br>
* Now we must give the configuration a name, "ARMCM3-STM32F103-GCC (flash and
* run)" in this example, then setup the various configuration pages as follow:
* <br><br>
* The "Main" tab:
* @image html eclipse008.jpg
* <br><br>
* The "Debugger" tab:
* @image html eclipse009.jpg
* <br><br>
* The "Commands" tab:
* @image html eclipse010.jpg
* <br>
* Note that the "Commands" tab contains the part that changes depending on
* the target. The complete commands sequence (it is not fully visible in the
* image) for STM32 is:
* @code
* monitor soft_reset_halt
* monitor wait_halt
* monitor poll
* monitor flash probe 0
* monitor stm32x mass_erase 0
* monitor flash write_bank 0 ch.bin 0
* monitor soft_reset_halt
* symbol-file ch.elf
* thbreak main
* continue
* @endcode
* <br><br>
* The "Common" tab:
* @image html eclipse011.jpg
* <br>
* Now the debug configuration is complete.
*
* @subsection eclipse2_configuring_openocd Configuring and running OpenOCD
* OpenOCD must be run, with appropriate parameters, before starting your
* debug session. Please refer to the OpenOCD documentation in order to
* properly launch it for your target.
* <br>**To be completed**
*
* @section eclipse2_debugging Debugging
* Now we are ready to debug an application on the target. Note that Eclipse
* have a mechanism called "Perspectives", you edit and compile your source
* code while you are in the "C/C++ perspective" while the debugging is
* performed in the "Debug perspective". You can switch perspective at any
* time, even while there is an active debug session. If you install more of
* the many Eclipse extension plugins (there are thousands) you may have even
* more perspectives available.
*
* @subsection eclipse2_debugging_start Starting a Debug Session
* In order to start a debugging session first make sure that OpenOCD is
* running then press the drop down menu on the right side of the
* debug icon in the toolbar (the small green bug) and select your
* debug configuration (we created just one but you may have multiple
* debug configurations in your project, as example I usually create
* another debug configuration that just starts the target without
* uploading the code).
* <br><br>
* @image html eclipse012.jpg
* <br>
* The debugger will be initialized, you will see the operation in progress on
* the console then Eclipse will switch to the debug perspective and you will
* see your program stopped on the default breakpoint in the main function.
* <br><br>
* @image html eclipse013.jpg
* <br>
* From there you can perform all the usual debugging tasks, set breakpoints,
* single step execution, variables, memory and registers inspection etc.
* Please refer to the Eclipse documentation about those "normal" operations.
* Note that if the debugging start procedure hangs then there is probably
* an error in your configuration or problems with the target, read the
* console log and/or the OpenOCD output in order to understand where the
* problem is.
*
* @subsection eclipse2_debugging_stop Stopping a Debug Session
* From the debug perspective press the stop button (small red square) in the
* debug window, the target will be stopped and you may both return to the
* C/C++ perspective or start it again.
*/

130
ChibiOS_2.0.8/docs/src/events.dox Normal file
View File

@@ -0,0 +1,130 @@
/*
ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 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/>.
---
A special exception to the GPL can be applied should you wish to distribute
a combined work that includes ChibiOS/RT, without being obliged to provide
the source code for any proprietary components. See the file exception.txt
for full details of how and when the exception can be applied.
*/
/**
* @page article_events Events Explained
* Events are an important feature in ChibiOS/RT, most device drivers generate
* events in order to notify the application that something happened at the
* I/O level.<br>
* While event flags are not something unknown in other operating systems,
* their peculiar implementation in ChibiOS/RT requires a more in depth
* explanation.<br>
* Lets start with the events related terminology:
* - <b>Event Source</b>, an @p EventSource is a system object that can be
* @a broadcasted asynchronously in response of a system event, as example,
* when the CAN driver receives a packet from the CAN bus it @a broadcasts
* an event source in order to inform the registered threads that a packet
* has just arrived.
* - <b>Broadcast</b>, the operation performed on an event source in order
* to inform the @a registered threads that an event just occurred.
* Broadcasting can happened both in interrupt handlers and in threads.
* - <b>Event Listener</b>, a system object that associates a @p Thread object
* to an event source. The process of associating a @p Thread to an
* @p EventSource using an @p EventListener is called @a registration.
* - <b>Registration</b>, action performed by a thread in order to be informed
* of events from a specific event source. Of course a thread can be
* @a registered on more than one event source by using multiple
* @p EventListener objects. Threads can also @a unregister from an event
* source.
* - <b>Pend</b>, each thread has a mask of @a pending events. The @a broadcast
* operation @a pends an event mask on all the @a registered threads.
* - <b>Wait</b>, synchronous operation performed by a thread in order to
* @a wait a specific combination of events. The API offers a variety of
* @a wait functions, please refer to the events API documentation.
* .
* Note that events are asynchronously generated, as example in an interrupt
* handler, but are synchronously served.
*
* <h2>Events related data structures</h2>
* The following diagram explains the relationship between an event source,
* its list of event listeners and the @a registered threads.
* @dot
digraph example {
rankdir="LR";
node [shape=rectangle, fontname=Helvetica, fontsize=8,
fixedsize="true", width="1.0", height="0.5"];
edge [fontname=Helvetica, fontsize=8, sep=3.0];
es [shape=record, label="EventSource | es_next", style="bold"];
subgraph cluster_0 {
fontname=Helvetica;
label = "Listeners List";
color = blue;
node [shape=record, fontname=Helvetica, fontsize=8,
fixedsize="true", width="1.5", height="1.0"];
el4 [label="EventListener 4 | el_mask: 0x0001 | el_listener | el_next"];
el3 [label="EventListener 3 | el_mask: 0x0C00 | el_listener | el_next"];
el2 [label="EventListener 2 | el_mask: 0x0001 | el_listener | el_next"];
el1 [label="EventListener 1 | el_mask: 0x0004 | el_listener | el_next"];
el1 -> el2 -> el3 -> el4 [label=" el_next", constraint=false];
}
subgraph cluster_1 {
fontname=Helvetica;
label = "Registered Threads";
color = blue;
node [shape=record, fontname=Helvetica, fontsize=8,
fixedsize="true", width="1.5", height="0.8"];
t1 [label="Thread 1 | p_epending:0x0000 | p_ewmask:0xFFFF"];
t2 [label="Thread 2 | p_epending:0x000F | p_ewmask:0x0C01"];
t3 [label="Thread 3 | p_epending:0x0008 | p_ewmask:0x0001"];
t4 [label="Thread 4 | p_epending:0x0000 | p_ewmask:0xFFFF"];
}
es -> el1 [label=" es_next"];
el4 -> es [label=" el_next"];
el1 -> t1 [label="el_listener"];
el2 -> t2 [label="el_listener"];
el3 -> t3 [label="el_listener"];
el4 -> t4 [label="el_listener"];
}
* @enddot
* Note that each event listener has a different bit mask to be @a pended on
* its associated thread when the event source is @a broadcasted, this means
* that each thread can define its own event identifiers independently. A
* @a broadcast operation can also @a pend more than one bit on the
* @a registered threads.<br>
* The threads have a variety of @a wait primitives, they can @a wait for one
* or more event flags to become @a pending, and can also specify AND/OR
* conditions, as example a thread can @a wait for any event to become
* @a pending or @a wait for all the specified events to become @a pending.<br>
* The field @p p_epending is the mask of the currently pending events,
* the field @p p_ewmask is the mask of the events the thread is interested
* on in that moment (AND or OR condition depending on the invoked
* @a wait API).
*
* <h2>Use Scenarios</h2>
* Events are best used when one of more of the following conditions are
* required:
* - Having to wait on multiple conditions, Events are the only mechanism
* that easily allow that.
* - Synchronous response to one or more asynchronous events.
* - Single threaded applications working in a event driver environment (but
* events are not limited to single threaded applications).
* .
*/

95
ChibiOS_2.0.8/docs/src/goals.dox Normal file
View File

@@ -0,0 +1,95 @@
/*
ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 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/>.
---
A special exception to the GPL can be applied should you wish to distribute
a combined work that includes ChibiOS/RT, without being obliged to provide
the source code for any proprietary components. See the file exception.txt
for full details of how and when the exception can be applied.
*/
/**
* @page goals Project Goals
* <h2>Another RTOS?</h2>
* The first question to be answered is: there was really the need for YET
* ANOTHER RTOS?<br>
* There are several reasons:
* - The ChibiOS/RT ancestor was created more than 15 years ago and while it
* had far less features than the current product it was complete and
* functioning. ChibiOS/RT is just a new (and silly) name given to
* something created when there were not many free RTOSes around (actually
* none, at least none in my knowledge, there was no widespread Internet
* at that time).
* - When, after a while, I needed a RTOS again, none of the existing FOSS
* projects met my expectations or my ideas of how a RTOS should be, not
* even close (see below). I decided that work on that old project was
* a better idea than contribute to, or fork, something else.
* - I wanted another toy.
* .
* <h2>Why is it different?</h2>
* Well, there are some design choices that should be explained and contribute
* to make ChibiOS/RT a peculiar design. Nothing really new in itself but
* the whole is interesting:
*
* <h3>Static design</h3>
* Everything in the kernel is static, nowhere memory is allocated or freed,
* there are three allocator subsystems but those are options and not part of
* core OS. Safety is something you design in, not something you can add later.
*
* <h3>No tables, arrays or other fixed structures</h3>
* The kernel has no internal tables, there is nothing that must be configured
* at compile time or that can overflow at run time. No upper bounds, the
* internal structures are all dynamic even if all the objects are statically
* allocated.
*
* <h3>No error conditions and no error checks</h3>
* All the system APIs have no error conditions, all the previous points are
* finalized to this objective. Everything you can invoke in the kernel is
* designed to not fail unless you pass garbage as parameters, stray pointers
* as examples. The APIs are not slowed down by parameter checks,
* parameter checks (and consistency checks) do exist but only when the
* debug switch is activated.<br>
* All the static core APIs always succeed if correct parameters are passed.
* Exception to this are the optional allocators APIs that, of course,
* can report memory exhausted.
*
* <h3>Very simple APIs</h3>
* Each API should have the parameters you would expect for that function and
* do just one thing with no options.
*
* <h3>Fast and compact</h3>
* Note, first "fast" then "compact", the focus is on speed and execution
* efficiency and then on code size. This does not mean that the OS is large,
* the kernel size with all the subsystems activated weighs around <b>5.3KiB</b>
* and can shrink down around to <b>1.2Kib</b> in a minimal configuration
* (STM32, Cortex-M3). It would be possible to make something even smaller but:
* -# It would be pointless, it is already @a really small.
* -# I would not trade efficiency or features in order to save few bytes.
* .
* About the "fast" part, the kernel is able to start/exit over
* <b>220,000 threads per second</b> on a 72MHz STM32.
* The Context Switch takes <b>1.2 microseconds</b> on the same STM32.
*
* <h3>Tests and metrics</h3>
* I think it is nice to know how an OS is tested and how it performs before
* committing to use it. Test results on all the supported platforms and
* performance metrics are included in each ChibiOS/RT release. The test
* code is released as well, all the included demos are capable of executing
* the test suite and the OS benchmarks, see @ref testsuite.
*/

102
ChibiOS_2.0.8/docs/src/integrationguide.dox Normal file
View File

@@ -0,0 +1,102 @@
/*
ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 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/>.
---
A special exception to the GPL can be applied should you wish to distribute
a combined work that includes ChibiOS/RT, without being obliged to provide
the source code for any proprietary components. See the file exception.txt
for full details of how and when the exception can be applied.
*/
/**
* @page article_integrationguide Integration Guide
* All the delivered ChibiOS/RT demos are stand alone applications so if
* you just start your application from an existing demo there isn't any
* integration effort, you are simply using the existing makefiles, the
* default startup files etc, minimal effort.<br>
* The matter is very different if you are going to integrate the OS into
* a different runtime framework or if you want to use a different build
* system, in that case you have the problem to integrate the OS source
* code into your application.
*
* <h2>What this guide does not cover</h2>
* This guide has a limited scope, the following topics are handled elsewhere:
* - Porting the OS to different architectures or different compilers is
* not covered in this guide, see @ref article_portguide instead.
* - This guide does not describe any specific environment or development
* tool, it is assumed you already know in detail the environment you
* want to work with.
* .
*
* <h2>Article Index</h2>
* - @ref integrationguide_kernel
* - @ref integrationguide_hal
* .
* @section integrationguide_kernel Integrating the Kernel
* This section covers the scenario where you want to use the ChibiOS/RT
* kernel into an existing application. In order to accomplish this you need
* to import in your project two components:
* - The portable kernel.
* - The port layer for your microcontroller.
* .
* See the @ref architecture for more details.
* You need to add the following files to your build process:
* - All the source files contained under <tt>./os/kernel/src</tt>, note that
* you should add all of them even if you don't plan to use some of the
* subsystems. Unused subsystems can be excluded from the kernel
* configuration file @p chconf.h.
* - All the source files contained under
* <tt>./os/ports/<i>@<compiler@></i>/<i>@<architecture@></i></tt>.
* Note that those could be both C source files and assembler source files
* and that some architectures have an extra directories layer containing
* files required for a specific platform.
* .
* You also need to add to the compiler options the following paths for
* searching header files:
* - The portable kernel headers <tt>./os/kernel/include</tt>.
* - The port layer headers
* <tt>./os/ports/<i>@<compiler@></i>/<i>@<architecture@></i></tt>.
* .
* @section integrationguide_hal Integrating the HAL
* If, in addition to the kernel as described in the previous section, you also
* need to integrate the HAL into your application you also need to import
* the following components:
* - HAL portable files.
* - Platform specific files.
* .
* See the @ref architecture for more details.
* You need to add the following files to your build process:
* - All the source files contained under <tt>./os/hal/src</tt>, note that
* you should add all of them even if you don't plan to use some of the
* subsystems. Unused drivers can be excluded from the HAL configuration
* file @p halconf.h.
* - All the source files contained under
* <tt>./os/hal/platforms/<i>@<platform@></i></tt>.
* - All the source files contained under
* <tt>./boards/<i>@<board_model@></i></tt>.
* .
* You also need to add to the compiler options the following paths for
* searching header files:
* - The portable HAL headers <tt>./os/hal/include</tt>.
* - The platform layer headers
* <tt>./os/hal/platforms/<i>@<platform@></i></tt>.
* - The board description headers
* <tt>./boards/<i>@<board_model@></i></tt>.
* .
*/

76
ChibiOS_2.0.8/docs/src/interrupts.dox Normal file
View File

@@ -0,0 +1,76 @@
/*
ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 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/>.
---
A special exception to the GPL can be applied should you wish to distribute
a combined work that includes ChibiOS/RT, without being obliged to provide
the source code for any proprietary components. See the file exception.txt
for full details of how and when the exception can be applied.
*/
/**
* @page article_interrupts How to write interrupt handlers
* Since version 1.1.0 ChibiOS/RT offers a cross-platform method for writing
* interrupt handlers. Port-related and compiler-related details are
* encapsulated within standard system macros.
*
* <h2>Writing Regular Interrupt handlers</h2>
* A Regular Interrupts handler (see @ref interrupt_classes) must be written
* using the following general form:
* @code
CH_IRQ_HANDLER(myIRQ) {
CH_IRQ_PROLOGUE();
// IRQ handling code, preemptable if the architecture supports it.
chSysLockFromIsr();
// Invocation of some I-Class system APIs, never preemptable.
chSysUnlockFromIsr();
// More IRQ handling code, again preemptable.
CH_IRQ_EPILOGUE();
}
* @endcode
*
* <h2>Writing Fast Interrupt handlers</h2>
* In those architectures (@ref ARM7 and @ref ARMCMx) supporting Fast
* Interrupts (see @ref interrupt_classes) handlers must be written
* using the following general form:
* @code
CH_FAST_IRQ_HANDLER(myIRQ) {
// Fast IRQ handling code, preemptable if the architecture supports it.
// The invocation of any API is forbidden here because fast interrupt
// handlers can preempt the kernel even within its critical zones in
// order to minimize latency.
}
* @endcode
*
* <h2>Handlers naming</h2>
* A note about the handler name "myIRQ", in some ports it must be a
* vector number rather than a function name, it could also be a name from
* within a predefined set, see the notes about the various ports.
*
* <h2>Important Notes</h2>
* - There is an important application note about ARM7 interrupt handlers,
* please read about it in the ARM7 port section: @ref ARM7_IH
* .
*/

142
ChibiOS_2.0.8/docs/src/jitter.dox Normal file
View File

@@ -0,0 +1,142 @@
/*
ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 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/>.
---
A special exception to the GPL can be applied should you wish to distribute
a combined work that includes ChibiOS/RT, without being obliged to provide
the source code for any proprietary components. See the file exception.txt
for full details of how and when the exception can be applied.
*/
/**
* @page article_jitter Response Time and Jitter
* Response time jitter is one of the most sneaky source of problems when
* designing a real time system. When using a RTOS like ChibiOS/RT one must
* be aware of what the jitter is and how it can affect the performance of the
* system. A good place to start is this
* <a href="http://en.wikipedia.org/wiki/Jitter" target="_blank">Wikipedia
* article</a>.
*
* <h2>Interrupt handlers execution time</h2>
* The total execution time of an interrupt handler includes:
* - Hardware interrupts latency, this parameter is pretty much fixed and
* characteristic of the system.
* - Fixed handler overhead, as example registers stacking/unstacking.
* - Interrupt specific handler code execution time, as example, in a serial
* driver, this is the time used by the handler to transfer data from/to
* the UART.
* - OS overhead. Any operating system requires to run some extra code
* in interrupt handlers in order to handle correct preemption and Context
* Switching.
* .
* <h2>Interrupt Response Time</h2>
* The Interrupt Response Time is the time from an interrupt event and the
* execution of the handler code. Unfortunately this time is not constant
* in most cases, see the following graph:
*
* @dot
digraph example {
rankdir="LR";
node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true", width="0.75", height="0.75"];
edge [fontname=Helvetica, fontsize=8];
int [label="Interrupt"];
busy [label="Busy"];
served [label="Interrupt\nServed"];
int -> served [label="Not Busy (minimum latency)"];
int -> busy [label="Not Ready"];
busy -> busy [label="Still Busy\n(added latency)"];
busy -> served [label="Finally Ready"];
}
* @enddot
*
* In this scenario the jitter (busy state) is represented by the sum of:
* - Higher or equal priority interrupt handlers execution time combined.
* This time can go from zero to the maximum randomly. This value can be
* guaranteed to be zero only if the interrupt has the highest priority in
* the system.
* - Highest execution time among lower priority handlers. This value is zero
* on those architectures (Cortex-M3 as example) where interrupt handlers
* can be preempted by higher priority sources.
* - Longest time in a kernel lock zone that can delay interrupt servicing.
* This value is zero for fast interrupt sources, see @ref system_states.
* .
* <h2>Threads Flyback Time</h2>
* This is the time between an event, as example an interrupt, and the
* execution of the thread that will process it. Imagine the following
* graph as the continuation of the previous one.
*
* @dot
digraph example {
rankdir="LR";
node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true", width="0.75", height="0.75"];
edge [fontname=Helvetica, fontsize=8];
served [label="Interrupt\nServed"];
busy [label="Busy"];
thread [label="Thread\nAwakened"];
served -> busy [label="Not highest Priority"];
busy -> busy [label="Higher priority Threads\n(added latency)"];
busy -> thread [label="Highest Priority"];
served -> thread [label="Highest Priority (minimum latency)"];
}
* @enddot
*
* In this scenario all the jitter sources previously discussed are also
* present and there is the added jitter caused by the activity of the
* higher priority threads.
*
* <h2>Jitter Mitigation</h2>
* For each of the previously described jitter sources there are possible
* mitigation actions.
*
* <h3>Interrupt handlers optimization</h3>
* An obvious mitigation action is to optimize the interrupt handler code as
* much as possible for speed.<br>
* Complex actions should never be performed in interrupt handlers.
* An handler should just serve the interrupt and wakeup a dedicated thread in
* order to handle the bulk of the work.<br>
* Another possible mitigation action is to evaluate if a specific interrupt
* handler really needs to interact with the OS, if the handler uses full
* stand-alone code then it is possible to remove the OS related overhead.<br>
*
* <h3>Kernel lock zones</h3>
* The OS kernel protects some critical internal data structure by disabling
* (fully in simple architecture, to some extent in more advanced
* microcontrollers) the interrupt sources. Because of this the kernel itself
* is a jitter cause, a good OS design minimizes the jitter generated by the
* kernel by using adequate data structures, algorithms and coding
* practices.<br>
* A good OS design is not the whole story, some OS primitives may generate
* more or less jitter depending on the system state, as example the maximum
* number of threads on a certain queue, the maximum number of nested mutexes
* and so on. Some algorithms employed internally can have constant execution
* time but others may have linear execution time or be even more complex.
*
* <h3>Higher priority threads activity</h3>
* At thread level, the response time is affected by the interrupt-related
* jitter but mainly by the activity of the higher priority threads and
* contention on protected resources.<br>
* It is possible to improve the system overall response time and reduce jitter
* by carefully assigning priorities to the various threads and carefully
* designing mutual exclusion zones.<br>
* The use of the proper synchronization mechanism (semaphores, mutexes, events,
* messages and so on) also helps to improve the overall system performance.
* The use of the Priority Inheritance algorithm implemented in the mutexes
* subsystem can improve the overall response time and reduce jitter but it is
* not a magic wand, a proper system design comes first.
*/

126
ChibiOS_2.0.8/docs/src/licfaq.dox Normal file
View File

@@ -0,0 +1,126 @@
/*
ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 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/>.
---
A special exception to the GPL can be applied should you wish to distribute
a combined work that includes ChibiOS/RT, without being obliged to provide
the source code for any proprietary components. See the file exception.txt
for full details of how and when the exception can be applied.
*/
/**
* @page lic_faq License and F.A.Q.
* ChibiOS/RT is a <a href="http://www.gnu.org/licenses" target="_top">
* GPL3</a>-licensed product but it offers a linking exception in its stable
* releases.<br>
* This article contains some answers about the exception.
*
* @section faq Frequently Asked Questions
* - <b>Is ChibiOS/RT free ?</b><br>
* Yes, free as both in free beer and freedom.
* - <b>Can I use it in my commercial embedded product?</b><br>
* Yes, you just have to advertise that you are using ChibiOS/RT by putting
* a link to the project somewhere on your web site or documentation.
* - <b>Am I forced to release the source code of my product?</b><br>
* The exception to the GPL allows you to use ChibiOS/RT in your commercial
* application without have to release your source code under certains
* conditions. See the @ref exception_text under "Approved Interfaces" for
* details.
* - <b>What I have to contribute back?</b><br>
* In general you have to offer changes done on existing files (where
* allowed) or new developments done using the OS template files. As example:
* - Ports to new architectures because a new port uses copyrighted OS
* template files.
* - New, HAL-style, device drivers because device drivers use copyrighted
* template files.
* - Improvements on modifiable OS code as described in the
* "approved interfaces" section of the @ref exception_text.
* .
* - <b>Is the exception applicable to any ChibiOS/RT version ?</b><br>
* The exception is valid only for ChibiOS/RT releases marked as @e stable.
* Beta, unstable or development versions are covered by the GPL3 alone
* because are meant for testing only.
* - <b>I don't want to be bound by any of the above restriction, is this
* possible?</b><br>
* You may contact us about a commercial license.
* .
* @section exception_text GPL Exception Text
<center><b>GPL Exception Text for ChibiOS/RT 1.4.x</b></center>
In addition, as a special exception, the copyright holder of ChibiOS/RT,
gives You the additional right to link the unmodified code of this Program with
code not covered under the GNU General Public License ("Non-GPL Code") and to
distribute linked combinations including the two, subject to the limitations
in this paragraph.
-# Non-GPL Code permitted under this exception must only link to the
unmodified code of this Program through those well defined interfaces
identified as "Approved Interfaces".
-# Every copy of the combined work is accompanied by a written statement
that details to the recipient the version of ChibiOS/RT used and an
offer by yourself to provide the ChibiOS/RT source code should the
recipient request it.
-# The combined work is not itself an RTOS, scheduler, kernel or related
product.
-# The combined work is not itself a binary library intended for linking
into other software applications.
.
<center><b>The Approved Interfaces</b></center>
-# The files of Non-GPL Code may include the unmodified ChibiOS/RT
distribution header files contained under:
- ./os/kernel/include
- ./os/hal/include
- ./os/hal/platforms
- ./os/various
.
without causing the resulting work to be covered by the GNU General
Public License.
-# The files of Non-GPL Code may link to the unmodified ChibiOS/RT
distribution files contained under:
- ./os/kernel/src
- ./os/hal/src
- ./os/hal/platforms
- ./os/various
.
without causing the resulting work to be covered by the GNU General
Public License.
-# The files of Non-GPL Code may link to, or include, the modified or
unmodified ChibiOS/RT distribution files contained under:
- ./os/kernel/templates
- ./os/hal/templates
- ./os/ports
- ./boards
- ./demos
.
without causing the resulting work to be covered by the GNU General
Public License.
.
Only the copyright holder of ChibiOS/RT may make changes or additions to the
list of Approved Interfaces.
You must obey the GNU General Public License in all respects for all of the
Program code and other code used in conjunction with the Program except the
Non-GPL Code covered by this exception.
*
*/

75
ChibiOS_2.0.8/docs/src/lifecycle.dox Normal file
View File

@@ -0,0 +1,75 @@
/*
ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 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/>.
---
A special exception to the GPL can be applied should you wish to distribute
a combined work that includes ChibiOS/RT, without being obliged to provide
the source code for any proprietary components. See the file exception.txt
for full details of how and when the exception can be applied.
*/
/**
* @page article_lifecycle Threads Lifecycle
* In ChibiOS/RT threads are divided in two categories:
* - <b>Static threads</b>. The memory used for static threads is allocated at
* compile time so static threads are always there, there is no management
* to be done.
* - <b>Dynamic threads</b>. Dynamic threads are allocated at runtime from one
* of the available allocators (see @ref heaps, @ref pools).
* .
* Dynamic threads create the problem of who is responsible of releasing
* their memory because a thread cannot dispose its own memory.<br>
* This is handled in ChibiOS/RT through the mechanism of "thread references",
* When the @p CH_USE_DYNAMIC option is enabled the threads become objects
* with a reference counter. The memory of a thread, if dynamic, is freed
* when the last reference to the thread is released while the thread is in
* its @p THD_STATE_FINAL state.<br>
* The following diagram explains the mechanism:
* @dot
digraph example {
rankdir="LR";
node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true", width="0.75", height="0.75"];
edge [fontname=Helvetica, fontsize=8];
init [label="No thread", style="bold"];
alive [label="Alive"];
final [label="Terminated"];
detached [label="Detached", style="bold"];
init -> alive [label="chThdCreateX()"];
alive -> alive [label="chThdAddRef()"];
alive -> alive [label="chThdRelease()\n[ref > 0]"];
alive -> detached [label="chThdRelease()\n[ref == 0]"];
alive -> init [label="chThdWait()\n[ref == 0]"];
alive -> final [label="chThdExit()\nreturn"];
final -> final [label="chThdAddRef()"];
final -> final [label="chThdRelease()\nchThdWait()\n[ref > 0]"];
final -> init [label="chThdRelease()\nchThdWait()\n[ref == 0]"];
}
* @enddot
* <br>
* As you can see the easiest way to ensure that the memory is released is
* to make another thread perform a @p chThdWait() on the dynamic thread.<br>
* If all the references to the threads are released while the thread is
* still alive then the thread goes in a "detached" state and its memory
* cannot be recovered unless there is a dedicated task in the system that
* scans the threads through the @ref registry subsystem, scanning the registry
* has the side effect to release the zombies (detached and then terminated
* threads).
*/

77
ChibiOS_2.0.8/docs/src/main.dox Normal file
View File

@@ -0,0 +1,77 @@
/*
ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 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/>.
---
A special exception to the GPL can be applied should you wish to distribute
a combined work that includes ChibiOS/RT, without being obliged to provide
the source code for any proprietary components. See the file exception.txt
for full details of how and when the exception can be applied.
*/
/**
* @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">&#12385;&#12403;</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 a PC
* under Linux or Windows.<br>
* Timers, I/O channels and other HW resources are simulated in a guest OS
* process and the application code does not need to be aware of it.
* - 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 6KiB 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.
* - Optional Hardware Abstraction Layer (HAL) with support for many device
* driver models and device driver implementations.
* .
* <h2>Related pages</h2>
* - @subpage credits
* - @subpage lic_faq
* - @subpage goals
* - @subpage target
* - @subpage architecture
* - @subpage concepts
* - @subpage articles
* - @subpage testsuite
* .
*/

145
ChibiOS_2.0.8/docs/src/memory.dox Normal file
View File

@@ -0,0 +1,145 @@
/*
ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 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/>.
---
A special exception to the GPL can be applied should you wish to distribute
a combined work that includes ChibiOS/RT, without being obliged to provide
the source code for any proprietary components. See the file exception.txt
for full details of how and when the exception can be applied.
*/
/**
* @page article_manage_memory How to manage memory
* ChibiOS/RT is a static kernel so you don't need to manage memory at all
* if your application doesn't really require it. This doesn't mean that
* the OS is unable to manage memory but just that memory management is an
* optional part of the whole.<br>
* The OS offers three distinct ways to manage memory, each one with its
* weaknesses and strengths:
* - Core Memory Manager. See @ref memcore.
* - Heap Allocator. See @ref heaps.
* - Memory Pools. See @ref pools.
* .
* The three mechanisms are able to coexist and are well integrated, as example
* the heap allocator uses the core memory manager in order to get more
* memory blocks, memory pools can optionally do the same thing.
*
* <h2>The three subsystems</h2>
* This is a small comparison table regarding the three subsystems, C-runtime
* and static objects are thrown in there for comparison:<br><br>
* <table style="text-align: center; width: 95%;"
* align="center" border="1" cellpadding="2" cellspacing="0">
* <tr>
* <th style="width: 100px; background-color: rgb(192, 192, 192);">
* <small>Subsystem</small>
* </th>
* <th style="width: 80px; background-color: rgb(192, 192, 192);">
* <small>Free capable</small>
* </th>
* <th style="width: 80px; background-color: rgb(192, 192, 192);">
* <small>Constant time</small>
* </th>
* <th style="width: 80px; background-color: rgb(192, 192, 192);">
* <small>Safe</small>
* </th>
* <th style="width: 80px; background-color: rgb(192, 192, 192);">
* <small>From IRQ</small>
* </th>
* <th style="background-color: rgb(192, 192, 192);">
* <small>Notes</small>
* </th>
* </tr>
* <tr>
* <th style="background-color: rgb(224, 224, 224);">
* <small>Static Objects</small>
* </th>
* <td><small>N/A</small></td>
* <td><small>N/A</small></td>
* <td><small>YES</small></td>
* <td><small>YES</small></td>
* <td style="text-align: left;">
* Preferred solution for safety applications.
* </td>
* </tr>
* <tr>
* <th style="background-color: rgb(224, 224, 224);">
* <small>Core Memory Manager</small>
* </th>
* <td><small>NO</small></td>
* <td><small>YES</small></td>
* <td><small>YES</small></td>
* <td><small>YES</small></td>
* <td style="text-align: left;">
* Fast and safe but unable to free allocated memory.
* </td>
* </tr>
* <tr>
* <th style="background-color: rgb(224, 224, 224);">
* <small>Heap Allocator</small>
* </th>
* <td><small>YES</small></td>
* <td><small>NO</small></td>
* <td><small>NO</small></td>
* <td><small>NO</small></td>
* <td style="text-align: left;">
* Unsafe because fragmentation and not constant time, cannot be used
* from IRQ handlers.
* </td>
* </tr>
* <tr>
* <th style="background-color: rgb(224, 224, 224);">
* <small>Memory Pools</small>
* </th>
* <td><small>YES</small></td>
* <td><small>YES</small></td>
* <td><small>YES</small></td>
* <td><small>YES</small></td>
* <td style="text-align: left;">
* Fast and safe but it can handle fixed size objects only, you may have
* multiple memory pools however.
* </td>
* </tr>
* <tr>
* <th style="background-color: rgb(224, 224, 224);">
* <small>C-Runtime</small>
* </th>
* <td><small>YES</small></td>
* <td><small>NO</small></td>
* <td><small>NO</small></td>
* <td><small>NO</small></td>
* <td style="text-align: left;">
* Unsafe because fragmentation, not constant time, cannot be used
* from IRQ handlers and not thread safe. The C runtime must also be
* modified in order to work with the other allocators.
* </td>
* </tr>
* </table>
* <br>
* When designing a system it is recommended to proceed as follow:
* -# Use static objects and initializers whenever possible.
* -# Where dynamic allocation is required without have to free the allocated
* memory then use the Core Memory Manager allocation APIs.
* -# Where dynamic allocation is required evaluate if one or more memory
* pools can be used.
* -# If all the above points do not satisfy your requirements then use the
* heap allocator.
* -# Consider the C-runtime allocator only for legacy code.
* .
*/

217
ChibiOS_2.0.8/docs/src/mutualexcl.dox Normal file
View File

@@ -0,0 +1,217 @@
/*
ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 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/>.
---
A special exception to the GPL can be applied should you wish to distribute
a combined work that includes ChibiOS/RT, without being obliged to provide
the source code for any proprietary components. See the file exception.txt
for full details of how and when the exception can be applied.
*/
/**
* @page article_mutual_exclusion Mutual Exclusion guide
* The most common problem when writing multithreaded code is the
* synchronization on the shared resources/services.<br>
* ChibiOS/RT offers a rich variety of mechanisms that apparently solve the
* same problem. I wrote apparently because each mechanism has its pro and
* cons.
* This article will introduce the various mechanisms and the explain the
* right scenarios for each one.
*
* <h2>Basics</h2>
* Some of the concepts mentioned in this article can be found in the
* following Wikipedia articles:
* - <a href="http://en.wikipedia.org/wiki/Mutual_exclusion" target="_blank">
* Mutual Exclusion</a>
* - <a href="http://en.wikipedia.org/wiki/Priority_inversion" target="_blank">
* Priority Inversion</a>
* - <a href="http://en.wikipedia.org/wiki/Priority_inheritance"
* target="_blank">Priority Inheritance</a>
* - <a href="http://en.wikipedia.org/wiki/Priority_ceiling" target="_blank">
* Priority Ceiling</a>
* .
* <h2>Mutual exclusion by System Locks</h2>
* This is the lowest level mechanism, the system is locked by invoking the
* @p chSysLock() API and then unlocked by invoking @p chSysUnlock().<br>
* The implementation is architecture dependent but it is guaranteed to, at
* least, disable the interrupt sources with hardware priority below or equal
* the kernel level.
*
* <h3>Advantages</h3>
* - It is the lightest as execution time, often a lock or unlock becomes just a
* single inlined assembler instruction.
* - It ensures mutual exclusion among threads but also interrupt handling code.
* - The implementation would ensure mutual exclusion even on multicore
* architectures where multiple hardware threads are present.
* .
* <h3>Disadvantages</h3>
* - Disabling interrupts for a long period of time can deteriorate the overall
* system response time and/or introduce jitter.
* .
* <h3>When use Locks</h3>
* - When mutual exclusion with interrupt handlers is required.
* - When the operation within the lock zone is very simple and has finite
* time.
* .
* <h3>Example</h3>
* @code
* ...
* chSysLock();
* /* Protected code */
* chSysUnlock();
* ...
* @endcode
*
* <h2>Mutual exclusion by Semaphores</h2>
* In ChibiOS/RT the counting semaphores are mainly meant as a
* synchronization mechanism between interrupt handlers and high level code
* running at thread level. Usually a thread waits on a semaphore that is
* signaled asynchronously by an interrupt handler.<br>
* The semaphores can, however, be used as simple mutexes by initializing
* the semaphore counter to one.
*
* <h3>Advantages</h3>
* - The semaphores code is "already there" if you use the I/O queues or
* mailboxes and you don't want to enable the mutexes too in order to save
* space.
* - Semaphores are lighter than mutexes because their queues are FIFO
* ordered and do not have any overhead caused by the priority inheritance
* algorithm.
* - A semaphore takes less RAM than a mutex (12 vs 16 bytes on 32 bit
* architectures).
* .
* <h3>Disadvantages</h3>
* - Semaphore queues are FIFO ordered by default, an option exist to make
* them priority ordered but this can impact I/O performance because
* semaphores are used in I/O queues.
* - Semaphores do not implement the Priority Inheritance algorithm.
* .
* <h3>When use Semaphores</h3>
* - When you don't need queuing by priority nor the Priority Inheritance
* algorithm.
* - When RAM/ROM space is scarce.
* .
* <h3>Example</h3>
* @code
* static Semaphore sem; /* Semaphore declaration */
* ...
* chSemInit(&sem, 1); /* Semaphore initialization before use */
* ...
* chSemWait(&sem);
* /* Protected code */
* chSemSignal(&sem);
* ...
* @endcode
*
* <h2>Mutual exclusion by Mutexes</h2>
* The mutexes are the mechanism intended as the most general solution for
* Mutual Exclusion.
*
* <h3>Advantages</h3>
* - Mutexes implement the Priority Inheritance algorithm that is an important
* tool in reducing jitter and improve overall system response time (it is
* not a magic solution, just another tool for the system designer).
* .
* <h3>Disadvantages</h3>
* - Heaviest among all the possible choices. The Priority Inheritance method
* is efficiently implemented but nothing is more efficient than no code at
* all.
* .
* <h3>When use Mutexes</h3>
* - When you are designing a very complex system with hard realtime
* requirements.
* .
* <h3>Example</h3>
* @code
* static Mutex mtx; /* Mutex declaration */
* ...
* chMtxInit(&mtx); /* Mutex initialization before use */
* ...
* chMtxLock(&mtx);
* /* Protected code */
* chMtxUnlock();
* ...
* @endcode
*
* <h2>Mutual exclusion by priority boost</h2>
* Another way to implement mutual exclusion is to boost the thread priority
* to a level higher than all of the threads competing for a certain resource.
* This solution effectively implements an Immediate Priority Ceiling
* algorithm.
*
* <h3>Advantages</h3>
* - Almost free as code size, you need no semaphores nor mutexes.
* - No RAM overhead.
* - Fast execution, priority change is a quick operation under ChibiOS/RT.
* - The Priority Ceiling protocol can help mitigate potential Priority
* Inversion problems.
* .
* <h3>Disadvantages</h3>
* - Makes the design more complicated because priorities must be assigned to
* not just threads but also assigned to the resources to be protected.
* - Locking a resource affects all the threads with lower priority even if
* not interested to the resource.
* - All the threads that can access the resource must have lower priority
* than the resource itself.
* - The mechanism is not easy to understand in the code unless it is clearly
* documented.
* - This method does not work in on multicore architectures where multiple
* hardware threads are present.
* - Only useful in very simple applications.
* .
* <h3>Example</h3>
* @code
* /* Priority assigned to the resource, threads must have lower
* priority than this.*/
* #define AAA_RESOURCE_PRIORITY NORMALPRIO+10
* ...
* /* Locks the resources AAA.*/
* tprio_t aaa_old_prio = chThdSetPriority(AAA_RESOURCE_PRIORITY);
* /* Accessing resource AAA */
* chThdSetPriority(aaa_old_prio); /* Unlocks AAA.*/
* ...
* @endcode
*
* <h2>Mutual exclusion by message passing</h2>
* Another method is to make a single dedicated thread execute the critical
* code and make it work as a messages server. The other threads can request
* the service to the server by sending a properly formatted message and
* then wait for the answer with the result.<br>
* This method is very useful when integrating into the system components not
* designed to be reentrant or to be executed in a multithreaded environment,
* as example a 3rd part file system or a networking protocol stack.
*
* <h3>Advantages</h3>
* - It is possible to encapsulate very complex logic without worry about
* about concurrent accesses.
* - If the encapsulate code uses a large stack area only the server thread
* have to allocate enough RAM, the client threads save RAM by just
* requesting the service to the server.
* - Clean system architecture.
* - This method also implements a form of Priority Ceiling. The ceiling is
* the priority of the server thread itself.
* .
* <h3>Disadvantages</h3>
* - More complex implementation, a protocol must be created between clients
* and server.
* - Two context switches are required for each request to the server (but
* ChibiOSRT is very efficient at that).
* - Requires a dedicated thread as server.
* .
*/

127
ChibiOS_2.0.8/docs/src/portguide.dox Normal file
View File

@@ -0,0 +1,127 @@
/*
ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 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/>.
---
A special exception to the GPL can be applied should you wish to distribute
a combined work that includes ChibiOS/RT, without being obliged to provide
the source code for any proprietary components. See the file exception.txt
for full details of how and when the exception can be applied.
*/
/**
* @page article_portguide Porting ChibiOS/RT for Dummies
* Porting the operating system on a new platform is one of the most common
* tasks. The difficulty can range from easy to very difficult depending
* on several factors.<br>
* We can divide in problem in several classes of progressively increasing
* difficulty:
* - @ref port_board
* - @ref port_family
* - @ref port_chip
* - @ref port_core
* .
* Another kind of port type is porting to another compiler and this is an
* added complexity level on the above classes. The kernel itself is portable
* but the port-specific code usually contains compiler specific extensions to
* the C language and the asm files syntax is almost never compatible.
*
* @section port_board Porting the OS to a new board
* This is the easiest port type, the scenario is that the specific
* microcontroller is already supported and a demo exists. This scenario also
* applies when porting the OS on a custom hardware using a supported
* microcontroller. This task can be easily performed with the following
* steps:
* -# Create a new directory under ./boards and copy inside the board files
* from another board using the same microcontroller.
* -# Customize the board files:
* - @p board.h This file contains the I/O pins setup for the uC, it
* may also contain other board-dependent settings, as example, the clock
* frequency. Customize this file depending on your target hardware.
* - @p board.c This file contains the initialization code, it is possible
* you just need to customize @p board.h and not this file. If you have
* some hardware specific initialization code then put it here.
* .
* -# Create a new directory under the ChibiOS/RT installation directory:
* <tt>./projects/<i>@<my_app_name@></i></tt>
* -# Copy an existing demo code under the newly created directory.
* -# Customize the demo:
* - @p Makefile You may edit this file in order to remove the test related
* sources and/or add you application source files.
* - @p main.c It contains the demo simple code, clean it and write your
* own @p main() function here, use this file just as a template.
* -# Compile your application and debug.
* .
* @section port_family Porting the OS to a closely related microcontroller
* In this scenario all the above steps are required but an analysis must
* be performed to evaluate the differences between from the supported micro
* and the target micro. Often the micros just differ for the memory area
* sizes and a change to the linker script is enough (the file is usually
* named @p ch.ld). Chips having more or less peripherals, everything else
* being the same or compatible are not a problem also as long the timer and
* the serial peripherals used by the port do not change.<br>
* If there are differences in the internal peripherals, as example non
* compatible interrupt controllers (this happens in the LPC2000 family)
* or differences in UARTS, timers etc then the port falls in the following
* category.
*
* @section port_chip Porting the OS to another microcontroller using the same core
* This kind of port is required when a target microcontroller has the same
* core (a common example: ARM7) of a supported microcontroller but has
* differences in the internal peripherals.<br>
* If this is your case proceed as follow:
* -# Create a new directory under @p <tt>./os/io/platforms</tt> and
* name it with the microcontroller name (or family name).<br>
* In case of the ARM-based microcontroller you also need to create a
* equally named directory under
* @p <tt>./os/ports/<i>@<compiler@></i>/<i>@<arch@></i></tt> and
* put there the microcontroller related files such as the vectors table,
* see the existing ports as example.
* -# Copy into the newly created directory the most closely related existing
* chip port or the naked template files from
* @p <tt>./os/io/templates</tt>.
* -# Work out the differences in the drivers or implement them if you started
* from the templates.
* -# Edit/create the documentation file @p <tt>platform.dox</tt>, this
* is required if you want to regenerate this documentation including
* your work.
* .
* Usually this kind of port just requires a serial driver (and those are very
* similar each other) and some code for the interrupt controller (this one
* can be part of the core port, as example the Cortex-M3 has this as standard
* part of the core).<br>
* When the chip port is completed created your application as seen in the
* previous sections.
*
* @section port_core Porting the OS to a whole new architecture
* This is the hardest scenario, the time required by core ports depends
* strongly by the target architecture complexity and the level of support you
* need for the architecture specific features.<br>
* As a reference, the MSP430 port took me 2 hours and it worked at the first
* run, it can be a reference for simple architectures, the ARM Cortex-M3 was
* painful instead, the architecture enforces you to implement things in a very
* specific way and I spent 2 week to go through all the documentation and
* figure out the correct way to implement the port (you can see that the
* preemption context switch is done in a very peculiar way because the
* exceptions architecture).<br>
* One thing is sure, port an OS to a new architecture is not an easy task and
* if you have the required experience for such an effort then probably you
* don't need any advice from me. Just follow the directory patterns and fill
* the OS template files, the hardest part is decide the correct and efficient
* way to implement the context switching.
*/

57
ChibiOS_2.0.8/docs/src/roundrobin.dox Normal file
View File

@@ -0,0 +1,57 @@
/*
ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 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/>.
---
A special exception to the GPL can be applied should you wish to distribute
a combined work that includes ChibiOS/RT, without being obliged to provide
the source code for any proprietary components. See the file exception.txt
for full details of how and when the exception can be applied.
*/
/**
* @page article_roundrobin Round Robin scheduling explained
* Unlike many other RTOSes, ChibiOS/RT supports multiple threads at the
* same priority level and schedules them using an <i>aggressive</i>
* round-robin strategy.<br>
* The strategy is defined as aggressive because any scheduling event
* causes the round-robin threads to rotate.<br>
* A round-robin rotation can happen because of the following events:
* - The currently executed thread voluntarily invokes the @p chThdYield()
* API in order to allow the execution of another thread at the same
* priority level, if any.
* - The currently executed thread voluntarily goes into a sleep state
* (see @ref thread_states), when the thread is awakened it goes behind
* any other thread at the same priority level.
* - The currently executed thread is preempted by an higher priority
* thread, the thread is reinserted in the ready list (see @ref scheduling)
* behind any other thread at the same priority level.
* - If the @p CH_TIME_QUANTUM configuration constant is set to a value
* greater than zero and if the specified time quantum expired and if
* a thread with equal priority is ready then the currently executing
* thread is automatically reinserted in the ready list behind any
* other thread at the same priority level.
* .
* As you can see the @p CH_TIME_QUANTUM setting is really useful only if
* there are threads at the same priority level that can run not preempted
* for long periods of time and that do not explicitly yield using
* @p chThdYield(). Because of this you should consider setting
* @p CH_TIME_QUANTUM to zero in your configuration file, this makes the
* kernel much faster and smaller and <b>does not</b> forbid the use of
* multiple threads at the same priority level.
*/

88
ChibiOS_2.0.8/docs/src/saveram.dox Normal file
View File

@@ -0,0 +1,88 @@
/*
ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 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/>.
---
A special exception to the GPL can be applied should you wish to distribute
a combined work that includes ChibiOS/RT, without being obliged to provide
the source code for any proprietary components. See the file exception.txt
for full details of how and when the exception can be applied.
*/
/**
* @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();
...
chThdCreateStatic(waMyThread, sizeof(waMyThread), NORMALPRIO, MyThread, NULL);
...
}
* @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 WORKING_AREA(waMyThread, 64);
__attribute__((noreturn))
static void MyThread(void *arg) {
while (!chThdShoudTerminate()) {
/* Do thread inner work */
}
chThdExit(1);
}
main() {
chSysInit();
...
chThdCreateStatic(waMyThread, sizeof(waMyThread), NORMALPRIO,
(tfunc_t)MyThread, NULL);
...
}
* @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.
*/

114
ChibiOS_2.0.8/docs/src/stacks.dox Normal file
View File

@@ -0,0 +1,114 @@
/*
ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 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/>.
---
A special exception to the GPL can be applied should you wish to distribute
a combined work that includes ChibiOS/RT, without being obliged to provide
the source code for any proprietary components. See the file exception.txt
for full details of how and when the exception can be applied.
*/
/**
* @page article_stacks Stacks and stack sizes
* In an RTOS like ChibiOS/RT there are several dedicated stacks, each stack
* has a dedicated RAM space that must have a correctly sized assigned area.
* <h2>The stacks</h2>
* There are several stacks in the systems, some are always present, some
* others are present only in some architectures:
* - <b>Main stack</b>, this stack is used by the @p main() function and the
* thread that execute it. It is not a normal thread stack because it is
* initialized in the startup code and its size is defined in a port
* dependent way. Details are in the various ports documentation.
* - <b>Interrupt Stack</b>, some architectures have a dedicated interrupt
* stack. This is an important feature in a multithreaded environment,
* without a dedicated interrupt stack each thread has to reserve
* enough space, for interrupts servicing, within its own stack. This space,
* multiplied by the total threads number, can amount to a significant RAM
* overhead.
* - <b>Thread Stack</b>, each thread has a dedicated stack for its own
* execution and context switch.
* - <b>Other Stacks</b>, some architectures (ARM) can have other stacks but
* the OS does not directly use any of them.
* .
* <h2>Risks</h2>
* The most critical thing when writing an embedded multithreaded application
* is to determine the correct stack size for main, threads and, when present,
* interrupts.<br>
* Assigning too much space to a stack is a waste of RAM, assigning too little
* space leads to crashes or, worst scenario, hard to track instability.
*
* <h2>Assigning the correct size</h2>
* You may try to examine the asm listings in order to calculate the exact
* stack requirements but this requires much time, experience and patience.<br>
* An alternative way is to use an interactive method. Follow this procedure
* for each thread in the system:
* - Enable the following debug options in the kernel:
* - @p CH_DBG_ENABLE_STACK_CHECK, this enables a stack check before any
* context switch. This option halts the system in @p chSysHalt() just
* before a stack overflow happens. The halt condition is caused by
* a stack overflow when the global variable @p panic_msg is set to
* @p NULL, normally it would point to a panic message.
* - @p CH_DBG_FILL_THREADS, this option fills the threads working area
* with an easily recognizable pattern (0x55).
* - Assign a large and safe size to the thread stack, as example 256 bytes
* on 32 MCUs, 128 bytes on 8/16 bit MCUs. This is almost always too much
* for simple threads.
* - Run the application, if the application crashes or halts then increase
* the stack size and repeat (you know how to use the debugger right?).
* - Let the application run and make sure to trigger the thread in a way to
* make it follow most or all its code paths. If the application crashes or
* halts then increase the stack size and repeat.
* - Stop the application using the debugger and examine the thread working
* area (you know what a map file is, right?). You can see that the thread
* stack overwrote the fill pattern (0x55) from the top of the working area
* downward. You can estimate the excess stack by counting the untouched
* locations.
* - Trim down the stack size and repeat until the application still runs
* correctly and you have a decent margin in the stack.
* - Repeat for all the thread classes in the system.
* - Turn off the debug options.
* - Done.
* .
* <h2>Final Notes</h2>
* Some useful info:
* - Stack overflows are the most common problems source during development,
* when in trouble with crashes or anomalous behaviors always first verify
* stack sizes.
* - The required stack size can, and very often does change when changing
* compiler vendor, compiler version, compiler options, code type (ARM
* or THUMB as example).
* - Code compiled in THUMB mode uses more stack space compared to the
* same code compiled in ARM mode. In GCC this is related to lack of tail
* calls optimizations in THUMB mode, this is probably true also in other
* compilers.
* - Speed optimized code often requires less stack space compared to space
* optimized code. Be careful when changing optimizations.
* - The interrupts space overhead on the thread stacks (@p INT_REQUIRED_STACK
* defined in @p chcore.h) is included in the total working area size
* by the system macros @p THD_WA_SIZE() and @p WORKING_AREA().<br>
* The correct way to reserve space into the thread stacks for interrupts
* processing is to override the @p INT_REQUIRED_STACK default value.
* Architectures with a dedicated interrupt stack do not require changes
* to this value. Resizing of the global interrupt stack may be required
* instead.
* - Often is a good idea to have some extra space in stacks unless you
* are really starved on RAM. Anyway, it is best to optimize stack space
* at the very end of your development cycle.
* .
*/

140
ChibiOS_2.0.8/docs/src/stop_os.dox Normal file
View File

@@ -0,0 +1,140 @@
/*
ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 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/>.
---
A special exception to the GPL can be applied should you wish to distribute
a combined work that includes ChibiOS/RT, without being obliged to provide
the source code for any proprietary components. See the file exception.txt
for full details of how and when the exception can be applied.
*/
/**
* @page article_stop_os How to cleanly stop the OS
* Stopping the OS should not be normally required but there are scenarios
* where one might want the complete control over the system again.
* As example entering into a bootload mode, or invoking some flashing
* algorithm locked in ROM.<br>
* ChibiOS/RT does not have a shutdown API and there is a reason for this,
* stopping the kernel would not be enough, a well defined operations sequence
* is required.<br>
* The shutdown operation should always be implemented into the @p main()
* function because in that context the stack pointer is guaranteed to be
* in the area allocated by the startup code. Stopping from a thread would
* leave the stack pointer "somewhere".<br>
* The shutdown sequence should include the following steps, some steps
* are optional and depend on the application:
* - Safely stop critical threads. As example a thread that uses a File System
* should flush all the modified buffers to the persistent storage before
* terminating.<br>
* The system should be designed to request the thread termination using
* @p chThdTerminate() and then wait its termination using @p chThdWait().
* This phase can be skipped for non-critical threads.
* - Invoke the xxxStop() method on all the active device drivers, this
* disables the interrupt sources used by the various peripherals. This
* is required in order to not have interrupts after the shutdown that
* may invoke OS primitives.
* - Invoke chSysDisable().
* - Stop the system timer whose service routine invokes
* @p chSysTimerHandlerI().
* - Disable any other interrupt source that may invoke OS APIs. In general
* all the interrupt sources that have handlers declared by using the
* @p CH_IRQ_HANDLER() macro.
* - Perform any application related de-initialization.
* - Invoke chSysEnable().
* .
* Now the OS is stopped and you can safely assume there are nothing going on
* under the hood. From here you can also restart the OS after finishing your
* critical operations using the following sequence:
* - Invoke chSysDisable().
* - Restart the system timer.
* - Reinitialize the OS by invoking @p chSysInit().
* - Restart your device drivers using the @p xxxStart() methods.
* - Restart all your threads.
* .
* <h2>Example</h2>
* This is an example of an hypothetical application that have to shutdown
* the OS when a certain event is generated.
* @code
#include "ch.h"
#include "hal.h"
/* A shutdown flag.*/
bool_t shutdown_required;
/* Critical thread.*/
static void my_thread(void *p) {
while (!chThdShouldTerminate()) {
/* Normal thread activity code.*/
}
/* Thread de-initialization before terminating, here you put the critical
thread finalization code.*/
return 0;
}
/* Main program, it is entered with interrupts disabled.*/
void main(void) {
/* HAL initialization, you need to do this just once.*/
halInit();
/* Main loop, the main() function never exits.*/
while (TRUE) {
Thread *tp;
shutdown_required = FALSE;
/* ChibiOS/RT initialization. This function becomes an OS thread.*/
chSysInit();
/* Starting a device driver, SD2 in this case.*/
sdStart(&SD2, NULL);
/* Starting our critical thread.*/
tp = chThdCreateFromHeap(NULL, THD_WA_SIZE(256),
NORMALPRIO, my_thread, &SD2);
/* Main thread activity into a loop.*/
while (!shutdown_required) {
/* Main activity, OS active until a shutdown becomes necessary.*/
}
/* Starting the shutdown sequence.*/
chThdTerminate(tp); /* Requesting termination. */
chThdWait(tp); /* Waiting for the actual termination. */
sdStop(&SD2); /* Stopping serial port 2. */
chSysDisable();
stop_system_timer();
stop_any_other_interrupt();
chSysEnable();
/* Now the main function is again a normal function, no more a
OS thread.*/
do_funny_stuff();
/* Restarting the OS but you could also stop the system or trigger a
reset instead.*/
chSysDisable();
}
}
* @endcode
* As you can see it is possible to jump in and out of the "OS mode" quite
* easily. Note that this is just an example, the real code could be very
* different depending on your requirements.
*/

89
ChibiOS_2.0.8/docs/src/target.dox Normal file
View File

@@ -0,0 +1,89 @@
/*
ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 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/>.
---
A special exception to the GPL can be applied should you wish to distribute
a combined work that includes ChibiOS/RT, without being obliged to provide
the source code for any proprietary components. See the file exception.txt
for full details of how and when the exception can be applied.
*/
/**
* @page target Application Range
* @brief ChibiOS/RT Application Range.
* - @ref applications
* - @ref min_requirements
* - @ref desirable_features
* - @ref upper_limit
* .
* @section applications Application Scenarios
* ChibiOS/RT is usable in many applicative areas, as example and not limited
* to:
* - Automotive.
* - Robotic Applications.
* - Consumer Electronics.
* - Energy Management.
* - Teaching and Learning.
* - Hobby.
* .
* @section min_requirements Absolute Minimum Requirements
* A certain set of minimum system requirements must be satisfied in order to
* use ChibiOS/RT on a new architecture:
* - 8bits architecture minimum.
* - A "real" stack pointer that can be positioned anywhere in the data address
* space. The OS could be ported to architectures with an hardware stack but
* I wouldn't recommend it because the context switch would become
* ridiculously inefficient.
* - Support for maskable interrupt sources and at least an OS-dedicated timer.
* - Support for standard C89 (C99 supported) language with no
* architecture-related non-standard restrictions. Non standard mandatory
* language extensions or restrictions may result in reduced functionality
* or impossibility of use.
* - 256/512bytes RAM permanently allocated to the kernel and its two mandatory
* threads "idle" and "main", the exact amount depends on the architecture.
* This figure is not inclusive of the HAL and device drivers (non mandatory
* components).
* - 8KiB of program space for a full featured kernel scalable down to about
* 1.2KiB for reduced configurations. This figure is not inclusive of the
* HAL and device drivers (non mandatory components).
* .
* @section desirable_features Desirable Features
* - Efficient instruction set for linked lists traversal. The kernel makes
* extensive use of simple and bidirectional linked lists so the performance
* is directly affected by the supported addressing modes, number of
* registers etc.
* - Uniformly sized C pointers.
* - 2KiB RAM.
* - 16KiB ROM/Flash.
* .
* @section upper_limit Upper Recommended Limit
* The application range of ChibiOS/RT ends when one or more of the following
* features are required:
* - Separation between user code space and kernel space, both just logical or
* using a Memory Management/Protection Unit. Applications in ChibiOS/RT are
* supposed to be monolithic and trusted. The kernel and the application
* share the same address space.
* - Multiple applications. ChibiOS/RT supports the single multithreaded
* application model.
* - Multicore SMP architectures. Currently ChibiOS/RT only supports a single
* core unless running multiple distinct and separate OS instances.
* A true multicore kernel is planned for when multicore MCUs will become
* commonly available.
* .
*/

98
ChibiOS_2.0.8/docs/src/timing.dox Normal file
View File

@@ -0,0 +1,98 @@
/*
ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 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/>.
---
A special exception to the GPL can be applied should you wish to distribute
a combined work that includes ChibiOS/RT, without being obliged to provide
the source code for any proprietary components. See the file exception.txt
for full details of how and when the exception can be applied.
*/
/**
* @page article_timing Reliable timings using Threads
* One common task is to have threads do something at regular, scheduled,
* intervals.
* An obvious solution is to write something like this:
* @code
msg_t my_thread(void *param) {
while (TRUE) {
do_something();
chThdSleepMilliseconds(1000); // Fixed interval
}
}
* @endcode
* This example works well assuming that the @p do_something() execution time
* is well below the system tick period and that @p my_thread() is not
* preempted by other threads that could insert long intervals.<br>
* If the above conditions are not satisfied you may have @p do_something()
* executed at irregular intervals, as example:<br><br>
* T0...T0+1000...T0+2002...T0+3002...T0+4005...etc.<br><br>
* Also note that the error increases over time and this kind of behavior can
* lead to anomalies really hard to debug.
* <h2>A better solution</h2>
* It is possible to rewrite the above code using absolute deadlines rather
* than fixed intervals:
* @code
msg_t my_thread(void *param) {
systick_t time = chTimeNow(); // T0
while (TRUE) {
time += MS2ST(1000); // Next deadline
do_something();
chThdSleepUntil(time);
}
}
* @endcode
* Using this code @p do_something() will always be executed at an absolute
* deadline time and the error will not accumulate over time regardless of
* the execution time and delays inserted by other threads.<br>
* Note that this solution requires that the @p do_something() execution
* time must not exceed the deadline or the thread would stay sleeping into
* @p chThdSleepUntil().
*
* <h2>A different way</h2>
* Another way to perform activities at regular intervals is the use of a
* virtual timer. Virtual timers are able to generate callbacks at scheduled
* intervals. Virtual timers are one shot timers so you need to restart them
* from within the callback if you need a periodic timer like in this case.
* @code
VirtualTimer vt;
void do_something(void *p) {
chVTSetI(&vt, MS2ST(1000), do_something, p); // Restarts the timer.
// Periodic code here.
}
int main(int argc, char **argv) {
chSysLock();
chVTSetI(&vt, MS2ST(1000), do_something, NULL); // Starts the timer.
chSysUnlock();
...
}
* @endcode
* Note that the callback code is executed from within the I-Locked state (see
* @ref system_states) so you can only execute I-Class APIs from there (see
* @ref api_suffixes).<br>
* This solution has the advantage to not require a dedicated thread and
* thus uses much less RAM but the periodic code must have a very short
* execution time or it would degrade the overall system response time.
*/

155
ChibiOS_2.0.8/docs/src/wakeup.dox Normal file
View File

@@ -0,0 +1,155 @@
/*
ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010 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/>.
---
A special exception to the GPL can be applied should you wish to distribute
a combined work that includes ChibiOS/RT, without being obliged to provide
the source code for any proprietary components. See the file exception.txt
for full details of how and when the exception can be applied.
*/
/**
* @page article_wakeup How to wake up a thread from an interrupt handler
* Waking up a thread after an hardware event is one of the most common tasks
* that an RTOS must be able to perform efficiently. In ChibiOS/RT there are
* several mechanisms that can be used, often each mechanism is best suited
* in a specific scenario.
*
* <h2>Synchronously waking up a specific thread</h2>
* A common situation is to have to synchronously wake up a specific thread.
* This can be accomplished without the use of any specific synchronization
* primitive, it uses the very efficient low level scheduler APIs, note that
* you can also optionally send a simple message from the IRQ handler to
* the thread.
* @code
static Thread *tp = NULL;
void mythread(void *p) {
while (TRUE) {
msg_t msg;
// Waiting for the IRQ to happen.
chSysLock();
tp = chThdSelf();
chSchGoSleepS(PRSUSPENDED);
msg = chThdSelf()->p_rdymsg; // Retrieving the message, optional
chSysUnlock();
// Perform processing here.
}
}
CH_IRQ_HANDLER(myIRQ) {
CH_IRQ_PROLOGUE();
// Wakes up the thread.
chSysLockFromIsr();
if (tp != NULL) {
tp->p_rdymsg = (msg_t)55; // Sending the message, optional
chSchReadyI(tp);
tp = NULL;
}
chSysUnlockFromIsr().
CH_IRQ_EPILOGUE();
}
* @endcode
*
* <h2>Synchronously waking up one of the waiting threads</h2>
* Lets assume you have a queue of waiting threads, you want to wake up
* the threads one by one in FIFO order, if there are no waiting threads
* then nothing happens.<br>
* This can be accomplished using a @p Semaphore object initialized to zero:
* @code
CH_IRQ_HANDLER(myIRQ) {
CH_IRQ_PROLOGUE();
// If there is at least one waiting thread then signal it.
chSysLockFromIsr();
if (chSemGetCounterI(&mysem) < 0)
chSemSignalI(&mysem);
chSysUnlockFromIsr().
CH_IRQ_EPILOGUE();
}
* @endcode
*
* <h2>Synchronously waking up all the waiting threads</h2>
* In this scenario you want to synchronously wake up all the waiting threads,
* if there are no waiting threads then nothing happens.<br>
* This can be accomplished using a @p Semaphore object initialized to zero:
* @code
CH_IRQ_HANDLER(myIRQ) {
CH_IRQ_PROLOGUE();
// Wakes up all the threads waiting on the semaphore.
chSysLockFromIsr();
chSemResetI(&mysem);
chSysUnlockFromIsr().
CH_IRQ_EPILOGUE();
}
* @endcode
*
* <h2>Asynchronously waking up a specific thread</h2>
* If you have to asynchronously wake up a specific thread then a simple
* event flags can be used.
* @code
static Thread *tp;
void mythread(void *p) {
tp = chThdSelf();
while (TRUE) {
// Checks if an IRQ happened else wait.
chEvtWaitAny((eventmask_t)1);
// Perform processing here.
}
}
CH_IRQ_HANDLER(myIRQ) {
CH_IRQ_PROLOGUE();
// Wakes up the thread.
chSysLockFromIsr();
chEvtSignalI(tp, (eventmask_t)1);
chSysUnlockFromIsr().
CH_IRQ_EPILOGUE();
}
* @endcode
*
* <h2>Asynchronously waking up one or more threads</h2>
* By using event sources it is possible to asynchronously wake up one or more
* listener threads. The mechanism requires a single initialized
* @p EventSource object, all the threads registered as listeners on the
* event source will be broadcasted.
* @code
CH_IRQ_HANDLER(myIRQ) {
CH_IRQ_PROLOGUE();
// Pends an event flag on all the listening threads.
chSysLockFromIsr();
chEvtBroadcastI(&my_event_source);
chSysUnlockFromIsr().
CH_IRQ_EPILOGUE();
}
* @endcode
*/