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

docs/ch.txt

@@ -3,7 +3,7 @@
  * @author Giovanni Di Sirio (gdisirio@users.sourceforge.net).
  * @section Chibi Chibi ?
  * 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
+ * @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>.
  * @section ch_features Features
@@ -68,9 +68,9 @@
  * @a Heap, @a Pool.
  * The suffix is not present for normal APIs but can be one of
  * the following:
- * - <b>"I"</b>, I-Class APIs are invokeable only from the I-Locked or S-Locked
+ * - <b>"I"</b>, I-Class APIs are invokable only from the I-Locked or S-Locked
  *   states. See @ref system_states.
- * - <b>"S"</b>, S-Class APIs are invokeable only from the S-Locked state. See
+ * - <b>"S"</b>, S-Class APIs are invokable only from the S-Locked state. See
  *   @ref system_states.
  *
  * The APIs without suffix can be invoked only from the user code in the Normal
@@ -105,33 +105,78 @@
  *   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>All Disabled</b>. When the system is in this state both the maskable
+ * - <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 chSysDisable() or chSysEnable().
+ *   possible to use any system API except @p chSysSuspend() or
- *   This state is entered using @p chSysDisableAll().
+ *   @p chSysEnable().
- * - <b>Disabled</b>. In this state the fast interrupt sources are enabled but
+ *   This state is entered using @p chSysDisable().
+ * - <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 chSysDisableAll() or chSysEnable().
+ *   to use any system API except @p chSysDisable() or @p chSysEnable().
  * - <b>Normal</b>. All the interrupt sources are enabled and the system APIs
  *   are accessible, threads are running.
+ * - <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. I-Class and S-Class APIs are
+ *   Fast interrupt sources are enabled. S-Class and I-Class APIs are
- *   invokeable in this state.
+ *   invokable in this state.
  * - <b>I-Locked</b>. Kernel locked and regular interrupt sources disabled.
- *   I-Class and APIs are invokeable from this state.
+ *   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 chSysLockI() and then
- *   invoke any I-Class API.
+ *   invoke any 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>. No system APIs are accessible.
- * - <b>Serving Non-Maskable Interrupt</b>. No systemAPIs are accessible.
+ * - <b>Serving Non-Maskable Interrupt</b>. System APIs are not accessible.
- * - <b>Halted</b>. All interrupt sources disabled and system stopped into an
+ * - <b>Halted</b>. All interrupt sources are disabled and system stopped into
- *   infinite loop. This state can be reached if the debug mode is activated
+ *   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 state are just <b>Logical States</b> that can have no
- * real machine state associated. The following diagram shows the possible
+ * real machine state associated on some architectures. The following diagram
- * transitions between the states:
+ * 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"];
+      init [label="Initialization", 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"];
+      sfi [label="SFI"];
+      init -> norm [label="chSysInit()", fontname=Helvetica, fontsize=8];
+      norm -> slock [label="chSysLock()", fontname=Helvetica, fontsize=8, constraint=false];
+      slock -> norm [label="chSysUnlock()", fontname=Helvetica, fontsize=8];
+      norm -> susp [label="chSysSuspend()", fontname=Helvetica, fontsize=8];
+      susp -> disab [label="chSysDisable()", fontname=Helvetica, fontsize=8];
+      norm -> disab [label="chSysDisable()", fontname=Helvetica, fontsize=8];
+      susp -> norm [label="chSysEnable()", fontname=Helvetica, fontsize=8];
+      disab -> norm [label="chSysEnable()", fontname=Helvetica, fontsize=8];
+      slock -> ilock [dir="both", label="Context Switch", fontname=Helvetica, fontsize=8];
+      norm -> sri [style="dotted", label="Regular IRQ", fontname=Helvetica, fontsize=8];
+      norm -> sfi [style="dotted", label="Fast IRQ", fontname=Helvetica, fontsize=8];
+      susp -> sfi [style="dotted", label="Fast IRQ", fontname=Helvetica, fontsize=8];
+      sri -> norm [label="Regular IRQ return", fontname=Helvetica, fontsize=8];
+      sfi -> norm [label="Fast IRQ return", fontname=Helvetica, fontsize=8];
+      sfi -> susp [label="Fast IRQ return", fontname=Helvetica, fontsize=8];
+      sri -> ilock [label="chSysLockI()", fontname=Helvetica, fontsize=8, constraint=false];
+      ilock -> sri [label="chSysUnlockI()", fontname=Helvetica, fontsize=8];
+      norm -> sleep [label="Idle Thread", fontname=Helvetica, fontsize=8];
+      sleep -> sri [style="dotted", label="Regular IRQ", fontname=Helvetica, fontsize=8];
+      sleep -> sfi [style="dotted", label="Fast IRQ", fontname=Helvetica, fontsize=8];
+  }
+ * @enddot
+ * Note, the Halted and SNMI states can be reached from any state and are not
+ * shown for simplicity.
  *
  * @section scheduling Scheduling
  * The strategy is very simple the currently ready thread with the highest

src/include/sys.h

@@ -57,7 +57,7 @@
  *       interrupts or be exactly equivalent to @p chSysDisable().
  * @note Do not invoke this API from within a kernel lock.
  */
-#define chSysDisableAll() sys_disable_all()
+#define chSysDisable() sys_disable()
 
 /**
  * Raises the system interrupt priority mask to system level.
@@ -69,7 +69,7 @@
  * @note This API is no replacement for @p chSysLock(), the @p chSysLock()
  *       could do more than just disable the interrupts.
  */
-#define chSysDisable() sys_disable()
+#define chSysSuspend() sys_suspend()
 
 /**
  * Lowers the system interrupt priority mask to user level.

src/templates/chcore.c

@@ -72,13 +72,13 @@ void sys_unlock_from_isr(void) {
  * Disables all the interrupt sources.
  * @note Of course non maskable interrupt sources are not included.
  */
-void sys_disable_all() {
+void sys_disable() {
 }
 
 /**
  * Disables the interrupt sources that are not supposed to preempt the kernel.
  */
-void sys_disable(void) {
+void sys_suspend(void) {
 }
 
 /**

src/templates/chcore.h

@@ -130,8 +130,8 @@ typedef struct {
 extern "C" {
 #endif
   void sys_init(void);
-  void sys_disable_all(void);
   void sys_disable(void);
+  void sys_suspend(void);
   void sys_enable(void);
   void sys_lock(void);
   void sys_unlock(void);