From: klueska Date: Fri, 14 Sep 2007 22:45:30 +0000 (+0000) Subject: Update to TEP115 X-Git-Tag: release_tinyos_2_1_0_0~732 X-Git-Url: https://oss.titaniummirror.com/gitweb/?p=tinyos-2.x.git;a=commitdiff_plain;h=d5d000d990811fff92c641d5bb717fc20ba337d9 Update to TEP115 --- diff --git a/doc/html/tep115.html b/doc/html/tep115.html index e2ad1e4b..8e6bfac7 100644 --- a/doc/html/tep115.html +++ b/doc/html/tep115.html @@ -11,21 +11,30 @@ /* :Author: David Goodger :Contact: goodger@users.sourceforge.net -:date: $Date$ -:version: $Revision$ -:copyright: This stylesheet has been placed in the public domain. +:Date: $Date$ +:Revision: $Revision$ +:Copyright: This stylesheet has been placed in the public domain. Default cascading style sheet for the HTML output of Docutils. + +See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to +customize this style sheet. */ -body { - font-family: Times; - font-size: 16px; -} + +/* used to remove borders from tables and images */ +.borderless, table.borderless td, table.borderless th { + border: 0 } + +table.borderless td, table.borderless th { + /* Override padding for "table.docutils td" with "! important". + The right padding separates the table cells. */ + padding: 0 0.5em 0 0 ! important } .first { + /* Override more specific margin styles with "! important". */ margin-top: 0 ! important } -.last { +.last, .with-subtitle { margin-bottom: 0 ! important } .hidden { @@ -38,9 +47,14 @@ a.toc-backref { blockquote.epigraph { margin: 2em 5em ; } -dd { +dl.docutils dd { margin-bottom: 0.5em } +/* Uncomment (and remove this text!) to get bold-faced definition list terms +dl.docutils dt { + font-weight: bold } +*/ + div.abstract { margin: 2em 5em } @@ -48,12 +62,18 @@ div.abstract p.topic-title { font-weight: bold ; text-align: center } -div.attention, div.caution, div.danger, div.error, div.hint, -div.important, div.note, div.tip, div.warning, div.admonition { +div.admonition, div.attention, div.caution, div.danger, div.error, +div.hint, div.important, div.note, div.tip, div.warning { margin: 2em ; border: medium outset ; padding: 1em } +div.admonition p.admonition-title, div.hint p.admonition-title, +div.important p.admonition-title, div.note p.admonition-title, +div.tip p.admonition-title { + font-weight: bold ; + font-family: sans-serif } + div.attention p.admonition-title, div.caution p.admonition-title, div.danger p.admonition-title, div.error p.admonition-title, div.warning p.admonition-title { @@ -61,11 +81,14 @@ div.warning p.admonition-title { font-weight: bold ; font-family: sans-serif } -div.hint p.admonition-title, div.important p.admonition-title, -div.note p.admonition-title, div.tip p.admonition-title, -div.admonition p.admonition-title { - font-weight: bold ; - font-family: sans-serif } +/* Uncomment (and remove this text!) to get reduced vertical space in + compound paragraphs. +div.compound .compound-first, div.compound .compound-middle { + margin-bottom: 0.5em } + +div.compound .compound-last, div.compound .compound-middle { + margin-top: 0.5em } +*/ div.dedication { margin: 2em 5em ; @@ -77,9 +100,11 @@ div.dedication p.topic-title { font-style: normal } div.figure { - margin-left: 2em } + margin-left: 2em ; + margin-right: 2em } div.footer, div.header { + clear: both; font-size: smaller } div.line-block { @@ -95,7 +120,7 @@ div.line-block div.line-block { div.sidebar { margin-left: 1em ; border: medium outset ; - padding: 0em 1em ; + padding: 1em ; background-color: #ffffee ; width: 40% ; float: right ; @@ -122,32 +147,25 @@ div.system-message p.system-message-title { div.topic { margin: 2em } -h1 { - font-family: Arial, sans-serif; - font-size: 20px; -} +h1.section-subtitle, h2.section-subtitle, h3.section-subtitle, +h4.section-subtitle, h5.section-subtitle, h6.section-subtitle { + margin-top: 0.4em } h1.title { - text-align: center; - font-size: 32px; -} - -h2 { - font-size: 16px; - font-family: Arial, sans-serif; -} + text-align: center } h2.subtitle { text-align: center } -h3 { - font-size: 12px; - font-family: Arial, sans-serif; -} - -hr { +hr.docutils { width: 75% } +img.align-left { + clear: left } + +img.align-right { + clear: right } + ol.simple, ul.simple { margin-bottom: 1em } @@ -204,18 +222,10 @@ pre.address { font-family: serif ; font-size: 100% } -pre.line-block { - font-family: serif ; - font-size: 100% } - pre.literal-block, pre.doctest-block { margin-left: 2em ; margin-right: 2em ; - background-color: #eeeeee; - border-color: #000000; - border-width: thin; - font-size: 14px -} + background-color: #eeeeee } span.classifier { font-family: sans-serif ; @@ -231,46 +241,49 @@ span.interpreted { span.option { white-space: nowrap } -span.option-argument { - font-style: italic } - span.pre { white-space: pre } span.problematic { color: red } -table { - margin-top: 0.5em ; - margin-bottom: 0.5em } +span.section-subtitle { + /* font-size relative to parent (h1..h6 element) */ + font-size: 80% } table.citation { - border-left: solid thin gray ; - padding-left: 0.5ex } + border-left: solid 1px gray; + margin-left: 1px } table.docinfo { - margin: 2em 4em; -} + margin: 2em 4em } + +table.docutils { + margin-top: 0.5em ; + margin-bottom: 0.5em } table.footnote { - border-left: solid thin black ; - padding-left: 0.5ex } + border-left: solid 1px black; + margin-left: 1px } -td, th { +table.docutils td, table.docutils th, +table.docinfo td, table.docinfo th { padding-left: 0.5em ; padding-right: 0.5em ; vertical-align: top } -th.docinfo-name, th.field-name { +table.docutils th.field-name, table.docinfo th.docinfo-name { font-weight: bold ; text-align: left ; - white-space: nowrap; - } + white-space: nowrap ; + padding-left: 0 } -h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt { +h1 tt.docutils, h2 tt.docutils, h3 tt.docutils, +h4 tt.docutils, h5 tt.docutils, h6 tt.docutils { font-size: 100% } -tt {} +tt.docutils { + background-color: #eeeeee } ul.auto-toc { list-style-type: none } @@ -322,16 +335,16 @@ of this memo is unlimited. This memo is in full compliance with TEP

1. Introduction

TinyOS platforms have limited energy. A unified power management -strategy for all devices and peripherpals is not feasible, as +strategy for all devices and peripherals is not feasible, as they vary significantly in warm-up times, power profiles, and operation latencies. While some devices, such as microcontrollers, can efficiently calculate their lowest possible power state very quickly, others, such as sensors with warm-up times, require external knowledge to do so.

-

In TinyOS 1.x, an application is responsible for all power management. +

In TinyOS 1.x, applications are responsible for all power management. Low-level subsystems, such as an SPI bus, are explicitly powered on and off by higher level abstractions. This approach of deep calls -to StdControl.start and StdControl.stop introduces strange behaviors +to StdControl.start() and StdControl.stop() introduces strange behaviors and can get in the way of power conservation. Turning off the radio on the Telos platform, for example, turns off the SPI bus and therefore prevents the flash driver from working. Additionally, the microcontroller @@ -357,7 +370,8 @@ power management.

The explicit model provides a means for a single client to manually control the power state of a dedicated physical device (as defined by [TEP108]). Whenever this client tells the device to power up or down -it does so without delay (albeit that caused by hardware). This model +it does so without delay (except for delays in the hardware of course). +This model can be particularly useful when the control information driving the selection of the proper power state of a device relies on external logic contained in higher level components. The following section @@ -415,7 +429,7 @@ representing a hardware device that can be powered on and off MUST provide one of these three interfaces. The selection of the right interface depends on the latencies involved in changing between these two states as well as the -nature of the code (sync or async) executing any of the interfaces +nature of the code (sync or async) executing any of the interface's commands.

3.1 Power Management with StdControl

@@ -448,7 +462,8 @@ device MUST be completely powered on, allowing calls to commands of other interfaces implemented by the device to succeed.

Upon the successful return of a call to StdControl.stop(), a device MUST be completely powered down, and any calls to commands -of other interfaces implemented by that device MUST return FAIL or EOFF.

+of other interfaces implemented by that device that actually access +the device hardware MUST return FAIL or EOFF.

If a device is not able to complete the StdControl.start() or StdControl.stop() request for any reason, it MUST return FAIL.

Based on these specifications, the following matrix has been created @@ -495,7 +510,7 @@ configuration DeviceC {

3.2 Power Management with SplitControl

When a device's powerup and powerdown times are non-negligible, the -``SplitControl`` interface MUST be used in place of the ``StdControl`` +``SplitControl`` interface SHOULD be used in place of the ``StdControl`` interface. The definition of this interface can be seen below:

 interface SplitControl {
@@ -508,12 +523,12 @@ interface SplitControl {
 
An external component MUST call SplitControl.start() to power a
 device on and SplitControl.stop() to power a device off.  Calls to
 either command return one of SUCCESS, FAIL, EBUSY, or
-EALREADY. SUCCESS indicates that the device has now started chaning
-its power mode and it will signal a corresponding completion event in
-the future. EBUSY indicates that the device is in the midst of the
-other operation (e.g., it is starting when stop is called or stopping
+EALREADY. SUCCESS indicates that the device has now started changing
+its power state and will signal a corresponding completion event in
+the future. EBUSY indicates that the device is in the midst of either starting
+or stopping (e.g., it is starting when stop is called or stopping
 when start is called) and will not issue an event. EALREADY indicates
-that the device is already in that state; the call is erroneus and a
+that the device is already in that state; the call is erroneous and a
 completion event will not be signaled. FAIL indicates that the
 device's power state could not be changed. More explicitly:

 
Successful calls to SplitControl.start() MUST signal one of
@@ -525,7 +540,8 @@ be completely powered on, and operation requests through calls to commands
 of other interfaces implemented by the device MAY succeed.

 
Upon signalling a SplitControl.stopDone(SUCCESS), a device MUST be
 completely powered down, and any subsequent calls to commands of other
-interfaces implemented by the device MUST return EOFF or FAIL.

+interfaces implemented by the device that actually access
+the device hardware MUST return EOFF or FAIL.

 
If a device is powered on and a successful call to SplitControl.stop()
 signals a SplitControl.stopDone(FAIL), the device MUST still be fully
 powered on, and operation requests through calls to commands of other
@@ -541,12 +557,12 @@ or SplitControl.stop()SplitControl.startDone() or SplitControl.stopDone()
 will be signaled in the future.

-
Calls to SplitControl.start()` when the device is started
+
Calls to SplitControl.start() when the device is started
 or SplitControl.stop() while the device is stopped MUST
 return EALREADY, indicating that the device is already in that
 state. The corresponding completion event (startDone for start
 or stopDone for stop) MUST NOT be signaled.

-
Calls to SplitControl.start()` when the device is stopping or
+
Calls to SplitControl.start() when the device is stopping or
 SplitControl.stop() while the device is starting MUST return
 EBUSY, indicating that the device is busy performing a differnet
 operation. The correspodning completion event (startDone for start or
@@ -605,6 +621,27 @@ configuration DeviceC {
   }
 }
+
+

Note

+

Other approaches were considered for the return values of +SplitControl.start() and SplitControl.stop(). One such +approach would have replaced EBUSY with SUCCESS when +SplitControl.start() was called while in the process of stopping +and SplitControl.stop() was called while in the process of starting. +However, implementing such an approach adds unwanted complexity to +a device driver. It is unreasonable to expect the implementor of +each driver to implement this functionality.

+

Returning EBUSY is the most straightforward, unambiguous value +that can be returned in such a situation. By returning +EBUSY when a device is in a transitional state, the components +built on top of a driver unambiguously know exactly why a call to +start() or stop() did not succeed, and can take action accordingly. +Since only ONE component should ever implement the SplitControl +interface for a given device, it isn't unreasonable to expect them +to keep track of this return value themselves. There is, of course, +nothing preventing someone from creating a component +on top of each driver implementation that implements things differently.

+

3.3 Power Management with AsyncStdControl

@@ -681,13 +718,14 @@ For cases when some of these features are known a-priori or are restricted in some sense, it is preferable that the system provide architectural support for enforcing a meaningful default power-management policy instead of passing that task on to the application programmer to be -solved on a case-by-case basis.

+solved on a case-by-case basis. The following section discusses these power +management policies and the components that implement them in greater detail.

4.1. Power Management Policies

Just as generic arbiters are offered in TinyOS 2.x to provide the arbitration functionality required by shared resources, generic power management policies are also offered to allow the power management of -non-virtualised devices to be automatically control.

+non-virtualised devices to be automatically controlled.

Through the use of the arbiter components described in [TEP108], device drivers implemented as shared resources provide the type of restricted resource interdependency where default power-management @@ -731,9 +769,9 @@ by one of its clients. Whenever a client puts in a request, the (or immediateRequested() event) from the arbiter it is associated with. Upon receiving this event, the Power Manager MUST power up the resource through the StdControl-like interface provided by the lower level -abstraction of the physical device. The Power Manager SHOULD release the +abstraction of the physical device. The Power Manager MUST release the ownership of the resource (using the ResourceDefaultOwner.release() -command) but MUST wait until after the resource has been fully powered on +command) and MUST wait until after the resource has been fully powered on before doing so.

Modeling devices as shared resources and allowing them to be controlled in the way described here, solves the problems outlined in @@ -826,7 +864,8 @@ devices are powered on and off immediately after they have been requested and released. The second policy is implemented using a deferred power control scheme, whereby devices are powered on immediately after being requested, but powered off after -some small delay from being released.

+some small delay from being released. This delay is configurable +to meet the varying needs of different device drivers.

Each policy has three different implementations for use by each of the StdControl, SplitControl, and AsyncStdControl interfaces.

@@ -853,12 +892,11 @@ interfaces.

5. Author's Address

Kevin Klues
-
503 Bryan Hall
-
Washington University
-
St. Louis, MO 63130
+
444 Gates Hall
+
Stanford University
+
Stanford, CA 94305-9030

-
phone - +1-314-935-6355
-
email - klueska@cs.wustl.edu
+
email - klueska@cs.stanford.edu

Vlado Handziski
Sekr FT5
diff --git a/doc/txt/tep115.txt b/doc/txt/tep115.txt index ae96a51a..f224d458 100644 --- a/doc/txt/tep115.txt +++ b/doc/txt/tep115.txt @@ -32,17 +32,17 @@ This memo documents how TinyOS 2.x manages the power state of physical ====================================================================== TinyOS platforms have limited energy. A unified power management -strategy for all devices and peripherpals is not feasible, as +strategy for all devices and peripherals is not feasible, as they vary significantly in warm-up times, power profiles, and operation latencies. While some devices, such as microcontrollers, can efficiently calculate their lowest possible power state very quickly, others, such as sensors with warm-up times, require external knowledge to do so. -In TinyOS 1.x, an application is responsible for all power management. +In TinyOS 1.x, applications are responsible for all power management. Low-level subsystems, such as an SPI bus, are explicitly powered on and off by higher level abstractions. This approach of deep calls -to StdControl.start and StdControl.stop introduces strange behaviors +to ``StdControl.start()`` and ``StdControl.stop()`` introduces strange behaviors and can get in the way of power conservation. Turning off the radio on the Telos platform, for example, turns off the SPI bus and therefore prevents the flash driver from working. Additionally, the microcontroller @@ -73,7 +73,8 @@ power management*. The explicit model provides a means for a single client to manually control the power state of a dedicated physical device (as defined by [TEP108]_). Whenever this client tells the device to power up or down -it does so without delay (albeit that caused by hardware). This model +it does so without delay (except for delays in the hardware of course). +This model can be particularly useful when the control information driving the selection of the proper power state of a device relies on external logic contained in higher level components. The following section @@ -135,7 +136,7 @@ representing a hardware device that can be powered on and off MUST provide one of these three interfaces. The selection of the right interface depends on the latencies involved in changing between these two states as well as the -nature of the code (sync or async) executing any of the interfaces +nature of the code (sync or async) executing any of the interface's commands. 3.1 Power Management with ``StdControl`` @@ -172,7 +173,8 @@ interfaces implemented by the device to succeed. Upon the successful return of a call to ``StdControl.stop()``, a device MUST be completely powered down, and any calls to commands -of other interfaces implemented by that device MUST return FAIL or EOFF. +of other interfaces implemented by that device that actually access +the device hardware MUST return FAIL or EOFF. If a device is not able to complete the ``StdControl.start()`` or ``StdControl.stop()`` request for any reason, it MUST return FAIL. @@ -206,7 +208,7 @@ Devices providing this interface would do so as shown below:: ---------------------------------------------------------------------- When a device's powerup and powerdown times are non-negligible, the -*``SplitControl``* interface MUST be used in place of the *``StdControl``* +*``SplitControl``* interface SHOULD be used in place of the *``StdControl``* interface. The definition of this interface can be seen below:: interface SplitControl { @@ -220,12 +222,12 @@ interface. The definition of this interface can be seen below:: An external component MUST call ``SplitControl.start()`` to power a device on and ``SplitControl.stop()`` to power a device off. Calls to either command return one of SUCCESS, FAIL, EBUSY, or -EALREADY. SUCCESS indicates that the device has now started chaning -its power mode and it will signal a corresponding completion event in -the future. EBUSY indicates that the device is in the midst of the -other operation (e.g., it is starting when stop is called or stopping +EALREADY. SUCCESS indicates that the device has now started changing +its power state and will signal a corresponding completion event in +the future. EBUSY indicates that the device is in the midst of either starting +or stopping (e.g., it is starting when stop is called or stopping when start is called) and will not issue an event. EALREADY indicates -that the device is already in that state; the call is erroneus and a +that the device is already in that state; the call is erroneous and a completion event will not be signaled. FAIL indicates that the device's power state could not be changed. More explicitly: @@ -241,7 +243,8 @@ of other interfaces implemented by the device MAY succeed. Upon signalling a ``SplitControl.stopDone(SUCCESS)``, a device MUST be completely powered down, and any subsequent calls to commands of other -interfaces implemented by the device MUST return EOFF or FAIL. +interfaces implemented by the device that actually access +the device hardware MUST return EOFF or FAIL. If a device is powered on and a successful call to ``SplitControl.stop()`` signals a ``SplitControl.stopDone(FAIL)``, the device MUST still be fully @@ -262,13 +265,13 @@ SUCCESS, with the anticipation that a corresponding ``SplitControl.startDone()`` or ``SplitControl.stopDone()`` will be signaled in the future. -Calls to `SplitControl.start()`` when the device is started +Calls to ``SplitControl.start()`` when the device is started or ``SplitControl.stop()`` while the device is stopped MUST return EALREADY, indicating that the device is already in that state. The corresponding completion event (startDone for start or stopDone for stop) MUST NOT be signaled. -Calls to `SplitControl.start()`` when the device is stopping or +Calls to ``SplitControl.start()`` when the device is stopping or ``SplitControl.stop()`` while the device is starting MUST return EBUSY, indicating that the device is busy performing a differnet operation. The correspodning completion event (startDone for start or @@ -297,7 +300,28 @@ Devices providing this interface would do so as shown below:: .... } } - + +.. Note:: + + Other approaches were considered for the return values of + ``SplitControl.start()`` and ``SplitControl.stop()``. One such + approach would have replaced EBUSY with SUCCESS when + ``SplitControl.start()`` was called while in the process of stopping + and ``SplitControl.stop()`` was called while in the process of starting. + However, implementing such an approach adds unwanted complexity to + a device driver. It is unreasonable to expect the implementor of + each driver to implement this functionality. + + Returning EBUSY is the most straightforward, unambiguous value + that can be returned in such a situation. By returning + EBUSY when a device is in a transitional state, the components + built on top of a driver unambiguously know exactly why a call to + ``start()`` or ``stop()`` did not succeed, and can take action accordingly. + Since only ONE component should ever implement the ``SplitControl`` + interface for a given device, it isn't unreasonable to expect them + to keep track of this return value themselves. There is, of course, + nothing preventing someone from creating a component + on top of each driver implementation that implements things differently. 3.3 Power Management with ``AsyncStdControl`` ---------------------------------------------------------------------- @@ -380,7 +404,8 @@ For cases when some of these features are known a-priori or are restricted in some sense, it is preferable that the system provide architectural support for enforcing a meaningful *default* power-management policy instead of passing that task on to the application programmer to be -solved on a case-by-case basis. +solved on a case-by-case basis. The following section discusses these power +management policies and the components that implement them in greater detail. 4.1. Power Management Policies @@ -389,7 +414,7 @@ solved on a case-by-case basis. Just as generic arbiters are offered in TinyOS 2.x to provide the arbitration functionality required by shared resources, generic power management policies are also offered to allow the power management of -non-virtualised devices to be automatically control. +non-virtualised devices to be automatically controlled. Through the use of the arbiter components described in [TEP108]_, device drivers implemented as shared resources provide the type of @@ -437,9 +462,9 @@ by one of its clients. Whenever a client puts in a request, the (or ``immediateRequested()`` event) from the arbiter it is associated with. Upon receiving this event, the *Power Manager* MUST power up the resource through the StdControl-like interface provided by the lower level -abstraction of the physical device. The *Power Manager* SHOULD release the +abstraction of the physical device. The *Power Manager* MUST release the ownership of the resource (using the ``ResourceDefaultOwner.release()`` -command) but MUST wait until after the resource has been fully powered on +command) and MUST wait until after the resource has been fully powered on before doing so. Modeling devices as shared resources and allowing them to be @@ -537,7 +562,8 @@ devices are powered on and off immediately after they have been requested and released. The second policy is implemented using a *deferred* power control scheme, whereby devices are powered on immediately after being requested, but powered off after -some small delay from being released. +some small delay from being released. This delay is configurable +to meet the varying needs of different device drivers. Each policy has three different implementations for use by each of the ``StdControl``, ``SplitControl``, and ``AsyncStdControl`` @@ -559,12 +585,11 @@ Deferred Power Management: 5. Author's Address ==================================================================== | Kevin Klues -| 503 Bryan Hall -| Washington University -| St. Louis, MO 63130 +| 444 Gates Hall +| Stanford University +| Stanford, CA 94305-9030 | -| phone - +1-314-935-6355 -| email - klueska@cs.wustl.edu +| email - klueska@cs.stanford.edu | | Vlado Handziski | Sekr FT5