Modified TEP 112.

diff --git a/doc/html/tep112.html b/doc/html/tep112.html
index 2dcba25ef56fcd2c22903d7e9a1359fd589339dd..233585f5c7457537977ec4203bc7533ad6811c48 100644 (file)
--- a/doc/html/tep112.html
+++ b/doc/html/tep112.html
@@ -303,9 +303,9 @@ ul.auto-toc {
 <td>Robert Szewczyk, Philip Levis, Martin Turon, Lama Nachman, Philip Buonadonna, Vlado Handziski</td></tr>
 <tr class="field"><th class="docinfo-name">Draft-Created:</th><td class="field-body">19-Sep-2005</td>
 </tr>
 <td>Robert Szewczyk, Philip Levis, Martin Turon, Lama Nachman, Philip Buonadonna, Vlado Handziski</td></tr>
 <tr class="field"><th class="docinfo-name">Draft-Created:</th><td class="field-body">19-Sep-2005</td>
 </tr>

-<tr class="field"><th class="docinfo-name">Draft-Version:</th><td class="field-body">1.1.2.2</td>
+<tr class="field"><th class="docinfo-name">Draft-Version:</th><td class="field-body">1.5</td>

 </tr>
 </tr>

-<tr class="field"><th class="docinfo-name">Draft-Modified:</th><td class="field-body">2005-10-31</td>
+<tr class="field"><th class="docinfo-name">Draft-Modified:</th><td class="field-body">2006-12-12</td>

 </tr>
 <tr class="field"><th class="docinfo-name">Draft-Discuss:</th><td class="field-body">TinyOS Developer List &lt;tinyos-devel at mail.millennium.berkeley.edu&gt;</td>
 </tr>
 </tr>
 <tr class="field"><th class="docinfo-name">Draft-Discuss:</th><td class="field-body">TinyOS Developer List &lt;tinyos-devel at mail.millennium.berkeley.edu&gt;</td>
 </tr>


@@ -342,7 +342,7 @@ management.</p>
 </div>
 <div class="section">
 <h1><a id="background" name="background">2. Background</a></h1>
 </div>
 <div class="section">
 <h1><a id="background" name="background">2. Background</a></h1>

-<p>The TinyOS scheduler[_tep106] puts a processor into a sleep state when
+<p>The TinyOS scheduler[<a class="reference" href="#id3">2</a>] 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


@@ -403,11 +403,10 @@ state, the function performs the calculation, and the override allows
 higher level components to introduce additional requirements, if
 needed.</p>
 <p>These three mechanisms all operate in the TinyOS core scheduling loop,
 higher level components to introduce additional requirements, if
 needed.</p>
 <p>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[<a class="reference" href="#id3">2</a>]. 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
-<tt class="docutils literal"><span class="pre">Scheduler.runNextTask()</span></tt>, when its sleep parameter is TRUE (i.e.,
-<tt class="docutils literal"><span class="pre">call</span> <span class="pre">Scheduler.runNextTask(TRUE)</span></tt>).</p>
+Sequence[<a class="reference" href="#id4">3</a>]. The command in question is
+<tt class="docutils literal"><span class="pre">Scheduler.taskLoop()</span></tt>, when microcontroller sleeping is enabled.</p>

 <p>If this command is called when the task queue is empty, the TinyOS
 scheduler puts the microcontroller to sleep. It does so through
 the <tt class="docutils literal"><span class="pre">McuSleep</span></tt> interface:</p>
 <p>If this command is called when the task queue is empty, the TinyOS
 scheduler puts the microcontroller to sleep. It does so through
 the <tt class="docutils literal"><span class="pre">McuSleep</span></tt> interface:</p>


@@ -461,7 +460,7 @@ whose signature MUST include the following interfaces:</p>
 <div class="section">
 <h1><a id="the-dirty-bit" name="the-dirty-bit">3.1 The Dirty Bit</a></h1>
 <p>Whenever a Hardware Presentation Layer (HPL, see TEP 2: Hardware
 <div class="section">
 <h1><a id="the-dirty-bit" name="the-dirty-bit">3.1 The Dirty Bit</a></h1>
 <p>Whenever a Hardware Presentation Layer (HPL, see TEP 2: Hardware

-Abstraction Architecture[_tep2]) component changes an aspect of
+Abstraction Architecture[<a class="reference" href="#id2">1</a>]) 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 <em>dirty bit</em>. 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 <em>dirty bit</em>. If


@@ -571,6 +570,8 @@ thirty cycles; implementations SHOULD be a simple return of a cached
 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.</p>
 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.</p>

+<p>Section 5 describes one example use of McuPowerOverride, in the
+timer stack for the Atmega128 microcontroller family.</p>

 </div>
 <div class="section">
 <h1><a id="peripherals-and-subsystems" name="peripherals-and-subsystems">4. Peripherals and Subsystems</a></h1>
 </div>
 <div class="section">
 <h1><a id="peripherals-and-subsystems" name="peripherals-and-subsystems">4. Peripherals and Subsystems</a></h1>


@@ -584,24 +585,25 @@ component represents to enter an inactive, low-power state.</p>
 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
 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.</p>
-<p>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 <em>mechanism</em> to control
-subsystem power states, but no real <em>policy</em> for arbitrating
-conflicting requirements from components built on top of them.</p>
-<p>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.</p>
+appropriately when the system next goes to sleep. TEP 115[<a class="reference" href="#id6">5</a>]
+describes the power management of non-virtualized devices in
+greater detail, and TEP 108[<a class="reference" href="#id5">4</a>] describes how TinyOS can automatically
+include power management into shared non-virtualized devices.</p>

 </div>
 <div class="section">
 </div>
 <div class="section">

-<h1><a id="author-s-address" name="author-s-address">5. Author's Address</a></h1>
+<h1><a id="implementation" name="implementation">5. Implementation</a></h1>
+<p>An implementation of McuSleepC can be found in <tt class="docutils literal"><span class="pre">tinyos-2.x/tos/chips/atm128</span></tt>,
+<tt class="docutils literal"><span class="pre">tinyos-2.x/tos/chips/msp430</span></tt>, and <tt class="docutils literal"><span class="pre">tinyos-2.x/tos/chips/px27ax</span></tt>.</p>
+<p>An example of a 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
+<tt class="docutils literal"><span class="pre">tinyos-2.x/tos/chips/atm128/timer/HplAtm128Timer0AsyncP.nc</span></tt>, and
+<tt class="docutils literal"><span class="pre">tinyos-2.x/tos/chips/atm128/timer/HplAtm128Timer0AsyncC.nc</span></tt> automatically
+wires it to McuSleepC if it is included.</p>
+</div>
+<div class="section">
+<h1><a id="author-s-address" name="author-s-address">6. Author's Address</a></h1>

 <div class="line-block">
 <div class="line">Robert Szewczyk</div>
 <div class="line">Moteiv Corporation</div>
 <div class="line-block">
 <div class="line">Robert Szewczyk</div>
 <div class="line">Moteiv Corporation</div>


@@ -658,28 +660,34 @@ of the basic HIL mechanisms.</p>
 </div>
 <div class="section">
 <h1><a id="citations" name="citations">6. Citations</a></h1>
 </div>
 <div class="section">
 <h1><a id="citations" name="citations">6. Citations</a></h1>

-<table class="docutils citation" frame="void" id="tep106" rules="none">
+<table class="docutils footnote" frame="void" id="id2" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a name="id2">[1]</a></td><td>TEP 2: Hardware Abstraction Architecture</td></tr>
+</tbody>
+</table>
+<table class="docutils footnote" frame="void" id="id3" rules="none">

 <colgroup><col class="label" /><col /></colgroup>
 <tbody valign="top">
 <colgroup><col class="label" /><col /></colgroup>
 <tbody valign="top">

-<tr><td class="label"><a name="tep106">[tep106]</a></td><td>TEP 106: Schedulers and Tasks.</td></tr>
+<tr><td class="label"><a name="id3">[2]</a></td><td>TEP 106: Schedulers and Tasks.</td></tr>

 </tbody>
 </table>
 </tbody>
 </table>

-<table class="docutils citation" frame="void" id="tep107" rules="none">
+<table class="docutils footnote" frame="void" id="id4" rules="none">

 <colgroup><col class="label" /><col /></colgroup>
 <tbody valign="top">
 <colgroup><col class="label" /><col /></colgroup>
 <tbody valign="top">

-<tr><td class="label"><a name="tep107">[tep107]</a></td><td>TEP 107: TinyOS 2.x Boot Sequence.</td></tr>
+<tr><td class="label"><a name="id4">[3]</a></td><td>TEP 107: TinyOS 2.x Boot Sequence.</td></tr>

 </tbody>
 </table>
 </tbody>
 </table>

-<table class="docutils citation" frame="void" id="tep110" rules="none">
+<table class="docutils footnote" frame="void" id="id5" rules="none">

 <colgroup><col class="label" /><col /></colgroup>
 <tbody valign="top">
 <colgroup><col class="label" /><col /></colgroup>
 <tbody valign="top">

-<tr><td class="label"><a name="tep110">[tep110]</a></td><td>TEP 110: Service Distributions.</td></tr>
+<tr><td class="label"><a name="id5">[4]</a></td><td>TEP 108: Resource Arbitration</td></tr>

 </tbody>
 </table>
 </tbody>
 </table>

-<table class="docutils citation" frame="void" id="tep2" rules="none">
+<table class="docutils footnote" frame="void" id="id6" rules="none">

 <colgroup><col class="label" /><col /></colgroup>
 <tbody valign="top">
 <colgroup><col class="label" /><col /></colgroup>
 <tbody valign="top">

-<tr><td class="label"><a name="tep2">[tep2]</a></td><td>TEP 2: Hardware Abstraction Architecture.</td></tr>
+<tr><td class="label"><a name="id6">[5]</a></td><td>TEP 115: Power Management of Non-Virtualised Devices</td></tr>

 </tbody>
 </table>
 </div>
 </tbody>
 </table>
 </div>

diff --git a/doc/txt/tep112.txt b/doc/txt/tep112.txt
index c4ca981b288a9ebaacfc204a74d1b8d37a17c6a8..dc5b1e26cb1864474a90ce0a0c81685650e35ce7 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


@@ -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,6 +248,9 @@ 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.
+

 4. Peripherals and Subsystems
 ====================================================================
 
 4. Peripherals and Subsystems
 ====================================================================
 


@@ -263,25 +265,26 @@ 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
 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 of a 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.
+
+6. Author's Address

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


@@ -339,10 +342,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.