diff options
Diffstat (limited to 'docs/ch.txt')
| -rw-r--r-- | docs/ch.txt | 79 |
1 files changed, 62 insertions, 17 deletions
diff --git a/docs/ch.txt b/docs/ch.txt index c05df4761..7d5a4ced7 100644 --- a/docs/ch.txt +++ b/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">ちび</span>OS/RT) \endhtmlonly
+ * @htmlonly (<span class="t_nihongo_kanji" xml:lang="ja" lang="ja">ちび</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().
- * This state is entered using @p chSysDisableAll().
- * - <b>Disabled</b>. In this state the fast interrupt sources are enabled but
+ * possible to use any system API except @p chSysSuspend() or
+ * @p chSysEnable().
+ * 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
- * invokeable in this state.
+ * Fast interrupt sources are enabled. S-Class and I-Class APIs are
+ * 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>Halted</b>. All interrupt sources disabled and system stopped into an
- * infinite loop. This state can be reached if the debug mode is activated
+ * - <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 state are just <b>Logical States</b> that can have no
- * real machine state associated. The following diagram shows the possible
- * transitions between the states:
+ * real machine state associated 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"];
+ 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
|