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 dc5b1e26cb1864474a90ce0a0c81685650e35ce7..5b2a99f3634e1dccb01b679675edc498654fc7c2 100644 (file)
--- a/doc/txt/tep112.txt
+++ b/doc/txt/tep112.txt
@@ -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
-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
@@ -251,14 +251,23 @@ 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
-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
-``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
@@ -276,7 +285,7 @@ include power management into shared non-virtualized devices.
 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 of a use of McuPowerOverride can be found in the atmega128 timer
+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 
@@ -284,6 +293,19 @@ that is going to fire soon.  The implementation can be found in
 ``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
 ====================================================================