Improvements to the concepts article.

git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@2181 35acf78f-673a-0410-8e92-d51de3d6d3f4

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