From 598423fd309b4d0cf871bc1151b9d3d97a078cd6 Mon Sep 17 00:00:00 2001 From: gdisirio Date: Sat, 17 Jan 2009 14:08:53 +0000 Subject: [PATCH] git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@622 35acf78f-673a-0410-8e92-d51de3d6d3f4 --- docs/ch.txt | 79 +++++++++++++++++++++++++++++++++--------- src/include/sys.h | 4 +-- src/templates/chcore.c | 4 +-- src/templates/chcore.h | 2 +- 4 files changed, 67 insertions(+), 22 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 (ちびOS/RT) \endhtmlonly + * @htmlonly (ちびOS/RT) \endhtmlonly * means small Real Time Operating System. * Source Wikipedia. * @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: - * - "I", I-Class APIs are invokeable only from the I-Locked or S-Locked + * - "I", I-Class APIs are invokable only from the I-Locked or S-Locked * states. See @ref system_states. - * - "S", S-Class APIs are invokeable only from the S-Locked state. See + * - "S", 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. - * - All Disabled. When the system is in this state both the maskable + * - Disabled. 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(). - * - Disabled. 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(). + * - Suspended. 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(). * - Normal. All the interrupt sources are enabled and the system APIs * are accessible, threads are running. + * - Sleep. 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. * - S-Locked. 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. * - I-Locked. Kernel locked and regular interrupt sources disabled. - * I-Class and APIs are invokeable from this state. + * I-Class APIs are invokable from this state. * - Serving Regular Interrupt. 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. * - Serving Fast Interrupt. No system APIs are accessible. - * - Serving Non-Maskable Interrupt. No systemAPIs are accessible. - * - Halted. All interrupt sources disabled and system stopped into an - * infinite loop. This state can be reached if the debug mode is activated + * - Serving Non-Maskable Interrupt. System APIs are not accessible. + * - Halted. All interrupt sources are disabled and system stopped into + * an infinite loop. This state can be reached if the debug mode is activated * and an error is detected or after explicitly invoking * @p chSysHalt(). * * Note that the above state are just Logical States 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 diff --git a/src/include/sys.h b/src/include/sys.h index ae38a5639..0c58a9c8e 100644 --- a/src/include/sys.h +++ b/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. diff --git a/src/templates/chcore.c b/src/templates/chcore.c index 84f0b7418..677c4ea2f 100644 --- a/src/templates/chcore.c +++ b/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) { } /** diff --git a/src/templates/chcore.h b/src/templates/chcore.h index dec2deee7..92852fead 100644 --- a/src/templates/chcore.h +++ b/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);