diff options
Diffstat (limited to 'docs/src')
| -rw-r--r-- | docs/src/concepts.dox | 246 |
1 files changed, 181 insertions, 65 deletions
diff --git a/docs/src/concepts.dox b/docs/src/concepts.dox index 9c09041a7..35c086506 100644 --- a/docs/src/concepts.dox +++ b/docs/src/concepts.dox @@ -36,7 +36,7 @@ * @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
+ * @section api_suffixes API Name 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
@@ -112,58 +112,104 @@ * real associated machine state on some architectures. The following diagram
* shows the possible transitions between the states:
*
+ * @if LATEX_PDF
* @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"];
+ size="5, 7";
+ 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()"];
+ disab -> susp [label="chSysSuspend()"];
+ 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
+ * @else
+ * @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()"];
+ disab -> susp [label="chSysSuspend()"];
+ 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
+ * @endif
* 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"];
+ size="5, 7";
+ 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 *"];
+ sfi [label="SFI"];
+ any1 -> sfi [style="dotted", label="Fast IRQ"];
+ sfi -> any1 [label="Fast IRQ return"];
+ }
+ * @enddot
+ * @dot
+ digraph example {
+ size="5, 7";
+ rankdir="LR";
+ node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true", width="0.75", height="0.75"];
+ edge [fontname=Helvetica, fontsize=8];
+ any2 [label="Any State"];
+ halt [label="Halted"];
+ SNMI [label="SNMI"];
+ 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>.
@@ -174,8 +220,10 @@ * 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>
+ * @if LATEX_PDF
* @dot
digraph example {
+ size="5, 7";
rankdir="LR";
node [shape=square, fontname=Helvetica, fontsize=8,
@@ -209,35 +257,99 @@ rh -> T3 -> Tm -> T2 -> T1 -> Ti -> rh [label="p_prev"];
}
* @enddot
+ * @else
+ * @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
+ * @endif
* <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
+ * @section thread_states Thread States
* The image shows how threads can change their state in ChibiOS/RT.<br>
+ * @if LATEX_PDF
+ * @dot
+ digraph example {
+ size="5, 7";
+ 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="chSchWakepuS()"];
+ sleep -> ready [label="chSchWakepuS()"];
+ run -> stop [label="chThdExit()"];
+ }
+ * @enddot
+ * @else
* @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()"];
+ 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="chSchWakepuS()"];
+ sleep -> ready [label="chSchWakepuS()"];
+ run -> stop [label="chThdExit()"];
}
* @enddot
+ * @endif
*
* @section priority Priority Levels
* Priorities in ChibiOS/RT are a contiguous numerical range but the initial
@@ -261,13 +373,17 @@ * (inclusive) are reserved. This is the highest numerical value of the
* priorities space.
* .
- * @section warea Threads Working Area
+ * @section warea Thread 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>
+ * @if LATEX_PDF
+ * @image latex workspace.eps
+ * @else
* @image html workspace.png
+ * @endif
* <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
|