Merge TinyOS 2.1.1 into master.

[tinyos-2.x.git] / doc / txt / tep112.txt

diff --git a/doc/txt/tep112.txt b/doc/txt/tep112.txt
index c4ca981b288a9ebaacfc204a74d1b8d37a17c6a8..5b2a99f3634e1dccb01b679675edc498654fc7c2 100644 (file)
--- a/doc/txt/tep112.txt
+++ b/doc/txt/tep112.txt
@@ -50,7 +50,7 @@ management.
 2. Background
 ====================================================================
 
 2. Background
 ====================================================================
 

-The TinyOS scheduler[_tep106] puts a processor into a sleep state when
+The TinyOS scheduler[2_] puts a processor into a sleep state when

 the task queue is empty. However, processors can have a spectrum of
 power states. For example, the MSP430 has one active mode (issuing
 instructions) and five low-power modes. The low power modes range from
 the task queue is empty. However, processors can have a spectrum of
 power states. For example, the MSP430 has one active mode (issuing
 instructions) and five low-power modes. The low power modes range from


@@ -97,7 +97,7 @@ introduce wakeup latency, a factor which could be of interest to
 higher-level components. While wakeup latency is not a significant
 issue on very low power microcontrollers, such as the Atmega128 and
 MSP430, more powerful processors, such as the Xscale family (the basis
 higher-level components. While wakeup latency is not a significant
 issue on very low power microcontrollers, such as the Atmega128 and
 MSP430, more powerful processors, such as the Xscale family (the basis

-of platforms such as the imote2) can power states with wakeup
+of platforms such as the imote2) can have power states with wakeup

 latencies as large as 5ms. For some application domains, this latency
 could be a serious issue. Higher level components therefore need a way
 to give the TinyOS microcontroller power manager information on their
 latencies as large as 5ms. For some application domains, this latency
 could be a serious issue. Higher level components therefore need a way
 to give the TinyOS microcontroller power manager information on their


@@ -116,11 +116,10 @@ higher level components to introduce additional requirements, if
 needed.
 
 These three mechanisms all operate in the TinyOS core scheduling loop,
 needed.
 
 These three mechanisms all operate in the TinyOS core scheduling loop,

-described in TEP 106: Schedulers and Tasks[_tep106]. This loop is
+described in TEP 106: Schedulers and Tasks[2_]. This loop is

 called from the boot sequence, which is described in TEP 107: Boot
 called from the boot sequence, which is described in TEP 107: Boot

-Sequence[_tep107]. The command in question is
-``Scheduler.runNextTask()``, when its sleep parameter is TRUE (i.e.,
-``call Scheduler.runNextTask(TRUE)``).
+Sequence[3_]. The command in question is
+``Scheduler.taskLoop()``, when microcontroller sleeping is enabled.

 
 If this command is called when the task queue is empty, the TinyOS
 scheduler puts the microcontroller to sleep. It does so through
 
 If this command is called when the task queue is empty, the TinyOS
 scheduler puts the microcontroller to sleep. It does so through


@@ -171,7 +170,7 @@ McuSleepC MAY have additional interfaces.
 ====================================================================
 
 Whenever a Hardware Presentation Layer (HPL, see TEP 2: Hardware
 ====================================================================
 
 Whenever a Hardware Presentation Layer (HPL, see TEP 2: Hardware

-Abstraction Architecture[_tep2]) component changes an aspect of
+Abstraction Architecture[1_]) component changes an aspect of

 hardware configuration that might change the possible low power state
 of the microcontroller, it MUST call McuPowerState.update(). This is
 the first power management mechanism, a *dirty bit*. If
 hardware configuration that might change the possible low power state
 of the microcontroller, it MUST call McuPowerState.update(). This is
 the first power management mechanism, a *dirty bit*. If


@@ -249,39 +248,65 @@ variable. Wiring arbitrarily to this command is an easy way to cause
 TinyOS to behave badly. The presence of a combine function for
 mcu_power_t means that this command can have fan-out calls.
 
 TinyOS to behave badly. The presence of a combine function for
 mcu_power_t means that this command can have fan-out calls.
 

+Section 5 describes one example use of McuPowerOverride, in the
+timer stack for the Atmega128 microcontroller family.
+
+As part of power state override, a platform MUST define the enum
+TOS_SLEEP_NONE in its hardware.h file. This enum defines the highest
+power state of the platform's microcontroller in a chip-independent
+way. If a component wires to McuPowerOverride and returns TOS_SLEEP_NONE,
+this will cause TinyOS to never put the microcontroller into a power
+saving state. This enum allows a component to prevent sleep in a
+platform-independent way.
+

 4. Peripherals and Subsystems
 ====================================================================
 
 At the HIL level, TinyOS subsystems generally have a simple,
 imperative power management interface. Depending on the latencies
 4. Peripherals and Subsystems
 ====================================================================
 
 At the HIL level, TinyOS subsystems generally have a simple,
 imperative power management interface. Depending on the latencies

-involved, this interface is either ``StdControl`` or ``SplitControl``.
+involved, this interface is either ``StdControl``, ``SplitControl``,
+or ``AsyncStdControl``.

 These interfaces are imperative in that when any component calls
 These interfaces are imperative in that when any component calls

-``StdControl.stop`` on another component, it causes the subsystem that
+``stop`` on another component, it causes the subsystem that

 component represents to enter an inactive, low-power state.
 
 From the perspective of MCU power management, this transition causes a
 change in status and control registers (e.g., a clock is
 disabled). Following the requirements in 3.1, the MCU power management
 subsystem will be notified of a significant change and act
 component represents to enter an inactive, low-power state.
 
 From the perspective of MCU power management, this transition causes a
 change in status and control registers (e.g., a clock is
 disabled). Following the requirements in 3.1, the MCU power management
 subsystem will be notified of a significant change and act

-appropriately when the system next goes to sleep.
-
-These imperative appraoches are flexible and powerful, but are also
-very error prone, partially due to their deep semantics. For example,
-depending on the circumstances, an application calling StdControl.stop
-on a routing layer may or may not also want to turn off the underlying
-radio. StdControl and SplitControl provide a *mechanism* to control
-subsystem power states, but no real *policy* for arbitrating
-conflicting requirements from components built on top of them.
-
-Service distributions (described in TEP 110[_tep110]) are responsible
-for providing policies on top of these low-level mechanisms. OSKI, for
-example, the sample distribution described in TEP 110, uses an
-OR-policy: a subsystem is active if any of its clients want it active,
-and inactive iff all of its clients want it inactive. Other
-distributions can provide alternative power management policies in top
-of the basic HIL mechanisms.
-
-5. Author's Address
+appropriately when the system next goes to sleep. TEP 115[5_]
+describes the power management of non-virtualized devices in 
+greater detail, and TEP 108[4_] describes how TinyOS can automatically
+include power management into shared non-virtualized devices.
+
+5. Implementation
+====================================================================
+
+An implementation of McuSleepC can be found in ``tinyos-2.x/tos/chips/atm128``, 
+``tinyos-2.x/tos/chips/msp430``, and ``tinyos-2.x/tos/chips/px27ax``. 
+
+An example use of McuPowerOverride can be found in the atmega128 timer
+system. Because some low-power states have much longer wakeup latencies than
+others, the timer system does not allow long latencies if it has a timer
+that is going to fire soon.  The implementation can be found in 
+``tinyos-2.x/tos/chips/atm128/timer/HplAtm128Timer0AsyncP.nc``, and
+``tinyos-2.x/tos/chips/atm128/timer/HplAtm128Timer0AsyncC.nc`` automatically
+wires it to McuSleepC if it is included.
+
+For the atmega128 microcontroller, TOS_SLEEP_NONE is the "idle" power
+state.
+
+A second example use of McuPowerOverride is in the msp430 timer system.
+By default, the msp430 lowest power state is LPM4, which does not keep
+clocks enabled. If ``tinyos-2.x/tos/chips/msp430/timer/Msp430ClockC.nc''
+is included in the component graph, however, this configuration wires
+the McuPowerOverride of ``tinyos-2.x/tos/chips/msp430/timer/Msp430ClockP.nc``
+to McuSleepC. This implemementation of McuPowerOverride raises the lowest
+power state to LPM3, which keeps clocks enabled.
+
+For msp430 microcontrollers, TOS_SLEEP_NONE is the "active" power state.
+
+6. Author's Address

 ====================================================================
 
 | Robert Szewczyk
 ====================================================================
 
 | Robert Szewczyk


@@ -339,10 +364,13 @@ of the basic HIL mechanisms.
 6. Citations
 ====================================================================
 
 6. Citations
 ====================================================================
 

-.. [tep106] TEP 106: Schedulers and Tasks.
+.. [1] TEP 2: Hardware Abstraction Architecture
+
+.. [2] TEP 106: Schedulers and Tasks.
+
+.. [3] TEP 107: TinyOS 2.x Boot Sequence.

 
 

-.. [tep107] TEP 107: TinyOS 2.x Boot Sequence.
+.. [4] TEP 108: Resource Arbitration

 
 

-.. [tep110] TEP 110: Service Distributions.
+.. [5] TEP 115: Power Management of Non-Virtualised Devices

 
 

-.. [tep2] TEP 2: Hardware Abstraction Architecture.