Improvements to the concepts article.

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

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,6 +112,41 @@
  * real associated machine state on some architectures. The following diagram
  * shows the possible transitions between the states:
  *
+ * @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];
+    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";
@@ -134,6 +169,7 @@
     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];
@@ -143,21 +179,31 @@
     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 {
+    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 *"];
-      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"];
+  }
+ * @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"];
@@ -174,6 +220,44 @@
  * 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,
+          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
+ * @else
  * @dot
   digraph example {
     rankdir="LR";
@@ -209,15 +293,18 @@
     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 {
-      /*rankdir="LR";*/
+    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"];
@@ -233,11 +320,36 @@
     suspend -> run [label="chThdResume()"];
     suspend -> ready [label="chThdResume()"];
     run -> sleep [label="chSchGoSleepS()"];
-      sleep -> run [label="chSchWakepS()"];
+    sleep -> run [label="chSchWakepuS()"];
-      sleep -> ready [label="chSchWakepS()"];
+    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="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