[Tinyos-2-commits] CVS: tinyos-2.x/doc/html tep115.html,1.10,1.11
Kevin Klues
klueska at users.sourceforge.net
Fri Sep 14 15:45:32 PDT 2007
Update of /cvsroot/tinyos/tinyos-2.x/doc/html
In directory sc8-pr-cvs10.sourceforge.net:/tmp/cvs-serv28561/html
Modified Files:
tep115.html
Log Message:
Update to TEP115
Index: tep115.html
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/doc/html/tep115.html,v
retrieving revision 1.10
retrieving revision 1.11
diff -C2 -d -r1.10 -r1.11
*** tep115.html 14 Aug 2007 18:58:00 -0000 1.10
--- tep115.html 14 Sep 2007 22:45:30 -0000 1.11
***************
*** 12,30 ****
:Author: David Goodger
:Contact: goodger at users.sourceforge.net
! :date: $Date$
! :version: $Revision$
! :copyright: This stylesheet has been placed in the public domain.
Default cascading style sheet for the HTML output of Docutils.
*/
! body {
! font-family: Times;
! font-size: 16px;
! }
.first {
margin-top: 0 ! important }
! .last {
margin-bottom: 0 ! important }
--- 12,39 ----
:Author: David Goodger
:Contact: goodger at users.sourceforge.net
! :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.
*/
!
! /* 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, .with-subtitle {
margin-bottom: 0 ! important }
***************
*** 39,45 ****
margin: 2em 5em ; }
! dd {
margin-bottom: 0.5em }
div.abstract {
margin: 2em 5em }
--- 48,59 ----
margin: 2em 5em ; }
! 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 }
***************
*** 49,58 ****
text-align: center }
! div.attention, div.caution, div.danger, div.error, div.hint,
! div.important, div.note, div.tip, div.warning, div.admonition {
margin: 2em ;
border: medium outset ;
padding: 1em }
div.attention p.admonition-title, div.caution p.admonition-title,
div.danger p.admonition-title, div.error p.admonition-title,
--- 63,78 ----
text-align: center }
! 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,
***************
*** 62,70 ****
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 }
div.dedication {
--- 82,93 ----
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 {
***************
*** 78,84 ****
div.figure {
! margin-left: 2em }
div.footer, div.header {
font-size: smaller }
--- 101,109 ----
div.figure {
! margin-left: 2em ;
! margin-right: 2em }
div.footer, div.header {
+ clear: both;
font-size: smaller }
***************
*** 96,100 ****
margin-left: 1em ;
border: medium outset ;
! padding: 0em 1em ;
background-color: #ffffee ;
width: 40% ;
--- 121,125 ----
margin-left: 1em ;
border: medium outset ;
! padding: 1em ;
background-color: #ffffee ;
width: 40% ;
***************
*** 123,152 ****
margin: 2em }
! h1 {
! font-family: Arial, sans-serif;
! font-size: 20px;
! }
h1.title {
! text-align: center;
! font-size: 32px;
! }
!
! h2 {
! font-size: 16px;
! font-family: Arial, sans-serif;
! }
h2.subtitle {
text-align: center }
! h3 {
! font-size: 12px;
! font-family: Arial, sans-serif;
! }
!
! hr {
width: 75% }
ol.simple, ul.simple {
margin-bottom: 1em }
--- 148,170 ----
margin: 2em }
! 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 }
h2.subtitle {
text-align: center }
! hr.docutils {
width: 75% }
+ img.align-left {
+ clear: left }
+
+ img.align-right {
+ clear: right }
+
ol.simple, ul.simple {
margin-bottom: 1em }
***************
*** 205,220 ****
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
! }
span.classifier {
--- 223,230 ----
font-size: 100% }
pre.literal-block, pre.doctest-block {
margin-left: 2em ;
margin-right: 2em ;
! background-color: #eeeeee }
span.classifier {
***************
*** 232,238 ****
white-space: nowrap }
- span.option-argument {
- font-style: italic }
-
span.pre {
white-space: pre }
--- 242,245 ----
***************
*** 241,275 ****
color: red }
! table {
! margin-top: 0.5em ;
! margin-bottom: 0.5em }
table.citation {
! border-left: solid thin gray ;
! padding-left: 0.5ex }
table.docinfo {
! margin: 2em 4em;
! }
table.footnote {
! border-left: solid thin black ;
! padding-left: 0.5ex }
! td, th {
padding-left: 0.5em ;
padding-right: 0.5em ;
vertical-align: top }
! th.docinfo-name, th.field-name {
font-weight: bold ;
text-align: left ;
! white-space: nowrap;
! }
! h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt {
font-size: 100% }
! tt {}
ul.auto-toc {
--- 248,288 ----
color: red }
! span.section-subtitle {
! /* font-size relative to parent (h1..h6 element) */
! font-size: 80% }
table.citation {
! border-left: solid 1px gray;
! margin-left: 1px }
table.docinfo {
! margin: 2em 4em }
!
! table.docutils {
! margin-top: 0.5em ;
! margin-bottom: 0.5em }
table.footnote {
! border-left: solid 1px black;
! margin-left: 1px }
! table.docutils td, table.docutils th,
! table.docinfo td, table.docinfo th {
padding-left: 0.5em ;
padding-right: 0.5em ;
vertical-align: top }
! table.docutils th.field-name, table.docinfo th.docinfo-name {
font-weight: bold ;
text-align: left ;
! white-space: nowrap ;
! padding-left: 0 }
! h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
! h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
font-size: 100% }
! tt.docutils {
! background-color: #eeeeee }
ul.auto-toc {
***************
*** 323,327 ****
<h1><a id="introduction" name="introduction">1. Introduction</a></h1>
<p>TinyOS platforms have limited energy. A unified power management
! strategy for all devices and peripherpals is not feasible, as
they vary significantly in warm-up times, power profiles, and
operation latencies. While some devices, such as
--- 336,340 ----
<h1><a id="introduction" name="introduction">1. Introduction</a></h1>
<p>TinyOS platforms have limited energy. A unified power management
! 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
***************
*** 329,336 ****
power state very quickly, others, such as sensors with warm-up
times, require external knowledge to do so.</p>
! <p>In TinyOS 1.x, an application is 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
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
--- 342,349 ----
power state very quickly, others, such as sensors with warm-up
times, require external knowledge to do so.</p>
! <p>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 <tt class="docutils literal"><span class="pre">StdControl.start()</span></tt> and <tt class="docutils literal"><span class="pre">StdControl.stop()</span></tt> 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
***************
*** 358,362 ****
control the power state of a dedicated physical device (as defined by
<a class="citation-reference" href="#tep108" id="id3" name="id3">[TEP108]</a>). Whenever this client tells the device to power up or down
! it does so without delay (albeit that caused by hardware). This model
can be particularly useful when the control information driving the
selection of the proper power state of a device relies on external
--- 371,376 ----
control the power state of a dedicated physical device (as defined by
<a class="citation-reference" href="#tep108" id="id3" name="id3">[TEP108]</a>). Whenever this client tells the device to power up or down
! 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
***************
*** 416,420 ****
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
commands.</p>
<div class="section">
--- 430,434 ----
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 interface's
commands.</p>
<div class="section">
***************
*** 449,453 ****
<p>Upon the successful return of a call to <tt class="docutils literal"><span class="pre">StdControl.stop()</span></tt>, a
device MUST be completely powered down, and any calls to commands
! of other interfaces implemented by that device MUST return FAIL or EOFF.</p>
<p>If a device is not able to complete the <tt class="docutils literal"><span class="pre">StdControl.start()</span></tt> or
<tt class="docutils literal"><span class="pre">StdControl.stop()</span></tt> request for any reason, it MUST return FAIL.</p>
--- 463,468 ----
<p>Upon the successful return of a call to <tt class="docutils literal"><span class="pre">StdControl.stop()</span></tt>, a
device MUST be completely powered down, and any calls to commands
! of other interfaces implemented by that device that actually access
! the device hardware MUST return FAIL or EOFF.</p>
<p>If a device is not able to complete the <tt class="docutils literal"><span class="pre">StdControl.start()</span></tt> or
<tt class="docutils literal"><span class="pre">StdControl.stop()</span></tt> request for any reason, it MUST return FAIL.</p>
***************
*** 496,500 ****
<h2><a id="power-management-with-splitcontrol" name="power-management-with-splitcontrol">3.2 Power Management with <tt class="docutils literal"><span class="pre">SplitControl</span></tt></a></h2>
<p>When a device's powerup and powerdown times are non-negligible, the
! <em>``SplitControl``</em> interface MUST be used in place of the <em>``StdControl``</em>
interface. The definition of this interface can be seen below:</p>
<pre class="literal-block">
--- 511,515 ----
<h2><a id="power-management-with-splitcontrol" name="power-management-with-splitcontrol">3.2 Power Management with <tt class="docutils literal"><span class="pre">SplitControl</span></tt></a></h2>
<p>When a device's powerup and powerdown times are non-negligible, the
! <em>``SplitControl``</em> interface SHOULD be used in place of the <em>``StdControl``</em>
interface. The definition of this interface can be seen below:</p>
<pre class="literal-block">
***************
*** 509,518 ****
device on and <tt class="docutils literal"><span class="pre">SplitControl.stop()</span></tt> 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
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
completion event will not be signaled. FAIL indicates that the
device's power state could not be changed. More explicitly:</p>
--- 524,533 ----
device on and <tt class="docutils literal"><span class="pre">SplitControl.stop()</span></tt> 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 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 erroneous and a
completion event will not be signaled. FAIL indicates that the
device's power state could not be changed. More explicitly:</p>
***************
*** 526,530 ****
<p>Upon signalling a <tt class="docutils literal"><span class="pre">SplitControl.stopDone(SUCCESS)</span></tt>, 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.</p>
<p>If a device is powered on and a successful call to <tt class="docutils literal"><span class="pre">SplitControl.stop()</span></tt>
signals a <tt class="docutils literal"><span class="pre">SplitControl.stopDone(FAIL)</span></tt>, the device MUST still be fully
--- 541,546 ----
<p>Upon signalling a <tt class="docutils literal"><span class="pre">SplitControl.stopDone(SUCCESS)</span></tt>, a device MUST be
completely powered down, and any subsequent calls to commands of other
! interfaces implemented by the device that actually access
! the device hardware MUST return EOFF or FAIL.</p>
<p>If a device is powered on and a successful call to <tt class="docutils literal"><span class="pre">SplitControl.stop()</span></tt>
signals a <tt class="docutils literal"><span class="pre">SplitControl.stopDone(FAIL)</span></tt>, the device MUST still be fully
***************
*** 542,551 ****
<tt class="docutils literal"><span class="pre">SplitControl.startDone()</span></tt> or <tt class="docutils literal"><span class="pre">SplitControl.stopDone()</span></tt>
will be signaled in the future.</p>
! <p>Calls to <cite>SplitControl.start()`</cite> when the device is started
or <tt class="docutils literal"><span class="pre">SplitControl.stop()</span></tt> 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.</p>
! <p>Calls to <cite>SplitControl.start()`</cite> when the device is stopping or
<tt class="docutils literal"><span class="pre">SplitControl.stop()</span></tt> while the device is starting MUST return
EBUSY, indicating that the device is busy performing a differnet
--- 558,567 ----
<tt class="docutils literal"><span class="pre">SplitControl.startDone()</span></tt> or <tt class="docutils literal"><span class="pre">SplitControl.stopDone()</span></tt>
will be signaled in the future.</p>
! <p>Calls to <tt class="docutils literal"><span class="pre">SplitControl.start()</span></tt> when the device is started
or <tt class="docutils literal"><span class="pre">SplitControl.stop()</span></tt> 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.</p>
! <p>Calls to <tt class="docutils literal"><span class="pre">SplitControl.start()</span></tt> when the device is stopping or
<tt class="docutils literal"><span class="pre">SplitControl.stop()</span></tt> while the device is starting MUST return
EBUSY, indicating that the device is busy performing a differnet
***************
*** 606,609 ****
--- 622,646 ----
}
</pre>
+ <div class="note">
+ <p class="first admonition-title">Note</p>
+ <p>Other approaches were considered for the return values of
+ <tt class="docutils literal"><span class="pre">SplitControl.start()</span></tt> and <tt class="docutils literal"><span class="pre">SplitControl.stop()</span></tt>. One such
+ approach would have replaced EBUSY with SUCCESS when
+ <tt class="docutils literal"><span class="pre">SplitControl.start()</span></tt> was called while in the process of stopping
+ and <tt class="docutils literal"><span class="pre">SplitControl.stop()</span></tt> 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.</p>
+ <p class="last">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
+ <tt class="docutils literal"><span class="pre">start()</span></tt> or <tt class="docutils literal"><span class="pre">stop()</span></tt> did not succeed, and can take action accordingly.
+ Since only ONE component should ever implement the <tt class="docutils literal"><span class="pre">SplitControl</span></tt>
+ 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.</p>
+ </div>
</div>
<div class="section">
***************
*** 682,686 ****
architectural support for enforcing a meaningful <em>default</em> power-management
policy instead of passing that task on to the application programmer to be
! solved on a case-by-case basis.</p>
<div class="section">
<h2><a id="power-management-policies" name="power-management-policies">4.1. Power Management Policies</a></h2>
--- 719,724 ----
architectural support for enforcing a meaningful <em>default</em> power-management
policy instead of passing that task on to the application programmer to be
! solved on a case-by-case basis. The following section discusses these power
! management policies and the components that implement them in greater detail.</p>
<div class="section">
<h2><a id="power-management-policies" name="power-management-policies">4.1. Power Management Policies</a></h2>
***************
*** 688,692 ****
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.</p>
<p>Through the use of the arbiter components described in <a class="citation-reference" href="#tep108" id="id6" name="id6">[TEP108]</a>,
device drivers implemented as shared resources provide the type of
--- 726,730 ----
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 controlled.</p>
<p>Through the use of the arbiter components described in <a class="citation-reference" href="#tep108" id="id6" name="id6">[TEP108]</a>,
device drivers implemented as shared resources provide the type of
***************
*** 732,738 ****
Upon receiving this event, the <em>Power Manager</em> MUST power up the
resource through the StdControl-like interface provided by the lower level
! abstraction of the physical device. The <em>Power Manager</em> SHOULD release the
ownership of the resource (using the <tt class="docutils literal"><span class="pre">ResourceDefaultOwner.release()</span></tt>
! command) but MUST wait until after the resource has been fully powered on
before doing so.</p>
<p>Modeling devices as shared resources and allowing them to be
--- 770,776 ----
Upon receiving this event, the <em>Power Manager</em> MUST power up the
resource through the StdControl-like interface provided by the lower level
! abstraction of the physical device. The <em>Power Manager</em> MUST release the
ownership of the resource (using the <tt class="docutils literal"><span class="pre">ResourceDefaultOwner.release()</span></tt>
! command) and MUST wait until after the resource has been fully powered on
before doing so.</p>
<p>Modeling devices as shared resources and allowing them to be
***************
*** 827,831 ****
a <em>deferred</em> power control scheme, whereby devices are powered
on immediately after being requested, but powered off after
! some small delay from being released.</p>
<p>Each policy has three different implementations for use by each of
the <tt class="docutils literal"><span class="pre">StdControl</span></tt>, <tt class="docutils literal"><span class="pre">SplitControl</span></tt>, and <tt class="docutils literal"><span class="pre">AsyncStdControl</span></tt>
--- 865,870 ----
a <em>deferred</em> power control scheme, whereby devices are powered
on immediately after being requested, but powered off after
! some small delay from being released. This delay is configurable
! to meet the varying needs of different device drivers.</p>
<p>Each policy has three different implementations for use by each of
the <tt class="docutils literal"><span class="pre">StdControl</span></tt>, <tt class="docutils literal"><span class="pre">SplitControl</span></tt>, and <tt class="docutils literal"><span class="pre">AsyncStdControl</span></tt>
***************
*** 854,863 ****
<div class="line-block">
<div class="line">Kevin Klues</div>
! <div class="line">503 Bryan Hall</div>
! <div class="line">Washington University</div>
! <div class="line">St. Louis, MO 63130</div>
<div class="line"><br /></div>
! <div class="line">phone - +1-314-935-6355</div>
! <div class="line">email - <a class="reference" href="mailto:klueska@cs.wustl.edu">klueska@cs.wustl.edu</a></div>
<div class="line"><br /></div>
<div class="line">Vlado Handziski</div>
--- 893,901 ----
<div class="line-block">
<div class="line">Kevin Klues</div>
! <div class="line">444 Gates Hall</div>
! <div class="line">Stanford University</div>
! <div class="line">Stanford, CA 94305-9030</div>
<div class="line"><br /></div>
! <div class="line">email - <a class="reference" href="mailto:klueska@cs.stanford.edu">klueska@cs.stanford.edu</a></div>
<div class="line"><br /></div>
<div class="line">Vlado Handziski</div>
More information about the Tinyos-2-commits
mailing list