[Tinyos-2-commits] CVS: tinyos-2.x/doc/html tep122.html, NONE,
1.1 tep130.html, NONE, 1.1 tep127.html, NONE, 1.1 tep128.html,
NONE, 1.1 tep105.html, NONE, 1.1 tep129.html, NONE,
1.1 tep2.html, 1.11, 1.12 tep119.html, 1.10, 1.11 tep113.html,
1.9, 1.10 tep123.html, 1.9, 1.10 tep126.html, 1.2,
1.3 tep1.html, 1.10, 1.11 tep106.html, 1.9, 1.10 tep101.html,
1.9, 1.10 tep118.html, 1.7, 1.8 tep124.html, 1.3,
1.4 tep125.html, 1.3, 1.4 overview.html, 1.8, 1.9 tep112.html,
1.9, 1.10 tep109.html, 1.8, 1.9 tep114.html, 1.8,
1.9 tep108.html, 1.10, 1.11 tep115.html, 1.9, 1.10 tep117.html,
1.8, 1.9 tep120.html, 1.9, 1.10 porting.html, 1.6,
1.7 tep116.html, 1.12, 1.13 tep110.html, 1.7, 1.8 tep121.html,
1.7, 1.8 tep102.html, 1.9, 1.10 tep107.html, 1.13,
1.14 tep103.html, 1.7, 1.8 tep3.html, 1.7, 1.8 tep111.html,
1.10, 1.11
Jan Beutel
beutel at users.sourceforge.net
Tue Aug 14 11:58:05 PDT 2007
Update of /cvsroot/tinyos/tinyos-2.x/doc/html
In directory sc8-pr-cvs10.sourceforge.net:/tmp/cvs-serv363/doc/html
Modified Files:
tep2.html tep119.html tep113.html tep123.html tep126.html
tep1.html tep106.html tep101.html tep118.html tep124.html
tep125.html overview.html tep112.html tep109.html tep114.html
tep108.html tep115.html tep117.html tep120.html porting.html
tep116.html tep110.html tep121.html tep102.html tep107.html
tep103.html tep3.html tep111.html
Added Files:
tep122.html tep130.html tep127.html tep128.html tep105.html
tep129.html
Log Message:
fixed html validation error in docs
--- NEW FILE: tep122.html ---
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
<title>IEEE EUI-64 Unique Node Identifier</title>
<meta name="author" content="Gilman Tolle, Jonathan Hui" />
<style type="text/css">
/*
:Author: David Goodger
:Contact: goodger at users.sourceforge.net
:date: $Date: 2007/08/14 18:57:59 $
:version: $Revision: 1.1 $
: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 }
.hidden {
display: none }
a.toc-backref {
text-decoration: none ;
color: black }
blockquote.epigraph {
margin: 2em 5em ; }
dd {
margin-bottom: 0.5em }
div.abstract {
margin: 2em 5em }
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 {
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,
div.warning p.admonition-title {
color: red ;
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 }
div.dedication {
margin: 2em 5em ;
text-align: center ;
font-style: italic }
div.dedication p.topic-title {
font-weight: bold ;
font-style: normal }
div.figure {
margin-left: 2em }
div.footer, div.header {
font-size: smaller }
div.line-block {
display: block ;
margin-top: 1em ;
margin-bottom: 1em }
div.line-block div.line-block {
margin-top: 0 ;
margin-bottom: 0 ;
margin-left: 1.5em }
div.sidebar {
margin-left: 1em ;
border: medium outset ;
padding: 0em 1em ;
background-color: #ffffee ;
width: 40% ;
float: right ;
clear: right }
div.sidebar p.rubric {
font-family: sans-serif ;
font-size: medium }
div.system-messages {
margin: 5em }
div.system-messages h1 {
color: red }
div.system-message {
border: medium outset ;
padding: 1em }
div.system-message p.system-message-title {
color: red ;
font-weight: bold }
div.topic {
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 }
ol.arabic {
list-style: decimal }
ol.loweralpha {
list-style: lower-alpha }
ol.upperalpha {
list-style: upper-alpha }
ol.lowerroman {
list-style: lower-roman }
ol.upperroman {
list-style: upper-roman }
p.attribution {
text-align: right ;
margin-left: 50% }
p.caption {
font-style: italic }
p.credits {
font-style: italic ;
font-size: smaller }
p.label {
white-space: nowrap }
p.rubric {
font-weight: bold ;
font-size: larger ;
color: maroon ;
text-align: center }
p.sidebar-title {
font-family: sans-serif ;
font-weight: bold ;
font-size: larger }
p.sidebar-subtitle {
font-family: sans-serif ;
font-weight: bold }
p.topic-title {
font-weight: bold }
pre.address {
margin-bottom: 0 ;
margin-top: 0 ;
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
}
span.classifier {
font-family: sans-serif ;
font-style: oblique }
span.classifier-delimiter {
font-family: sans-serif ;
font-weight: bold }
span.interpreted {
font-family: sans-serif }
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 }
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 {
list-style-type: none }
</style>
</head>
<body>
<div class="document" id="ieee-eui-64-unique-node-identifier">
<h1 class="title">IEEE EUI-64 Unique Node Identifier</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr class="field"><th class="docinfo-name">TEP:</th><td class="field-body">122</td>
</tr>
<tr class="field"><th class="docinfo-name">Group:</th><td class="field-body">Core Working Group</td>
</tr>
<tr class="field"><th class="docinfo-name">Type:</th><td class="field-body">Documentary</td>
</tr>
<tr><th class="docinfo-name">Status:</th>
<td>Draft</td></tr>
<tr class="field"><th class="docinfo-name">TinyOS-Version:</th><td class="field-body">2.x</td>
</tr>
<tr><th class="docinfo-name">Author:</th>
<td>Gilman Tolle, Jonathan Hui</td></tr>
<tr class="field"><th class="docinfo-name">Draft-Created:</th><td class="field-body">26-Apr-2006</td>
</tr>
<tr class="field"><th class="docinfo-name">Draft-Version:</th><td class="field-body"></td>
</tr>
<tr class="field"><th class="docinfo-name">Draft-Modified:</th><td class="field-body"></td>
</tr>
<tr class="field"><th class="docinfo-name">Draft-Discuss:</th><td class="field-body">TinyOS Developer List <tinyos-devel at mail.millennium.berkeley.edu></td>
</tr>
</tbody>
</table>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">This memo documents a part of TinyOS for the TinyOS Community, and
requests discussion and suggestions for improvements. Distribution
of this memo is unlimited. This memo is in full compliance with
TEP 1.</p>
</div>
<div class="section">
<h1><a id="abstract" name="abstract">Abstract</a></h1>
<p>A TinyOS application developer may desire a globally-unique node
identifier within the IEEE EUI-64 namespace. This document describes
the TinyOS components used to access such an identifier.</p>
</div>
<div class="section">
<h1><a id="interfaces" name="interfaces">1. Interfaces</a></h1>
<p>A platform that can provide a valid IEEE EUI-64 globally-unique node
identifier SHOULD provide it through a component with the signature
defined here, enabling platform-independent access to the identifier:</p>
<pre class="literal-block">
configuration LocalIeeeEui64C {
provides interface LocalIeeeEui64;
}
</pre>
<p>The identifier is accessed through the following interface:</p>
<pre class="literal-block">
interface LocalIeeeEui64 {
command ieee_eui64_t getId();
}
</pre>
<p>The ieee_eui64_t type is defined in <tt class="docutils literal"><span class="pre">tos/types/IeeeEui64.h</span></tt> as:</p>
<pre class="literal-block">
enum { IEEE_EUI64_LENGTH = 8; }
typedef struct ieee_eui64 {
uint8_t data[IEEE_EUI64_LENGTH];
} ieee_eui64_t;
</pre>
<p>If the platform can provide a valid IEEE EUI-64, the value returned
from this call MUST follow the IEEE EUI-64 standard.</p>
<p>If a platform can provide a unique identifier that is not a valid IEEE
EUI-64 identifier, it SHOULD provide its unique identifier through a
component with a different name and a different interface. The
definition of such an interface is outside the scope of this TEP.</p>
</div>
<div class="section">
<h1><a id="ieee-eui-64" name="ieee-eui-64">2. IEEE EUI-64</a></h1>
<p>The IEEE EUI-64 structure is copied here:</p>
<pre class="literal-block">
| company_id | extension identifier |
|addr+0 | addr+1 | addr+2 | addr+3 | addr+4 | addr+5 | addr+6 | addr+7|
| AC | DE | 48 | 23 | 45 | 67 | AB | CD |
10101100 11011110 01001000 00100011 01000101 01100111 10101011 11001101
| | | |
| most significant byte least significant byte |
most-significant bit least-significant bit
If provided in byte-addressable media, the original byte-address order
of the manufacturer is specified: the most through least significant
bytes of the EUI-64 value are contained within the lowest through
highest byte addresses, as illustrated above.
</pre>
<p>See: <a class="reference" href="http://standards.ieee.org/regauth/oui/tutorials/EUI64.html">http://standards.ieee.org/regauth/oui/tutorials/EUI64.html</a></p>
<p>The author of the LocalIeeeEui64C component MUST ensure that the
getId() call returns a valid EUI-64 identifier that follows the
standard, with the bytes in the order described above.</p>
</div>
<div class="section">
<h1><a id="implementation-notes" name="implementation-notes">3. Implementation Notes</a></h1>
<p>Some TinyOS node platforms contain a unique hardware identifier that
can be used to build the EUI-64 node identifier. That hardware
identifier may be obtained from several places, e.g. a dedicated
serial ID chip or a flash storage device. Users of the interface
described in this document MUST NOT require knowledge of how the
unique identifier is generated.</p>
<p>The EUI-64 node identifier MUST be available before the Boot.booted()
event is signalled. If the EUI-64 is derived from a hardware device,
the hardware device should be accessed during the Init portion of the
boot sequence.</p>
</div>
<div class="section">
<h1><a id="author-s-address" name="author-s-address">4. Author's Address</a></h1>
<div class="line-block">
<div class="line">Gilman Tolle</div>
<div class="line">Arch Rock Corporation</div>
<div class="line">657 Mission St. Suite 600</div>
<div class="line">San Francisco, CA 94105</div>
<div class="line"><br /></div>
<div class="line">phone - +1 415 692 0828</div>
<div class="line">email - <a class="reference" href="mailto:gtolle@archrock.com">gtolle@archrock.com</a></div>
</div>
<div class="line-block">
<div class="line">Jonathan Hui</div>
<div class="line">Arch Rock Corporation</div>
<div class="line">657 Mission St. Suite 600</div>
<div class="line">San Francisco, CA 94105</div>
<div class="line"><br /></div>
<div class="line">phone - +1 415 692 0828</div>
<div class="line">email - <a class="reference" href="mailto:jhui@archrock.com">jhui@archrock.com</a></div>
</div>
</div>
</div>
</body>
</html>
--- NEW FILE: tep130.html ---
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
<title>Testbeds - Setup and Interfaces</title>
<meta name="author" content="Jan Beutel" />
<style type="text/css">
/*
:Author: David Goodger
:Contact: goodger at users.sourceforge.net
:date: $Date: 2007/08/14 18:57:59 $
:version: $Revision: 1.1 $
: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 }
.hidden {
display: none }
a.toc-backref {
text-decoration: none ;
color: black }
blockquote.epigraph {
margin: 2em 5em ; }
dd {
margin-bottom: 0.5em }
div.abstract {
margin: 2em 5em }
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 {
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,
div.warning p.admonition-title {
color: red ;
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 }
div.dedication {
margin: 2em 5em ;
text-align: center ;
font-style: italic }
div.dedication p.topic-title {
font-weight: bold ;
font-style: normal }
div.figure {
margin-left: 2em }
div.footer, div.header {
font-size: smaller }
div.line-block {
display: block ;
margin-top: 1em ;
margin-bottom: 1em }
div.line-block div.line-block {
margin-top: 0 ;
margin-bottom: 0 ;
margin-left: 1.5em }
div.sidebar {
margin-left: 1em ;
border: medium outset ;
padding: 0em 1em ;
background-color: #ffffee ;
width: 40% ;
float: right ;
clear: right }
div.sidebar p.rubric {
font-family: sans-serif ;
font-size: medium }
div.system-messages {
margin: 5em }
div.system-messages h1 {
color: red }
div.system-message {
border: medium outset ;
padding: 1em }
div.system-message p.system-message-title {
color: red ;
font-weight: bold }
div.topic {
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 }
ol.arabic {
list-style: decimal }
ol.loweralpha {
list-style: lower-alpha }
ol.upperalpha {
list-style: upper-alpha }
ol.lowerroman {
list-style: lower-roman }
ol.upperroman {
list-style: upper-roman }
p.attribution {
text-align: right ;
margin-left: 50% }
p.caption {
font-style: italic }
p.credits {
font-style: italic ;
font-size: smaller }
p.label {
white-space: nowrap }
p.rubric {
font-weight: bold ;
font-size: larger ;
color: maroon ;
text-align: center }
p.sidebar-title {
font-family: sans-serif ;
font-weight: bold ;
font-size: larger }
p.sidebar-subtitle {
font-family: sans-serif ;
font-weight: bold }
p.topic-title {
font-weight: bold }
pre.address {
margin-bottom: 0 ;
margin-top: 0 ;
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
}
span.classifier {
font-family: sans-serif ;
font-style: oblique }
span.classifier-delimiter {
font-family: sans-serif ;
font-weight: bold }
span.interpreted {
font-family: sans-serif }
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 }
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 {
list-style-type: none }
</style>
</head>
<body>
<div class="document" id="testbeds-setup-and-interfaces">
<h1 class="title">Testbeds - Setup and Interfaces</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr class="field"><th class="docinfo-name">TEP:</th><td class="field-body">130</td>
</tr>
<tr class="field"><th class="docinfo-name">Group:</th><td class="field-body">Testbeds Working Group</td>
</tr>
<tr class="field"><th class="docinfo-name">Type:</th><td class="field-body">Documentary</td>
</tr>
<tr><th class="docinfo-name">Status:</th>
<td>Draft</td></tr>
<tr class="field"><th class="docinfo-name">TinyOS-Version:</th><td class="field-body">All</td>
</tr>
<tr><th class="docinfo-name">Author:</th>
<td>Jan Beutel</td></tr>
<tr class="field"><th class="docinfo-name">Draft-Created:</th><td class="field-body">14-Jun-2007</td>
</tr>
<tr class="field"><th class="docinfo-name">Draft-Version:</th><td class="field-body">1.2</td>
</tr>
<tr class="field"><th class="docinfo-name">Draft-Modified:</th><td class="field-body">2007-06-28</td>
</tr>
<tr class="field"><th class="docinfo-name">Draft-Discuss:</th><td class="field-body">TinyOS Testbed WG <<a class="reference" href="mailto:tinyos-testbed-wg@eecs.harvard.edu">tinyos-testbed-wg@eecs.harvard.edu</a>>></td>
</tr>
</tbody>
</table>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">This document specifies a Best Current Practices for the
TinyOS Community, and requests discussion and suggestions for
improvements. Distribution of this memo is unlimited.</p>
</div>
<div class="section">
<h1><a id="abstract" name="abstract">Abstract</a></h1>
<p>This memo describes the structure and interfaces required for TinyOS compliant
testbeds.</p>
</div>
<div class="section">
<h1><a id="introduction" name="introduction">1. Introduction</a></h1>
<p>The testing and validation of embedded code on real hardware is key to
successful development of TinyOS applications. Although popular and powerful for
high level analysis, current simulation methods lack in terms of level of
detail and accuracy when used accross multiple system layers where abstractions
and models used are inherently imperfect and impair results. Methods such as
hardware emulation commonly used in embedded system development allow the
execution of code on a hardware platform and therefore can guarantee timing but
are very limited in terms of scalability and often confined to a lab usage only.</p>
<p>Sensor network testbeds try to overcome these deficiencies by allowing to execute
software code under realistic operating conditions on real hardware embedded in
a target environment. This approach allows to generate a level of detail especially
in respect to the whole system (radio. processor, storage, sensors, interfaces)
and the wireless environment (noise, fading, shading, errors, failures) while
maintaining a certain degree of scalability. Remote programming as well as a
feedback of status and debugging information from the nodes using testbed
infrastructure alleviates the need for integrated services in sensor network
applications. Additionally testbeds allow to operate a set of nodes in a
controlled environment, i.e. using temperature variations or a controlled
wireless environment.</p>
<p>A typical testbed is made up of a number of nodes (?do we state amounts here?)
connected to a central resource for control and logging that are deployed in a
physical space (testing area). Typically the central resource is a server with
integrated datalogging capability. Often a web front end serves as a simple control and
visualization resource. For the submission of testing jobs and the analysis of
testing results external tools are attached to the central resource using a
standardized interface. This document serves as a key specification document for
such an interface and its intended usage.</p>
<p>MISSING: Difference of a testbed vs. a desktop test (e.g. single nodes with a
programmer or a simple usb grid)</p>
<p>Examples of currently used sensor network testbeds are MoteLab [<a class="reference" href="#id1">1</a>] and the
Deployment-Support Network [<a class="reference" href="#id2">2</a>].</p>
</div>
<div class="section">
<h1><a id="testbed-usage" name="testbed-usage">2. Testbed Usage</a></h1>
<p>A testbed can serve different purposes depending on the development status and
requirements of a specific project. While this document does not target to restrict
such usage it defines a set of mandatory modes of operation that a testbed must
be able to support:</p>
<p>Modes of Operation:</p>
<ul class="simple">
<li>Single Shot Operation</li>
</ul>
<p>Execute a testing job consisting of an uploading of a specific code image onto a
set of nodes, remote programming of nodes using a testbed resource, the
synchronized start of this software, capture of resulting target response, the
centralized storage and timestamping of all actions and target response, ending
of test execution, notification of a user of the end of test execution, output
of all stored data on demand.</p>
<ul class="simple">
<li>Repetitive (e.g. using continuous integration or for regression testing)</li>
</ul>
<p>A concatenation of single shot testing jobs, that in practice often will be used
with the variation of one or more parameters.</p>
<ul class="simple">
<li>Long Term Operation (Profiling)</li>
</ul>
<p>Other Topics:</p>
<ul class="simple">
<li>Federated Testbeds (in multiple environments)</li>
<li>Access/Resource Arbitration</li>
<li>Scheduling of testing jobs</li>
</ul>
</div>
<div class="section">
<h1><a id="testbed-services" name="testbed-services">3. Testbed Services</a></h1>
<p>Required Services:</p>
<ul class="simple">
<li>identification of target devices (presence, type, hw rev)</li>
<li>programming of target devices</li>
<li>resetting of target devices</li>
<li>logging of target response (UART mandatory, IRQ optional)</li>
<li>versioning/identification of uploaded software</li>
<li>identification/versioning/archiving of testing jobs</li>
<li>testbed status information</li>
<li>identification of testbed services</li>
<li>user authentification</li>
</ul>
<p>Optional:
- power measurements
- stimuli
- distributed scheduling of actions (at nodes)</p>
</div>
<div class="section">
<h1><a id="implementation" name="implementation">4. Implementation</a></h1>
<ul class="simple">
<li>Server, DB/Storage, Interface XMLRPC</li>
<li>Connection fabric</li>
<li>On- and offline logging</li>
<li>Supplied Power</li>
<li>Mote Hardware</li>
</ul>
<p>THINGS TO DISCUSS</p>
<ul class="simple">
<li>?Do we state minimum requirements?</li>
<li>number of nodes</li>
<li>power supply (fixed/batt)</li>
<li>power profiling</li>
<li>power on/off of targets? is simple reset/erasing enough?</li>
<li>feedback channel capabilities (delay, errors, lost packets...)</li>
<li>target control? is control of (writing to) targets required or is it an optional feature?</li>
<li>scheduling of actions (time synched???)</li>
</ul>
</div>
<div class="section">
<h1><a id="reference" name="reference">5. Reference</a></h1>
</div>
<div class="section">
<h1><a id="acknowledgments" name="acknowledgments">6. Acknowledgments</a></h1>
</div>
<div class="section">
<h1><a id="author-s-address" name="author-s-address">7. Author's Address</a></h1>
<div class="line-block">
<div class="line">Jan Beutel</div>
<div class="line">Gloriastr 35</div>
<div class="line">ETH Zurich</div>
<div class="line">8092 Zurich</div>
<div class="line">Switzerland</div>
<div class="line"><br /></div>
<div class="line">phone - +41 44 632 7032</div>
<div class="line"><br /></div>
<div class="line">email - <a class="reference" href="mailto:j.beutel@ieee.org">j.beutel@ieee.org</a></div>
</div>
</div>
<div class="section">
<h1><a id="citations" name="citations">8. Citations</a></h1>
<table class="docutils footnote" frame="void" id="id1" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a name="id1">[1]</a></td><td>G. Werner-Allen, P. Swieskowski, and M. Welsh. MoteLab: A wireless sensor
network testbed. In Proc. 4th Int'l Conf. Information Processing Sensor
Networks (IPSN '05), pages 483-488. IEEE, Piscataway, NJ, April 2005.</td></tr>
</tbody>
</table>
<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">[2]</a></td><td>M. Dyer, J. Beutel, L. Thiele, T. Kalt, P. Oehen, K. Martin, and P. Blum.
Deployment support network - a toolkit for the development of WSNs. In Proc.
4th European Workshop on Sensor Networks (EWSN 2007), volume 4373 of Lecture
Notes in Computer Science, pages 195-211. Springer, Berlin, January 2007.</td></tr>
</tbody>
</table>
</div>
<div class="section">
<h1><a id="appendix-a-example-appendix" name="appendix-a-example-appendix">Appendix A. Example Appendix</a></h1>
<p>This is an example appendix. Appendices begin with the letter A.</p>
</div>
</div>
</body>
</html>
--- NEW FILE: tep127.html ---
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
<title>Packet Link Layer</title>
<meta name="author" content="David Moss, Philip Levis" />
<style type="text/css">
/*
:Author: David Goodger
:Contact: goodger at users.sourceforge.net
:date: $Date: 2007/08/14 18:57:59 $
:version: $Revision: 1.1 $
: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 }
.hidden {
display: none }
a.toc-backref {
text-decoration: none ;
color: black }
blockquote.epigraph {
margin: 2em 5em ; }
dd {
margin-bottom: 0.5em }
div.abstract {
margin: 2em 5em }
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 {
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,
div.warning p.admonition-title {
color: red ;
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 }
div.dedication {
margin: 2em 5em ;
text-align: center ;
font-style: italic }
div.dedication p.topic-title {
font-weight: bold ;
font-style: normal }
div.figure {
margin-left: 2em }
div.footer, div.header {
font-size: smaller }
div.line-block {
display: block ;
margin-top: 1em ;
margin-bottom: 1em }
div.line-block div.line-block {
margin-top: 0 ;
margin-bottom: 0 ;
margin-left: 1.5em }
div.sidebar {
margin-left: 1em ;
border: medium outset ;
padding: 0em 1em ;
background-color: #ffffee ;
width: 40% ;
float: right ;
clear: right }
div.sidebar p.rubric {
font-family: sans-serif ;
font-size: medium }
div.system-messages {
margin: 5em }
div.system-messages h1 {
color: red }
div.system-message {
border: medium outset ;
padding: 1em }
div.system-message p.system-message-title {
color: red ;
font-weight: bold }
div.topic {
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 }
ol.arabic {
list-style: decimal }
ol.loweralpha {
list-style: lower-alpha }
ol.upperalpha {
list-style: upper-alpha }
ol.lowerroman {
list-style: lower-roman }
ol.upperroman {
list-style: upper-roman }
p.attribution {
text-align: right ;
margin-left: 50% }
p.caption {
font-style: italic }
p.credits {
font-style: italic ;
font-size: smaller }
p.label {
white-space: nowrap }
p.rubric {
font-weight: bold ;
font-size: larger ;
color: maroon ;
text-align: center }
p.sidebar-title {
font-family: sans-serif ;
font-weight: bold ;
font-size: larger }
p.sidebar-subtitle {
font-family: sans-serif ;
font-weight: bold }
p.topic-title {
font-weight: bold }
pre.address {
margin-bottom: 0 ;
margin-top: 0 ;
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
}
span.classifier {
font-family: sans-serif ;
font-style: oblique }
span.classifier-delimiter {
font-family: sans-serif ;
font-weight: bold }
span.interpreted {
font-family: sans-serif }
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 }
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 {
list-style-type: none }
</style>
</head>
<body>
<div class="document" id="packet-link-layer">
<h1 class="title">Packet Link Layer</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr class="field"><th class="docinfo-name">TEP:</th><td class="field-body">127</td>
</tr>
<tr class="field"><th class="docinfo-name">Group:</th><td class="field-body">Core Working Group</td>
</tr>
<tr class="field"><th class="docinfo-name">Type:</th><td class="field-body">Documentary</td>
</tr>
<tr><th class="docinfo-name">Status:</th>
<td>Draft</td></tr>
<tr class="field"><th class="docinfo-name">TinyOS-Version:</th><td class="field-body">2.x</td>
</tr>
<tr><th class="docinfo-name">Author:</th>
<td>David Moss, Philip Levis</td></tr>
</tbody>
</table>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">This memo documents a part of TinyOS for the TinyOS Community, and
requests discussion and suggestions for improvements. Distribution
of this memo is unlimited. This memo is in full compliance with
TEP 1.</p>
</div>
<div class="section">
<h1><a id="abstract" name="abstract">Abstract</a></h1>
<p>This TEP describes the behavior and interfaces of the TinyOS 2.x
Packet Link Layer. The Packet Link Layer is an optional radio stack
layer responsible for the reliable delivery of a packet from node to
node. Packet Link provides error correction functionality found in
Layer 2 of the OSI model <a class="footnote-reference" href="#id2" id="id1" name="id1">[1]</a>.</p>
</div>
<div class="section">
<h1><a id="introduction" name="introduction">1. Introduction</a></h1>
<p>In wireless networks, packets are regularly dropped between point to point
communications due to interference or RF range. Correcting these dropped
packets requires the transmitter to first recognize that the packet was
not acknowledged, and then retransmit that packet.</p>
<p>Retransmitting the packet adds its own set of issues. Specifically, the
receiver will receive duplicate packets due to its own dropped acknowledgements.
Logic is therefore required to allow receiver to recognize and dump duplicate
packets, but only after the acknowledgement has been sent back to the
transmitter.</p>
<p>With these two pieces of functionality: the ability for a transmitter to
keep retrying until it gets an acknowledgement and the ability
for a receiver to accept only a single copy of the packet, a Packet Link Layer
can be formed to reliably deliver a single packet from point to point.</p>
</div>
<div class="section">
<h1><a id="design-considerations" name="design-considerations">2. Design Considerations</a></h1>
<div class="section">
<h2><a id="time-spent-retrying-a-delivery" name="time-spent-retrying-a-delivery">2.1 Time spent retrying a delivery</a></h2>
<p>Some networks have different timing characteristics than others.
Consider a person carrying a wireless device while walking in and out
of RF range of another node. In this case, the device may want to
retry the transmission a few times over the course of a few seconds before
declaring the delivery unsuccessful. A robust Packet Link Layer should
allow the developer to specify the amount of time spent retrying as well
as the number of retries to send.</p>
</div>
<div class="section">
<h2><a id="setting-the-packet-sequence-number" name="setting-the-packet-sequence-number">2.2 Setting the packet sequence number</a></h2>
<p>To detect duplicate packets, a sequence number byte can be used
within the packet to verify against previously received
packets. If the source address and sequence number of a newly received
packet matches that of a previously received packet, then the newly received
packet is a duplicate and may be dumped. To prevent the packet sequence
number byte from changing on each retransmission, the byte should be set
at or above the Packet Link Layer and never changed below.</p>
</div>
<div class="section">
<h2><a id="false-acknowledgements" name="false-acknowledgements">2.3 False Acknowledgements</a></h2>
<p>The low levels of a radio stack or the radio chip itself are typically
responsible for generating packet acknowledgements. It has been
observed in some platforms that the radio chip will generate false
auto-acknowledgements. This occurs when the radio receives the packet and
sends an acknowledgement but the microcontroller never gets the message
due to some error. In this case, the transmitter would believe the
packet got to the destination successfully but the receiver would have
no knowledge that a packet was received. Software initiated
acknowledgements prevent this issue by removing the possibility of
false acknowledgements.</p>
</div>
</div>
<div class="section">
<h1><a id="interface" name="interface">3. Interface</a></h1>
<div class="section">
<h2><a id="packetlink-interface" name="packetlink-interface">3.1 PacketLink Interface</a></h2>
<p>The TEP proposes this PacketLink interface::</p>
<pre class="literal-block">
interface PacketLink {
command void setRetries(message_t *msg, uint16_t maxRetries);
command void setRetryDelay(message_t *msg, uint16_t retryDelay);
command uint16_t getRetries(message_t *msg);
command uint16_t getRetryDelay(message_t *msg);
command bool wasDelivered(message_t *msg);
}
</pre>
<p>PacketLinks interface functions:</p>
<blockquote>
<tt class="docutils literal"><span class="pre">setRetries(message_t</span> <span class="pre">*msg,</span> <span class="pre">uint16_t</span> <span class="pre">maxRetries)</span></tt></blockquote>
<ul>
<li><p class="first">Sets the maximum number of times to retry the transmission of the message</p>
<p><tt class="docutils literal"><span class="pre">setRetryDelay(message_t</span> <span class="pre">*msg,</span> <span class="pre">uint16_t</span> <span class="pre">retryDelay)</span></tt></p>
</li>
<li><p class="first">Set the delay, in milliseconds, between each retransmission</p>
<p><tt class="docutils literal"><span class="pre">getRetries(message_t</span> <span class="pre">*msg)</span></tt></p>
</li>
<li><p class="first">Returns the maximum number of retries configured for the given message</p>
<p><tt class="docutils literal"><span class="pre">getRetryDelay(message_t</span> <span class="pre">*msg)</span></tt></p>
</li>
<li><p class="first">Returns the delay, in milliseconds, between each retransmission for the given
message</p>
<p><tt class="docutils literal"><span class="pre">wasDelivered(message_t</span> <span class="pre">*msg)</span></tt></p>
</li>
<li><p class="first">This command may be called after the sendDone() event is signaled. It is the
equivalent of <tt class="docutils literal"><span class="pre">PacketAcknowledgements.wasAcked(message_t</span> <span class="pre">*msg)</span></tt>, so is only
a helper function to make the PacketLink interface easier to use.</p>
</li>
</ul>
</div>
<div class="section">
<h2><a id="expected-behavior" name="expected-behavior">3.2 Expected Behavior</a></h2>
<p>The PacketLink interface is accessed by the application layer before
the packet is passed to the radio stack for transmission. The application
layer will call setRetries(...) and setRetryDelay(...), passing in the
message it is about to send.</p>
<p>The interface MUST configure metadata for the packet to specify the maximum
number of retries and the amount of delay between each retry. When the
send process reaches the Packet Link Layer, it MUST automatically check the
packet's metadata and retry sending the packet as previously configured.</p>
<p>For example, to configure a packet to be retried a maximum of 50 times
over the next 5 seconds, the developer would execute the following commands
before sending the packet::</p>
<pre class="literal-block">
call PacketLink.setRetries(msg, 50);
call PacketLink.setRetryDelay(msg, 100);
</pre>
<p>By placing a 100 ms delay between each retry and allowing up to 50 retries
maximum, the maximum amount of time the message will be transmitted is
(50 * 100) ms, or 5000 ms.</p>
<p>When transmitting a packet configured for reliable delivery to the
broadcast address, the Packet Link Layer SHOULD allow the packet to be
retried. This will let the transmitter know that at least one node
received the message.</p>
</div>
</div>
<div class="section">
<h1><a id="author-s-address" name="author-s-address">4. Author's Address</a></h1>
<div class="line-block">
<div class="line">David Moss</div>
<div class="line">Rincon Research Corporation</div>
<div class="line">101 N. Wilmot, Suite 101</div>
<div class="line">Tucson, AZ 85750</div>
<div class="line"><br /></div>
<div class="line">phone - +1 520 519 3138</div>
<div class="line">email ? <a class="reference" href="mailto:dmm@rincon.com">dmm@rincon.com</a></div>
<div class="line"><br /></div>
<div class="line"><br /></div>
<div class="line">Philip Levis</div>
<div class="line">358 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">phone - +1 650 725 9046</div>
<div class="line">email - <a class="reference" href="mailto:pal@cs.stanford.edu">pal@cs.stanford.edu</a></div>
<div class="line"><br /></div>
</div>
</div>
<div class="section">
<h1><a id="citations" name="citations">5. Citations</a></h1>
<table class="docutils footnote" frame="void" id="id2" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id1" name="id2">[1]</a></td><td>"OSI model" <a class="reference" href="http://en.wikipedia.org/wiki/OSI_model">http://en.wikipedia.org/wiki/OSI_model</a></td></tr>
</tbody>
</table>
</div>
</div>
</body>
</html>
--- NEW FILE: tep128.html ---
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
<title>Platform Independent Non-Volatile Storage Abstractions</title>
<meta name="authors" content="David Moss Junzhao Du Prabal Dutta Deepak Ganesan Kevin Klues Manju Ajay Martin and Gaurav Mathur" />
<style type="text/css">
/*
:Author: David Goodger
:Contact: goodger at users.sourceforge.net
:date: $Date: 2007/08/14 18:58:00 $
:version: $Revision: 1.1 $
: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 }
.hidden {
display: none }
a.toc-backref {
text-decoration: none ;
color: black }
blockquote.epigraph {
margin: 2em 5em ; }
dd {
margin-bottom: 0.5em }
div.abstract {
margin: 2em 5em }
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 {
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,
div.warning p.admonition-title {
color: red ;
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 }
div.dedication {
margin: 2em 5em ;
text-align: center ;
font-style: italic }
div.dedication p.topic-title {
font-weight: bold ;
font-style: normal }
div.figure {
margin-left: 2em }
div.footer, div.header {
font-size: smaller }
div.line-block {
display: block ;
margin-top: 1em ;
margin-bottom: 1em }
div.line-block div.line-block {
margin-top: 0 ;
margin-bottom: 0 ;
margin-left: 1.5em }
div.sidebar {
margin-left: 1em ;
border: medium outset ;
padding: 0em 1em ;
background-color: #ffffee ;
width: 40% ;
float: right ;
clear: right }
div.sidebar p.rubric {
font-family: sans-serif ;
font-size: medium }
div.system-messages {
margin: 5em }
div.system-messages h1 {
color: red }
div.system-message {
border: medium outset ;
padding: 1em }
div.system-message p.system-message-title {
color: red ;
font-weight: bold }
div.topic {
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 }
ol.arabic {
list-style: decimal }
ol.loweralpha {
list-style: lower-alpha }
ol.upperalpha {
list-style: upper-alpha }
ol.lowerroman {
list-style: lower-roman }
ol.upperroman {
list-style: upper-roman }
p.attribution {
text-align: right ;
margin-left: 50% }
p.caption {
font-style: italic }
p.credits {
font-style: italic ;
font-size: smaller }
p.label {
white-space: nowrap }
p.rubric {
font-weight: bold ;
font-size: larger ;
color: maroon ;
text-align: center }
p.sidebar-title {
font-family: sans-serif ;
font-weight: bold ;
font-size: larger }
p.sidebar-subtitle {
font-family: sans-serif ;
font-weight: bold }
p.topic-title {
font-weight: bold }
pre.address {
margin-bottom: 0 ;
margin-top: 0 ;
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
}
span.classifier {
font-family: sans-serif ;
font-style: oblique }
span.classifier-delimiter {
font-family: sans-serif ;
font-weight: bold }
span.interpreted {
font-family: sans-serif }
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 }
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 {
list-style-type: none }
</style>
</head>
<body>
<div class="document" id="platform-independent-non-volatile-storage-abstractions">
<h1 class="title">Platform Independent Non-Volatile Storage Abstractions</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr class="field"><th class="docinfo-name">TEP:</th><td class="field-body">128</td>
</tr>
<tr class="field"><th class="docinfo-name">Group:</th><td class="field-body">Storage Working Group</td>
</tr>
<tr class="field"><th class="docinfo-name">Type:</th><td class="field-body">Documentary</td>
</tr>
<tr><th class="docinfo-name">Status:</th>
<td>DRAFT</td></tr>
<tr class="field"><th class="docinfo-name">TinyOS-Version:</th><td class="field-body">2.x</td>
</tr>
<tr><th class="docinfo-name">Authors:</th>
<td>David Moss
<br />Junzhao Du
<br />Prabal Dutta
<br />Deepak Ganesan
<br />Kevin Klues
<br />Manju
<br />Ajay Martin
<br />and Gaurav Mathur</td></tr>
</tbody>
</table>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">This memo documents a part of TinyOS for the TinyOS Community, and
requests discussion and suggestions for improvements. Distribution
of this memo is unlimited. This memo is in full compliance with
TEP 1.</p>
</div>
<div class="section">
<h1><a id="abstract" name="abstract">Abstract</a></h1>
<p>The storage abstractions proposed by TEP 103 are implemented on a
platform-dependent basis. A version of BlockStorage, ConfigStorage,
and LogStorage were created from the ground up for both the
AT45DB and ST M25P80 flash chips. Looking forward into the further
growth and development of hardware, rebuilding each of these storage
layers for every new flash chip will be time consuming and cause
compatibility issues.</p>
<p>We propose a layer of abstraction to reside between a chip-dependent
flash chip implementation and platform-independent storage
implementations. This abstraction layer should provide methods
to perform basic flash operations (read, write, erase, flush, crc),
as well as provide information about the physical properties of the
flash chip. Efficiency concerns are mitigated by the fact that each
platform-independent abstraction is implemented in a platform-dependent
manner, allowing it to exist on different types of memory such as
NAND flash, NOR flash, and EEPROM. This abstraction layer should
allow one implementation of each storage solution to operate across
many different platforms.</p>
</div>
<div class="section">
<h1><a id="introduction" name="introduction">1. Introduction</a></h1>
<p>The implementations of the BlockStorage, ConfigStorage, and LogStorage
layers described in TEP 103 [1] are platform dependent. Platform-
dependent implementations can cause behavioral and usage differences
as well as compiling problems when attempting to port an application
written on one platform to another. A true abstraction layer would
exhibit the same set of interfaces and no differences in behavior when
implemented across various types of non-volatile memory.</p>
<p>A well defined non-volatile memory abstraction layer should allow core
functionality to work on a variety of platforms without modification.
Some flash chips may provide extra functionality. If a particular
applications on a specific platform wants to take advantage of
extra functionality provided by a flash chip, it still has the opportunity
to access those features directly with the understanding that its
implementation is no longer considered platform-independent.</p>
<div class="section">
<h2><a id="platform-dependent-volume-settings" name="platform-dependent-volume-settings">1.1 Platform-dependent volume settings</a></h2>
<p>Differences exist between the TEP 103 storage implementations
on the AT45DB, ST M25P80, and PXA27X P30 flash chips.</p>
<p>First, volume information is defined using two distinct methods. As
was discussed in TEP 103, an XML file is responsible for the
allocation of flash memory into volumes at compile time. Individual
storage layers can then mount to the defined volumes, which
allows those layers to share the flash memory resource amongst
each other.</p>
<p>The AT45DB implementation running on mica* platforms converts the
information presented in the application's volumes XML file into
information accessible through macros::</p>
<pre class="literal-block">
#ifndef STORAGE_VOLUMES_H
#define STORAGE_VOLUMES_H
enum {
VOLUME_BLOCKTEST,
};
#endif
#if defined(VS)
VS(VOLUME_BLOCKTEST, 1024)
#undef VS
#endif
#if defined(VB)
VB(VOLUME_BLOCKTEST, 0)
#undef VB
#endif
</pre>
<p>The ST M25P80 implementation running on TelosB/Tmote platforms,
on the other hand, converts the information in the volumes XML
file into an array of constants::</p>
<pre class="literal-block">
#ifndef __STORAGE_VOLUME_H__
#define __STORAGE_VOLUME_H__
#include "Stm25p.h"
#define VOLUME_BLOCKTEST 0
static const stm25p_volume_info_t STM25P_VMAP[ 1 ] = {
{ base : 0, size : 4 },
};
#endif
</pre>
<p>Furthermore, the two implementations defined incompatible interfaces for
accessing information about volumes. For example, the AT45DB interface
provides the following::</p>
<pre class="literal-block">
interface At45dbVolume {
command at45page_t remap(at45page_t volumePage);
command at45page_t volumeSize();
}
</pre>
<p>The ST M25P80 interface defines a different interface, which allows
applications to access the volume settings directly through the
stm25p_volume_info_t array::</p>
<pre class="literal-block">
interface Stm25pVolume {
async event volume_id_t getVolumeId();
}
</pre>
<p>Accessing volume information is very platform-dependent.
A single method should be integrated to access volume
settings and non-volatile memory properties across any platform.</p>
<p>Another issue exists with the previous concept of volumes. Any storage
solution that wishes to retain valid data while erasing invalid data
MUST have access to at least two erase units. Circular logging,
configuration storage, variable storage, dictionary storage, file
systems, and more all require a minimum of two erase units to be
implemented effectively. One erase unit can be used to erase
all the invalid data while other erase unit(s) retains any valid data.</p>
<p>Therefore, the minimum allowable volume size should be twice the size
of a single erase unit to effectively support the majority of
storage applications. The XML tools that process and allocate
volumes should prevent a user from defining a volume too small::</p>
<pre class="literal-block">
+------------+--------+------------+-----------+------------+
| | AT45DB | ST M25P | PXA27x | K9K1G08R0B |
+------------+--------+------------+-----------+------------+
| Min.Volume | 512B | 512B-128kB | 128-256kB | 16kB-64kB |
+------------+--------+------------+-----------+------------+
</pre>
</div>
<div class="section">
<h2><a id="platform-dependent-component-signatures" name="platform-dependent-component-signatures">1.2 Platform-dependent component signatures</a></h2>
<p>The storage components' signatures differ across implementations.
For example, the PXA27X P30 flash defines "P30BlockC", "P30ConfigC",
and "P30LogC" in place of "BlockStorageC", "ConfigStorageC", and
"LogStorageC". Furthermore, the BlockStorageC configuration in the
AT45DB implementation takes the following form::</p>
<pre class="literal-block">
generic configuration BlockStorageC(volume_id_t volid) {
provides {
interface BlockWrite;
interface BlockRead;
}
}
</pre>
<p>while the ST M25P80 implementation adds another interface::</p>
<pre class="literal-block">
generic configuration BlockStorageC( volume_id_t volume_id ) {
provides interface BlockRead;
provides interface BlockWrite;
provides interface StorageMap;
}
</pre>
<p>The StorageMap interface on the M25P80 flash chip simply allows
an application to convert a volume-based virtual address into
a physical address on flash. Although it is a good idea, it
is not consistent with other platforms' defined interfaces.</p>
</div>
</div>
<div class="section">
<h1><a id="directstorage" name="directstorage">2. DirectStorage</a></h1>
<div class="section">
<h2><a id="differences-and-advantages" name="differences-and-advantages">3.1 Differences and advantages</a></h2>
<p>The core current BlockStorage, ConfigStorage, and LogStorage
layers can all be implemented on a platform-independent abstraction
layer. Providing an interface that allows direct, unimpeded
access to the memory below while offering information about
the properties of that memory is the first step in doing so.</p>
<p>The DirectStorage interface was created to as part of the answer to this
issue. DirectStorage resembles the BlockStorage interface in many ways,
with two significant exceptions:</p>
<p>1. Erase operation
BlockStorage's behavior erases the entire volume at a time, which may
consist of multiple erase units. DirectStorage allows erases to occur
on per-erase unit basis. Therefore, if only a portion of the volume
needs to be erased, it can.</p>
<p>2. Organization
BlockStorage defines two different interfaces for interacting with the
flash: BlockRead and BlockWrite. These two interfaces are combined
into one interface. The getSize() command provided by the BlockRead
interface is removed and replaced with VolumeSettings, which will be
discussed later. Also, sync()/syncDone() is replaced with
flush/flushDone(), which is responsible for writing any data that
has not already been written to non-volatile memory. Although
the crc() command can technically exist above BlockStorage as
well as DirectStorage, it remains in DirectStorage for its ease
of use.</p>
<p>Finally, layers should have the ability to be added beneath DirectStorage
to further optimize and enable memory operation. For example, the
ST M25P80 flash does not have any on-board RAM buffers, so it
is up to the microcontroller to buffer and flush out data to write units.
This functionality may not be desirable on all applications because
it uses valuable microcontroller resources; therefore, it should
be removable as layers can be added and removed from radio stack
architecture.</p>
<p>Other memory types may require extra support in and underneath
the hood of DirectStorage as well. NAND flash, for example,
requires bad block management and error correction. This functionality
can be implemented without changing the behavior of the DirectStorage
interface above.</p>
</div>
<div class="section">
<h2><a id="directstorage-interface" name="directstorage-interface">3.2 DirectStorage Interface</a></h2>
<p>The DirectStorage interface is described below. Each "addr" variable
is a virtual address, with 0x0 relative to the base address of the
volume. This base address may actually be physically located
somewhere else on the non-volatile memory::</p>
<pre class="literal-block">
interface DirectStorage {
command error_t read(uint32_t addr, void *buf, uint32_t len);
command error_t write(uint32_t addr, void *buf, uint32_t len);
command error_t erase(uint16_t eraseUnitIndex);
command error_t flush();
command error_t crc(uint32_t addr, uint32_t len, uint16_t baseCrc);
event void readDone(uint32_t addr, void *buf, uint32_t len, error_t error);
event void writeDone(uint32_t addr, void *buf, uint32_t len, error_t error);
event void eraseDone(uint16_t eraseUnitIndex, error_t error);
event void flushDone(error_t error);
event void crcDone(uint16_t calculatedCrc, uint32_t addr, uint32_t len, error_t error);
}
</pre>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">read(uint32_t</span> <span class="pre">addr,</span> <span class="pre">void</span> <span class="pre">'*buf',</span> <span class="pre">uint32_t</span> <span class="pre">len);</span></tt></dt>
<dd><ul class="first last simple">
<li>Read 'len' bytes into <tt class="docutils literal"><span class="pre">*buf</span></tt> from the given address</li>
<li>Returns FAIL if the volume is already in use</li>
<li>Signals readDone(...) when complete.</li>
</ul>
</dd>
<dt><tt class="docutils literal"><span class="pre">write(uint32_t</span> <span class="pre">addr,</span> <span class="pre">void</span> <span class="pre">'*buf',</span> <span class="pre">uint32_t</span> <span class="pre">len);</span></tt></dt>
<dd><ul class="first last simple">
<li>Write 'len' bytes from <tt class="docutils literal"><span class="pre">*buf</span></tt> starting at the given address</li>
<li>Returns FAIL if the volume is already in use</li>
<li>Signals writeDone(...) when complete.</li>
</ul>
</dd>
<dt><tt class="docutils literal"><span class="pre">erase(uint16_t</span> <span class="pre">eraseUnitIndex);</span></tt></dt>
<dd><ul class="first last simple">
<li>Erase a single 0-indexed erase unit</li>
<li>Returns FAIL if the volume is already in use</li>
<li>Signals eraseDone(...) when complete.</li>
</ul>
</dd>
<dt>flush()</dt>
<dd><ul class="first last simple">
<li>All data that has been previously written and is not yet located on
non-volatile memory should be immediately stored to non-volatile memory.</li>
<li>Returns FAIL if the operation cannot be completed at this time</li>
<li>Signals flushDone(...) when complete.</li>
</ul>
</dd>
<dt>crc(uint32_t addr, uint32_t len, uint16_t baseCrc);</dt>
<dd><ul class="first last simple">
<li>Calculate the CRC of 'len' bytes starting at the given address, using
the given baseCrc as a seed.</li>
<li>Returns FAIL if the volume is already in use</li>
<li>Signals crcDone(...) when complete.</li>
</ul>
</dd>
</dl>
</div>
<div class="section">
<h2><a id="directmodify-interface" name="directmodify-interface">3.3 DirectModify Interface</a></h2>
<p>Some memory types have the ability to modify their contents without
destroying surrounding data.</p>
<p>The AT45DB NOR-flash, for example, is able to do this because
it has built in RAM buffers coupled with small erase unit sizes.
The physical RAM buffers perform a read-modify-write operation to
effectively change the contents of flash, allowing it to emulate
the behavior of an EEPROM with the speed and efficiency of NOR-flash.</p>
<p>The ATmega128 microcontroller has 4kB of internal EEPROM memory which
can be directly modified. Also, the MSP430 has 256 bytes of internal
NOR-flash memory which is divided into two segments of 128 bytes each.
When implemented properly, this NOR-flash memory can be modified in a
fault-tolerant manner.</p>
<p>The ST M25P80 NOR-flash cannot support modification without sacrificing
significant overhead. It has 16 erase units that are 64kB each,
which is too large to effectively modify bytes.</p>
<p>While not all memories support modification, a unified interface
should exist to interact with memories that do. This interface
should be access with the understanding that applications built
on top may not be portable to all memory types. Also, DirectStorage
and DirectModify are mounted to their own individual volumes, so
DirectModify cannot share its allocated memory resources with
a DirectStorage interface::</p>
<pre class="literal-block">
interface DirectModify {
command error_t modify(uint32_t addr, void *buf, uint32_t len);
command error_t read(uint32_t addr, void *buf, uint32_t len);
command error_t erase(uint16_t eraseUnitIndex);
command error_t flush();
command error_t crc(uint32_t addr, uint32_t len, uint16_t baseCrc);
command bool isSupported();
event void modified(uint32_t addr, void *buf, uint32_t len, error_t error);
event void readDone(uint32_t addr, void *buf, uint32_t len, error_t error);
event void eraseDone(uint16_t eraseUnitIndex, error_t error);
event void flushDone(error_t error);
event void crcDone(uint16_t calculatedCrc, uint32_t addr, uint32_t len, error_t error);
}
</pre>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">modify(uint32_t</span> <span class="pre">addr,</span> <span class="pre">void</span> <span class="pre">*buf,</span> <span class="pre">uint32_t</span> <span class="pre">len)</span></tt></dt>
<dd><ul class="first last simple">
<li>Modify 'len' bytes located on non-volatile memory at the given address,
replacing them with data from the given buffer</li>
<li>Returns FAIL if the volume is already in use</li>
<li>Signals modified(...) when the operation is complete</li>
</ul>
</dd>
<dt><tt class="docutils literal"><span class="pre">read(uint32_t</span> <span class="pre">addr,</span> <span class="pre">void</span> <span class="pre">*buf,</span> <span class="pre">uint32_t</span> <span class="pre">len)</span></tt></dt>
<dd><ul class="first last simple">
<li>Read 'len' bytes into <tt class="docutils literal"><span class="pre">*buf</span></tt> from the given address</li>
<li>Same as DirectStorage.read(...)</li>
<li>Returns FAIL if the volume is already in use</li>
<li>Signals readDone(...) when complete.</li>
</ul>
</dd>
<dt><tt class="docutils literal"><span class="pre">erase(uint16_t</span> <span class="pre">eraseUnitIndex);</span></tt></dt>
<dd><ul class="first last simple">
<li>Erase a single 0-indexed erase unit</li>
<li>Returns FAIL if the volume is already in use</li>
<li>Signals eraseDone(...) when complete.</li>
</ul>
</dd>
<dt><tt class="docutils literal"><span class="pre">flush()</span></tt></dt>
<dd><ul class="first last simple">
<li>All data that has been previously written and is not yet located on
non-volatile memory should be immediately stored to non-volatile memory.</li>
<li>Same behavior as flush() methods found in Java</li>
<li>Returns FAIL if the operation cannot be completed at this time</li>
<li>Signals flushDone(...) when complete.</li>
</ul>
</dd>
<dt><tt class="docutils literal"><span class="pre">crc(uint32_t</span> <span class="pre">addr,</span> <span class="pre">uint32_t</span> <span class="pre">len,</span> <span class="pre">uint16_t</span> <span class="pre">baseCrc);</span></tt></dt>
<dd><ul class="first last simple">
<li>Calculate the CRC of 'len' bytes starting at the given address, using
the given baseCrc as a seed.</li>
<li>Returns FAIL if the volume is already in use</li>
<li>Signals crcDone(...) when complete.</li>
</ul>
</dd>
<dt><tt class="docutils literal"><span class="pre">isSupported()</span></tt></dt>
<dd><ul class="first last simple">
<li>Returns TRUE if DirectModify is available on the current memory type</li>
</ul>
</dd>
</dl>
</div>
<div class="section">
<h2><a id="volumesettings-interface" name="volumesettings-interface">3.4 VolumeSettings Interface</a></h2>
<p>As was shown in Section 1.1, finding information about the current
volume required platform-dependent methods of access. VolumeSettings
provides a unified method of accessing information about the underlying
memory chip and volume settings.</p>
<p>VolumeSettings MUST be implemented separately for DirectStorage and
DirectModify, not only because those abstractions will exist on
separate volumes, but also because the DirectModify interface may
change the available size of the volume to support certain memory
types such as NAND- and NOR-flash::</p>
<pre class="literal-block">
interface VolumeSettings {
command uint32_t getVolumeSize();
command uint32_t getTotalEraseUnits();
command uint32_t getEraseUnitSize();
command uint32_t getTotalWriteUnits();
command uint32_t getWriteUnitSize();
command uint8_t getFillByte();
command uint8_t getEraseUnitSizeLog2();
command uint8_t getWriteUnitSizeLog2();
}
</pre>
<dl class="docutils">
<dt>getVolumeSize()</dt>
<dd><ul class="first last simple">
<li>Returns the size of the volume the DirectStorage layer
is mounted to, in bytes</li>
</ul>
</dd>
<dt>getTotalEraseUnits()</dt>
<dd><ul class="first last simple">
<li>Returns the total number of erase units on the mounted volume</li>
</ul>
</dd>
<dt>getEraseUnitSize()</dt>
<dd><ul class="first last simple">
<li>Returns the size of an individual erase unit, in bytes</li>
</ul>
</dd>
<dt>getTotalWriteUnits()</dt>
<dd><ul class="first last simple">
<li>Returns the total number of write units on the mounted volume</li>
</ul>
</dd>
<dt>getWriteUnitSize()</dt>
<dd><ul class="first last simple">
<li>Returns the size of an individual write unit, in bytes</li>
</ul>
</dd>
<dt>getFillByte()</dt>
<dd><ul class="first last simple">
<li>Returns the default byte value found on the memory after an erase,
which is typically 0xFF</li>
</ul>
</dd>
<dt>getEraseUnitSizeLog2()</dt>
<dd><ul class="first last simple">
<li>Returns the size of an erase unit in Log2 format for ease of
calculations</li>
</ul>
</dd>
<dt>getWriteUnitSizeLog2()</dt>
<dd><ul class="first last simple">
<li>Returns the size of a write unit in Log2 format for ease of
calculations</li>
</ul>
</dd>
</dl>
</div>
</div>
<div class="section">
<h1><a id="author-s-address" name="author-s-address">4. Author's Address</a></h1>
<div class="line-block">
<div class="line">David Moss</div>
<div class="line">Rincon Research Corporation</div>
<div class="line">101 N. Wilmot, Suite 101</div>
<div class="line">Tucson, AZ 85750</div>
<div class="line"><br /></div>
<div class="line">phone - +1 520 519 3138</div>
<div class="line">phone - +1 520 519 3146</div>
<div class="line">email ? <a class="reference" href="mailto:dmm@rincon.com">dmm@rincon.com</a></div>
<div class="line"><br /></div>
<div class="line">Junzhao Du</div>
<div class="line">Contact -</div>
<div class="line"><br /></div>
<div class="line">Prabal Dutta</div>
<div class="line">Contact -</div>
<div class="line"><br /></div>
<div class="line">Deepak Ganesan</div>
<div class="line">Contact -</div>
<div class="line"><br /></div>
<div class="line">Kevin Klues</div>
<div class="line">Contact -</div>
<div class="line"><br /></div>
<div class="line">Manju</div>
<div class="line">Contact -</div>
<div class="line"><br /></div>
<div class="line">Ajay Martin</div>
<div class="line">Contact -</div>
<div class="line"><br /></div>
<div class="line">Gaurav Mathur</div>
<div class="line">Contact -</div>
</div>
</div>
<div class="section">
<h1><a id="citations" name="citations">5. Citations</a></h1>
<table class="docutils footnote" frame="void" id="id1" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a name="id1">[1]</a></td><td>TEP 103: Permanent Data Storage (Flash). <a class="reference" href="http://tinyos.cvs.sourceforge.net/">http://tinyos.cvs.sourceforge.net/</a><em>checkout</em>/tinyos/tinyos-2.x/doc/html/tep103.html</td></tr>
</tbody>
</table>
<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">[2]</a></td><td>Atmel AT45DB041B datasheet. <a class="reference" href="http://www.atmel.com/dyn/resources/prod_documents/DOC1432.PDF">http://www.atmel.com/dyn/resources/prod_documents/DOC1432.PDF</a></td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id3" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a name="id3">[3]</a></td><td>ST M25P80 datasheet. <a class="reference" href="http://www.st.com/stonline/products/literature/ds/8495/m25p80.pdf">http://www.st.com/stonline/products/literature/ds/8495/m25p80.pdf</a></td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id4" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a name="id4">[4]</a></td><td>K9K1G08R0B datasheet. <a class="reference" href="http://www.samsung.com/Products/Semiconductor/NANDFlash/SLC_SmallBlock/1Gbit/K9K1G08R0B/ds_k9k1g08x0b_rev10.pdf">http://www.samsung.com/Products/Semiconductor/NANDFlash/SLC_SmallBlock/1Gbit/K9K1G08R0B/ds_k9k1g08x0b_rev10.pdf</a></td></tr>
</tbody>
</table>
</div>
</div>
</body>
</html>
--- NEW FILE: tep105.html ---
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
<title>Low Power Listening</title>
<meta name="author" content="David Moss, Jonathan Hui, Kevin Klues" />
<style type="text/css">
/*
:Author: David Goodger
:Contact: goodger at users.sourceforge.net
:date: $Date: 2007/08/14 18:58:00 $
:version: $Revision: 1.1 $
: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 }
.hidden {
display: none }
a.toc-backref {
text-decoration: none ;
color: black }
blockquote.epigraph {
margin: 2em 5em ; }
dd {
margin-bottom: 0.5em }
div.abstract {
margin: 2em 5em }
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 {
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,
div.warning p.admonition-title {
color: red ;
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 }
div.dedication {
margin: 2em 5em ;
text-align: center ;
font-style: italic }
div.dedication p.topic-title {
font-weight: bold ;
font-style: normal }
div.figure {
margin-left: 2em }
div.footer, div.header {
font-size: smaller }
div.line-block {
display: block ;
margin-top: 1em ;
margin-bottom: 1em }
div.line-block div.line-block {
margin-top: 0 ;
margin-bottom: 0 ;
margin-left: 1.5em }
div.sidebar {
margin-left: 1em ;
border: medium outset ;
padding: 0em 1em ;
background-color: #ffffee ;
width: 40% ;
float: right ;
clear: right }
div.sidebar p.rubric {
font-family: sans-serif ;
font-size: medium }
div.system-messages {
margin: 5em }
div.system-messages h1 {
color: red }
div.system-message {
border: medium outset ;
padding: 1em }
div.system-message p.system-message-title {
color: red ;
font-weight: bold }
div.topic {
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 }
ol.arabic {
list-style: decimal }
ol.loweralpha {
list-style: lower-alpha }
ol.upperalpha {
list-style: upper-alpha }
ol.lowerroman {
list-style: lower-roman }
ol.upperroman {
list-style: upper-roman }
p.attribution {
text-align: right ;
margin-left: 50% }
p.caption {
font-style: italic }
p.credits {
font-style: italic ;
font-size: smaller }
p.label {
white-space: nowrap }
p.rubric {
font-weight: bold ;
font-size: larger ;
color: maroon ;
text-align: center }
p.sidebar-title {
font-family: sans-serif ;
font-weight: bold ;
font-size: larger }
p.sidebar-subtitle {
font-family: sans-serif ;
font-weight: bold }
p.topic-title {
font-weight: bold }
pre.address {
margin-bottom: 0 ;
margin-top: 0 ;
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
}
span.classifier {
font-family: sans-serif ;
font-style: oblique }
span.classifier-delimiter {
font-family: sans-serif ;
font-weight: bold }
span.interpreted {
font-family: sans-serif }
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 }
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 {
list-style-type: none }
</style>
</head>
<body>
<div class="document" id="low-power-listening">
<h1 class="title">Low Power Listening</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr class="field"><th class="docinfo-name">TEP:</th><td class="field-body">105</td>
</tr>
<tr class="field"><th class="docinfo-name">Group:</th><td class="field-body">Core Working Group</td>
</tr>
<tr class="field"><th class="docinfo-name">Type:</th><td class="field-body">Documentary</td>
</tr>
<tr><th class="docinfo-name">Status:</th>
<td>Final</td></tr>
<tr class="field"><th class="docinfo-name">TinyOS-Version:</th><td class="field-body">2.x</td>
</tr>
<tr><th class="docinfo-name">Author:</th>
<td>David Moss, Jonathan Hui, Kevin Klues</td></tr>
</tbody>
</table>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">This memo documents a part of TinyOS for the TinyOS Community, and
requests discussion and suggestions for improvements. Distribution
of this memo is unlimited. This memo is in full compliance with
TEP 1.</p>
</div>
<div class="section">
<h1><a id="abstract" name="abstract">Abstract</a></h1>
<p>This TEP describes the structure and implementation of the TinyOS 2.x
link layer abstractions. The architecture is designed to allow each radio
type to implement its own low power strategy within the Hardware Adaptation
Layer (HAL), while maintaining a common application interface. The
history and strategies for low power listening are discussed, as well
as expected behavior and implementation recommendations.</p>
</div>
<div class="section">
<h1><a id="introduction" name="introduction">1. Introduction</a></h1>
<p>Asynchronous low power listening is a strategy used to duty cycle
the radio while ensuring reliable message delivery since TinyOS 1.x
<a class="citation-reference" href="#mica2" id="id1" name="id1">[MICA2]</a>.</p>
<p>While a CC1000 or CC2420 radio is turned on and listening, it can
actively consume anywhere between 7.4 to 18.8 mA on top of the power
consumed by other components in the system <a class="citation-reference" href="#cc1000" id="id2" name="id2">[CC1000]</a>,[CC2420]_.
This can rapidly deplete batteries. In the interest of extending
battery lifetime, it is best to duty cycle the radio on and off to
prevent this idle waste of energy. In an asychronous low power
message delivery scheme, the duty cycling receiver node saves the
most energy by performing short, periodic receive checks. The power
consumption burden is then placed on the transmitter node, which
must modulate the radio channel long enough for the recipient?s
receive check to detect an incoming message. A synchronous low
power message delivery scheme takes this idea a step further by
allowing the transmitter to only transmit when it knows the
destination node is performing a receive check.</p>
</div>
<div class="section">
<h1><a id="background" name="background">2. Background</a></h1>
<div class="section">
<h2><a id="early-tinyos-1-x-cc1000-low-power-listening-implementation" name="early-tinyos-1-x-cc1000-low-power-listening-implementation">2.1 Early TinyOS 1.x CC1000 Low Power Listening Implementation</a></h2>
<p>TinyOS 1.x introduced low power listening on the CC1000 radio, but
never introduced a similar scheme for the CC2420 radio in the baseline.
The CC1000 radio had the following low power listening commands,
provided directly by CC1000RadioIntM::</p>
<pre class="literal-block">
command result_t SetListeningMode(uint8_t power);
command uint8_t GetListeningMode();
command result_t SetTransmitMode(uint8_t power);
command uint8_t GetTransmitMode();
</pre>
<p>The uint8_t 'power' mode parameter was initially defined as follows::</p>
<pre class="literal-block">
//Original CC1000 Low Power Listening Modes
Power Mode 0 = 100% duty cycle
Power Mode 1 = 35.5% duty cycle
Power Mode 2 = 11.5% duty cycle
Power Mode 3 = 7.53% duty cycle
Power Mode 4 = 5.61% duty cycle
Power Mode 5 = 2.22% duty cycle
Power Mode 6 = 1.00% duty cycle
</pre>
<p>There were several issues with this interface and implementation.
First, setting up a low power network was cumbersome. The low power
listening commands had to be directly wired through CC1000RadioIntM,
and called while the radio was not performing any transactions.
Second, each node in a network was expected to have the same radio
power mode. Finally, the pre-programmed duty cycles were not linear
and offered a very limited selection of options.</p>
<p>In this low power listening implementation, the transmitter mote would
transmit a packet that consisted of an extremely long preamble. This
preamble was long enough to span a complete receive check period. On
the receiver?s end, the radio would turn on and read bits from the
radio. If a preamble sequence was detected in the incoming bits, the
receiver?s radio would remain on for the full duration of the
transmitter?s preamble and wait for the packet at the end.</p>
<p>This original low power listening scheme was rather inefficient on both
the transmit and receive end. On the receive end, turning on the radio
completely and reading in bits typically cost much more energy than
necessary. The transmitter's long preamble could end up costing both
nodes to have their radios on much longer than required, sending and
receiving useless preamble bits.</p>
</div>
<div class="section">
<h2><a id="cc1000-pulse-check-implementation" name="cc1000-pulse-check-implementation">2.2 CC1000 Pulse Check Implementation</a></h2>
<p>Joe Polastre and Jason Hill developed a better receive check
implementation in the CC1000 ?Pulse Check? radio stack for TinyOS 1.x,
while maintaining the same interface. This implementation took advantage
of a Clear Channel Assessment (CCA) to determine if a transmitter was
nearby.</p>
<p>In this implementation, the CC1000 radio did not have to be turned on
completely, so it consumed less maximum current than the previous
implementation. The radio on-time was also significantly reduced, only
turning on long enough for a single ADC conversion to occur. If energy
was detected on the channel after the first ADC conversion, subsequent
ADC conversions would verify this before committing to turning the
radio receiver on completely.</p>
<p>In this implementation the receiver's efficiency dramatically improved,
but the transmitter still sent a long, inefficient preamble. Energy
consumption used to transmit messages was still high, while throughput
was still low.</p>
</div>
<div class="section">
<h2><a id="possible-improvements" name="possible-improvements">2.3 Possible Improvements</a></h2>
<p>Low power listening is a struggle between minimizing energy efficiency
and maximizing throughput. In an asynchronous low power listening
scheme, several improvements can be made over earlier implementations.
One improvement that could have been made to earlier implementations is
to remove the long transmitted preamble and send many smaller messages
instead. For example, the transmitter could send the same message over
and over again for the duration of the receiver's receive check period.
The receiver could wake up and see that another node is transmitting,
receive a full message, and finally send back an acknowledgement for that
message. The transmitter would see the acknowledgement and stop
transmitting early, so both nodes can perform some high speed transaction
or go back to sleep. Useless preamble bits are minimized while useful
packet information is maximized. Incidentally, this is a good strategy
for CC2420 low power listening. This strategy certainly improves energy
efficiency and throughput, but further improvements may be possible by
employing a synchronous delivery method on top of this type of
asynchronous low power listening scheme.</p>
<p>Improvements can also be made to the original low power listening
interfaces. For example, instead of pre-programming power modes and
duty cycles, a low power listening interface should allow the developer
the flexibility to deploy a network of nodes with whatever duty cycle
percentage or sleep time desired for each individual node. Nodes with
different receive check periods should still have the ability to
reliably communicate with each other with little difficulty.</p>
</div>
</div>
<div class="section">
<h1><a id="interfaces" name="interfaces">3. Interfaces</a></h1>
</div>
<div class="section">
<h1><a id="low-power-listening-interface" name="low-power-listening-interface">3.1 Low Power Listening Interface</a></h1>
<p>The LowPowerListening interface MUST be provided for each radio by the
platform independent ActiveMessageC configuration.</p>
<p>In some implementations, low power listening may have an option to
compile into the radio stack for memory footprint reasons. If low
power listening is not compiled in with the stack, calls to
LowPowerListening MUST be handled by a dummy implementation.</p>
<p>The TEP proposes this LowPowerListening interface::</p>
<pre class="literal-block">
interface LowPowerListening {
command void setLocalSleepInterval(uint16_t sleepIntervalMs);
command uint16_t getLocalSleepInterval();
command void setLocalDutyCycle(uint16_t dutyCycle);
command uint16_t getLocalDutyCycle();
command void setRxSleepInterval(message_t *msg, uint16_t sleepIntervalMs);
command uint16_t getRxSleepInterval(message_t *msg);
command void setRxDutyCycle(message_t *msg, uint16_t dutyCycle);
command uint16_t getRxDutyCycle(message_t *msg);
command uint16_t dutyCycleToSleepInterval(uint16_t dutyCycle);
command uint16_t sleepIntervalToDutyCycle(uint16_t sleepInterval);
}
</pre>
<dl class="docutils">
<dt>setLocalSleepInterval(uint16_t sleepIntervalMs)</dt>
<dd><ul class="first last simple">
<li>Sets the local node?s radio sleep interval, in milliseconds.</li>
</ul>
</dd>
<dt>getLocalSleepInterval()</dt>
<dd><ul class="first last simple">
<li>Retrieves the local node?s sleep interval, in milliseconds. If duty cycle percentage was originally set, it is automatically converted to a sleep interval.</li>
</ul>
</dd>
<dt>setLocalDutyCycle(uint16_t dutyCycle)</dt>
<dd><ul class="first last simple">
<li>Set the local node?s duty cycle percentage, in units of [percentage*100].</li>
</ul>
</dd>
<dt>getLocalDutyCycle()</dt>
<dd><ul class="first last simple">
<li>Retrieves the local node?s duty cycle percentage. If sleep interval in milliseconds was originally set, it is automatically converted to a duty cycle percentage.</li>
</ul>
</dd>
<dt>setRxSleepInterval(message_t *msg, uint16_t sleepIntervalMs)</dt>
<dd><ul class="first last simple">
<li>The given message will soon be sent to a low power receiver. The sleepIntervalMs is the sleep interval of that low power receiver, in milliseconds. When sent, the radio stack will automatically transmit the message so as to be detected by the low power receiver.</li>
</ul>
</dd>
<dt>getRxSleepInterval(message_t *msg)</dt>
<dd><ul class="first last simple">
<li>Retrieves the message destination?s sleep interval. If a duty cycle was originally set for the outgoing message, it is automatically converted to a sleep interval.</li>
</ul>
</dd>
<dt>setRxDutyCycle(message_t *msg, uint16_t dutyCycle)</dt>
<dd><ul class="first last simple">
<li>The given message will soon be sent to a low power receiver. The dutyCycle is the duty cycle percentage, in units of [percentage*100], of that low power receiver. When sent, the radio stack will automatically transmit the message so as to be detected by the low power receiver.</li>
</ul>
</dd>
<dt>getRxDutyCycle(message_t *msg)</dt>
<dd><ul class="first last simple">
<li>Retrieves the message destination?s duty cycle percentage. If a sleep interval was originally set for the outgoing message, it is automatically converted to a duty cycle percentage.</li>
</ul>
</dd>
<dt>dutyCycleToSleepInterval(uint16_t dutyCycle)</dt>
<dd><ul class="first last simple">
<li>Converts the given duty cycle percentage to a sleep interval in milliseconds.</li>
</ul>
</dd>
<dt>sleepIntervalToDutyCycle(uint16_t sleepInterval)</dt>
<dd><ul class="first last simple">
<li>Converts the given sleep interval in milliseconds to a duty cycle percentage.</li>
</ul>
</dd>
</dl>
<div class="section">
<h2><a id="split-control-behaviour" name="split-control-behaviour">3.2 Split Control Behaviour</a></h2>
<p>Low power listening MUST be enabled and disabled through the radio?s
standard SplitControl interface, returning exactly one SplitControl
event upon completion. While the radio is duty cycling, it MUST NOT
alert the application layer each time the radio turns on and off to
perform a receive check or send a message.</p>
</div>
<div class="section">
<h2><a id="send-interface-behaviour" name="send-interface-behaviour">3.3 Send Interface Behaviour</a></h2>
<p>Attempts to send a message before SplitControl.start() has been called
SHOULD return EOFF, signifying the radio has not been enabled. When
SplitControl.start() has been called by the application layer, calls
to Send MUST turn the radio on automatically if the radio is currently
off due to duty cycling. If a message is already in the process of
being sent, multiple calls to Send should return FAIL.</p>
<p>The Send.sendDone(?) event SHOULD signal SUCCESS upon the successful
completion of the message delivery process, regardless if any mote
actually received the message.</p>
</div>
<div class="section">
<h2><a id="receive-interface-behaviour" name="receive-interface-behaviour">3.4 Receive Interface Behaviour</a></h2>
<p>Upon the successful reception of a message, the low power receive event
handler SHOULD drop duplicate messages sent to the broadcast address.
For example, the CC2420 implementation can perform this by checking
the message_t?s dsn value, where each dsn value is identical for every
message used in the delivery.</p>
<p>After the first successful message reception, the receiver?s radio
SHOULD stay on for a brief period of time to allow any further
transactions to occur at high speed. If no subsequent messages are
detected going inbound or outbound after some short delay, the radio
MUST continue duty cycling as configured.</p>
</div>
</div>
<div class="section">
<h1><a id="low-power-listening-message-t-metadata" name="low-power-listening-message-t-metadata">4. Low Power Listening message_t Metadata</a></h1>
<p>To store the extra 16-bit receiver low power listening value, the radio
stack?s message_t footer MUST contain a parameter to store the message
destination?s receive check sleep interval in milliseconds or duty cycle
percentage. For example, the low power listening CC2420 message_t footer
stores the message's receive check interval in milliseconds, as shown
below <a class="citation-reference" href="#tep111" id="id3" name="id3">[TEP111]</a>.:</p>
<pre class="literal-block">
typedef nx_struct cc2420_metadata_t {
nx_uint8_t tx_power;
nx_uint8_t rssi;
nx_uint8_t lqi;
nx_bool crc;
nx_bool ack;
nx_uint16_t time;
nx_uint16_t rxInterval;
} cc2420_metadata_t;
</pre>
</div>
<div class="section">
<h1><a id="recommendations-for-hal-implementation" name="recommendations-for-hal-implementation">5. Recommendations for HAL Implementation</a></h1>
<p>In the interest of minimizing energy while maximizing throughput, it
is RECOMMENDED that any asynchronous low power listening implementation
use clear channel assessment methods to determine the presence of a
nearby transmitter. It is also RECOMMENDED that the transmitter send
duplicate messages continuously with minimum or no backoff period instead
of one long message. Removing backoffs on a continuous send delivery
scheme will allow the channel to be modulated sufficiently for a receiver
to quickly detect; furthermore, enabling acknowledgements on each
outgoing duplicate packet will allow the transmit period to be cut short
based on when the receiver actually receives the message.</p>
<p>Asynchronous low power listening requires some memory overhead, so
sometimes it is better to leave the added architecture out when it is
not required. When it is feasible to do so, it is RECOMMENDED that
the preprocessor variable LOW_POWER_LISTENING be defined when low
power listening functionality is to be compiled in with the radio stack,
and not defined when low power listening functionality shouldn?t exist.</p>
<p>It is RECOMMENDED that the radio on-time for actual receive checks be a
measured value to help approximate the duty cycle percentage.</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">David Moss</div>
<div class="line">Rincon Research Corporation</div>
<div class="line">101 N. Wilmot, Suite 101</div>
<div class="line">Tucson, AZ 85750</div>
<div class="line"><br /></div>
<div class="line">phone - +1 520 519 3138</div>
<div class="line">email ? <a class="reference" href="mailto:dmm@rincon.com">dmm@rincon.com</a></div>
<div class="line"><br /></div>
<div class="line">Jonathan Hui</div>
<div class="line">657 Mission St. Ste. 600</div>
<div class="line">Arched Rock Corporation</div>
<div class="line">San Francisco, CA 94105-4120</div>
<div class="line"><br /></div>
<div class="line">phone - +1 415 692 0828</div>
<div class="line">email - <a class="reference" href="mailto:jhui@archedrock.com">jhui@archedrock.com</a></div>
<div class="line"><br /></div>
<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>
</div>
<div class="section">
<h1><a id="citations" name="citations">7. Citations</a></h1>
<table class="docutils citation" frame="void" id="mica2" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id1" name="mica2">[MICA2]</a></td><td>"MICA2 Radio Stack for TinyOS." <a class="reference" href="http://www.tinyos.net/tinyos-1.x/doc/mica2radio/CC1000.html">http://www.tinyos.net/tinyos-1.x/doc/mica2radio/CC1000.html</a></td></tr>
</tbody>
</table>
<table class="docutils citation" frame="void" id="tep111" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id3" name="tep111">[TEP111]</a></td><td>TEP 111: message_t.</td></tr>
</tbody>
</table>
<table class="docutils citation" frame="void" id="cc1000" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id2" name="cc1000">[CC1000]</a></td><td>TI/Chipcon CC1000 Datasheet. <a class="reference" href="http://www.chipcon.com/files/CC1000_Data_Sheet_2_2.pdf">http://www.chipcon.com/files/CC1000_Data_Sheet_2_2.pdf</a></td></tr>
</tbody>
</table>
<table class="docutils citation" frame="void" id="cc2420" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a name="cc2420">[CC2420]</a></td><td>TI/Chipcon CC2420 Datasheet. <a class="reference" href="http://www.chipcon.com/files/CC2420_Data_Sheet_1_3.pdf">http://www.chipcon.com/files/CC2420_Data_Sheet_1_3.pdf</a></td></tr>
</tbody>
</table>
</div>
</div>
</body>
</html>
--- NEW FILE: tep129.html ---
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
<title>Basic Platform Independent Non-Volatile Storage Layers</title>
<meta name="authors" content="David Moss Junzhao Du Prabal Dutta Deepak Ganesan Kevin Klues Manju Ajay Martin and Gaurav Mathur" />
<style type="text/css">
/*
:Author: David Goodger
:Contact: goodger at users.sourceforge.net
:date: $Date: 2007/08/14 18:58:00 $
:version: $Revision: 1.1 $
: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 }
.hidden {
display: none }
a.toc-backref {
text-decoration: none ;
color: black }
blockquote.epigraph {
margin: 2em 5em ; }
dd {
margin-bottom: 0.5em }
div.abstract {
margin: 2em 5em }
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 {
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,
div.warning p.admonition-title {
color: red ;
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 }
div.dedication {
margin: 2em 5em ;
text-align: center ;
font-style: italic }
div.dedication p.topic-title {
font-weight: bold ;
font-style: normal }
div.figure {
margin-left: 2em }
div.footer, div.header {
font-size: smaller }
div.line-block {
display: block ;
margin-top: 1em ;
margin-bottom: 1em }
div.line-block div.line-block {
margin-top: 0 ;
margin-bottom: 0 ;
margin-left: 1.5em }
div.sidebar {
margin-left: 1em ;
border: medium outset ;
padding: 0em 1em ;
background-color: #ffffee ;
width: 40% ;
float: right ;
clear: right }
div.sidebar p.rubric {
font-family: sans-serif ;
font-size: medium }
div.system-messages {
margin: 5em }
div.system-messages h1 {
color: red }
div.system-message {
border: medium outset ;
padding: 1em }
div.system-message p.system-message-title {
color: red ;
font-weight: bold }
div.topic {
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 }
ol.arabic {
list-style: decimal }
ol.loweralpha {
list-style: lower-alpha }
ol.upperalpha {
list-style: upper-alpha }
ol.lowerroman {
list-style: lower-roman }
ol.upperroman {
list-style: upper-roman }
p.attribution {
text-align: right ;
margin-left: 50% }
p.caption {
font-style: italic }
p.credits {
font-style: italic ;
font-size: smaller }
p.label {
white-space: nowrap }
p.rubric {
font-weight: bold ;
font-size: larger ;
color: maroon ;
text-align: center }
p.sidebar-title {
font-family: sans-serif ;
font-weight: bold ;
font-size: larger }
p.sidebar-subtitle {
font-family: sans-serif ;
font-weight: bold }
p.topic-title {
font-weight: bold }
pre.address {
margin-bottom: 0 ;
margin-top: 0 ;
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
}
span.classifier {
font-family: sans-serif ;
font-style: oblique }
span.classifier-delimiter {
font-family: sans-serif ;
font-weight: bold }
span.interpreted {
font-family: sans-serif }
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 }
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 {
list-style-type: none }
</style>
</head>
<body>
<div class="document" id="basic-platform-independent-non-volatile-storage-layers">
<h1 class="title">Basic Platform Independent Non-Volatile Storage Layers</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr class="field"><th class="docinfo-name">TEP:</th><td class="field-body">129</td>
</tr>
<tr class="field"><th class="docinfo-name">Group:</th><td class="field-body">Storage Working Group</td>
</tr>
<tr class="field"><th class="docinfo-name">Type:</th><td class="field-body">Documentary</td>
</tr>
<tr><th class="docinfo-name">Status:</th>
<td>DRAFT</td></tr>
<tr class="field"><th class="docinfo-name">TinyOS-Version:</th><td class="field-body">2.x</td>
</tr>
<tr><th class="docinfo-name">Authors:</th>
<td>David Moss
<br />Junzhao Du
<br />Prabal Dutta
<br />Deepak Ganesan
<br />Kevin Klues
<br />Manju
<br />Ajay Martin
<br />and Gaurav Mathur</td></tr>
</tbody>
</table>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">This memo documents a part of TinyOS for the TinyOS Community, and
requests discussion and suggestions for improvements. Distribution
of this memo is unlimited. This memo is in full compliance with
TEP 1.</p>
</div>
<div class="section">
<h1><a id="abstract" name="abstract">Abstract</a></h1>
<p>The storage abstractions proposed by TEP 103 are implemented on a
platform-dependent basis. A version of BlockStorage, ConfigStorage,
and LogStorage were created from the ground up for both the
AT45DB and ST M25P80 flash chips. Looking forward into the further
growth and development of hardware, rebuilding each of these storage
layers for every new flash chip will be time consuming and cause
compatibility issues.</p>
<p>We propose versions of BlockStorage, ConfigStorage, and LogStorage
be built on top of a platform-independent interface. This would
allow one version of each to exist on multiple platforms.
Platform-independent implementation concepts are discussed
along with recommended solutions, and changes are proposed to the
interfaces defined by TEP 103.</p>
</div>
<div class="section">
<h1><a id="introduction" name="introduction">1. Introduction</a></h1>
<p>The implementations of the BlockStorage, ConfigStorage, and LogStorage
layers described in TEP 103 <a class="footnote-reference" href="#id6" id="id1" name="id1">[1]</a> are platform-dependent. Platform-
dependent implementations can cause behavioral and usage differences
as well as compiling problems when attempting to port an application
written on one platform to another.</p>
<p>Building upon the DirectStorage, DirectModify, and VolumeSettings
abstraction layers defined in TEP128 <a class="footnote-reference" href="#id7" id="id2" name="id2">[2]</a>, the three basic storage
solutions can be implemented in a platform-independent manner.
This requires combining all properties of various memory types,
which aids in the creation of platform-independent storage solutions.
Behavioral differences are minimized, and applications using
the platform-independent storage layers can expect to work the
same way on different types of non-volatile memory.</p>
</div>
<div class="section">
<h1><a id="implementing-a-platform-independent-blockstorage" name="implementing-a-platform-independent-blockstorage">2. Implementing a platform-independent BlockStorage</a></h1>
<p>The DirectStorage interface initially stemmed from the BlockStorage
interface with differences in interfaces, organization, and
erase behavior, as well as the additional VolumeSettings interface.
To implement BlockStorage on DirectStorage, the erase behavior must
be extended to erase the entire volume instead of an individual erase unit.</p>
<p>VolumeSettings can first be accessed to determine the total number of erase
units in the currently mounted volume. Looping through these erase units,
DirectStorage is accessed to erase() each one. At the end of the erase
operation, the entire volume is set back to fill bytes (0xFF).</p>
<div class="section">
<h2><a id="improved-blockstorage-interface" name="improved-blockstorage-interface">2.1 Improved BlockStorage interface</a></h2>
<p>Previous BlockStorage interfaces were divided into BlockRead and
BlockWrite. This was found to be cumbersome because applications
typically required access to both interfaces. The getSize() is
unnecessary due to the addition of the VolumeSettings interface.
All other BlockStorage commands can simply pass through to their
respective DirectStorage functions. This TEP proposes the following
unified BlockStorage interface::</p>
<pre class="literal-block">
interface BlockStorage {
command error_t read(uint32_t addr, void *buf, uint32_t len);
command error_t write(uint32_t addr, void *buf, uint32_t len);
command error_t erase();
command error_t flush();
command error_t crc(uint32_t addr, uint32_t len, uint16_t baseCrc);
event void readDone(uint32_t addr, void *buf, uint32_t len, error_t error);
event void writeDone(uint32_t addr, void *buf, uint32_t len, error_t error);
event void eraseDone(error_t error);
event void flushDone(error_t error);
event void crcDone(uint16_t calculatedCrc, uint32_t addr, uint32_t len, error_t error);
}
</pre>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">read(uint32_t</span> <span class="pre">addr,</span> <span class="pre">void</span> <span class="pre">*buf,</span> <span class="pre">uint32_t</span> <span class="pre">len);</span></tt></dt>
<dd><ul class="first last simple">
<li>Read 'len' bytes into <tt class="docutils literal"><span class="pre">*buf</span></tt> from the given address</li>
<li>Returns FAIL if the request cannot be handled</li>
<li>Signals readDone(...) when complete.</li>
</ul>
</dd>
<dt><tt class="docutils literal"><span class="pre">write(uint32_t</span> <span class="pre">addr,</span> <span class="pre">void</span> <span class="pre">*buf,</span> <span class="pre">uint32_t</span> <span class="pre">len);</span></tt></dt>
<dd><ul class="first last simple">
<li>Write 'len' bytes from <tt class="docutils literal"><span class="pre">*buf</span></tt> starting at the given address</li>
<li>Returns FAIL if the request cannot be handled</li>
<li>Signals writeDone(...) when complete.</li>
</ul>
</dd>
<dt>erase();</dt>
<dd><ul class="first last simple">
<li>Erase the entire volume</li>
<li>Returns FAIL if the request cannot be handled</li>
<li>Signals eraseDone(...) when complete.</li>
</ul>
</dd>
<dt>flush()</dt>
<dd><ul class="first last simple">
<li>All data that has been previously written and is not yet located on
non-volatile memory should be immediately stored to non-volatile memory.</li>
<li>Returns FAIL if the operation cannot be completed at this time</li>
<li>Signals flushDone(...) when complete.</li>
</ul>
</dd>
<dt>crc(uint32_t addr, uint32_t len, uint16_t baseCrc);</dt>
<dd><ul class="first last simple">
<li>Calculate the CRC of 'len' bytes starting at the given address, using
the given baseCrc as a seed.</li>
<li>Returns FAIL if the request cannot be handled</li>
<li>Signals crcDone(...) when complete.</li>
</ul>
</dd>
</dl>
</div>
</div>
<div class="section">
<h1><a id="implementing-a-platform-independent-logstorage" name="implementing-a-platform-independent-logstorage">3. Implementing a platform-independent LogStorage</a></h1>
<p>As described in TEP 103, logging can be implemented using two
different methods: linear and circular. A linear log fills up
its volume and stops when it comes to the end. A circular log allows
at least half of its volume to remain valid while continuing to write
the other half. As previously described, this requires at least
two erase units to be effective.</p>
<p>Both logging behaviors can be implemented using the same code.
A flag for linear log behavior prevents the logger from
freeing up an erase unit in which to continue writing.</p>
<p>It should also be noted that the use of a circular log mandates
the use of at least two erase units on the volume. As discussed
in TEP128 <a class="footnote-reference" href="#id7" id="id3" name="id3">[2]</a>, forcing volumes to contain at least two erase
units solves this issue.</p>
<div class="section">
<h2><a id="logstorage-boot-behavior" name="logstorage-boot-behavior">3.1 LogStorage Boot Behavior</a></h2>
<p>In the previous LogStorage implementations, reboots cause data to be
lost or overwritten because the beginning and ends of the log were
never located. Preventing previously stored data from being lost
or overwritten after reboot is critical for the successful use and
integration of logging storage components within a practical,
deployable system.</p>
<p>A method is required on boot to locate the first memory location to
read from as well as the next available memory location to write to.
Although one method is to use microcontroller user memory
to store the information, the goal is to avoid relying on external
support due to cross-platform compatibility reasons. Luckily, storing
and updating this information on the volume itself is easier than
it seems.</p>
<p>Flash cannot overwrite areas of memory it has already written without
performing a read-modify-write operation, and this operation is
not supported on many flash types. Regardless of whether the memory
type can support modifications, all types of memory - including EEPROM -
should take wear-leveling into account. Combining these properties,
it is possible to design a method of maintaining and updating logging
start and stop information in a cross-platform compatible manner.</p>
<p>The method of locating logging properties on boot is simplified by making
entries aligned to erase unit boundaries, never allowing a single
entry to bridge erase units. This also prevents invalid entries
from being created as a result of erasing an erase unit.</p>
<p>To find the first available write address to add new log entries,
the first header entry on each erase unit is evaluated to find the
greatest 32-bit "cookie" value that is not fill-bytes (0xFFFFFFFF).
The erase unit with the largest value contains the newest data.
Next, each entry in that erase unit can be iterated through by reading
each header and skipping the length of the header + data, until a
header with the value 0xFFFFFFFF is located. The address of this
location is the first available address to write.</p>
<p>Finding the first available address for reading involves the same process.
The first header entry on each erase unit is evaluated to find the lowest
32-bit "cookie" value. The entry with the lowest value is the beginning
of the log.</p>
<p>The first entry to read from and last address to write to MUST be
located on platform boot.</p>
</div>
<div class="section">
<h2><a id="appending-log-entries" name="appending-log-entries">3.2 Appending log entries</a></h2>
<p>The previous M25P80 log storage implementation is a good place to start.
In it, each write consists of a 32-bit header "cookie" and the data to
be appended to the log. Locating the beginning of the log is therefore
a matter of finding the lowest header cookie value. If this were to be
implemented so entries align with erase unit boundaries, only the
first header of each erase unit needs to be checked for the lowest value.</p>
<p>32-bits leaves plenty of space to increment log entry values for.
If the log were to append one chunk of data every second, it would
take 136.1 years before the 32-bit header recycles to 0 and causes
an issue in properly locating the first and last log entries.
This is well beyond the expected lifetime of a deployed system.</p>
<p>Each header entry can provide additional support for every
data entry by allowing it to track the amount of appended data as well
as an optional 8-bit CRC to verify the data is valid::</p>
<pre class="literal-block">
typedef struct log_header_t {
uint32_t cookie;
uint8_t length;
uint8_t crc;
} log_header_t;
</pre>
<p>When the logger appends to the next erase unit boundary, it can first erase
it to ensure future appends are not corrupted by existing bytes. At the
point where it reaches the end of its volume, the 'circular' logging
flag can be used to determine if the logger should go back to the
beginning of the volume and continue writing. Again, this is performed
in conjunction with the VolumeStorage interface to determine erase unit
properties.</p>
</div>
<div class="section">
<h2><a id="reading-log-entries" name="reading-log-entries">3.3 Reading log entries</a></h2>
<p>After the first log entry is located, entries are extracted by first
reading the header of a single entry, and using the information from
the header to pull out the subsequent log information. After each read,
the read pointer is updated to point to the read location of the next header.</p>
<p>If the header ID is fill bytes (0xFFFFFFFF), then the entry is
invalid and the read process has reached the end of the log. As with
the ST M25P80 implementation, entries may be randomly seeked by
providing the 32-bit "cookie" identifier to locate.</p>
</div>
<div class="section">
<h2><a id="logging-conclusions" name="logging-conclusions">3.5 Logging conclusions</a></h2>
<p>This proposed logging storage solution will provide the
ability to maintain and locate previously logged data as well as
support truly circular logs by mandating more than one erase unit per
volume. Behavioral differences between flash chip implementations
are eliminated so one application can access logging storage across
all platforms. Furthermore, reboots will not cause logged information
to be lost or overwritten.</p>
<p>Existing LogRead and LogWrite interfaces defined in TEP 103 <a class="footnote-reference" href="#id7" id="id4" name="id4">[2]</a> are
sufficient to implement cross-platform logging abilities.</p>
</div>
</div>
<div class="section">
<h1><a id="implementing-a-platform-independent-configstorage" name="implementing-a-platform-independent-configstorage">4. Implementing a platform-independent ConfigStorage</a></h1>
<p>The previous interface to ConfigStorage looks very similar to that
of BlockStorage. The ConfigStorage interface allows reads and
writes to arbitrary addresses, which is not optimal. One critical
concept behind the storage of configuration data is the ability to
modify and overwrite existing parameters while preventing surrounding
data from being corrupted. The former ConfigStorage definition did
not support this, so a new solution should be explored and developed.</p>
<p>This new solution should prevent an application from specifying
addresses to read and write to on the volume. Instead, it should dictate
addresses underneath, not allowing applications to see those addresses.
In essence, the solution should handle the allocation of memory and
take the burden of determining valid addresses off of the application
layer. This will allow it to support multiple components written by
different authors on the same system.</p>
<div class="section">
<h2><a id="hash-based-configuration-storage" name="hash-based-configuration-storage">4.1 Hash-based configuration storage</a></h2>
<p>Several practical deployments have demonstrated the effectiveness of
a hash-based configuration storage solution. In it, any module
in a system can store and update any type of data of any size without
destroying other modules' information.</p>
<p>The implementation is similar to that of ConfigStorage in that each
entry contains a header followed by a variable amount of data.
The header is different than ConfigStorage headers in that instead
of containing a 32-bit cookie, it contains a 32-bit hash key and
a magic number to keep track of state::</p>
<pre class="literal-block">
typedef struct config_header_t {
uint32_t hashId;
uint8_t magic;
uint8_t length;
uint8_t crc;
} config_header_t;
</pre>
<p>The magic number allows Configuration storage to determine if the
entry is valid or has been deleted. Because non-volatile memory typically
writes from 1's to 0's, the magic number can take on a finite number of
values before it is filled with 0's. For example::</p>
<pre class="literal-block">
enum {
ENTRY_EMPTY = 0xFF,
ENTRY_VALID = 0xEE,
ENTRY_INVALID = 0xDD,
};
</pre>
<p>Configuration data can be stored and retrieved by indexing it with
a hash key. Like AM types in the radio stack <a class="footnote-reference" href="#id8" id="id5" name="id5">[3]</a>, each key is uniquely
defined by the developer.</p>
<p>Each new update to the configuration storage should create an entirely
new entry while invalidating any previous entry containing the same hash key.
Optionally, a small cache in RAM can be used to maintain information about
where existing hash ID's are located in memory, so non-volatile memory
does not need to be traversed each time.</p>
<p>When space runs out on one erase unit, the next erase unit can be used
to copy in all valid data from the first. The first erase unit can
then be erased. This allows parameters and configuration data to be
infinitely updated so long as the amount of valid data plus supporting
headers is less than half the volume's total erase unit size.</p>
</div>
<div class="section">
<h2><a id="improved-configstorage-interface" name="improved-configstorage-interface">4.2 Improved ConfigStorage interface</a></h2>
<p>The interface to access the configuration storage mechanism is proposed
as follows, allowing the application layer to continually update
previously stored parameters while preventing it from accessing
memory addresses directly::</p>
<pre class="literal-block">
interface ConfigStorage {
command error_t getTotalKeys();
command error_t insert(uint32_t key, void *value, uint16_t valueSize);
command error_t retrieve(uint32_t key, void *valueHolder, uint16_t maxValueSize);
command error_t remove(uint32_t key);
command error_t getFirstKey();
command uint32_t getLastKey();
command error_t getNextKey(uint32_t presentKey);
event void inserted(uint32_t key, void *value, uint16_t valueSize, error_t error);
event void retrieved(uint32_t key, void *valueHolder, uint16_t valueSize, error_t error);
event void removed(uint32_t key, error_t error);
event void nextKey(uint32_t nextKey, error_t error);
event void totalKeys(uint16_t totalKeys);
}
</pre>
<dl class="docutils">
<dt>getTotalKeys()</dt>
<dd><ul class="first last simple">
<li>Determine the total number of valid keys stored on non-volatile memory</li>
<li>Signals totalKeys(...) when complete</li>
</ul>
</dd>
<dt><tt class="docutils literal"><span class="pre">insert(uint32_t</span> <span class="pre">key,</span> <span class="pre">void</span> <span class="pre">*value,</span> <span class="pre">uint16_t</span> <span class="pre">valueSize)</span></tt></dt>
<dd><ul class="first last simple">
<li>Insert some data into the configuration storage associated with the
given key</li>
<li>Signals inserted(...) when complete</li>
</ul>
</dd>
<dt><tt class="docutils literal"><span class="pre">retrieve(uint32_t</span> <span class="pre">key,</span> <span class="pre">void</span> <span class="pre">*valueHolder,</span> <span class="pre">uint16_t</span> <span class="pre">maxValueSize)</span></tt></dt>
<dd><ul class="first last simple">
<li>Retrieve the value associated with the given key. The maximum value
size is the maximum amount of data that can be loaded into the
<tt class="docutils literal"><span class="pre">*valueHolder</span></tt> location, to avoid overflow</li>
<li>Signals retrieved(...) when complete</li>
</ul>
</dd>
<dt>remove(uint32_t key)</dt>
<dd><ul class="first last simple">
<li>Removes the given key and its associated values from non-volatile memory</li>
<li>Signals removed(...) when complete</li>
</ul>
</dd>
<dt>getFirstKey()</dt>
<dd><ul class="first last simple">
<li>Determines the first key available for reading on non-volatile memory</li>
<li>Signals nextKey(...) when complete</li>
</ul>
</dd>
<dt>getNextKey(uint32_t presentKey)</dt>
<dd><ul class="first last simple">
<li>Obtain the next available key on non-volatile memory based on the
current key. Allows the application to traverse through all stored
keys.</li>
<li>Signals nextKey(...) when complete</li>
</ul>
</dd>
<dt>getLastKey()</dt>
<dd><ul class="first last simple">
<li>Returns last key available for reading on non-volatile memory.</li>
<li>This value is assumed to be located in cache, so it can
return immediately</li>
</ul>
</dd>
</dl>
</div>
</div>
<div class="section">
<h1><a id="author-s-address" name="author-s-address">5. Author's Address</a></h1>
<div class="line-block">
<div class="line">David Moss</div>
<div class="line">Rincon Research Corporation</div>
<div class="line">101 N. Wilmot, Suite 101</div>
<div class="line">Tucson, AZ 85750</div>
<div class="line"><br /></div>
<div class="line">phone - +1 520 519 3138</div>
<div class="line">phone - +1 520 519 3146</div>
<div class="line">email ? <a class="reference" href="mailto:dmm@rincon.com">dmm@rincon.com</a></div>
<div class="line"><br /></div>
<div class="line">Junzhao Du</div>
<div class="line">Contact -</div>
<div class="line"><br /></div>
<div class="line">Prabal Dutta</div>
<div class="line">Contact -</div>
<div class="line"><br /></div>
<div class="line">Deepak Ganesan</div>
<div class="line">Contact -</div>
<div class="line"><br /></div>
<div class="line">Kevin Klues</div>
<div class="line">Contact -</div>
<div class="line"><br /></div>
<div class="line">Manju</div>
<div class="line">Contact -</div>
<div class="line"><br /></div>
<div class="line">Ajay Martin</div>
<div class="line">Contact -</div>
<div class="line"><br /></div>
<div class="line">Gaurav Mathur</div>
<div class="line">Contact -</div>
</div>
</div>
<div class="section">
<h1><a id="citations" name="citations">6. Citations</a></h1>
<table class="docutils footnote" frame="void" id="id6" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id1" name="id6">[1]</a></td><td>TEP 103: Permanent Data Storage (Flash).</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id7" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a name="id7">[2]</a></td><td><em>(<a class="fn-backref" href="#id2">1</a>, <a class="fn-backref" href="#id3">2</a>, <a class="fn-backref" href="#id4">3</a>)</em> TEP 128: Platform independent Non-Volatile Storage Abstraction Layers</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id8" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id5" name="id8">[3]</a></td><td>TEP 116: Packet Protocols</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id9" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a name="id9">[4]</a></td><td>Atmel AT45DB041B datasheet. <a class="reference" href="http://www.atmel.com/dyn/resources/prod_documents/DOC1432.PDF">http://www.atmel.com/dyn/resources/prod_documents/DOC1432.PDF</a></td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id10" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a name="id10">[5]</a></td><td>ST M25P80 datasheet. <a class="reference" href="http://www.st.com/stonline/products/literature/ds/8495/m25p80.pdf">http://www.st.com/stonline/products/literature/ds/8495/m25p80.pdf</a></td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id11" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a name="id11">[6]</a></td><td>K9K1G08R0B datasheet. <a class="reference" href="http://www.samsung.com/Products/Semiconductor/NANDFlash/SLC_SmallBlock/1Gbit/K9K1G08R0B/ds_k9k1g08x0b_rev10.pdf">http://www.samsung.com/Products/Semiconductor/NANDFlash/SLC_SmallBlock/1Gbit/K9K1G08R0B/ds_k9k1g08x0b_rev10.pdf</a></td></tr>
</tbody>
</table>
</div>
</div>
</body>
</html>
Index: tep2.html
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/doc/html/tep2.html,v
retrieving revision 1.11
retrieving revision 1.12
diff -C2 -d -r1.11 -r1.12
*** tep2.html 21 Apr 2007 07:04:39 -0000 1.11
--- tep2.html 14 Aug 2007 18:57:59 -0000 1.12
***************
*** 4,10 ****
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
! <meta name="generator" content="Docutils 0.3.6: http://docutils.sourceforge.net/" />
<title>Hardware Abstraction Architecture</title>
! <meta name="author" content="Vlado Handziski, Joseph Polastre, Jan-Hinrich Hauer, Cory Sharp, Adam Wolisz, David Culler, David Gay" />
<style type="text/css">
--- 4,10 ----
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
! <meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
<title>Hardware Abstraction Architecture</title>
! <meta name="author" content="Vlado Handziski, Joseph Polastre, Jan-Hinrich Hauer, Cory Sharp, Adam Wolisz, David Culler, David Gay" />
<style type="text/css">
***************
*** 42,50 ****
margin-bottom: 0.5em }
- /* Uncomment (& remove this text!) to get bold-faced definition list terms
- dt {
- font-weight: bold }
- */
-
div.abstract {
margin: 2em 5em }
--- 42,45 ----
***************
*** 284,287 ****
--- 279,283 ----
</head>
<body>
+ <div class="document" id="hardware-abstraction-architecture">
<h1 class="title">Hardware Abstraction Architecture</h1>
<table class="docinfo" frame="void" rules="none">
***************
*** 300,304 ****
</tr>
<tr><th class="docinfo-name">Author:</th>
! <td>Vlado Handziski, Joseph Polastre, Jan-Hinrich Hauer,
Cory Sharp, Adam Wolisz, David Culler, David Gay</td></tr>
<tr class="field"><th class="docinfo-name">Draft-Created:</th><td class="field-body">14-Sep-2004</td>
--- 296,300 ----
</tr>
<tr><th class="docinfo-name">Author:</th>
! <td>Vlado Handziski, Joseph Polastre, Jan-Hinrich Hauer,
Cory Sharp, Adam Wolisz, David Culler, David Gay</td></tr>
<tr class="field"><th class="docinfo-name">Draft-Created:</th><td class="field-body">14-Sep-2004</td>
***************
*** 312,316 ****
</tbody>
</table>
- <div class="document" id="hardware-abstraction-architecture">
<div class="note">
<p class="first admonition-title">Note</p>
--- 308,311 ----
***************
*** 323,328 ****
memo is in full compliance with <a class="citation-reference" href="#tep1" id="id3" name="id3">[TEP1]</a>.</p>
</div>
! <div class="section" id="abstract">
! <h1><a name="abstract">Abstract</a></h1>
<p>This TEP documents a <em>Hardware Abstraction Architecture (HAA)</em> for
TinyOS 2.0 that balances the conflicting requirements of code
--- 318,323 ----
memo is in full compliance with <a class="citation-reference" href="#tep1" id="id3" name="id3">[TEP1]</a>.</p>
</div>
! <div class="section">
! <h1><a id="abstract" name="abstract">Abstract</a></h1>
<p>This TEP documents a <em>Hardware Abstraction Architecture (HAA)</em> for
TinyOS 2.0 that balances the conflicting requirements of code
***************
*** 336,341 ****
outweigh the need for cross-platform compatibility.</p>
</div>
! <div class="section" id="introduction">
! <h1><a name="introduction">1. Introduction</a></h1>
<p>The introduction of hardware abstraction in operating systems has
proved valuable for increasing portability and simplifying application
--- 331,336 ----
outweigh the need for cross-platform compatibility.</p>
</div>
! <div class="section">
! <h1><a id="introduction" name="introduction">1. Introduction</a></h1>
<p>The introduction of hardware abstraction in operating systems has
proved valuable for increasing portability and simplifying application
***************
*** 359,372 ****
<p>The rest of this TEP specifies:</p>
<ul class="simple">
! <li>the details of the <em>HAA</em> and its three distinct layers
(<a class="reference" href="#architecture">2. Architecture</a>)</li>
! <li>guidelines on selecting the "right" level of abstraction
(<a class="reference" href="#combining-different-levels-of-abstraction">3. Combining different levels of abstraction</a>)</li>
<li>how hardware abstractions can be shared among different TinyOS
platforms (<a class="reference" href="#horizontal-decomposition">4. Horizontal decomposition</a>)</li>
! <li>the level of hardware abstraction for the processing units
(<a class="reference" href="#cpu-abstraction">5. CPU abstraction</a>)</li>
<li>how some hardware abstractions may realize different degrees of
! alignment with the <em>HAA</em> top layer
(<a class="reference" href="#hil-alignment">6. HIL alignment</a>)</li>
</ul>
--- 354,367 ----
<p>The rest of this TEP specifies:</p>
<ul class="simple">
! <li>the details of the <em>HAA</em> and its three distinct layers
(<a class="reference" href="#architecture">2. Architecture</a>)</li>
! <li>guidelines on selecting the "right" level of abstraction
(<a class="reference" href="#combining-different-levels-of-abstraction">3. Combining different levels of abstraction</a>)</li>
<li>how hardware abstractions can be shared among different TinyOS
platforms (<a class="reference" href="#horizontal-decomposition">4. Horizontal decomposition</a>)</li>
! <li>the level of hardware abstraction for the processing units
(<a class="reference" href="#cpu-abstraction">5. CPU abstraction</a>)</li>
<li>how some hardware abstractions may realize different degrees of
! alignment with the <em>HAA</em> top layer
(<a class="reference" href="#hil-alignment">6. HIL alignment</a>)</li>
</ul>
***************
*** 376,381 ****
and <a class="citation-reference" href="#tep112" id="id7" name="id7">[TEP112]</a> and <a class="citation-reference" href="#tep115" id="id8" name="id8">[TEP115]</a> explain how power management is realized.</p>
</div>
! <div class="section" id="architecture">
! <h1><a name="architecture">2. Architecture</a></h1>
<p>In the proposed architecture (<a class="reference" href="#fig-1">Fig.1</a>), the hardware abstraction
functionality is organized in three distinct layers of components.
--- 371,376 ----
and <a class="citation-reference" href="#tep112" id="id7" name="id7">[TEP112]</a> and <a class="citation-reference" href="#tep115" id="id8" name="id8">[TEP115]</a> explain how power management is realized.</p>
</div>
! <div class="section">
! <h1><a id="architecture" name="architecture">2. Architecture</a></h1>
<p>In the proposed architecture (<a class="reference" href="#fig-1">Fig.1</a>), the hardware abstraction
functionality is organized in three distinct layers of components.
***************
*** 388,392 ****
developer more freedom in the design and the implementation of
reusable applications.</p>
! <a class="target" id="fig-1" name="fig-1"></a><pre class="literal-block">
+-----------------------------+
| |
--- 383,387 ----
developer more freedom in the design and the implementation of
reusable applications.</p>
! <pre class="literal-block" id="fig-1">
+-----------------------------+
| |
***************
*** 426,430 ****
+-------------+ +-------------+ +-------------+ +-------------+
!
Fig.1: The proposed Hardware Abstraction Architecture
</pre>
--- 421,425 ----
+-------------+ +-------------+ +-------------+ +-------------+
!
Fig.1: The proposed Hardware Abstraction Architecture
</pre>
***************
*** 440,445 ****
<p>The rest of the section discusses the specific roles of each component
layer in more detail.</p>
! <div class="section" id="hardware-presentation-layer-hpl">
! <h2><a name="hardware-presentation-layer-hpl">Hardware Presentation Layer (HPL)</a></h2>
<p>The components belonging to the <em>HPL</em> are positioned directly over the
HW/SW interface. As the name suggests, their major task is to
--- 435,440 ----
<p>The rest of the section discusses the specific roles of each component
layer in more detail.</p>
! <div class="section">
! <h2><a id="hardware-presentation-layer-hpl" name="hardware-presentation-layer-hpl">Hardware Presentation Layer (HPL)</a></h2>
<p>The components belonging to the <em>HPL</em> are positioned directly over the
HW/SW interface. As the name suggests, their major task is to
***************
*** 497,502 ****
implementation code.</p>
</div>
! <div class="section" id="hardware-adaptation-layer-hal">
! <h2><a name="hardware-adaptation-layer-hal">Hardware Adaptation Layer (HAL)</a></h2>
<p>The adaptation layer components represent the core of the
architecture. They use the raw interfaces provided by the <em>HPL</em>
--- 492,497 ----
implementation code.</p>
</div>
! <div class="section">
! <h2><a id="hardware-adaptation-layer-hal" name="hardware-adaptation-layer-hal">Hardware Adaptation Layer (HAL)</a></h2>
<p>The adaptation layer components represent the core of the
architecture. They use the raw interfaces provided by the <em>HPL</em>
***************
*** 519,524 ****
compile-time detection of abstraction interface usage errors.</p>
</div>
! <div class="section" id="hardware-interface-layer-hil">
! <h2><a name="hardware-interface-layer-hil">Hardware Interface Layer (HIL)</a></h2>
<p>The final tier in the architecture is formed by the <em>HIL</em> components
that take the platform-specific abstractions provided by the <em>HAL</em> and
--- 514,519 ----
compile-time detection of abstraction interface usage errors.</p>
</div>
! <div class="section">
! <h2><a id="hardware-interface-layer-hil" name="hardware-interface-layer-hil">Hardware Interface Layer (HIL)</a></h2>
<p>The final tier in the architecture is formed by the <em>HIL</em> components
that take the platform-specific abstractions provided by the <em>HAL</em> and
***************
*** 559,564 ****
</div>
</div>
! <div class="section" id="combining-different-levels-of-abstraction">
! <h1><a name="combining-different-levels-of-abstraction">3. Combining different levels of abstraction</a></h1>
<p>Providing two levels of abstraction to the application --the <em>HIL</em> and
<em>HAL</em>-- means that a hardware asset may be accessed at two levels in
--- 554,559 ----
</div>
</div>
! <div class="section">
! <h1><a id="combining-different-levels-of-abstraction" name="combining-different-levels-of-abstraction">3. Combining different levels of abstraction</a></h1>
<p>Providing two levels of abstraction to the application --the <em>HIL</em> and
<em>HAL</em>-- means that a hardware asset may be accessed at two levels in
***************
*** 582,586 ****
over the conversion process. (<a class="reference" href="#fig-2">Fig.2</a>) depicts how the ADC hardware
stack on the MSP430 MCU on the level of <em>HIL</em> and <em>HAL</em> in parallel.</p>
! <a class="target" id="fig-2" name="fig-2"></a><pre class="literal-block">
+--------------------------------+
| APP |
--- 577,581 ----
over the conversion process. (<a class="reference" href="#fig-2">Fig.2</a>) depicts how the ADC hardware
stack on the MSP430 MCU on the level of <em>HIL</em> and <em>HAL</em> in parallel.</p>
! <pre class="literal-block" id="fig-2">
+--------------------------------+
| APP |
***************
*** 624,629 ****
guaranteed.</p>
</div>
! <div class="section" id="horizontal-decomposition">
! <h1><a name="horizontal-decomposition">4. Horizontal decomposition</a></h1>
<p>In addition to the <em>vertical</em> decomposition of the <em>HAA</em>, a
<em>horizontal</em> decomposition can promote reuse of the hardware resource
--- 619,624 ----
guaranteed.</p>
</div>
! <div class="section">
! <h1><a id="horizontal-decomposition" name="horizontal-decomposition">4. Horizontal decomposition</a></h1>
<p>In addition to the <em>vertical</em> decomposition of the <em>HAA</em>, a
<em>horizontal</em> decomposition can promote reuse of the hardware resource
***************
*** 635,639 ****
Platforms are then built as compositions of different chip components
with the help of "glue" components that perform the mapping (<a class="reference" href="#fig-3">Fig.3</a>)</p>
! <a class="target" id="fig-3" name="fig-3"></a><pre class="literal-block">
+----------------------------------------------------+
| AppC |
--- 630,634 ----
Platforms are then built as compositions of different chip components
with the help of "glue" components that perform the mapping (<a class="reference" href="#fig-3">Fig.3</a>)</p>
! <pre class="literal-block" id="fig-3">
+----------------------------------------------------+
| AppC |
***************
*** 707,712 ****
chips are connected to the same physical bus interconnect.</p>
</div>
! <div class="section" id="cpu-abstraction">
! <h1><a name="cpu-abstraction">5. CPU abstraction</a></h1>
<p>In TinyOS most of the variability between the processing units is
hidden from the OS simply by using a nesC/C based programming language
--- 702,707 ----
chips are connected to the same physical bus interconnect.</p>
</div>
! <div class="section">
! <h1><a id="cpu-abstraction" name="cpu-abstraction">5. CPU abstraction</a></h1>
<p>In TinyOS most of the variability between the processing units is
hidden from the OS simply by using a nesC/C based programming language
***************
*** 725,730 ****
addressed.</p>
</div>
! <div class="section" id="hil-alignment">
! <h1><a name="hil-alignment">6. HIL alignment</a></h1>
<p>While the <em>HAA</em> requires that the <em>HIL</em> provides full hardware
independence (<a class="reference" href="#strong-real-hils">Strong/Real HILs</a>), some abstractions might only
--- 720,725 ----
addressed.</p>
</div>
! <div class="section">
! <h1><a id="hil-alignment" name="hil-alignment">6. HIL alignment</a></h1>
<p>While the <em>HAA</em> requires that the <em>HIL</em> provides full hardware
independence (<a class="reference" href="#strong-real-hils">Strong/Real HILs</a>), some abstractions might only
***************
*** 737,742 ****
<li><em>platform-specific X:</em> X is defined on just one platform</li>
</ul>
! <div class="section" id="strong-real-hils">
! <h2><a name="strong-real-hils">Strong/Real HILs</a></h2>
<p><em>Strong/Real HILs</em> mean that "code using these abstractions can
reasonably be expected to behave the same on all implementations".
--- 732,737 ----
<li><em>platform-specific X:</em> X is defined on just one platform</li>
</ul>
! <div class="section">
! <h2><a id="strong-real-hils" name="strong-real-hils">Strong/Real HILs</a></h2>
<p><em>Strong/Real HILs</em> mean that "code using these abstractions can
reasonably be expected to behave the same on all implementations".
***************
*** 751,756 ****
(<a class="citation-reference" href="#tep111" id="id17" name="id17">[TEP111]</a>).</p>
</div>
! <div class="section" id="weak-hils">
! <h2><a name="weak-hils">Weak HILs</a></h2>
<p><em>Weak HILs</em> mean that one "can write portable code over these
abstractions, but any use of them involves platform-specific
--- 746,751 ----
(<a class="citation-reference" href="#tep111" id="id17" name="id17">[TEP111]</a>).</p>
</div>
! <div class="section">
! <h2><a id="weak-hils" name="weak-hils">Weak HILs</a></h2>
<p><em>Weak HILs</em> mean that one "can write portable code over these
abstractions, but any use of them involves platform-specific
***************
*** 774,779 ****
developers.</p>
</div>
! <div class="section" id="hardware-independent-interfaces-hii">
! <h2><a name="hardware-independent-interfaces-hii">Hardware Independent Interfaces (HII)</a></h2>
<p><em>Hardware Independent Interfaces (HII)</em>, is just an interface
definition intended for use across multiple platforms.</p>
--- 769,774 ----
developers.</p>
</div>
! <div class="section">
! <h2><a id="hardware-independent-interfaces-hii" name="hardware-independent-interfaces-hii">Hardware Independent Interfaces (HII)</a></h2>
<p><em>Hardware Independent Interfaces (HII)</em>, is just an interface
definition intended for use across multiple platforms.</p>
***************
*** 781,786 ****
the Alarm/Counter/etc interfaces from <a class="citation-reference" href="#tep102" id="id19" name="id19">[TEP102]</a>.</p>
</div>
! <div class="section" id="utility-components">
! <h2><a name="utility-components">Utility components</a></h2>
<p><em>Utility components</em> are pieces of clearly portable code (typically
generic components), which aren't exposing a self-contained service.
--- 776,781 ----
the Alarm/Counter/etc interfaces from <a class="citation-reference" href="#tep102" id="id19" name="id19">[TEP102]</a>.</p>
</div>
! <div class="section">
! <h2><a id="utility-components" name="utility-components">Utility components</a></h2>
<p><em>Utility components</em> are pieces of clearly portable code (typically
generic components), which aren't exposing a self-contained service.
***************
*** 789,794 ****
</div>
</div>
! <div class="section" id="conclusion">
! <h1><a name="conclusion">6. Conclusion</a></h1>
<p>The proposed hardware abstraction architecture provides a set of core
services that eliminate duplicated code and provide a coherent view of
--- 784,789 ----
</div>
</div>
! <div class="section">
! <h1><a id="conclusion" name="conclusion">6. Conclusion</a></h1>
<p>The proposed hardware abstraction architecture provides a set of core
services that eliminate duplicated code and provide a coherent view of
***************
*** 800,808 ****
remainder of the application.</p>
</div>
! <div class="section" id="author-s-address">
! <h1><a name="author-s-address">Author's Address</a></h1>
<div class="line-block">
! <div class="line">Vlado Handziski (handzisk at tkn.tu-berlin.de) <a class="footnote-reference" href="#id27" id="id20" name="id20">[1]</a> </div>
! <div class="line">Joseph Polastre (polastre at cs.berkeley.edu) <a class="footnote-reference" href="#id28" id="id21" name="id21">[2]</a> </div>
<div class="line">Jan-Hinrich Hauer (hauer at tkn.tu-berlin.de) <a class="footnote-reference" href="#id27" id="id22" name="id22">[1]</a></div>
<div class="line">Cory Sharp (cssharp at eecs.berkeley.edu) <a class="footnote-reference" href="#id28" id="id23" name="id23">[2]</a></div>
--- 795,803 ----
remainder of the application.</p>
</div>
! <div class="section">
! <h1><a id="author-s-address" name="author-s-address">Author's Address</a></h1>
<div class="line-block">
! <div class="line">Vlado Handziski (handzisk at tkn.tu-berlin.de) <a class="footnote-reference" href="#id27" id="id20" name="id20">[1]</a></div>
! <div class="line">Joseph Polastre (polastre at cs.berkeley.edu) <a class="footnote-reference" href="#id28" id="id21" name="id21">[2]</a></div>
<div class="line">Jan-Hinrich Hauer (hauer at tkn.tu-berlin.de) <a class="footnote-reference" href="#id27" id="id22" name="id22">[1]</a></div>
<div class="line">Cory Sharp (cssharp at eecs.berkeley.edu) <a class="footnote-reference" href="#id28" id="id23" name="id23">[2]</a></div>
***************
*** 814,820 ****
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
! <tr><td class="label"><a name="id27">[1]</a></td><td><em>(<a class="fn-backref" href="#id20">1</a>, <a class="fn-backref" href="#id22">2</a>, <a class="fn-backref" href="#id24">3</a>)</em> Technische Universitaet Berlin
! Telecommunication Networks Group
! Sekr. FT 5, Einsteinufer 25
10587 Berlin, Germany</td></tr>
</tbody>
--- 809,815 ----
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
! <tr><td class="label"><a name="id27">[1]</a></td><td><em>(<a class="fn-backref" href="#id20">1</a>, <a class="fn-backref" href="#id22">2</a>, <a class="fn-backref" href="#id24">3</a>)</em> Technische Universitaet Berlin
! Telecommunication Networks Group
! Sekr. FT 5, Einsteinufer 25
10587 Berlin, Germany</td></tr>
</tbody>
***************
*** 824,828 ****
<tbody valign="top">
<tr><td class="label"><a name="id28">[2]</a></td><td><em>(<a class="fn-backref" href="#id21">1</a>, <a class="fn-backref" href="#id23">2</a>, <a class="fn-backref" href="#id25">3</a>)</em> University of California, Berkeley
! Computer Science Department
Berkeley, CA 94720 USA</td></tr>
</tbody>
--- 819,823 ----
<tbody valign="top">
<tr><td class="label"><a name="id28">[2]</a></td><td><em>(<a class="fn-backref" href="#id21">1</a>, <a class="fn-backref" href="#id23">2</a>, <a class="fn-backref" href="#id25">3</a>)</em> University of California, Berkeley
! Computer Science Department
Berkeley, CA 94720 USA</td></tr>
</tbody>
***************
*** 837,842 ****
</table>
</div>
! <div class="section" id="citations">
! <h1><a name="citations">Citations</a></h1>
<table class="docutils citation" frame="void" id="haa2005" rules="none">
<colgroup><col class="label" /><col /></colgroup>
--- 832,837 ----
</table>
</div>
! <div class="section">
! <h1><a id="citations" name="citations">Citations</a></h1>
<table class="docutils citation" frame="void" id="haa2005" rules="none">
<colgroup><col class="label" /><col /></colgroup>
***************
*** 851,859 ****
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
! <tr><td class="label"><a class="fn-backref" href="#id2" name="t2-tr">[T2_TR]</a></td><td>P. Levis, D. Gay, V. Handziski, J.-H.Hauer, B.Greenstein,
! M.Turon, J.Hui, K.Klues, C.Sharp, R.Szewczyk, J.Polastre,
! P.Buonadonna, L.Nachman, G.Tolle, D.Culler, and A.Wolisz,
! "T2: A Second Generation OS For Embedded Sensor Networks",
! <em>Technical Report TKN-05-007</em>, Telecommunication Networks Group,
Technische Universität Berlin, November 2005.</td></tr>
</tbody>
--- 846,854 ----
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
! <tr><td class="label"><a class="fn-backref" href="#id2" name="t2-tr">[T2_TR]</a></td><td>P. Levis, D. Gay, V. Handziski, J.-H.Hauer, B.Greenstein,
! M.Turon, J.Hui, K.Klues, C.Sharp, R.Szewczyk, J.Polastre,
! P.Buonadonna, L.Nachman, G.Tolle, D.Culler, and A.Wolisz,
! "T2: A Second Generation OS For Embedded Sensor Networks",
! <em>Technical Report TKN-05-007</em>, Telecommunication Networks Group,
Technische Universität Berlin, November 2005.</td></tr>
</tbody>
***************
*** 869,873 ****
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
! <tr><td class="label"><a class="fn-backref" href="#id11" name="netbsd">[NetBSD]</a></td><td>"The NetBSD project home page", <em>Online</em>,
<a class="reference" href="http://www.netbsd.org">http://www.netbsd.org</a></td></tr>
</tbody>
--- 864,868 ----
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
! <tr><td class="label"><a class="fn-backref" href="#id11" name="netbsd">[NetBSD]</a></td><td>"The NetBSD project home page", <em>Online</em>,
<a class="reference" href="http://www.netbsd.org">http://www.netbsd.org</a></td></tr>
</tbody>
Index: tep119.html
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/doc/html/tep119.html,v
retrieving revision 1.10
retrieving revision 1.11
diff -C2 -d -r1.10 -r1.11
*** tep119.html 21 Apr 2007 07:04:39 -0000 1.10
--- tep119.html 14 Aug 2007 18:57:59 -0000 1.11
***************
*** 4,8 ****
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
! <meta name="generator" content="Docutils 0.3.6: http://docutils.sourceforge.net/" />
<title>Collection</title>
<meta name="author" content="Rodrigo Fonseca, Omprakash Gnawali, Kyle Jamieson, and Philip Levis" />
--- 4,8 ----
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
! <meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
<title>Collection</title>
<meta name="author" content="Rodrigo Fonseca, Omprakash Gnawali, Kyle Jamieson, and Philip Levis" />
***************
*** 42,50 ****
margin-bottom: 0.5em }
- /* Uncomment (& remove this text!) to get bold-faced definition list terms
- dt {
- font-weight: bold }
- */
-
div.abstract {
margin: 2em 5em }
--- 42,45 ----
***************
*** 284,287 ****
--- 279,283 ----
</head>
<body>
+ <div class="document" id="collection">
<h1 class="title">Collection</h1>
<table class="docinfo" frame="void" rules="none">
***************
*** 307,311 ****
</tbody>
</table>
- <div class="document" id="collection">
<div class="note">
<p class="first admonition-title">Note</p>
--- 303,306 ----
***************
*** 315,320 ****
TEP 1.</p>
</div>
! <div class="section" id="abstract">
! <h1><a name="abstract">Abstract</a></h1>
<p>The memo documents the interfaces, components, and semantics used by
collection protocol in TinyOS 2.x. Collection provides a best-effort,
--- 310,315 ----
TEP 1.</p>
</div>
! <div class="section">
! <h1><a id="abstract" name="abstract">Abstract</a></h1>
<p>The memo documents the interfaces, components, and semantics used by
collection protocol in TinyOS 2.x. Collection provides a best-effort,
***************
*** 324,333 ****
a packet does not specify which root the packet is destined to.</p>
</div>
! <div class="section" id="introduction">
! <h1><a name="introduction">1. Introduction</a></h1>
<p>Collecting data at a base station is a common requirement of sensor
network applications. The general approach used is to build one
or more collection <em>trees</em>, each of which is rooted at a base
! station. When a node has data which needs to be collected, it
sends the data up the tree, and it forwards collection data that
other nodes send to it. Sometimes, depending on the form of data
--- 319,328 ----
a packet does not specify which root the packet is destined to.</p>
</div>
! <div class="section">
! <h1><a id="introduction" name="introduction">1. Introduction</a></h1>
<p>Collecting data at a base station is a common requirement of sensor
network applications. The general approach used is to build one
or more collection <em>trees</em>, each of which is rooted at a base
! station. When a node has data which needs to be collected, it
sends the data up the tree, and it forwards collection data that
other nodes send to it. Sometimes, depending on the form of data
***************
*** 336,340 ****
redundant transmissions.</p>
<p>When a network has multiple base stations that act as <em>root</em> nodes,
! rather than one tree, it has a <em>forest</em> of trees. By picking a
parent node, a collection protocol implicitly joins one of these
trees. Collection provides a best-effort,
--- 331,335 ----
redundant transmissions.</p>
<p>When a network has multiple base stations that act as <em>root</em> nodes,
! rather than one tree, it has a <em>forest</em> of trees. By picking a
parent node, a collection protocol implicitly joins one of these
trees. Collection provides a best-effort,
***************
*** 342,346 ****
it is an <em>anycast</em> protocol. The semantics is that the protocol
will make a reasonable effort to deliver the message to at least
! one of the roots in the network. There are however no guarantees of
delivery, and there can be duplicates delivered to one or more
roots. There is also no ordering guarantees.</p>
--- 337,341 ----
it is an <em>anycast</em> protocol. The semantics is that the protocol
will make a reasonable effort to deliver the message to at least
! one of the roots in the network. There are however no guarantees of
delivery, and there can be duplicates delivered to one or more
roots. There is also no ordering guarantees.</p>
***************
*** 355,360 ****
<li>Loop detection, detecting when a node selects one of its
descendants as a new parent.</li>
! <li>Duplicate suppression, detecting and dealing with when lost
! acknowledgments are causing packets to replicate in the
network, wasting bandwidth.</li>
<li>Link estimation, evaluating the link quality to single-hop
--- 350,355 ----
<li>Loop detection, detecting when a node selects one of its
descendants as a new parent.</li>
! <li>Duplicate suppression, detecting and dealing with when lost
! acknowledgments are causing packets to replicate in the
network, wasting bandwidth.</li>
<li>Link estimation, evaluating the link quality to single-hop
***************
*** 367,372 ****
for a collection service outlined above.</p>
</div>
! <div class="section" id="collection-interfaces">
! <h1><a name="collection-interfaces">2. Collection interfaces</a></h1>
<p>A node can perform four different roles in collection: producer,
consumer, snooper, and in-network processor. Depending on their role,
--- 362,367 ----
for a collection service outlined above.</p>
</div>
! <div class="section">
! <h1><a id="collection-interfaces" name="collection-interfaces">2. Collection interfaces</a></h1>
<p>A node can perform four different roles in collection: producer,
consumer, snooper, and in-network processor. Depending on their role,
***************
*** 375,380 ****
<p>A consumer is a root of a tree. The set of all roots and the paths that
lead to them form the collection routing infrastructure in the network.
! For any connected set of nodes implementing the collection protocol
! there is only one collection infrastructure, <em>i.e.</em>, all roots in this
set active at the same time are part of the same infrastructure.</p>
<p>A node is configured to become a root by using the RootControl
--- 370,375 ----
<p>A consumer is a root of a tree. The set of all roots and the paths that
lead to them form the collection routing infrastructure in the network.
! For any connected set of nodes implementing the collection protocol
! there is only one collection infrastructure, <em>i.e.</em>, all roots in this
set active at the same time are part of the same infrastructure.</p>
<p>A node is configured to become a root by using the RootControl
***************
*** 414,419 ****
to Intercept during instantiation.</p>
</div>
! <div class="section" id="collection-services">
! <h1><a name="collection-services">3 Collection Services</a></h1>
<p>A collection service MUST provide one component, CollectionC,
which has the following signature:</p>
--- 409,414 ----
to Intercept during instantiation.</p>
</div>
! <div class="section">
! <h1><a id="collection-services" name="collection-services">3 Collection Services</a></h1>
<p>A collection service MUST provide one component, CollectionC,
which has the following signature:</p>
***************
*** 464,469 ****
<p>Packet and CollectionPacket allow components to access collection
data packet fields [<a class="reference" href="#id1">1</a>].</p>
! <div class="section" id="collectionsenderc">
! <h2><a name="collectionsenderc">3.1 CollectionSenderC</a></h2>
<p>Collection has a virtualized sending abstraction, the generic
component CollectionSenderC:</p>
--- 459,464 ----
<p>Packet and CollectionPacket allow components to access collection
data packet fields [<a class="reference" href="#id1">1</a>].</p>
! <div class="section">
! <h2><a id="collectionsenderc" name="collectionsenderc">3.1 CollectionSenderC</a></h2>
<p>Collection has a virtualized sending abstraction, the generic
component CollectionSenderC:</p>
***************
*** 483,488 ****
</div>
</div>
! <div class="section" id="implementation">
! <h1><a name="implementation">4 Implementation</a></h1>
<p>An implementation of this TEP can be found in
<tt class="docutils literal"><span class="pre">tinyos-2.x/tos/lib/net/ctp</span></tt> and <tt class="docutils literal"><span class="pre">tinyos-2.x/tos/lib/net/le</span></tt>, in
--- 478,483 ----
</div>
</div>
! <div class="section">
! <h1><a id="implementation" name="implementation">4 Implementation</a></h1>
<p>An implementation of this TEP can be found in
<tt class="docutils literal"><span class="pre">tinyos-2.x/tos/lib/net/ctp</span></tt> and <tt class="docutils literal"><span class="pre">tinyos-2.x/tos/lib/net/le</span></tt>, in
***************
*** 499,504 ****
routing protocol and route selection are decoupled from the
forwarding policies, such as queueing and timing.</p>
! <div class="section" id="linkestimatorp">
! <h2><a name="linkestimatorp">4.1 LinkEstimatorP</a></h2>
<p>LinkEstimatorP estimates the quality of link to or from each
neighbor. Link estimation can be done in a variety of ways, and we
--- 494,499 ----
routing protocol and route selection are decoupled from the
forwarding policies, such as queueing and timing.</p>
! <div class="section">
! <h2><a id="linkestimatorp" name="linkestimatorp">4.1 LinkEstimatorP</a></h2>
<p>LinkEstimatorP estimates the quality of link to or from each
neighbor. Link estimation can be done in a variety of ways, and we
***************
*** 553,562 ****
</pre>
</div>
! <div class="section" id="ctproutingenginep">
! <h2><a name="ctproutingenginep">4.2 CtpRoutingEngineP</a></h2>
<p>CtpRoutingEngineP is responsible for computing routes to the roots of a
tree. In traditional networking terminology, this is part of the
control plane of the network, and is does not directly forward any
! data packets, which is the responsibility of CtpForwardingEngine.
The main interface between the two is UnicastNameFreeRouting.</p>
<p>CtpRoutingEngineP uses the LinkEstimator interface to learn
--- 548,557 ----
</pre>
</div>
! <div class="section">
! <h2><a id="ctproutingenginep" name="ctproutingenginep">4.2 CtpRoutingEngineP</a></h2>
<p>CtpRoutingEngineP is responsible for computing routes to the roots of a
tree. In traditional networking terminology, this is part of the
control plane of the network, and is does not directly forward any
! data packets, which is the responsibility of CtpForwardingEngine.
The main interface between the two is UnicastNameFreeRouting.</p>
<p>CtpRoutingEngineP uses the LinkEstimator interface to learn
***************
*** 564,573 ****
the quality of links to and from the neighbors. The routing protocol
on which collection is implemented MUST be a tree-based routing
! protocol with a single or multiple roots. CtpRoutingEngineP
allows a node to be configured as a root or a non-root node
dynamically. CtpRoutingEngineP maintains multiple candidate next hops:</p>
<pre class="literal-block">
! generic module CtpRoutingEngineP(uint8_t routingTableSize,
! uint16_t minInterval,
uint16_t maxInterval) {
provides {
--- 559,568 ----
the quality of links to and from the neighbors. The routing protocol
on which collection is implemented MUST be a tree-based routing
! protocol with a single or multiple roots. CtpRoutingEngineP
allows a node to be configured as a root or a non-root node
dynamically. CtpRoutingEngineP maintains multiple candidate next hops:</p>
<pre class="literal-block">
! generic module CtpRoutingEngineP(uint8_t routingTableSize,
! uint16_t minInterval,
uint16_t maxInterval) {
provides {
***************
*** 578,582 ****
interface CtpRoutingPacket;
interface Init;
! }
uses {
interface AMSend as BeaconSend;
--- 573,577 ----
interface CtpRoutingPacket;
interface Init;
! }
uses {
interface AMSend as BeaconSend;
***************
*** 604,611 ****
</pre>
</div>
! <div class="section" id="ctpforwardingenginep">
! <h2><a name="ctpforwardingenginep">4.3 CtpForwardingEngineP</a></h2>
<p>The CtpForwardingEngineP component provides all the top level interfaces
! (except RootControl) which CollectionC provides and an application
uses. It deals with retransmissions, duplicate suppression, packet
timing, loop detection, and also informs the LinkEstimator of the
--- 599,606 ----
</pre>
</div>
! <div class="section">
! <h2><a id="ctpforwardingenginep" name="ctpforwardingenginep">4.3 CtpForwardingEngineP</a></h2>
<p>The CtpForwardingEngineP component provides all the top level interfaces
! (except RootControl) which CollectionC provides and an application
uses. It deals with retransmissions, duplicate suppression, packet
timing, loop detection, and also informs the LinkEstimator of the
***************
*** 664,671 ****
</div>
</div>
! <div class="section" id="author-addresses">
! <h1><a name="author-addresses">5. Author Addresses</a></h1>
<div class="line-block">
! <div class="line">Rodrigo Fonseca </div>
<div class="line">473 Soda Hall</div>
<div class="line">Berkeley, CA 94720-1776</div>
--- 659,666 ----
</div>
</div>
! <div class="section">
! <h1><a id="author-addresses" name="author-addresses">5. Author Addresses</a></h1>
<div class="line-block">
! <div class="line">Rodrigo Fonseca</div>
<div class="line">473 Soda Hall</div>
<div class="line">Berkeley, CA 94720-1776</div>
***************
*** 676,682 ****
<div class="line"><br /></div>
<div class="line">Omprakash Gnawali</div>
! <div class="line">Ronald Tutor Hall (RTH) 418 </div>
<div class="line">3710 S. McClintock Avenue</div>
! <div class="line">Los Angeles, CA 90089 </div>
<div class="line"><br /></div>
<div class="line">phone - +1 213 821-5627</div>
--- 671,677 ----
<div class="line"><br /></div>
<div class="line">Omprakash Gnawali</div>
! <div class="line">Ronald Tutor Hall (RTH) 418</div>
<div class="line">3710 S. McClintock Avenue</div>
! <div class="line">Los Angeles, CA 90089</div>
<div class="line"><br /></div>
<div class="line">phone - +1 213 821-5627</div>
***************
*** 687,691 ****
<div class="line">The Stata Center</div>
<div class="line">32 Vassar St.</div>
! <div class="line">Cambridge, MA 02139 </div>
<div class="line"><br /></div>
<div class="line">email - <a class="reference" href="mailto:jamieson@csail.mit.edu">jamieson@csail.mit.edu</a></div>
--- 682,686 ----
<div class="line">The Stata Center</div>
<div class="line">32 Vassar St.</div>
! <div class="line">Cambridge, MA 02139</div>
<div class="line"><br /></div>
<div class="line">email - <a class="reference" href="mailto:jamieson@csail.mit.edu">jamieson@csail.mit.edu</a></div>
***************
*** 702,707 ****
</div>
</div>
! <div class="section" id="citations">
! <h1><a name="citations">6. Citations</a></h1>
<table class="docutils footnote" frame="void" id="id1" rules="none">
<colgroup><col class="label" /><col /></colgroup>
--- 697,702 ----
</div>
</div>
! <div class="section">
! <h1><a id="citations" name="citations">6. Citations</a></h1>
<table class="docutils footnote" frame="void" id="id1" rules="none">
<colgroup><col class="label" /><col /></colgroup>
Index: tep113.html
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/doc/html/tep113.html,v
retrieving revision 1.9
retrieving revision 1.10
diff -C2 -d -r1.9 -r1.10
*** tep113.html 21 Apr 2007 07:04:39 -0000 1.9
--- tep113.html 14 Aug 2007 18:57:59 -0000 1.10
***************
*** 4,8 ****
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
! <meta name="generator" content="Docutils 0.3.6: http://docutils.sourceforge.net/" />
<title>Serial Communication</title>
<meta name="author" content="Ben Greenstein and Philip Levis" />
--- 4,8 ----
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
! <meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
<title>Serial Communication</title>
<meta name="author" content="Ben Greenstein and Philip Levis" />
***************
*** 42,50 ****
margin-bottom: 0.5em }
- /* Uncomment (& remove this text!) to get bold-faced definition list terms
- dt {
- font-weight: bold }
- */
-
div.abstract {
margin: 2em 5em }
--- 42,45 ----
***************
*** 284,287 ****
--- 279,283 ----
</head>
<body>
+ <div class="document" id="serial-communication">
<h1 class="title">Serial Communication</h1>
<table class="docinfo" frame="void" rules="none">
***************
*** 311,315 ****
</tbody>
</table>
- <div class="document" id="serial-communication">
<div class="note">
<p class="first admonition-title">Note</p>
--- 307,310 ----
***************
*** 319,324 ****
TEP 1.</p>
</div>
! <div class="section" id="abstract">
! <h1><a name="abstract">Abstract</a></h1>
<p>This memo describes the structure and standard implementation of the
TinyOS 2.x serial communication system for mote-to-PC data
--- 314,319 ----
TEP 1.</p>
</div>
! <div class="section">
! <h1><a id="abstract" name="abstract">Abstract</a></h1>
<p>This memo describes the structure and standard implementation of the
TinyOS 2.x serial communication system for mote-to-PC data
***************
*** 330,335 ****
applications can communicate with arbitrary motes.</p>
</div>
! <div class="section" id="introduction">
! <h1><a name="introduction">1. Introduction</a></h1>
<p>Users need to read data out of a TinyOS network. The most common
approach is to attach a mote to a PC or laptop with a wired
--- 325,330 ----
applications can communicate with arbitrary motes.</p>
</div>
! <div class="section">
! <h1><a id="introduction" name="introduction">1. Introduction</a></h1>
<p>Users need to read data out of a TinyOS network. The most common
approach is to attach a mote to a PC or laptop with a wired
***************
*** 346,351 ****
TinyOS 2.x serial communication stack.</p>
</div>
! <div class="section" id="serial-stack-structure">
! <h1><a name="serial-stack-structure">2. Serial Stack Structure</a></h1>
<p>The TinyOS 2.x serial communication stack is broken up into four
functional components. From bottom to top, they are</p>
--- 341,346 ----
TinyOS 2.x serial communication stack.</p>
</div>
! <div class="section">
! <h1><a id="serial-stack-structure" name="serial-stack-structure">2. Serial Stack Structure</a></h1>
<p>The TinyOS 2.x serial communication stack is broken up into four
functional components. From bottom to top, they are</p>
***************
*** 358,375 ****
<p>Structurally, they look like this:</p>
<pre class="literal-block">
! _____________________
! | |
| Dispatcher | Packet formatting.
! |_____________________|
! _____________________
! | |
| Protocol | Acknowledgements, CRC computation,
|_____________________| windowing.
! _____________________
! | |
| Encoder/Framer | Translating raw bytes into frame
|_____________________| delimiters, escape bytes.
! _____________________
! | |
| Raw UART | Platform code for reading/writing
|_____________________| bytes over the serial connection.
--- 353,370 ----
<p>Structurally, they look like this:</p>
<pre class="literal-block">
! _____________________
! | |
| Dispatcher | Packet formatting.
! |_____________________|
! _____________________
! | |
| Protocol | Acknowledgements, CRC computation,
|_____________________| windowing.
! _____________________
! | |
| Encoder/Framer | Translating raw bytes into frame
|_____________________| delimiters, escape bytes.
! _____________________
! | |
| Raw UART | Platform code for reading/writing
|_____________________| bytes over the serial connection.
***************
*** 402,407 ****
<tt class="docutils literal"><span class="pre">SerialDispatcherC</span></tt> does this.</p>
</div>
! <div class="section" id="the-2-x-serial-stack-implementation">
! <h1><a name="the-2-x-serial-stack-implementation">3. The 2.x Serial Stack Implementation</a></h1>
<p>Section 2 describes the basic structure of the TinyOS 2.x serial
stack. This section describes its actual implementation,
--- 397,402 ----
<tt class="docutils literal"><span class="pre">SerialDispatcherC</span></tt> does this.</p>
</div>
! <div class="section">
! <h1><a id="the-2-x-serial-stack-implementation" name="the-2-x-serial-stack-implementation">3. The 2.x Serial Stack Implementation</a></h1>
<p>Section 2 describes the basic structure of the TinyOS 2.x serial
stack. This section describes its actual implementation,
***************
*** 409,414 ****
All of the components except for UartC are part of the serial
library that lives in <tt class="docutils literal"><span class="pre">tos/lib/serial</span></tt>.</p>
! <div class="section" id="raw-uart-uartc">
! <h2><a name="raw-uart-uartc">3.1 Raw UART: UartC</a></h2>
<p>The UART HIL[<a class="reference" href="#tep2">TEP2</a>] is <tt class="docutils literal"><span class="pre">UartC</span></tt>, which provides a byte-level
interface to the underlying serial communication. It provides the
--- 404,409 ----
All of the components except for UartC are part of the serial
library that lives in <tt class="docutils literal"><span class="pre">tos/lib/serial</span></tt>.</p>
! <div class="section">
! <h2><a id="raw-uart-uartc" name="raw-uart-uartc">3.1 Raw UART: UartC</a></h2>
<p>The UART HIL[<a class="reference" href="#tep2">TEP2</a>] is <tt class="docutils literal"><span class="pre">UartC</span></tt>, which provides a byte-level
interface to the underlying serial communication. It provides the
***************
*** 440,445 ****
port. This TEP does not consider this topic.</p>
</div>
! <div class="section" id="encoder-framer-hdlctranslatec">
! <h2><a name="encoder-framer-hdlctranslatec">3.2 Encoder/Framer: HdlcTranslateC</a></h2>
<p>HdlcTranslateC is the serial encoder/framer. It uses the
<tt class="docutils literal"><span class="pre">SerialByteComm</span></tt> interface and provides the <tt class="docutils literal"><span class="pre">SerialFrameComm</span></tt>
--- 435,440 ----
port. This TEP does not consider this topic.</p>
</div>
! <div class="section">
! <h2><a id="encoder-framer-hdlctranslatec" name="encoder-framer-hdlctranslatec">3.2 Encoder/Framer: HdlcTranslateC</a></h2>
<p>HdlcTranslateC is the serial encoder/framer. It uses the
<tt class="docutils literal"><span class="pre">SerialByteComm</span></tt> interface and provides the <tt class="docutils literal"><span class="pre">SerialFrameComm</span></tt>
***************
*** 476,481 ****
stored data byte.</p>
</div>
! <div class="section" id="protocol-serialp">
! <h2><a name="protocol-serialp">3.3 Protocol: SerialP</a></h2>
<p>The SerialP component implements the serial protocol using PPP/HDLC-
like framing (See RFC 1662[<a class="reference" href="#rfc1662">RFC1662</a>]). Type dispatch and buffer
--- 471,476 ----
stored data byte.</p>
</div>
! <div class="section">
! <h2><a id="protocol-serialp" name="protocol-serialp">3.3 Protocol: SerialP</a></h2>
<p>The SerialP component implements the serial protocol using PPP/HDLC-
like framing (See RFC 1662[<a class="reference" href="#rfc1662">RFC1662</a>]). Type dispatch and buffer
***************
*** 536,541 ****
actively sending an acknowledgement.</p>
</div>
! <div class="section" id="dispatcher-serialdispatcherc">
! <h2><a name="dispatcher-serialdispatcherc">3.4 Dispatcher: SerialDispatcherC</a></h2>
<p>SerialDispatcherC handles the data packets that the Protocol component
receives. It uses the SendBytePacket and ReceiveBytePacket interfaces,
--- 531,536 ----
actively sending an acknowledgement.</p>
</div>
! <div class="section">
! <h2><a id="dispatcher-serialdispatcherc" name="dispatcher-serialdispatcherc">3.4 Dispatcher: SerialDispatcherC</a></h2>
<p>SerialDispatcherC handles the data packets that the Protocol component
receives. It uses the SendBytePacket and ReceiveBytePacket interfaces,
***************
*** 575,580 ****
reuse any reserved identifiers.</p>
</div>
! <div class="section" id="serialactivemessagec">
! <h2><a name="serialactivemessagec">3.5 SerialActiveMessageC</a></h2>
<p>SerialActiveMessageC is a platform-independent active message layer
that operates on top of the serial communication
--- 570,575 ----
reuse any reserved identifiers.</p>
</div>
! <div class="section">
! <h2><a id="serialactivemessagec" name="serialactivemessagec">3.5 SerialActiveMessageC</a></h2>
<p>SerialActiveMessageC is a platform-independent active message layer
that operates on top of the serial communication
***************
*** 598,613 ****
components new SerialActiveMessageP() as AM, SerialDispatcherC;
components SerialPacketInfoActiveMessageP as Info;
!
Init = SerialDispatcherC;
Leds = SerialDispatcherC;
!
AMSend = AM;
Receive = AM;
Packet = AM;
AMPacket = AM;
!
AM.SubSend -> SerialDispatcherC.Send[TOS_SERIAL_ACTIVE_MESSAGE_ID];
AM.SubReceive -> SerialDispatcherC.Receive[TOS_SERIAL_ACTIVE_MESSAGE_ID];
!
SerialDispatcherC.SerialPacketInfo[TOS_SERIAL_ACTIVE_MESSAGE_ID] -> Info;
}
--- 593,608 ----
components new SerialActiveMessageP() as AM, SerialDispatcherC;
components SerialPacketInfoActiveMessageP as Info;
!
Init = SerialDispatcherC;
Leds = SerialDispatcherC;
!
AMSend = AM;
Receive = AM;
Packet = AM;
AMPacket = AM;
!
AM.SubSend -> SerialDispatcherC.Send[TOS_SERIAL_ACTIVE_MESSAGE_ID];
AM.SubReceive -> SerialDispatcherC.Receive[TOS_SERIAL_ACTIVE_MESSAGE_ID];
!
SerialDispatcherC.SerialPacketInfo[TOS_SERIAL_ACTIVE_MESSAGE_ID] -> Info;
}
***************
*** 630,635 ****
</pre>
</div>
! <div class="section" id="packet-format">
! <h2><a name="packet-format">3.6 Packet Format</a></h2>
<p>A data packet in the TinyOS 2.x serial stack has the following format
over the wire. Each protocol field is associated with a specific component:</p>
--- 625,630 ----
</pre>
</div>
! <div class="section">
! <h2><a id="packet-format" name="packet-format">3.6 Packet Format</a></h2>
<p>A data packet in the TinyOS 2.x serial stack has the following format
over the wire. Each protocol field is associated with a specific component:</p>
***************
*** 637,644 ****
____________________________________________
| | | | | | | |
! | | | | | | | |
|_|_|_|_|_______________________________|__|_|
F P S D Payload CR F
!
F = Framing byte, denoting start of packet: HdlcTranslateC
P = Protocol byte: SerialP
--- 632,639 ----
____________________________________________
| | | | | | | |
! | | | | | | | |
|_|_|_|_|_______________________________|__|_|
F P S D Payload CR F
!
F = Framing byte, denoting start of packet: HdlcTranslateC
P = Protocol byte: SerialP
***************
*** 659,664 ****
</div>
</div>
! <div class="section" id="access-abstractions">
! <h1><a name="access-abstractions">4. Access Abstractions</a></h1>
<p>Two generic components: SerialAMSenderC and SerialAMReceiverC connect
to SerialActiveMessageC to provide virtualized access to the serial
--- 654,659 ----
</div>
</div>
! <div class="section">
! <h1><a id="access-abstractions" name="access-abstractions">4. Access Abstractions</a></h1>
<p>Two generic components: SerialAMSenderC and SerialAMReceiverC connect
to SerialActiveMessageC to provide virtualized access to the serial
***************
*** 674,679 ****
no snooping capabilities.</p>
</div>
! <div class="section" id="author-s-address">
! <h1><a name="author-s-address">5. Author's Address</a></h1>
<div class="line-block">
<div class="line">Philip Levis</div>
--- 669,674 ----
no snooping capabilities.</p>
</div>
! <div class="section">
! <h1><a id="author-s-address" name="author-s-address">5. Author's Address</a></h1>
<div class="line-block">
<div class="line">Philip Levis</div>
***************
*** 696,701 ****
</div>
</div>
! <div class="section" id="citations">
! <h1><a name="citations">6. Citations</a></h1>
<table class="docutils citation" frame="void" id="tep2" rules="none">
<colgroup><col class="label" /><col /></colgroup>
--- 691,696 ----
</div>
</div>
! <div class="section">
! <h1><a id="citations" name="citations">6. Citations</a></h1>
<table class="docutils citation" frame="void" id="tep2" rules="none">
<colgroup><col class="label" /><col /></colgroup>
Index: tep123.html
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/doc/html/tep123.html,v
retrieving revision 1.9
retrieving revision 1.10
diff -C2 -d -r1.9 -r1.10
*** tep123.html 21 Apr 2007 07:04:39 -0000 1.9
--- tep123.html 14 Aug 2007 18:57:59 -0000 1.10
***************
*** 4,8 ****
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
! <meta name="generator" content="Docutils 0.3.6: http://docutils.sourceforge.net/" />
<title>The Collection Tree Protocol (CTP)</title>
<meta name="author" content="Rodrigo Fonseca, Omprakash Gnawali, Kyle Jamieson, Sukun Kim, Philip Levis, and Alec Woo" />
--- 4,8 ----
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
! <meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
<title>The Collection Tree Protocol (CTP)</title>
<meta name="author" content="Rodrigo Fonseca, Omprakash Gnawali, Kyle Jamieson, Sukun Kim, Philip Levis, and Alec Woo" />
***************
*** 42,50 ****
margin-bottom: 0.5em }
- /* Uncomment (& remove this text!) to get bold-faced definition list terms
- dt {
- font-weight: bold }
- */
-
div.abstract {
margin: 2em 5em }
--- 42,45 ----
***************
*** 284,287 ****
--- 279,283 ----
</head>
<body>
+ <div class="document" id="the-collection-tree-protocol-ctp">
<h1 class="title">The Collection Tree Protocol (CTP)</h1>
<table class="docinfo" frame="void" rules="none">
***************
*** 311,315 ****
</tbody>
</table>
- <div class="document" id="the-collection-tree-protocol-ctp">
<div class="note">
<p class="first admonition-title">Note</p>
--- 307,310 ----
***************
*** 319,333 ****
TEP 1.</p>
</div>
! <div class="section" id="abstract">
! <h1><a name="abstract">Abstract</a></h1>
! <p>This memo documents the Collection Tree Protocol (CTP), which
! provides best-effort anycast datagram communication to one of the
collection roots in a network.</p>
</div>
! <div class="section" id="introduction">
! <h1><a name="introduction">1. Introduction</a></h1>
</div>
! <div class="section" id="assumptions-and-limitations">
! <h1><a name="assumptions-and-limitations">2. Assumptions and Limitations</a></h1>
<p>CTP is a tree-based collection protocol. Some number of nodes in a
network advertise themselves as tree roots. Nodes form a set of routing
--- 314,328 ----
TEP 1.</p>
</div>
! <div class="section">
! <h1><a id="abstract" name="abstract">Abstract</a></h1>
! <p>This memo documents the Collection Tree Protocol (CTP), which
! provides best-effort anycast datagram communication to one of the
collection roots in a network.</p>
</div>
! <div class="section">
! <h1><a id="introduction" name="introduction">1. Introduction</a></h1>
</div>
! <div class="section">
! <h1><a id="assumptions-and-limitations" name="assumptions-and-limitations">2. Assumptions and Limitations</a></h1>
<p>CTP is a tree-based collection protocol. Some number of nodes in a
network advertise themselves as tree roots. Nodes form a set of routing
***************
*** 346,351 ****
</ol>
</blockquote>
! <p>CTP assumes that it has link quality estimates of some number of nearby
! neighbors. These provide an estimate of the number of transmissions it
takes for the node to send a unicast packet whose acknowledgment is
successfully received.</p>
--- 341,346 ----
</ol>
</blockquote>
! <p>CTP assumes that it has link quality estimates of some number of nearby
! neighbors. These provide an estimate of the number of transmissions it
takes for the node to send a unicast packet whose acknowledgment is
successfully received.</p>
***************
*** 357,362 ****
multiple small frames into a single data-link packet.</p>
</div>
! <div class="section" id="collection-and-ctp">
! <h1><a name="collection-and-ctp">3. Collection and CTP</a></h1>
<p>CTP uses expected transmissions (ETX) as its routing gradient. A root
has an ETX of 0. The ETX of a node is the ETX of its parent plus the
--- 352,357 ----
multiple small frames into a single data-link packet.</p>
</div>
! <div class="section">
! <h1><a id="collection-and-ctp" name="collection-and-ctp">3. Collection and CTP</a></h1>
<p>CTP uses expected transmissions (ETX) as its routing gradient. A root
has an ETX of 0. The ETX of a node is the ETX of its parent plus the
***************
*** 399,408 ****
to do so.</p>
</div>
! <div class="section" id="ctp-data-frame">
! <h1><a name="ctp-data-frame">4. CTP Data Frame</a></h1>
<p>The CTP data frame format is as follows:</p>
<pre class="literal-block">
! 1
! 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|P|C| reserved | THL |
--- 394,403 ----
to do so.</p>
</div>
! <div class="section">
! <h1><a id="ctp-data-frame" name="ctp-data-frame">4. CTP Data Frame</a></h1>
<p>The CTP data frame format is as follows:</p>
<pre class="literal-block">
! 1
! 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|P|C| reserved | THL |
***************
*** 410,418 ****
| ETX |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
! | origin |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
! | seqno | collect_id |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
! | data ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
</pre>
--- 405,413 ----
| ETX |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
! | origin |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
! | seqno | collect_id |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
! | data ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
</pre>
***************
*** 430,434 ****
</ul>
</blockquote>
! <p>Together, the origin, seqno and collect_id fields denote a unique
<strong>*origin packet.*</strong> Together, the origin, seqno, collect_id, and
THL denote a unique <strong>*packet instance*</strong> within the network. The
--- 425,429 ----
</ul>
</blockquote>
! <p>Together, the origin, seqno and collect_id fields denote a unique
<strong>*origin packet.*</strong> Together, the origin, seqno, collect_id, and
THL denote a unique <strong>*packet instance*</strong> within the network. The
***************
*** 439,457 ****
will route succesfully in the presence of transient loops unless the
THL happens to wrap around to a forwarded packet instance.</p>
! <p>A node MUST send CTP data frames as unicast messages with link-layer
acknowledgments enabled.</p>
</div>
! <div class="section" id="ctp-routing-frame">
! <h1><a name="ctp-routing-frame">5. CTP Routing Frame</a></h1>
<p>The CTP routing frame format is as follows:</p>
<pre class="literal-block">
! 1
! 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|P|C| reserved | parent |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
! | parent | ETX |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
! | ETX |
+-+-+-+-+-+-+-+-+
</pre>
--- 434,452 ----
will route succesfully in the presence of transient loops unless the
THL happens to wrap around to a forwarded packet instance.</p>
! <p>A node MUST send CTP data frames as unicast messages with link-layer
acknowledgments enabled.</p>
</div>
! <div class="section">
! <h1><a id="ctp-routing-frame" name="ctp-routing-frame">5. CTP Routing Frame</a></h1>
<p>The CTP routing frame format is as follows:</p>
<pre class="literal-block">
! 1
! 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|P|C| reserved | parent |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
! | parent | ETX |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
! | ETX |
+-+-+-+-+-+-+-+-+
</pre>
***************
*** 475,480 ****
future.</p>
</div>
! <div class="section" id="implementation">
! <h1><a name="implementation">6. Implementation</a></h1>
<p>An implementation of CTP can be found in the tos/lib/net/ctp directory
of TinyOS 2.0. This section describes the structure of that implementation
--- 470,475 ----
future.</p>
</div>
! <div class="section">
! <h1><a id="implementation" name="implementation">6. Implementation</a></h1>
<p>An implementation of CTP can be found in the tos/lib/net/ctp directory
of TinyOS 2.0. This section describes the structure of that implementation
***************
*** 490,495 ****
misleading: the forwarding engine is responsible for forwarded traffic
as well as traffic generated on the node.</p>
! <div class="section" id="link-estimation">
! <h2><a name="link-estimation">6.1 Link Estimation</a></h2>
<p>The implementation uses two mechanisms to estimate the quality of a link:
periodic LEEP <a class="footnote-reference" href="#id4" id="id1" name="id1">[1]</a> packets and data packets. The implementation sends
--- 485,490 ----
misleading: the forwarding engine is responsible for forwarded traffic
as well as traffic generated on the node.</p>
! <div class="section">
! <h2><a id="link-estimation" name="link-estimation">6.1 Link Estimation</a></h2>
<p>The implementation uses two mechanisms to estimate the quality of a link:
periodic LEEP <a class="footnote-reference" href="#id4" id="id1" name="id1">[1]</a> packets and data packets. The implementation sends
***************
*** 516,520 ****
them into an exponentially weighted moving average. Beacon-based
estimates seed the neighbor table. The expectation is that the low
! beacon rate in a stable network means that for a selected route,
data estimates will outweigh beacon estimates. Additionally, as
the rate at which CTP collects data estimates is proportional to
--- 511,515 ----
them into an exponentially weighted moving average. Beacon-based
estimates seed the neighbor table. The expectation is that the low
! beacon rate in a stable network means that for a selected route,
data estimates will outweigh beacon estimates. Additionally, as
the rate at which CTP collects data estimates is proportional to
***************
*** 524,529 ****
link estimator. It couples LEEP-based and data-based estimates.</p>
</div>
! <div class="section" id="routing-engine">
! <h2><a name="routing-engine">6.2 Routing Engine</a></h2>
<p>The implementation's routing engine is responsible for picking the next
hop for a data transmission. It keeps track of the path ETX values of
--- 519,524 ----
link estimator. It couples LEEP-based and data-based estimates.</p>
</div>
! <div class="section">
! <h2><a id="routing-engine" name="routing-engine">6.2 Routing Engine</a></h2>
<p>The implementation's routing engine is responsible for picking the next
hop for a data transmission. It keeps track of the path ETX values of
***************
*** 534,539 ****
implements the routing engine.</p>
</div>
! <div class="section" id="forwarding-engine">
! <h2><a name="forwarding-engine">6.3 Forwarding Engine</a></h2>
<p>The component <tt class="docutils literal"><span class="pre">tos/lib/net/ctp/CtpForwardingEngineP</span></tt> implements the
forwarding engine. It has five repsonsibilities:</p>
--- 529,534 ----
implements the routing engine.</p>
</div>
! <div class="section">
! <h2><a id="forwarding-engine" name="forwarding-engine">6.3 Forwarding Engine</a></h2>
<p>The component <tt class="docutils literal"><span class="pre">tos/lib/net/ctp/CtpForwardingEngineP</span></tt> implements the
forwarding engine. It has five repsonsibilities:</p>
***************
*** 576,583 ****
</div>
</div>
! <div class="section" id="citations">
! <h1><a name="citations">7. Citations</a></h1>
<div class="line-block">
! <div class="line">Rodrigo Fonseca </div>
<div class="line">473 Soda Hall</div>
<div class="line">Berkeley, CA 94720-1776</div>
--- 571,578 ----
</div>
</div>
! <div class="section">
! <h1><a id="citations" name="citations">7. Citations</a></h1>
<div class="line-block">
! <div class="line">Rodrigo Fonseca</div>
<div class="line">473 Soda Hall</div>
<div class="line">Berkeley, CA 94720-1776</div>
***************
*** 588,594 ****
<div class="line"><br /></div>
<div class="line">Omprakash Gnawali</div>
! <div class="line">Ronald Tutor Hall (RTH) 418 </div>
<div class="line">3710 S. McClintock Avenue</div>
! <div class="line">Los Angeles, CA 90089 </div>
<div class="line"><br /></div>
<div class="line">phone - +1 213 821-5627</div>
--- 583,589 ----
<div class="line"><br /></div>
<div class="line">Omprakash Gnawali</div>
! <div class="line">Ronald Tutor Hall (RTH) 418</div>
<div class="line">3710 S. McClintock Avenue</div>
! <div class="line">Los Angeles, CA 90089</div>
<div class="line"><br /></div>
<div class="line">phone - +1 213 821-5627</div>
***************
*** 599,603 ****
<div class="line">The Stata Center</div>
<div class="line">32 Vassar St.</div>
! <div class="line">Cambridge, MA 02139 </div>
<div class="line"><br /></div>
<div class="line">email - <a class="reference" href="mailto:jamieson@csail.mit.edu">jamieson@csail.mit.edu</a></div>
--- 594,598 ----
<div class="line">The Stata Center</div>
<div class="line">32 Vassar St.</div>
! <div class="line">Cambridge, MA 02139</div>
<div class="line"><br /></div>
<div class="line">email - <a class="reference" href="mailto:jamieson@csail.mit.edu">jamieson@csail.mit.edu</a></div>
***************
*** 614,619 ****
</div>
</div>
! <div class="section" id="id3">
! <h1><a name="id3">8. Citations</a></h1>
<table class="docutils footnote" frame="void" id="id4" rules="none">
<colgroup><col class="label" /><col /></colgroup>
--- 609,614 ----
</div>
</div>
! <div class="section">
! <h1><a id="id3" name="id3">8. Citations</a></h1>
<table class="docutils footnote" frame="void" id="id4" rules="none">
<colgroup><col class="label" /><col /></colgroup>
Index: tep126.html
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/doc/html/tep126.html,v
retrieving revision 1.2
retrieving revision 1.3
diff -C2 -d -r1.2 -r1.3
*** tep126.html 21 Apr 2007 07:04:39 -0000 1.2
--- tep126.html 14 Aug 2007 18:57:59 -0000 1.3
***************
*** 4,8 ****
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
! <meta name="generator" content="Docutils 0.3.6: http://docutils.sourceforge.net/" />
<title>CC2420 Radio Stack</title>
<meta name="author" content="David Moss, Jonathan Hui, Philip Levis, and Jung Il Choi" />
--- 4,8 ----
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
! <meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
<title>CC2420 Radio Stack</title>
[...1295 lines suppressed...]
</tbody>
</table>
! <table class="docutils footnote" frame="void" id="id13" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
! <tr><td class="label"><a name="id13">[3]</a></td><td><em>(<a class="fn-backref" href="#id4">1</a>, <a class="fn-backref" href="#id9">2</a>)</em> IEEE 802.15.4 Specification: <a class="reference" href="http://standards.ieee.org/getieee802/802.15.html">http://standards.ieee.org/getieee802/802.15.html</a></td></tr>
</tbody>
</table>
! <table class="docutils footnote" frame="void" id="id14" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
! <tr><td class="label"><a class="fn-backref" href="#id5" name="id14">[4]</a></td><td>TEP105: Low Power Listening</td></tr>
</tbody>
</table>
! <table class="docutils footnote" frame="void" id="id15" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
! <tr><td class="label"><a name="id15">[5]</a></td><td><em>(<a class="fn-backref" href="#id6">1</a>, <a class="fn-backref" href="#id7">2</a>)</em> TEP125: TinyOS 802.15.4 Frames</td></tr>
</tbody>
</table>
Index: tep1.html
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/doc/html/tep1.html,v
retrieving revision 1.10
retrieving revision 1.11
diff -C2 -d -r1.10 -r1.11
*** tep1.html 11 Jul 2007 16:13:08 -0000 1.10
--- tep1.html 14 Aug 2007 18:57:59 -0000 1.11
***************
*** 4,8 ****
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
! <meta name="generator" content="Docutils 0.3.7: http://docutils.sourceforge.net/" />
<title>TEP Structure and Keywords</title>
<meta name="author" content="Philip Levis" />
--- 4,8 ----
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
! <meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
<title>TEP Structure and Keywords</title>
<meta name="author" content="Philip Levis" />
***************
*** 42,50 ****
margin-bottom: 0.5em }
- /* Uncomment (& remove this text!) to get bold-faced definition list terms
- dt {
- font-weight: bold }
- */
-
div.abstract {
margin: 2em 5em }
--- 42,45 ----
***************
*** 310,321 ****
improvements. Distribution of this memo is unlimited.</p>
</div>
! <div class="section" id="abstract">
! <h1><a name="abstract">Abstract</a></h1>
<p>This memo describes the structure all TinyOS Extension Proposal (TEP)
documents follow, and defines the meaning of several key words in
those documents.</p>
</div>
! <div class="section" id="introduction">
! <h1><a name="introduction">1. Introduction</a></h1>
<p>In order to simplify management, reading, and tracking development,
all TinyOS Extension Proposals (TEPs) MUST have a particular
--- 305,316 ----
improvements. Distribution of this memo is unlimited.</p>
</div>
! <div class="section">
! <h1><a id="abstract" name="abstract">Abstract</a></h1>
<p>This memo describes the structure all TinyOS Extension Proposal (TEP)
documents follow, and defines the meaning of several key words in
those documents.</p>
</div>
! <div class="section">
! <h1><a id="introduction" name="introduction">1. Introduction</a></h1>
<p>In order to simplify management, reading, and tracking development,
all TinyOS Extension Proposals (TEPs) MUST have a particular
***************
*** 325,330 ****
describes and follows both.</p>
</div>
! <div class="section" id="keywords">
! <h1><a name="keywords">2. Keywords</a></h1>
<p>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
--- 320,325 ----
describes and follows both.</p>
</div>
! <div class="section">
! <h1><a id="keywords" name="keywords">2. Keywords</a></h1>
<p>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
***************
*** 334,349 ****
special meanings only when capitalized, and documents SHOULD avoid using
these words uncapitalized in order to minimize confusion.</p>
! <div class="section" id="must">
! <h2><a name="must">2.1 MUST</a></h2>
<p>MUST: This word, or the terms "REQUIRED" or "SHALL", mean that the
definition is an absolute requirement of the specification.</p>
</div>
! <div class="section" id="must-not">
! <h2><a name="must-not">2.2 MUST NOT</a></h2>
<p>MUST NOT: This phrase, or the phrase "SHALL NOT", mean that the
definition is an absolute prohibition of the specification.</p>
</div>
! <div class="section" id="should">
! <h2><a name="should">2.3 SHOULD</a></h2>
<p>SHOULD: This word, or the adjective "RECOMMENDED", mean that there
may exist valid reasons in particular circumstances to ignore a
--- 329,344 ----
special meanings only when capitalized, and documents SHOULD avoid using
these words uncapitalized in order to minimize confusion.</p>
! <div class="section">
! <h2><a id="must" name="must">2.1 MUST</a></h2>
<p>MUST: This word, or the terms "REQUIRED" or "SHALL", mean that the
definition is an absolute requirement of the specification.</p>
</div>
! <div class="section">
! <h2><a id="must-not" name="must-not">2.2 MUST NOT</a></h2>
<p>MUST NOT: This phrase, or the phrase "SHALL NOT", mean that the
definition is an absolute prohibition of the specification.</p>
</div>
! <div class="section">
! <h2><a id="should" name="should">2.3 SHOULD</a></h2>
<p>SHOULD: This word, or the adjective "RECOMMENDED", mean that there
may exist valid reasons in particular circumstances to ignore a
***************
*** 351,356 ****
carefully weighed before choosing a different course.</p>
</div>
! <div class="section" id="should-not">
! <h2><a name="should-not">2.4 SHOULD NOT</a></h2>
<p>SHOULD NOT: This phrase, or the phrase "NOT RECOMMENDED" mean that
there may exist valid reasons in particular circumstances when the
--- 346,351 ----
carefully weighed before choosing a different course.</p>
</div>
! <div class="section">
! <h2><a id="should-not" name="should-not">2.4 SHOULD NOT</a></h2>
<p>SHOULD NOT: This phrase, or the phrase "NOT RECOMMENDED" mean that
there may exist valid reasons in particular circumstances when the
***************
*** 359,364 ****
before implementing any behavior described with this label.</p>
</div>
! <div class="section" id="may">
! <h2><a name="may">2.5 MAY</a></h2>
<p>MAY: This word, or the adjective "OPTIONAL", mean that an item is
truly optional. One implementer may choose to include the item
--- 354,359 ----
before implementing any behavior described with this label.</p>
</div>
! <div class="section">
! <h2><a id="may" name="may">2.5 MAY</a></h2>
<p>MAY: This word, or the adjective "OPTIONAL", mean that an item is
truly optional. One implementer may choose to include the item
***************
*** 373,378 ****
course, for the feature the option provides.)</p>
</div>
! <div class="section" id="guidance-in-the-use-of-these-imperatives">
! <h2><a name="guidance-in-the-use-of-these-imperatives">2.6 Guidance in the use of these Imperatives</a></h2>
<p>Imperatives of the type defined in this memo must be used with care
and sparingly. In particular, they MUST only be used where it is
--- 368,373 ----
course, for the feature the option provides.)</p>
</div>
! <div class="section">
! <h2><a id="guidance-in-the-use-of-these-imperatives" name="guidance-in-the-use-of-these-imperatives">2.6 Guidance in the use of these Imperatives</a></h2>
<p>Imperatives of the type defined in this memo must be used with care
and sparingly. In particular, they MUST only be used where it is
***************
*** 384,397 ****
</div>
</div>
! <div class="section" id="tep-structure">
! <h1><a name="tep-structure">3. TEP Structure</a></h1>
<p>TEPs have two major parts, a header and a body. The header states
! document metadata, for management and status. The body contains the
content of the proposal.</p>
<p>All TEPs MUST conform to reStructuredText standards <a class="footnote-reference" href="#id2" id="id1" name="id1">[1]</a> and follow
the docutils template, to enable translation from reStructuredText
to HTML and LaTeX.</p>
! <div class="section" id="tep-header">
! <h2><a name="tep-header">3.1 TEP Header</a></h2>
<p>The TEP header has several fields which MUST be included, as well as
others which MAY be included. The TEP header MUST NOT include headers
--- 379,392 ----
</div>
</div>
! <div class="section">
! <h1><a id="tep-structure" name="tep-structure">3. TEP Structure</a></h1>
<p>TEPs have two major parts, a header and a body. The header states
! document metadata, for management and status. The body contains the
content of the proposal.</p>
<p>All TEPs MUST conform to reStructuredText standards <a class="footnote-reference" href="#id2" id="id1" name="id1">[1]</a> and follow
the docutils template, to enable translation from reStructuredText
to HTML and LaTeX.</p>
! <div class="section">
! <h2><a id="tep-header" name="tep-header">3.1 TEP Header</a></h2>
<p>The TEP header has several fields which MUST be included, as well as
others which MAY be included. The TEP header MUST NOT include headers
***************
*** 400,404 ****
included in all TEPs, in the order stated here.</p>
<p>The first field is "TEP," and specifies the TEP number of the
! document. A TEP's number is unique.. This document is TEP 1. The
TEP type (discussed below) determines TEP number assignment. Generally,
when a document is ready to be a TEP, it is assigned the smallest
--- 395,399 ----
included in all TEPs, in the order stated here.</p>
<p>The first field is "TEP," and specifies the TEP number of the
! document. A TEP's number is unique.. This document is TEP 1. The
TEP type (discussed below) determines TEP number assignment. Generally,
when a document is ready to be a TEP, it is assigned the smallest
***************
*** 417,421 ****
<p>Documentary TEPs describe a system or protocol that exists; a
documentary TEP MUST reference an implementation that a reader can
! easily obtain. Documentary TEPs simplify interoperability when
needed, and document TinyOS service implementations.</p>
<p>Informational TEPs provide information that is of interest to the
--- 412,416 ----
<p>Documentary TEPs describe a system or protocol that exists; a
documentary TEP MUST reference an implementation that a reader can
! easily obtain. Documentary TEPs simplify interoperability when
needed, and document TinyOS service implementations.</p>
<p>Informational TEPs provide information that is of interest to the
***************
*** 426,434 ****
<p>Experimental TEPs describe a completely experimental approach to a
problem, which are outside the TinyOS core and will not necessarily
! become part of it. Unlike Documentary TEPs, Experimental TEPs may
describe systems that do not have a reference implementation.</p>
<p>The fourth field is "Status," which specifies the status of the TEP.
A TEP status can either be "Draft," which means it is a work in
! progress, "Final," which means it is complete and will not change.
Once a TEP has the status "Final," the only change allowed is the
addition of an "Obsoleted By" field.</p>
--- 421,429 ----
<p>Experimental TEPs describe a completely experimental approach to a
problem, which are outside the TinyOS core and will not necessarily
! become part of it. Unlike Documentary TEPs, Experimental TEPs may
describe systems that do not have a reference implementation.</p>
<p>The fourth field is "Status," which specifies the status of the TEP.
A TEP status can either be "Draft," which means it is a work in
! progress, "Final," which means it is complete and will not change.
Once a TEP has the status "Final," the only change allowed is the
addition of an "Obsoleted By" field.</p>
***************
*** 458,462 ****
another TEP. The purpose of this field is to denote when a TEP represents
an addition to an existing TEP. Meeting the requirements of a TEP with an
! Extends field requires also meeting the requirements of all TEPs listed
in the Extends field.</p>
<p>If a TEP is a Draft, then four additional fields MUST be included:
--- 453,457 ----
another TEP. The purpose of this field is to denote when a TEP represents
an addition to an existing TEP. Meeting the requirements of a TEP with an
! Extends field requires also meeting the requirements of all TEPs listed
in the Extends field.</p>
<p>If a TEP is a Draft, then four additional fields MUST be included:
***************
*** 469,474 ****
have these fields, which are for Drafts only.</p>
</div>
! <div class="section" id="tep-body">
! <h2><a name="tep-body">3.2 TEP Body</a></h2>
<p>The first element of the TEP body MUST be the title of the document. A
TEP SHOULD follow the title with an Abstract, which gives a brief
--- 464,469 ----
have these fields, which are for Drafts only.</p>
</div>
! <div class="section">
! <h2><a id="tep-body" name="tep-body">3.2 TEP Body</a></h2>
<p>The first element of the TEP body MUST be the title of the document. A
TEP SHOULD follow the title with an Abstract, which gives a brief
***************
*** 493,511 ****
</div>
</div>
! <div class="section" id="reference">
! <h1><a name="reference">4. Reference</a></h1>
<p>The reference use of this document is TEP 1 (itself).</p>
</div>
! <div class="section" id="acknowledgments">
! <h1><a name="acknowledgments">5. Acknowledgments</a></h1>
<p>The definitions of the compliance terms are a direct copy of
definitions taken from IETF RFC 2119.</p>
</div>
! <div class="section" id="author-s-address">
! <h1><a name="author-s-address">6. Author's Address</a></h1>
<div class="line-block">
<div class="line">Philip Levis</div>
<div class="line">358 Gates Hall</div>
! <div class="line">Stanford University </div>
<div class="line">Stanford, CA 94305</div>
<div class="line"><br /></div>
--- 488,506 ----
</div>
</div>
! <div class="section">
! <h1><a id="reference" name="reference">4. Reference</a></h1>
<p>The reference use of this document is TEP 1 (itself).</p>
</div>
! <div class="section">
! <h1><a id="acknowledgments" name="acknowledgments">5. Acknowledgments</a></h1>
<p>The definitions of the compliance terms are a direct copy of
definitions taken from IETF RFC 2119.</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">Philip Levis</div>
<div class="line">358 Gates Hall</div>
! <div class="line">Stanford University</div>
<div class="line">Stanford, CA 94305</div>
<div class="line"><br /></div>
***************
*** 515,520 ****
</div>
</div>
! <div class="section" id="citations">
! <h1><a name="citations">7. Citations</a></h1>
<table class="docutils footnote" frame="void" id="id2" rules="none">
<colgroup><col class="label" /><col /></colgroup>
--- 510,515 ----
</div>
</div>
! <div class="section">
! <h1><a id="citations" name="citations">7. Citations</a></h1>
<table class="docutils footnote" frame="void" id="id2" rules="none">
<colgroup><col class="label" /><col /></colgroup>
***************
*** 524,529 ****
</table>
</div>
! <div class="section" id="appendix-a-example-appendix">
! <h1><a name="appendix-a-example-appendix">Appendix A. Example Appendix</a></h1>
<p>This is an example appendix. Appendices begin with the letter A.</p>
</div>
--- 519,524 ----
</table>
</div>
! <div class="section">
! <h1><a id="appendix-a-example-appendix" name="appendix-a-example-appendix">Appendix A. Example Appendix</a></h1>
<p>This is an example appendix. Appendices begin with the letter A.</p>
</div>
Index: tep106.html
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/doc/html/tep106.html,v
retrieving revision 1.9
retrieving revision 1.10
diff -C2 -d -r1.9 -r1.10
*** tep106.html 21 Apr 2007 07:04:39 -0000 1.9
--- tep106.html 14 Aug 2007 18:57:59 -0000 1.10
***************
*** 4,8 ****
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
! <meta name="generator" content="Docutils 0.3.6: http://docutils.sourceforge.net/" />
<title>Schedulers and Tasks</title>
<meta name="author" content="Philip Levis and Cory Sharp" />
--- 4,8 ----
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
! <meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
<title>Schedulers and Tasks</title>
<meta name="author" content="Philip Levis and Cory Sharp" />
***************
*** 42,50 ****
margin-bottom: 0.5em }
- /* Uncomment (& remove this text!) to get bold-faced definition list terms
- dt {
- font-weight: bold }
- */
-
div.abstract {
margin: 2em 5em }
--- 42,45 ----
***************
*** 284,287 ****
--- 279,283 ----
</head>
<body>
+ <div class="document" id="schedulers-and-tasks">
<h1 class="title">Schedulers and Tasks</h1>
<table class="docinfo" frame="void" rules="none">
***************
*** 303,307 ****
</tbody>
</table>
- <div class="document" id="schedulers-and-tasks">
<div class="note">
<p class="first admonition-title">Note</p>
--- 299,302 ----
***************
*** 311,321 ****
TEP 1.</p>
</div>
! <div class="section" id="abstract">
! <h1><a name="abstract">Abstract</a></h1>
<p>This memo documents the structure and implementation of tasks
and task schedulers in TinyOS 2.x.</p>
</div>
! <div class="section" id="introduction">
! <h1><a name="introduction">1. Introduction</a></h1>
<p>TinyOS has two basic computational abstractions: asynchronous events
and tasks. Early versions of TinyOS provided a single type of task --
--- 306,316 ----
TEP 1.</p>
</div>
! <div class="section">
! <h1><a id="abstract" name="abstract">Abstract</a></h1>
<p>This memo documents the structure and implementation of tasks
and task schedulers in TinyOS 2.x.</p>
</div>
! <div class="section">
! <h1><a id="introduction" name="introduction">1. Introduction</a></h1>
<p>TinyOS has two basic computational abstractions: asynchronous events
and tasks. Early versions of TinyOS provided a single type of task --
***************
*** 329,334 ****
greatly increases system dependability.</p>
</div>
! <div class="section" id="tasks-and-the-scheduler-in-tinyos-1-x">
! <h1><a name="tasks-and-the-scheduler-in-tinyos-1-x">2. Tasks and the Scheduler in TinyOS 1.x</a></h1>
<p>Tasks in TinyOS are a form of deferred procedure call (DPC) <a class="footnote-reference" href="#id5" id="id1" name="id1">[1]</a>, which
enable a program to defer a computation or operation until a later
--- 324,329 ----
greatly increases system dependability.</p>
</div>
! <div class="section">
! <h1><a id="tasks-and-the-scheduler-in-tinyos-1-x" name="tasks-and-the-scheduler-in-tinyos-1-x">2. Tasks and the Scheduler in TinyOS 1.x</a></h1>
<p>Tasks in TinyOS are a form of deferred procedure call (DPC) <a class="footnote-reference" href="#id5" id="id1" name="id1">[1]</a>, which
enable a program to defer a computation or operation until a later
***************
*** 341,346 ****
<pre class="literal-block">
task void computeTask() {
! // Code here
! }
</pre>
<p>and:</p>
--- 336,341 ----
<pre class="literal-block">
task void computeTask() {
! // Code here
! }
</pre>
<p>and:</p>
***************
*** 399,424 ****
buffer). As the <tt class="docutils literal"><span class="pre">sendDone()</span></tt> event was lost, this does not occur,
and the application stops sending network traffic.</p>
! <p>The solution to this particular problem in TinyOS 1.x is to signal
! sendDone() in the radio send complete interrupt if the post fails:
! this violates the sync/async boundary, but the justification is that
! a <em>possible</em> rare race condition is better than <em>certain</em> failure.
Another solution would be to use an interrupt source to periodically
retry posting the task; while this does not break the sync/async
! boundary, until the post succeeds the system cannot send packets.
The TinyOS 1.x model prevents it from doing any better.</p>
</div>
! <div class="section" id="tasks-in-tinyos-2-x">
! <h1><a name="tasks-in-tinyos-2-x">3. Tasks in TinyOS 2.x</a></h1>
<p>The semantics of tasks in TinyOS 2.x are different than those in 1.x.
This change is based on experiences with the limitations and run time
errors that the 1.x model introduces. <strong>In TinyOS 2.x, a basic post will
! only fail if and only if the task has already been posted and has not
! started execution.</strong> A task can always run, but can only have one
outstanding post at any time.</p>
<p>2.x achieves these semantics by allocating one
byte of state per task (the assumption is that there will be fewer than 255
! tasks in the system). While a very large number of tasks could make
this overhead noticable, it is not significant in practice.
! If a component needs to post a task several times, then the end of
the task logic can repost itself as need be.</p>
<p>For example, one can do this:</p>
--- 394,419 ----
buffer). As the <tt class="docutils literal"><span class="pre">sendDone()</span></tt> event was lost, this does not occur,
and the application stops sending network traffic.</p>
! <p>The solution to this particular problem in TinyOS 1.x is to signal
! sendDone() in the radio send complete interrupt if the post fails:
! this violates the sync/async boundary, but the justification is that
! a <em>possible</em> rare race condition is better than <em>certain</em> failure.
Another solution would be to use an interrupt source to periodically
retry posting the task; while this does not break the sync/async
! boundary, until the post succeeds the system cannot send packets.
The TinyOS 1.x model prevents it from doing any better.</p>
</div>
! <div class="section">
! <h1><a id="tasks-in-tinyos-2-x" name="tasks-in-tinyos-2-x">3. Tasks in TinyOS 2.x</a></h1>
<p>The semantics of tasks in TinyOS 2.x are different than those in 1.x.
This change is based on experiences with the limitations and run time
errors that the 1.x model introduces. <strong>In TinyOS 2.x, a basic post will
! only fail if and only if the task has already been posted and has not
! started execution.</strong> A task can always run, but can only have one
outstanding post at any time.</p>
<p>2.x achieves these semantics by allocating one
byte of state per task (the assumption is that there will be fewer than 255
! tasks in the system). While a very large number of tasks could make
this overhead noticable, it is not significant in practice.
! If a component needs to post a task several times, then the end of
the task logic can repost itself as need be.</p>
<p>For example, one can do this:</p>
***************
*** 430,434 ****
if (moreToProcess) {
post processTask();
! }
}
</pre>
--- 425,429 ----
if (moreToProcess) {
post processTask();
! }
}
</pre>
***************
*** 448,460 ****
to take an integer parameter could look like this:</p>
<pre class="literal-block">
! interface TaskParameter {
! async error_t command postTask(uint16_t param);
! event void runTask(uint16_t param);
! }
</pre>
<p>Using this task interface, a component could post a task with a
<tt class="docutils literal"><span class="pre">uint16_t</span></tt> parameter. When the scheduler runs the task, it will
signal the <tt class="docutils literal"><span class="pre">runTask</span></tt> event with the passed parameter, which contains
! the task's logic. Note, however, that this does not save any RAM:
the scheduler must have RAM allocated for the parameter. Furthermore, as
there can only be one copy of a task outstanding at any time, it
--- 443,455 ----
to take an integer parameter could look like this:</p>
<pre class="literal-block">
! interface TaskParameter {
! async error_t command postTask(uint16_t param);
! event void runTask(uint16_t param);
! }
</pre>
<p>Using this task interface, a component could post a task with a
<tt class="docutils literal"><span class="pre">uint16_t</span></tt> parameter. When the scheduler runs the task, it will
signal the <tt class="docutils literal"><span class="pre">runTask</span></tt> event with the passed parameter, which contains
! the task's logic. Note, however, that this does not save any RAM:
the scheduler must have RAM allocated for the parameter. Furthermore, as
there can only be one copy of a task outstanding at any time, it
***************
*** 476,480 ****
...
task void parameterTask() {
! // use param
}
</pre>
--- 471,475 ----
...
task void parameterTask() {
! // use param
}
</pre>
***************
*** 491,496 ****
</pre>
</div>
! <div class="section" id="the-scheduler-in-tinyos-2-x">
! <h1><a name="the-scheduler-in-tinyos-2-x">4. The Scheduler in TinyOS 2.x</a></h1>
<p>In TinyOS 2.x, the scheduler is a TinyOS component. Every scheduler
MUST support nesC tasks. It MAY also support any number of
--- 486,491 ----
</pre>
</div>
! <div class="section">
! <h1><a id="the-scheduler-in-tinyos-2-x" name="the-scheduler-in-tinyos-2-x">4. The Scheduler in TinyOS 2.x</a></h1>
<p>In TinyOS 2.x, the scheduler is a TinyOS component. Every scheduler
MUST support nesC tasks. It MAY also support any number of
***************
*** 508,534 ****
<p>For example, the standard TinyOS scheduler has this signature:</p>
<pre class="literal-block">
! module SchedulerBasicP {
! provides interface Scheduler;
! provides interface TaskBasic[uint8_t taskID];
! uses interface McuSleep;
! }
</pre>
<p>A scheduler MUST provide a parameterized TaskBasic interface.
If a call to TaskBasic.postTask() returns SUCCESS, the scheduler MUST run it
! eventually, so that starvation is not a concern. The scheduler MUST
return SUCCESS to a TaskBasic.postTask()
operation unless it is not the first call to TaskBasic.postTask() since
! that task's TaskBasic.runTask() event has been signaled. The
McuSleep interface is used for microcontroller power management;
its workings are explained in TEP 112 <a class="footnote-reference" href="#id7" id="id3" name="id3">[3]</a>.</p>
! <p>A scheduler MUST provide the Scheduler interface.
The Scheduler interface has commands for initialization and running
tasks, and is used by TinyOS to execute tasks:</p>
<pre class="literal-block">
! interface Scheduler {
! command void init();
! command bool runNextTask(bool sleep);
! command void taskLoop();
! }
</pre>
<p>The init() command initializes the task queue and scheduler data
--- 503,529 ----
<p>For example, the standard TinyOS scheduler has this signature:</p>
<pre class="literal-block">
! module SchedulerBasicP {
! provides interface Scheduler;
! provides interface TaskBasic[uint8_t taskID];
! uses interface McuSleep;
! }
</pre>
<p>A scheduler MUST provide a parameterized TaskBasic interface.
If a call to TaskBasic.postTask() returns SUCCESS, the scheduler MUST run it
! eventually, so that starvation is not a concern. The scheduler MUST
return SUCCESS to a TaskBasic.postTask()
operation unless it is not the first call to TaskBasic.postTask() since
! that task's TaskBasic.runTask() event has been signaled. The
McuSleep interface is used for microcontroller power management;
its workings are explained in TEP 112 <a class="footnote-reference" href="#id7" id="id3" name="id3">[3]</a>.</p>
! <p>A scheduler MUST provide the Scheduler interface.
The Scheduler interface has commands for initialization and running
tasks, and is used by TinyOS to execute tasks:</p>
<pre class="literal-block">
! interface Scheduler {
! command void init();
! command bool runNextTask(bool sleep);
! command void taskLoop();
! }
</pre>
<p>The init() command initializes the task queue and scheduler data
***************
*** 550,557 ****
<p>This is the TaskBasic interface:</p>
<pre class="literal-block">
! interface TaskBasic {
! async command error_t postTask();
! void event runTask();
! }
</pre>
<p>When a component declares a task with the <tt class="docutils literal"><span class="pre">task</span></tt> keyword in nesC, it
--- 545,552 ----
<p>This is the TaskBasic interface:</p>
<pre class="literal-block">
! interface TaskBasic {
! async command error_t postTask();
! void event runTask();
! }
</pre>
<p>When a component declares a task with the <tt class="docutils literal"><span class="pre">task</span></tt> keyword in nesC, it
***************
*** 559,564 ****
interface: the task body is the runTask event. When a component uses the
<tt class="docutils literal"><span class="pre">post</span></tt> keyword, it calls the postTask command. Each TaskBasic MUST be
! wired to the scheduler with a unique identifier as its parameter.
! The parameter MUST be obtained with the <tt class="docutils literal"><span class="pre">unique</span></tt> function in nesC,
with a key of <tt class="docutils literal"><span class="pre">"TinySchedulerC.TaskBasic"</span></tt>. The nesC compiler
automatically does this wiring when the <tt class="docutils literal"><span class="pre">task</span></tt> and <tt class="docutils literal"><span class="pre">post</span></tt>
--- 554,559 ----
interface: the task body is the runTask event. When a component uses the
<tt class="docutils literal"><span class="pre">post</span></tt> keyword, it calls the postTask command. Each TaskBasic MUST be
! wired to the scheduler with a unique identifier as its parameter.
! The parameter MUST be obtained with the <tt class="docutils literal"><span class="pre">unique</span></tt> function in nesC,
with a key of <tt class="docutils literal"><span class="pre">"TinySchedulerC.TaskBasic"</span></tt>. The nesC compiler
automatically does this wiring when the <tt class="docutils literal"><span class="pre">task</span></tt> and <tt class="docutils literal"><span class="pre">post</span></tt>
***************
*** 573,578 ****
the earlier task posting the later task.</p>
</div>
! <div class="section" id="replacing-the-scheduler">
! <h1><a name="replacing-the-scheduler">5. Replacing the Scheduler</a></h1>
<p>The TinyOS scheduler is presented as a component named TinySchedulerC.
The default TinyOS scheduler implementation is a module named
--- 568,573 ----
the earlier task posting the later task.</p>
</div>
! <div class="section">
! <h1><a id="replacing-the-scheduler" name="replacing-the-scheduler">5. Replacing the Scheduler</a></h1>
<p>The TinyOS scheduler is presented as a component named TinySchedulerC.
The default TinyOS scheduler implementation is a module named
***************
*** 587,591 ****
and task declarations and enables TinyOS core systems to operate
properly. Generally, TinyOS core code needs to be able to run unchanged
! with new scheduler implementations. All scheduler
implementations MUST provide the Scheduler interface.</p>
<p>For example, imagine a hypothetical scheduler that provides earliest
--- 582,586 ----
and task declarations and enables TinyOS core systems to operate
properly. Generally, TinyOS core code needs to be able to run unchanged
! with new scheduler implementations. All scheduler
implementations MUST provide the Scheduler interface.</p>
<p>For example, imagine a hypothetical scheduler that provides earliest
***************
*** 593,609 ****
interface:</p>
<pre class="literal-block">
! interface TaskEdf {
! async command error_t postTask(uint16_t deadlineMs);
! event void runTask();
! }
</pre>
<p>The scheduler implementation is named SchedulerEdfP, and provides both
TaskBasic and TaskEdf interfaces:</p>
<pre class="literal-block">
! module SchedulerEdfP {
! provides interface Scheduler;
! provides interface TaskBasic[uint8_t taskID];
! provides interface TaskEdf[uint8_t taskID];
! }
</pre>
<p>An application that wants to use SchedulerEdfP instead of
--- 588,604 ----
interface:</p>
<pre class="literal-block">
! interface TaskEdf {
! async command error_t postTask(uint16_t deadlineMs);
! event void runTask();
! }
</pre>
<p>The scheduler implementation is named SchedulerEdfP, and provides both
TaskBasic and TaskEdf interfaces:</p>
<pre class="literal-block">
! module SchedulerEdfP {
! provides interface Scheduler;
! provides interface TaskBasic[uint8_t taskID];
! provides interface TaskEdf[uint8_t taskID];
! }
</pre>
<p>An application that wants to use SchedulerEdfP instead of
***************
*** 611,625 ****
exports all of SchedulerEdfP's interfaces:</p>
<pre class="literal-block">
! configuration TinySchedulerC {
! provides interface Scheduler;
! provides interface TaskBasic[uint8_t taskID];
! provides interface TaskEdf[uint8_t taskID];
! }
! implementation {
! components SchedulerEdfP;
! Scheduler = SchedulerEdf;
! TaskBasic = SchedulerEdfP;
! TaskEDF = SchedulerEdfP;
! }
</pre>
<p>For a module to have an earliest deadline first task, it uses the
--- 606,620 ----
exports all of SchedulerEdfP's interfaces:</p>
<pre class="literal-block">
! configuration TinySchedulerC {
! provides interface Scheduler;
! provides interface TaskBasic[uint8_t taskID];
! provides interface TaskEdf[uint8_t taskID];
! }
! implementation {
! components SchedulerEdfP;
! Scheduler = SchedulerEdf;
! TaskBasic = SchedulerEdfP;
! TaskEDF = SchedulerEdfP;
! }
</pre>
<p>For a module to have an earliest deadline first task, it uses the
***************
*** 635,646 ****
tasks:</p>
<pre class="literal-block">
! configuration SomethingC {
! ...
! }
! implementation {
! components SomethingP, TinySchedulerC;
! SomethingP.SendTask -> TinySchedulerC.TaskEdf[unique(UQ_TASK_EDF)];
! SomethingP.SenseTask -> TinySchedulerC.TaskEdf[unique(UQ_TASK_EDF)];
! }
</pre>
<p>The module SomethingP also has a basic task. The nesC compiler
--- 630,641 ----
tasks:</p>
<pre class="literal-block">
! configuration SomethingC {
! ...
! }
! implementation {
! components SomethingP, TinySchedulerC;
! SomethingP.SendTask -> TinySchedulerC.TaskEdf[unique(UQ_TASK_EDF)];
! SomethingP.SenseTask -> TinySchedulerC.TaskEdf[unique(UQ_TASK_EDF)];
! }
</pre>
<p>The module SomethingP also has a basic task. The nesC compiler
***************
*** 652,671 ****
implementation of SomethingP that uses keywords for basic tasks:</p>
<pre class="literal-block">
! module SomethingP {
! uses interface TaskEdf as SendTask
! uses interface TaskEdf as SenseTask
! }
! implementation {
! // The TaskBasic, written with keywords
! task void cleanupTask() { ... some logic ... }
! event void SendTask.runTask() { ... some logic ... }
! event void SenseTask.runTask() { ... some logic ... }
! void internal_function() {
! call SenseTask.postTask(20);
! call SendTask.postTask(100);
! post cleanupTask();
! }
! }
</pre>
<p>The requirement that basic tasks not be subject to starvation
--- 647,666 ----
implementation of SomethingP that uses keywords for basic tasks:</p>
<pre class="literal-block">
! module SomethingP {
! uses interface TaskEdf as SendTask
! uses interface TaskEdf as SenseTask
! }
! implementation {
! // The TaskBasic, written with keywords
! task void cleanupTask() { ... some logic ... }
! event void SendTask.runTask() { ... some logic ... }
! event void SenseTask.runTask() { ... some logic ... }
! void internal_function() {
! call SenseTask.postTask(20);
! call SendTask.postTask(100);
! post cleanupTask();
! }
! }
</pre>
<p>The requirement that basic tasks not be subject to starvation
***************
*** 673,680 ****
basic tasks run eventually even if there is an unending stream of
short deadline tasks to run. Quantifying "eventually" is difficult,
! but a 1% share of the MCU cycles (or invocations) is a reasonable
approximation.</p>
<p>If the scheduler provides two instances of the same task interface,
! their unique keys are based on the name of the interface as the
scheduler presents it (the "as" keyword). For example, imagine
a scheduler which provides two instances of TaskBasic: standard
--- 668,675 ----
basic tasks run eventually even if there is an unending stream of
short deadline tasks to run. Quantifying "eventually" is difficult,
! but a 1% share of the MCU cycles (or invocations) is a reasonable
approximation.</p>
<p>If the scheduler provides two instances of the same task interface,
! their unique keys are based on the name of the interface as the
scheduler presents it (the "as" keyword). For example, imagine
a scheduler which provides two instances of TaskBasic: standard
***************
*** 682,704 ****
for the high priority queue before the standard queue:</p>
<pre class="literal-block">
! configuration TinySchedulerC {
! provides interface Scheduler;
! provides interface TaskBasic[uint8_t taskID];
! provides interface TaskBasic[uint8_t taskID] as TaskHighPriority;
! }
</pre>
<p>It cannot always select a high priority task because that could
! starve basic tasks. A component that uses a high priority task would
wire to TaskHighPriority with the key "TinySchedulerC.TaskHighPriority":</p>
<pre class="literal-block">
! configuration SomethingElseC {}
! implementation {
! components TinySchedulerC as Sched, SomethingElseP;
! SomethingElseP.RetransmitTask -> Sched.TaskHighPriority[unique("TinySchedulerC.TaskHighPriority")];
! }
</pre>
</div>
! <div class="section" id="implementation">
! <h1><a name="implementation">6. Implementation</a></h1>
<p>The following files in <tt class="docutils literal"><span class="pre">tinyos-2.x/tos/system</span></tt> contain the reference
implementations of the scheduler:</p>
--- 677,699 ----
for the high priority queue before the standard queue:</p>
<pre class="literal-block">
! configuration TinySchedulerC {
! provides interface Scheduler;
! provides interface TaskBasic[uint8_t taskID];
! provides interface TaskBasic[uint8_t taskID] as TaskHighPriority;
! }
</pre>
<p>It cannot always select a high priority task because that could
! starve basic tasks. A component that uses a high priority task would
wire to TaskHighPriority with the key "TinySchedulerC.TaskHighPriority":</p>
<pre class="literal-block">
! configuration SomethingElseC {}
! implementation {
! components TinySchedulerC as Sched, SomethingElseP;
! SomethingElseP.RetransmitTask -> Sched.TaskHighPriority[unique("TinySchedulerC.TaskHighPriority")];
! }
</pre>
</div>
! <div class="section">
! <h1><a id="implementation" name="implementation">6. Implementation</a></h1>
<p>The following files in <tt class="docutils literal"><span class="pre">tinyos-2.x/tos/system</span></tt> contain the reference
implementations of the scheduler:</p>
***************
*** 714,719 ****
at the URL <tt class="docutils literal"><span class="pre">http://csl.stanford.edu/~pal/tinyos/edf-sched.tgz.</span></tt></p>
</div>
! <div class="section" id="author-s-address">
! <h1><a name="author-s-address">7. Author's Address</a></h1>
<div class="line-block">
<div class="line">Philip Levis</div>
--- 709,714 ----
at the URL <tt class="docutils literal"><span class="pre">http://csl.stanford.edu/~pal/tinyos/edf-sched.tgz.</span></tt></p>
</div>
! <div class="section">
! <h1><a id="author-s-address" name="author-s-address">7. Author's Address</a></h1>
<div class="line-block">
<div class="line">Philip Levis</div>
***************
*** 722,726 ****
<div class="line">Stanford, CA 94305</div>
<div class="line"><br /></div>
! <div class="line">phone - +1 650 725 9046 </div>
<div class="line">email - <a class="reference" href="mailto:pal@cs.stanford.edu">pal@cs.stanford.edu</a></div>
<div class="line"><br /></div>
--- 717,721 ----
<div class="line">Stanford, CA 94305</div>
<div class="line"><br /></div>
! <div class="line">phone - +1 650 725 9046</div>
<div class="line">email - <a class="reference" href="mailto:pal@cs.stanford.edu">pal@cs.stanford.edu</a></div>
<div class="line"><br /></div>
***************
*** 733,742 ****
</div>
</div>
! <div class="section" id="citations">
! <h1><a name="citations">8. Citations</a></h1>
<table class="docutils footnote" frame="void" id="id5" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
! <tr><td class="label"><a class="fn-backref" href="#id1" name="id5">[1]</a></td><td>Erik Cota-Robles and James P. Held. "A Comparison of Windows
Driver Model Latency Performance on Windows NT and Windows 98." In
<em>Proceedings of the Third Symposium on Operating System Design
--- 728,737 ----
</div>
</div>
! <div class="section">
! <h1><a id="citations" name="citations">8. Citations</a></h1>
<table class="docutils footnote" frame="void" id="id5" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
! <tr><td class="label"><a class="fn-backref" href="#id1" name="id5">[1]</a></td><td>Erik Cota-Robles and James P. Held. "A Comparison of Windows
Driver Model Latency Performance on Windows NT and Windows 98." In
<em>Proceedings of the Third Symposium on Operating System Design
***************
*** 760,765 ****
</table>
</div>
! <div class="section" id="appendix-a-changing-the-scheduler">
! <h1><a name="appendix-a-changing-the-scheduler">Appendix A: Changing the Scheduler</a></h1>
<p>The nesC compiler transforms the post and task keywords into
nesC interfaces, wirings, and calls. By default, the statement:</p>
--- 755,760 ----
</table>
</div>
! <div class="section">
! <h1><a id="appendix-a-changing-the-scheduler" name="appendix-a-changing-the-scheduler">Appendix A: Changing the Scheduler</a></h1>
<p>The nesC compiler transforms the post and task keywords into
nesC interfaces, wirings, and calls. By default, the statement:</p>
***************
*** 772,776 ****
...
post x();
! }
}
--- 767,771 ----
...
post x();
! }
}
Index: tep101.html
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/doc/html/tep101.html,v
retrieving revision 1.9
retrieving revision 1.10
diff -C2 -d -r1.9 -r1.10
*** tep101.html 21 Apr 2007 07:04:39 -0000 1.9
--- tep101.html 14 Aug 2007 18:58:00 -0000 1.10
***************
*** 4,8 ****
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
! <meta name="generator" content="Docutils 0.3.6: http://docutils.sourceforge.net/" />
<title>Analog-to-Digital Converters (ADCs)</title>
<meta name="author" content="Jan-Hinrich Hauer, Philip Levis, Vlado Handziski, David Gay" />
--- 4,8 ----
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
! <meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
<title>Analog-to-Digital Converters (ADCs)</title>
<meta name="author" content="Jan-Hinrich Hauer, Philip Levis, Vlado Handziski, David Gay" />
***************
*** 42,50 ****
margin-bottom: 0.5em }
- /* Uncomment (& remove this text!) to get bold-faced definition list terms
- dt {
- font-weight: bold }
- */
-
div.abstract {
margin: 2em 5em }
--- 42,45 ----
***************
*** 284,287 ****
--- 279,283 ----
</head>
<body>
+ <div class="document" id="analog-to-digital-converters-adcs">
<h1 class="title">Analog-to-Digital Converters (ADCs)</h1>
<table class="docinfo" frame="void" rules="none">
***************
*** 303,307 ****
</tbody>
</table>
- <div class="document" id="analog-to-digital-converters-adcs">
<div class="note">
<p class="first admonition-title">Note</p>
--- 299,302 ----
***************
*** 311,316 ****
<a class="citation-reference" href="#tep1" id="id1" name="id1">[TEP1]</a>.</p>
</div>
! <div class="section" id="abstract">
! <h1><a name="abstract">Abstract</a></h1>
<p>This TEP proposes a hardware abstraction for analog-to-digital converters (ADCs)
in TinyOS 2.x, which is aligned to the three-layer Hardware Abstraction
--- 306,311 ----
<a class="citation-reference" href="#tep1" id="id1" name="id1">[TEP1]</a>.</p>
</div>
! <div class="section">
! <h1><a id="abstract" name="abstract">Abstract</a></h1>
<p>This TEP proposes a hardware abstraction for analog-to-digital converters (ADCs)
in TinyOS 2.x, which is aligned to the three-layer Hardware Abstraction
***************
*** 318,323 ****
documents the set of hardware-independent interfaces to an ADC.</p>
</div>
! <div class="section" id="introduction">
! <h1><a name="introduction">1. Introduction</a></h1>
<p>Analog-to-digital converters (ADCs) are devices that convert analog input
signals to discrete digital output signals, typically voltage to a binary
--- 313,318 ----
documents the set of hardware-independent interfaces to an ADC.</p>
</div>
! <div class="section">
! <h1><a id="introduction" name="introduction">1. Introduction</a></h1>
<p>Analog-to-digital converters (ADCs) are devices that convert analog input
signals to discrete digital output signals, typically voltage to a binary
***************
*** 422,429 ****
<li>the set of standard TinyOS interfaces for collecting ADC conversion
results and for configuring an ADC (<a class="reference" href="#interfaces">2. Interfaces</a>)</li>
! <li>guidelines on how an ADC's HAL should expose chip-specific
interfaces (<a class="reference" href="#hal-guidelines">3. HAL guidelines</a>)</li>
<li>what components an ADC's HIL MUST implement (<a class="reference" href="#hil-requirements">4. HIL requirements</a>)</li>
! <li>guidelines on how the HIL should be implemented
(<a class="reference" href="#hil-guidelines">5. HIL guidelines</a>)</li>
<li>a section pointing to current implementations (<a class="reference" href="#implementation">6. Implementation</a>)</li>
--- 417,424 ----
<li>the set of standard TinyOS interfaces for collecting ADC conversion
results and for configuring an ADC (<a class="reference" href="#interfaces">2. Interfaces</a>)</li>
! <li>guidelines on how an ADC's HAL should expose chip-specific
interfaces (<a class="reference" href="#hal-guidelines">3. HAL guidelines</a>)</li>
<li>what components an ADC's HIL MUST implement (<a class="reference" href="#hil-requirements">4. HIL requirements</a>)</li>
! <li>guidelines on how the HIL should be implemented
(<a class="reference" href="#hil-guidelines">5. HIL guidelines</a>)</li>
<li>a section pointing to current implementations (<a class="reference" href="#implementation">6. Implementation</a>)</li>
***************
*** 432,437 ****
for the TI MSP430 MCU.</p>
</div>
! <div class="section" id="interfaces">
! <h1><a name="interfaces">2. Interfaces</a></h1>
<p>This TEP proposes the <tt class="docutils literal"><span class="pre">AdcConfigure</span></tt> interface for ADC hardware configuration
and the <tt class="docutils literal"><span class="pre">Read</span></tt>, <tt class="docutils literal"><span class="pre">ReadStream</span></tt> and <tt class="docutils literal"><span class="pre">ReadNow</span></tt> interfaces to acquire
--- 427,432 ----
for the TI MSP430 MCU.</p>
</div>
! <div class="section">
! <h1><a id="interfaces" name="interfaces">2. Interfaces</a></h1>
<p>This TEP proposes the <tt class="docutils literal"><span class="pre">AdcConfigure</span></tt> interface for ADC hardware configuration
and the <tt class="docutils literal"><span class="pre">Read</span></tt>, <tt class="docutils literal"><span class="pre">ReadStream</span></tt> and <tt class="docutils literal"><span class="pre">ReadNow</span></tt> interfaces to acquire
***************
*** 440,450 ****
<tt class="docutils literal"><span class="pre">Read[Now|Stream]</span></tt> interface is always provided in conjunction with a
<tt class="docutils literal"><span class="pre">AdcConfigure</span></tt> interface.</p>
! <div class="section" id="interface-for-configuring-the-adc-hardware">
! <h2><a name="interface-for-configuring-the-adc-hardware">Interface for configuring the ADC hardware</a></h2>
<p>The <tt class="docutils literal"><span class="pre">AdcConfigure</span></tt> interface is defined as follows:</p>
<pre class="literal-block">
! interface AdcConfigure< config_type >
{
! async command config_type getConfiguration();
}
</pre>
--- 435,445 ----
<tt class="docutils literal"><span class="pre">Read[Now|Stream]</span></tt> interface is always provided in conjunction with a
<tt class="docutils literal"><span class="pre">AdcConfigure</span></tt> interface.</p>
! <div class="section">
! <h2><a id="interface-for-configuring-the-adc-hardware" name="interface-for-configuring-the-adc-hardware">Interface for configuring the ADC hardware</a></h2>
<p>The <tt class="docutils literal"><span class="pre">AdcConfigure</span></tt> interface is defined as follows:</p>
<pre class="literal-block">
! interface AdcConfigure< config_type >
{
! async command config_type getConfiguration();
}
</pre>
***************
*** 469,474 ****
configuration in program memory.</p>
</div>
! <div class="section" id="interfaces-for-acquiring-conversion-results">
! <h2><a name="interfaces-for-acquiring-conversion-results">Interfaces for acquiring conversion results</a></h2>
<p>This TEP proposes to adopt the following two source-independent data
collection interfaces from <a class="citation-reference" href="#tep114" id="id10" name="id10">[TEP114]</a> for the collection of ADC conversion
--- 464,469 ----
configuration in program memory.</p>
</div>
! <div class="section">
! <h2><a id="interfaces-for-acquiring-conversion-results" name="interfaces-for-acquiring-conversion-results">Interfaces for acquiring conversion results</a></h2>
<p>This TEP proposes to adopt the following two source-independent data
collection interfaces from <a class="citation-reference" href="#tep114" id="id10" name="id10">[TEP114]</a> for the collection of ADC conversion
***************
*** 489,510 ****
resolution of the conversion results - the actual resolution may be smaller
(e.g. uint16_t for a 12-bit ADC).</p>
! <div class="section" id="read">
! <h3><a name="read">Read</a></h3>
<p>The <tt class="docutils literal"><span class="pre">Read</span></tt> interface can be used to sample an ADC channel once and return a
single conversion result as an uninterpreted value. The <tt class="docutils literal"><span class="pre">Read</span></tt> interface is
documented in <a class="citation-reference" href="#tep114" id="id11" name="id11">[TEP114]</a>.</p>
</div>
! <div class="section" id="readstream">
! <h3><a name="readstream">ReadStream</a></h3>
<p>The <tt class="docutils literal"><span class="pre">ReadStream</span></tt> interface can be used to sample an ADC channel multiple
times with a specified sampling period. The <tt class="docutils literal"><span class="pre">ReadStream</span></tt> interface is
documented in <a class="citation-reference" href="#tep114" id="id12" name="id12">[TEP114]</a> .</p>
</div>
! <div class="section" id="readnow">
! <h3><a name="readnow">ReadNow</a></h3>
<p>The <tt class="docutils literal"><span class="pre">ReadNow</span></tt> interface is intended for split-phase low-latency
reading of small values:</p>
<pre class="literal-block">
! interface ReadNow<val_t>
{
async command error_t read();
--- 484,505 ----
resolution of the conversion results - the actual resolution may be smaller
(e.g. uint16_t for a 12-bit ADC).</p>
! <div class="section">
! <h3><a id="read" name="read">Read</a></h3>
<p>The <tt class="docutils literal"><span class="pre">Read</span></tt> interface can be used to sample an ADC channel once and return a
single conversion result as an uninterpreted value. The <tt class="docutils literal"><span class="pre">Read</span></tt> interface is
documented in <a class="citation-reference" href="#tep114" id="id11" name="id11">[TEP114]</a>.</p>
</div>
! <div class="section">
! <h3><a id="readstream" name="readstream">ReadStream</a></h3>
<p>The <tt class="docutils literal"><span class="pre">ReadStream</span></tt> interface can be used to sample an ADC channel multiple
times with a specified sampling period. The <tt class="docutils literal"><span class="pre">ReadStream</span></tt> interface is
documented in <a class="citation-reference" href="#tep114" id="id12" name="id12">[TEP114]</a> .</p>
</div>
! <div class="section">
! <h3><a id="readnow" name="readnow">ReadNow</a></h3>
<p>The <tt class="docutils literal"><span class="pre">ReadNow</span></tt> interface is intended for split-phase low-latency
reading of small values:</p>
<pre class="literal-block">
! interface ReadNow<val_t>
{
async command error_t read();
***************
*** 526,531 ****
</div>
</div>
! <div class="section" id="hal-guidelines">
! <h1><a name="hal-guidelines">3. HAL guidelines</a></h1>
<p>As explained in <a class="reference" href="#introduction">1. Introduction</a> the HAL exposes the full capabilities of the
ADC hardware. Therefore only chip- and platform-dependent clients can wire to
--- 521,526 ----
</div>
</div>
! <div class="section">
! <h1><a id="hal-guidelines" name="hal-guidelines">3. HAL guidelines</a></h1>
<p>As explained in <a class="reference" href="#introduction">1. Introduction</a> the HAL exposes the full capabilities of the
ADC hardware. Therefore only chip- and platform-dependent clients can wire to
***************
*** 534,539 ****
section to facilitate the mapping to the HIL representation. Appendix B shows
the signature of the HAL for the MSP430.</p>
! <div class="section" id="resource-reservation">
! <h2><a name="resource-reservation">Resource reservation</a></h2>
<p>As the ADC hardware is a shared resource that is usually multiplexed between
several clients some form of access arbitration is necessary. The HAL should
--- 529,534 ----
section to facilitate the mapping to the HIL representation. Appendix B shows
the signature of the HAL for the MSP430.</p>
! <div class="section">
! <h2><a id="resource-reservation" name="resource-reservation">Resource reservation</a></h2>
<p>As the ADC hardware is a shared resource that is usually multiplexed between
several clients some form of access arbitration is necessary. The HAL should
***************
*** 544,549 ****
arbiters and the <tt class="docutils literal"><span class="pre">Resource</span></tt> interface are the topic of <a class="citation-reference" href="#tep108" id="id15" name="id15">[TEP108]</a>.</p>
</div>
! <div class="section" id="configuration-and-sampling">
! <h2><a name="configuration-and-sampling">Configuration and sampling</a></h2>
<p>As the ADC hardware is a shared resource the HAL should support hardware
configuration and sampling per client (although per-port configuration is
--- 539,544 ----
arbiters and the <tt class="docutils literal"><span class="pre">Resource</span></tt> interface are the topic of <a class="citation-reference" href="#tep108" id="id15" name="id15">[TEP108]</a>.</p>
</div>
! <div class="section">
! <h2><a id="configuration-and-sampling" name="configuration-and-sampling">Configuration and sampling</a></h2>
<p>As the ADC hardware is a shared resource the HAL should support hardware
configuration and sampling per client (although per-port configuration is
***************
*** 567,572 ****
interfaces for the MSP430.</p>
</div>
! <div class="section" id="hal-virtualization">
! <h2><a name="hal-virtualization">HAL virtualization</a></h2>
<p>In order to hide wiring complexities and/or export only a subset of all ADC
functions generic ADC wrapper components may be provided on the level of HAL.
--- 562,567 ----
interfaces for the MSP430.</p>
</div>
! <div class="section">
! <h2><a id="hal-virtualization" name="hal-virtualization">HAL virtualization</a></h2>
<p>In order to hide wiring complexities and/or export only a subset of all ADC
functions generic ADC wrapper components may be provided on the level of HAL.
***************
*** 576,587 ****
</div>
</div>
! <div class="section" id="hil-requirements">
! <h1><a name="hil-requirements">4. HIL requirements</a></h1>
<p>The following generic components MUST be provided on all platforms that have an
ADC:</p>
<pre class="literal-block">
! AdcReadClientC
! AdcReadNowClientC
! AdcReadStreamClientC
</pre>
<p>These components provide virtualized access to the HIL of an ADC. They are
--- 571,582 ----
</div>
</div>
! <div class="section">
! <h1><a id="hil-requirements" name="hil-requirements">4. HIL requirements</a></h1>
<p>The following generic components MUST be provided on all platforms that have an
ADC:</p>
<pre class="literal-block">
! AdcReadClientC
! AdcReadNowClientC
! AdcReadStreamClientC
</pre>
<p>These components provide virtualized access to the HIL of an ADC. They are
***************
*** 593,598 ****
is a general one in TinyOS 2.x). Appendix C shows the <tt class="docutils literal"><span class="pre">AdcReadClientC</span></tt> for
the MSP430.</p>
! <div class="section" id="adcreadclientc">
! <h2><a name="adcreadclientc">AdcReadClientC</a></h2>
<pre class="literal-block">
generic configuration AdcReadClientC() {
--- 588,593 ----
is a general one in TinyOS 2.x). Appendix C shows the <tt class="docutils literal"><span class="pre">AdcReadClientC</span></tt> for
the MSP430.</p>
! <div class="section">
! <h2><a id="adcreadclientc" name="adcreadclientc">AdcReadClientC</a></h2>
<pre class="literal-block">
generic configuration AdcReadClientC() {
***************
*** 616,621 ****
an example, see the AdcReadClientC for the MSP430 in Appendix C).</p>
</div>
! <div class="section" id="adcreadnowclientc">
! <h2><a name="adcreadnowclientc">AdcReadNowClientC</a></h2>
<pre class="literal-block">
generic configuration AdcReadNowClientC() {
--- 611,616 ----
an example, see the AdcReadClientC for the MSP430 in Appendix C).</p>
</div>
! <div class="section">
! <h2><a id="adcreadnowclientc" name="adcreadnowclientc">AdcReadNowClientC</a></h2>
<pre class="literal-block">
generic configuration AdcReadNowClientC() {
***************
*** 648,653 ****
done for the AdcReadClientC see Appendix C).</p>
</div>
! <div class="section" id="adcreadstreamclientc">
! <h2><a name="adcreadstreamclientc">AdcReadStreamClientC</a></h2>
<pre class="literal-block">
generic configuration AdcReadStreamClientC() {
--- 643,648 ----
done for the AdcReadClientC see Appendix C).</p>
</div>
! <div class="section">
! <h2><a id="adcreadstreamclientc" name="adcreadstreamclientc">AdcReadStreamClientC</a></h2>
<pre class="literal-block">
generic configuration AdcReadStreamClientC() {
***************
*** 669,674 ****
</div>
</div>
! <div class="section" id="hil-guidelines">
! <h1><a name="hil-guidelines">5. HIL guidelines</a></h1>
<p>The HIL implementation of an ADC stack has two main tasks: it translates a
<tt class="docutils literal"><span class="pre">Read</span></tt>, <tt class="docutils literal"><span class="pre">ReadNow</span></tt> or <tt class="docutils literal"><span class="pre">ReadStream</span></tt> request to a chip-specific HAL sampling
--- 664,669 ----
</div>
</div>
! <div class="section">
! <h1><a id="hil-guidelines" name="hil-guidelines">5. HIL guidelines</a></h1>
<p>The HIL implementation of an ADC stack has two main tasks: it translates a
<tt class="docutils literal"><span class="pre">Read</span></tt>, <tt class="docutils literal"><span class="pre">ReadNow</span></tt> or <tt class="docutils literal"><span class="pre">ReadStream</span></tt> request to a chip-specific HAL sampling
***************
*** 700,707 ****
the conversion result(s) it forwards it to the respective <tt class="docutils literal"><span class="pre">ReadNow</span></tt> client.</p>
</div>
! <div class="section" id="implementation">
! <h1><a name="implementation">6. Implementation</a></h1>
! <div class="section" id="testadc-application">
! <h2><a name="testadc-application">TestAdc application</a></h2>
<p>An ADC HIL test application can be found in <tt class="docutils literal"><span class="pre">tinyos-2.x/apps/tests/TestAdc</span></tt>.
Note that this application instantiates generic DemoSensorC, DemoSensorStreamC
--- 695,702 ----
the conversion result(s) it forwards it to the respective <tt class="docutils literal"><span class="pre">ReadNow</span></tt> client.</p>
</div>
! <div class="section">
! <h1><a id="implementation" name="implementation">6. Implementation</a></h1>
! <div class="section">
! <h2><a id="testadc-application" name="testadc-application">TestAdc application</a></h2>
<p>An ADC HIL test application can be found in <tt class="docutils literal"><span class="pre">tinyos-2.x/apps/tests/TestAdc</span></tt>.
Note that this application instantiates generic DemoSensorC, DemoSensorStreamC
***************
*** 710,715 ****
<tt class="docutils literal"><span class="pre">tinyos-2.x/apps/tests/TestAdc/README.txt</span></tt> for more information.</p>
</div>
! <div class="section" id="haa-on-the-msp430-and-atmega-128">
! <h2><a name="haa-on-the-msp430-and-atmega-128">HAA on the MSP430 and Atmega 128</a></h2>
<p>The implementation of the ADC12 stack on the MSP430 can be found in
<tt class="docutils literal"><span class="pre">tinyos-2.x/tos/chips/msp430/adc12</span></tt>:</p>
--- 705,710 ----
<tt class="docutils literal"><span class="pre">tinyos-2.x/apps/tests/TestAdc/README.txt</span></tt> for more information.</p>
</div>
! <div class="section">
! <h2><a id="haa-on-the-msp430-and-atmega-128" name="haa-on-the-msp430-and-atmega-128">HAA on the MSP430 and Atmega 128</a></h2>
<p>The implementation of the ADC12 stack on the MSP430 can be found in
<tt class="docutils literal"><span class="pre">tinyos-2.x/tos/chips/msp430/adc12</span></tt>:</p>
***************
*** 731,735 ****
<li><tt class="docutils literal"><span class="pre">HplAtm128AdcC.nc</span></tt> is the HPL implementation</li>
<li><tt class="docutils literal"><span class="pre">Atm128AdcP.nc</span></tt> is the HAL implementation</li>
! <li><tt class="docutils literal"><span class="pre">AdcP.nc</span></tt>, <tt class="docutils literal"><span class="pre">WireAdcP.nc</span></tt> and the library components for arbitrating
'Read', 'ReadNow' and 'ReadStream', <tt class="docutils literal"><span class="pre">ArbitratedReadC</span></tt> and
<tt class="docutils literal"><span class="pre">ArbitratedReadStreamC</span></tt> (in <tt class="docutils literal"><span class="pre">tinyos-2.x/tos/system</span></tt>), realize
--- 726,730 ----
<li><tt class="docutils literal"><span class="pre">HplAtm128AdcC.nc</span></tt> is the HPL implementation</li>
<li><tt class="docutils literal"><span class="pre">Atm128AdcP.nc</span></tt> is the HAL implementation</li>
! <li><tt class="docutils literal"><span class="pre">AdcP.nc</span></tt>, <tt class="docutils literal"><span class="pre">WireAdcP.nc</span></tt> and the library components for arbitrating
'Read', 'ReadNow' and 'ReadStream', <tt class="docutils literal"><span class="pre">ArbitratedReadC</span></tt> and
<tt class="docutils literal"><span class="pre">ArbitratedReadStreamC</span></tt> (in <tt class="docutils literal"><span class="pre">tinyos-2.x/tos/system</span></tt>), realize
***************
*** 741,746 ****
</div>
</div>
! <div class="section" id="appendix-a-hardware-differences-between-platforms">
! <h1><a name="appendix-a-hardware-differences-between-platforms">Appendix A: Hardware differences between platforms</a></h1>
<p>The following table compares the characteristics of two microcontrollers
commonly used in TinyOS platforms:</p>
--- 736,741 ----
</div>
</div>
! <div class="section">
! <h1><a id="appendix-a-hardware-differences-between-platforms" name="appendix-a-hardware-differences-between-platforms">Appendix A: Hardware differences between platforms</a></h1>
<p>The following table compares the characteristics of two microcontrollers
commonly used in TinyOS platforms:</p>
***************
*** 752,758 ****
</colgroup>
<thead valign="bottom">
! <tr><th> </th>
! <th>Atmel Atmega 128</th>
! <th>TI MSP430 ADC12</th>
</tr>
</thead>
--- 747,753 ----
</colgroup>
<thead valign="bottom">
! <tr><th class="head"> </th>
! <th class="head">Atmel Atmega 128</th>
! <th class="head">TI MSP430 ADC12</th>
</tr>
</thead>
***************
*** 871,876 ****
</table>
</div>
! <div class="section" id="appendix-b-a-hal-representation-msp430-adc12">
! <h1><a name="appendix-b-a-hal-representation-msp430-adc12">Appendix B: a HAL representation: MSP430 ADC12</a></h1>
<p>This section shows the HAL signature for the ADC12 of the TI MSP430 MCU. It
reflects the four MSP430 ADC12 conversion modes as it lets a client sample an
--- 866,871 ----
</table>
</div>
! <div class="section">
! <h1><a id="appendix-b-a-hal-representation-msp430-adc12" name="appendix-b-a-hal-representation-msp430-adc12">Appendix B: a HAL representation: MSP430 ADC12</a></h1>
<p>This section shows the HAL signature for the ADC12 of the TI MSP430 MCU. It
reflects the four MSP430 ADC12 conversion modes as it lets a client sample an
***************
*** 883,897 ****
responsible for data transfer (managed in an exterior component):</p>
<pre class="literal-block">
! configuration Msp430Adc12P
! {
provides {
! interface Resource[uint8_t id];
! interface Msp430Adc12SingleChannel as SingleChannel[uint8_t id];
interface AsyncStdControl as DMAExtension[uint8_t id];
}
}
! interface Msp430Adc12SingleChannel
! {
async command error_t configureSingle(const msp430adc12_channel_config_t *config);
async command error_t configureSingleRepeat(const msp430adc12_channel_config_t *config, uint16_t jiffies);
--- 878,892 ----
responsible for data transfer (managed in an exterior component):</p>
<pre class="literal-block">
! configuration Msp430Adc12P
! {
provides {
! interface Resource[uint8_t id];
! interface Msp430Adc12SingleChannel as SingleChannel[uint8_t id];
interface AsyncStdControl as DMAExtension[uint8_t id];
}
}
! interface Msp430Adc12SingleChannel
! {
async command error_t configureSingle(const msp430adc12_channel_config_t *config);
async command error_t configureSingleRepeat(const msp430adc12_channel_config_t *config, uint16_t jiffies);
***************
*** 900,921 ****
async command error_t getData();
async event error_t singleDataReady(uint16_t data);
! async event uint16_t* multipleDataReady(uint16_t buffer[], uint16_t numSamples);
}
! typedef struct
! {
! unsigned int inch: 4; // input channel
! unsigned int sref: 3; // reference voltage
! unsigned int ref2_5v: 1; // reference voltage level
! unsigned int adc12ssel: 2; // clock source sample-hold-time
! unsigned int adc12div: 3; // clock divider sample-hold-time
unsigned int sht: 4; // sample-hold-time
! unsigned int sampcon_ssel: 2; // clock source sampcon signal
unsigned int sampcon_id: 2; // clock divider sampcon signal
} msp430adc12_channel_config_t;
</pre>
</div>
! <div class="section" id="appendix-c-a-hil-representation-msp430-adc12">
! <h1><a name="appendix-c-a-hil-representation-msp430-adc12">Appendix C: a HIL representation: MSP430 ADC12</a></h1>
<p>The signature of the AdcReadClientC component for the MSP430 ADC12 is as
follows:</p>
--- 895,916 ----
async command error_t getData();
async event error_t singleDataReady(uint16_t data);
! async event uint16_t* multipleDataReady(uint16_t buffer[], uint16_t numSamples);
}
! typedef struct
! {
! unsigned int inch: 4; // input channel
! unsigned int sref: 3; // reference voltage
! unsigned int ref2_5v: 1; // reference voltage level
! unsigned int adc12ssel: 2; // clock source sample-hold-time
! unsigned int adc12div: 3; // clock divider sample-hold-time
unsigned int sht: 4; // sample-hold-time
! unsigned int sampcon_ssel: 2; // clock source sampcon signal
unsigned int sampcon_id: 2; // clock divider sampcon signal
} msp430adc12_channel_config_t;
</pre>
</div>
! <div class="section">
! <h1><a id="appendix-c-a-hil-representation-msp430-adc12" name="appendix-c-a-hil-representation-msp430-adc12">Appendix C: a HIL representation: MSP430 ADC12</a></h1>
<p>The signature of the AdcReadClientC component for the MSP430 ADC12 is as
follows:</p>
Index: tep118.html
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/doc/html/tep118.html,v
retrieving revision 1.7
retrieving revision 1.8
diff -C2 -d -r1.7 -r1.8
*** tep118.html 21 Apr 2007 07:04:39 -0000 1.7
--- tep118.html 14 Aug 2007 18:58:00 -0000 1.8
***************
*** 4,8 ****
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
! <meta name="generator" content="Docutils 0.3.6: http://docutils.sourceforge.net/" />
<title>Dissemination</title>
<meta name="author" content="Philip Levis and Gilman Tolle" />
--- 4,8 ----
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
! <meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
<title>Dissemination</title>
<meta name="author" content="Philip Levis and Gilman Tolle" />
***************
*** 42,50 ****
margin-bottom: 0.5em }
- /* Uncomment (& remove this text!) to get bold-faced definition list terms
- dt {
- font-weight: bold }
- */
-
div.abstract {
margin: 2em 5em }
--- 42,45 ----
***************
*** 284,287 ****
--- 279,283 ----
</head>
<body>
+ <div class="document" id="dissemination">
<h1 class="title">Dissemination</h1>
<table class="docinfo" frame="void" rules="none">
***************
*** 303,309 ****
<tr class="field"><th class="docinfo-name">Draft-Created:</th><td class="field-body">10-Dec-2004</td>
</tr>
! <tr class="field"><th class="docinfo-name">Draft-Version:</th><td class="field-body">1.6</td>
</tr>
! <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 <tinyos-devel at mail.millennium.berkeley.edu></td>
--- 299,305 ----
<tr class="field"><th class="docinfo-name">Draft-Created:</th><td class="field-body">10-Dec-2004</td>
</tr>
! <tr class="field"><th class="docinfo-name">Draft-Version:</th><td class="field-body">1.7</td>
</tr>
! <tr class="field"><th class="docinfo-name">Draft-Modified:</th><td class="field-body">2007-06-14</td>
</tr>
<tr class="field"><th class="docinfo-name">Draft-Discuss:</th><td class="field-body">TinyOS Developer List <tinyos-devel at mail.millennium.berkeley.edu></td>
***************
*** 311,315 ****
</tbody>
</table>
- <div class="document" id="dissemination">
<div class="note">
<p class="first admonition-title">Note</p>
--- 307,310 ----
***************
*** 319,324 ****
TEP 1.</p>
</div>
! <div class="section" id="abstract">
! <h1><a name="abstract">Abstract</a></h1>
<p>The memo documents the interfaces, components, and semantics for
disseminating small (smaller than a single packet payload) pieces of
--- 314,319 ----
TEP 1.</p>
</div>
! <div class="section">
! <h1><a id="abstract" name="abstract">Abstract</a></h1>
<p>The memo documents the interfaces, components, and semantics for
disseminating small (smaller than a single packet payload) pieces of
***************
*** 326,331 ****
data to every node in a network.</p>
</div>
! <div class="section" id="introduction">
! <h1><a name="introduction">1. Introduction</a></h1>
<p>Dissemination is a basic sensor network protocol. The ability to
reliably deliver a piece of data to every node allows administrators
--- 321,326 ----
data to every node in a network.</p>
</div>
! <div class="section">
! <h1><a id="introduction" name="introduction">1. Introduction</a></h1>
<p>Dissemination is a basic sensor network protocol. The ability to
reliably deliver a piece of data to every node allows administrators
***************
*** 356,361 ****
dissemination service of this kind.</p>
</div>
! <div class="section" id="dissemination-interfaces">
! <h1><a name="dissemination-interfaces">2. Dissemination interfaces</a></h1>
<p>Small-value dissemination has two interfaces: DisseminationValue and
DisseminationUpdate. The former is for consumers of a disseminated
--- 351,356 ----
dissemination service of this kind.</p>
</div>
! <div class="section">
! <h1><a id="dissemination-interfaces" name="dissemination-interfaces">2. Dissemination interfaces</a></h1>
<p>Small-value dissemination has two interfaces: DisseminationValue and
DisseminationUpdate. The former is for consumers of a disseminated
***************
*** 364,368 ****
interface DisseminationValue<t> {
command const t* get();
! event void changed();
}
--- 359,363 ----
interface DisseminationValue<t> {
command const t* get();
! event void changed();
}
***************
*** 392,397 ****
so that eventually every node has the same data value.</p>
</div>
! <div class="section" id="dissemination-service">
! <h1><a name="dissemination-service">3 Dissemination Service</a></h1>
<p>A dissemination service MUST provide one component, DisseminatorC,
which has the following signature:</p>
--- 387,392 ----
so that eventually every node has the same data value.</p>
</div>
! <div class="section">
! <h1><a id="dissemination-service" name="dissemination-service">3 Dissemination Service</a></h1>
<p>A dissemination service MUST provide one component, DisseminatorC,
which has the following signature:</p>
***************
*** 402,406 ****
}
</pre>
! <p>The t argument MUST be able to fit in a single message_t[<a href="#id4" name="id5"><span class="problematic" id="id5">tep111_</span></a>] after
considering the headers that the dissemination protocol introduces.
A dissemination implementation SHOULD have a compile error if a larger
--- 397,401 ----
}
</pre>
! <p>The t argument MUST be able to fit in a single message_t [TEP111] after
considering the headers that the dissemination protocol introduces.
A dissemination implementation SHOULD have a compile error if a larger
***************
*** 422,427 ****
for the <tt class="docutils literal"><span class="pre">key</span></tt> argument.</p>
</div>
! <div class="section" id="dissemination-keys">
! <h1><a name="dissemination-keys">4 Dissemination Keys</a></h1>
<p>One issue that comes up when using this interfaces is the selection of
a key for each value. On one hand, using unique() is easy, but this
--- 417,422 ----
for the <tt class="docutils literal"><span class="pre">key</span></tt> argument.</p>
</div>
! <div class="section">
! <h1><a id="dissemination-keys" name="dissemination-keys">4 Dissemination Keys</a></h1>
<p>One issue that comes up when using this interfaces is the selection of
a key for each value. On one hand, using unique() is easy, but this
***************
*** 439,443 ****
<pre class="literal-block">
#include <disseminate_keys.h>
! configuration SomeComponentC {
...
}
--- 434,438 ----
<pre class="literal-block">
#include <disseminate_keys.h>
! configuration SomeComponentC {
...
}
***************
*** 450,454 ****
components SomeComponentP;
components new DisseminatorC(uint8_t, DIS_SOME_COMPONENT_KEY);
! SomeComponentP.ConfigVal -> DisseminatorC;
}
</pre>
--- 445,449 ----
components SomeComponentP;
components new DisseminatorC(uint8_t, DIS_SOME_COMPONENT_KEY);
! SomeComponentP.ConfigVal -> DisseminatorC;
}
</pre>
***************
*** 465,470 ****
interface, but will be used internally.</p>
</div>
! <div class="section" id="more-complex-dissemination">
! <h1><a name="more-complex-dissemination">5. More Complex Dissemination</a></h1>
<p>An application can use this low-level networking primitive to build
more complex dissemination systems. For example, if you want have a
--- 460,465 ----
interface, but will be used internally.</p>
</div>
! <div class="section">
! <h1><a id="more-complex-dissemination" name="more-complex-dissemination">5. More Complex Dissemination</a></h1>
<p>An application can use this low-level networking primitive to build
more complex dissemination systems. For example, if you want have a
***************
*** 474,479 ****
above interfaces.</p>
</div>
! <div class="section" id="implementation">
! <h1><a name="implementation">6. Implementation</a></h1>
<p>An implementation of this TEP can be found in
<tt class="docutils literal"><span class="pre">tinyos-2.x/tos/lib/net</span></tt>. This dissemination implementation uses
--- 469,474 ----
above interfaces.</p>
</div>
! <div class="section">
! <h1><a id="implementation" name="implementation">6. Implementation</a></h1>
<p>An implementation of this TEP can be found in
<tt class="docutils literal"><span class="pre">tinyos-2.x/tos/lib/net</span></tt>. This dissemination implementation uses
***************
*** 481,486 ****
trickle.</p>
</div>
! <div class="section" id="author-s-address">
! <h1><a name="author-s-address">6. Author's Address</a></h1>
<div class="line-block">
<div class="line">Philip Levis</div>
--- 476,481 ----
trickle.</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">Philip Levis</div>
***************
*** 502,507 ****
</div>
</div>
! <div class="section" id="citations">
! <h1><a name="citations">7. Citations</a></h1>
<table class="docutils footnote" frame="void" id="id2" rules="none">
<colgroup><col class="label" /><col /></colgroup>
--- 497,502 ----
</div>
</div>
! <div class="section">
! <h1><a id="citations" name="citations">7. Citations</a></h1>
<table class="docutils footnote" frame="void" id="id2" rules="none">
<colgroup><col class="label" /><col /></colgroup>
***************
*** 517,526 ****
</table>
</div>
- <div class="system-messages section">
- <h1><a>Docutils System Messages</a></h1>
- <div class="system-message" id="id4">
- <p class="system-message-title">System Message: <a name="id4">ERROR/3</a> (<tt class="docutils">txt/tep118.txt</tt>, line 116); <em><a href="#id5">backlink</a></em></p>
- Unknown target name: "tep111".</div>
- </div>
</div>
</body>
--- 512,515 ----
Index: tep124.html
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/doc/html/tep124.html,v
retrieving revision 1.3
retrieving revision 1.4
diff -C2 -d -r1.3 -r1.4
*** tep124.html 21 Apr 2007 07:04:39 -0000 1.3
--- tep124.html 14 Aug 2007 18:58:00 -0000 1.4
***************
*** 4,8 ****
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
! <meta name="generator" content="Docutils 0.3.6: http://docutils.sourceforge.net/" />
<title>The Link Estimation Exchange Protocol (LEEP)</title>
<meta name="author" content="Omprakash Gnawali" />
--- 4,8 ----
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
! <meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
<title>The Link Estimation Exchange Protocol (LEEP)</title>
<meta name="author" content="Omprakash Gnawali" />
***************
*** 42,50 ****
margin-bottom: 0.5em }
- /* Uncomment (& remove this text!) to get bold-faced definition list terms
- dt {
- font-weight: bold }
- */
-
div.abstract {
margin: 2em 5em }
--- 42,45 ----
***************
*** 284,287 ****
--- 279,283 ----
</head>
<body>
+ <div class="document" id="the-link-estimation-exchange-protocol-leep">
<h1 class="title">The Link Estimation Exchange Protocol (LEEP)</h1>
<table class="docinfo" frame="void" rules="none">
***************
*** 311,315 ****
</tbody>
</table>
- <div class="document" id="the-link-estimation-exchange-protocol-leep">
<div class="note">
<p class="first admonition-title">Note</p>
--- 307,310 ----
***************
*** 319,345 ****
TEP 1.</p>
</div>
! <div class="section" id="abstract">
! <h1><a name="abstract">Abstract</a></h1>
<p>The memo documents the Link Estimation Exchange Protocol (LEEP). Nodes
use LEEP to estimate and exchange information about the quality of
links to the neighbors.</p>
</div>
! <div class="section" id="introduction">
! <h1><a name="introduction">1. Introduction</a></h1>
<p>Routing protocols often require bi-directional link qualities to
compute the routes. Nodes can estimate the quality of the in-bound
link from a neighbor by estimating the ratio of successfully received
messages and the total transmitted messages. LEEP appends in-bound
! packet reception rate (PRR) estimates to packets. Other nodes hearing
these packets can combine the in-bound PRR values with their own
in-bound values to compute bi-directional link quality.</p>
</div>
! <div class="section" id="definitions">
! <h1><a name="definitions">2. Definitions</a></h1>
! <div class="section" id="link-quality">
! <h2><a name="link-quality">2.1 Link Quality</a></h2>
<p>The link quality between a directed node pair (A,B) is the probability
that a packet transmitted by A will be successfully received by B. The
! bidirectional link quality of an undirected node pair (A,B) is the
product of the link quality of (A,B) and (B,A). This definition
assumes independent link losses. It also includes the case when
--- 314,340 ----
TEP 1.</p>
</div>
! <div class="section">
! <h1><a id="abstract" name="abstract">Abstract</a></h1>
<p>The memo documents the Link Estimation Exchange Protocol (LEEP). Nodes
use LEEP to estimate and exchange information about the quality of
links to the neighbors.</p>
</div>
! <div class="section">
! <h1><a id="introduction" name="introduction">1. Introduction</a></h1>
<p>Routing protocols often require bi-directional link qualities to
compute the routes. Nodes can estimate the quality of the in-bound
link from a neighbor by estimating the ratio of successfully received
messages and the total transmitted messages. LEEP appends in-bound
! packet reception rate (PRR) estimates to packets. Other nodes hearing
these packets can combine the in-bound PRR values with their own
in-bound values to compute bi-directional link quality.</p>
</div>
! <div class="section">
! <h1><a id="definitions" name="definitions">2. Definitions</a></h1>
! <div class="section">
! <h2><a id="link-quality" name="link-quality">2.1 Link Quality</a></h2>
<p>The link quality between a directed node pair (A,B) is the probability
that a packet transmitted by A will be successfully received by B. The
! bidirectional link quality of an undirected node pair (A,B) is the
product of the link quality of (A,B) and (B,A). This definition
assumes independent link losses. It also includes the case when
***************
*** 347,352 ****
due to local interference or noise.</p>
</div>
! <div class="section" id="in-bound-link-quality">
! <h2><a name="in-bound-link-quality">2.2 In-bound Link Quality</a></h2>
<p>In a node pair (A,B), with B as the node of reference, in-bound link
quality is a value in the range of 0 to 255 that describes the quality
--- 342,347 ----
due to local interference or noise.</p>
</div>
! <div class="section">
! <h2><a id="in-bound-link-quality" name="in-bound-link-quality">2.2 In-bound Link Quality</a></h2>
<p>In a node pair (A,B), with B as the node of reference, in-bound link
quality is a value in the range of 0 to 255 that describes the quality
***************
*** 356,361 ****
the node B, or some other methods.</p>
</div>
! <div class="section" id="out-bound-link-quality">
! <h2><a name="out-bound-link-quality">2.3 Out-bound Link Quality</a></h2>
<p>In a node pair (A,B), with B as the node of reference, out-bound link
quality is defined as the quality of the link from B to A. B can
--- 351,356 ----
the node B, or some other methods.</p>
</div>
! <div class="section">
! <h2><a id="out-bound-link-quality" name="out-bound-link-quality">2.3 Out-bound Link Quality</a></h2>
<p>In a node pair (A,B), with B as the node of reference, out-bound link
quality is defined as the quality of the link from B to A. B can
***************
*** 364,377 ****
link qualities.</p>
</div>
! <div class="section" id="link-information-entry">
! <h2><a name="link-information-entry">2.4 Link Information Entry</a></h2>
<p>Link Information Entry created by node k is a tuple (n,q) where q is
the in-bound link quality from node n to k.</p>
</div>
</div>
! <div class="section" id="id1">
! <h1><a name="id1">3. The Link Estimation Exchange Protocol (LEEP)</a></h1>
! <div class="section" id="assumptions">
! <h2><a name="assumptions">3.1 Assumptions</a></h2>
<p>Following are the assumptions made by LEEP:</p>
<p>3.1.1. The data link frame has a single-hop source field.
--- 359,372 ----
link qualities.</p>
</div>
! <div class="section">
! <h2><a id="link-information-entry" name="link-information-entry">2.4 Link Information Entry</a></h2>
<p>Link Information Entry created by node k is a tuple (n,q) where q is
the in-bound link quality from node n to k.</p>
</div>
</div>
! <div class="section">
! <h1><a id="id1" name="id1">3. The Link Estimation Exchange Protocol (LEEP)</a></h1>
! <div class="section">
! <h2><a id="assumptions" name="assumptions">3.1 Assumptions</a></h2>
<p>Following are the assumptions made by LEEP:</p>
<p>3.1.1. The data link frame has a single-hop source field.
***************
*** 379,384 ****
3.1.3. The data link layer provides the length of the LEEP frame.</p>
</div>
! <div class="section" id="the-protocol">
! <h2><a name="the-protocol">3.2 The Protocol</a></h2>
<p>To compute the bi-directional link quality, in-bound link quality must
be exchanged among the neighbors. LEEP maintains a sequence number
--- 374,379 ----
3.1.3. The data link layer provides the length of the LEEP frame.</p>
</div>
! <div class="section">
! <h2><a id="the-protocol" name="the-protocol">3.2 The Protocol</a></h2>
<p>To compute the bi-directional link quality, in-bound link quality must
be exchanged among the neighbors. LEEP maintains a sequence number
***************
*** 393,398 ****
node identified by the data link source address.</p>
</div>
! <div class="section" id="leep-frame">
! <h2><a name="leep-frame">3.3 LEEP Frame</a></h2>
<p>A LEEP frame has a header, the payload, and a footer with the Link
Information (LI) entries as shown in this diagram:</p>
--- 388,393 ----
node identified by the data link source address.</p>
</div>
! <div class="section">
! <h2><a id="leep-frame" name="leep-frame">3.3 LEEP Frame</a></h2>
<p>A LEEP frame has a header, the payload, and a footer with the Link
Information (LI) entries as shown in this diagram:</p>
***************
*** 409,414 ****
Information entry.</p>
</div>
! <div class="section" id="leep-header">
! <h2><a name="leep-header">3.3.1 LEEP header</a></h2>
<p>The following diagram shows the LEEP header format:</p>
<pre class="literal-block">
--- 404,409 ----
Information entry.</p>
</div>
! <div class="section">
! <h2><a id="leep-header" name="leep-header">3.3.1 LEEP header</a></h2>
<p>The following diagram shows the LEEP header format:</p>
<pre class="literal-block">
***************
*** 428,433 ****
</blockquote>
</div>
! <div class="section" id="id2">
! <h2><a name="id2">3.3.2 Link Information Entry</a></h2>
<p>The following diagram shows the Link Information Entry format:</p>
<pre class="literal-block">
--- 423,428 ----
</blockquote>
</div>
! <div class="section">
! <h2><a id="id2" name="id2">3.3.2 Link Information Entry</a></h2>
<p>The following diagram shows the Link Information Entry format:</p>
<pre class="literal-block">
***************
*** 450,455 ****
</div>
</div>
! <div class="section" id="implementation">
! <h1><a name="implementation">4. Implementation</a></h1>
<p>The following files in <tt class="docutils literal"><span class="pre">tinyos-2.x/tos/lib/net/le</span></tt> provide a
reference implementation of LEEP described in this TEP.</p>
--- 445,450 ----
</div>
</div>
! <div class="section">
! <h1><a id="implementation" name="implementation">4. Implementation</a></h1>
<p>The following files in <tt class="docutils literal"><span class="pre">tinyos-2.x/tos/lib/net/le</span></tt> provide a
reference implementation of LEEP described in this TEP.</p>
***************
*** 469,479 ****
sent as a LEEP payload, are sent.</p>
</div>
! <div class="section" id="author-s-address">
! <h1><a name="author-s-address">5. Author's Address</a></h1>
<div class="line-block">
<div class="line">Omprakash Gnawali</div>
! <div class="line">Ronald Tutor Hall (RTH) 418 </div>
<div class="line">3710 S. McClintock Avenue</div>
! <div class="line">Los Angeles, CA 90089 </div>
<div class="line"><br /></div>
<div class="line">phone - +1 213 821-5627</div>
--- 464,474 ----
sent as a LEEP payload, are sent.</p>
</div>
! <div class="section">
! <h1><a id="author-s-address" name="author-s-address">5. Author's Address</a></h1>
<div class="line-block">
<div class="line">Omprakash Gnawali</div>
! <div class="line">Ronald Tutor Hall (RTH) 418</div>
<div class="line">3710 S. McClintock Avenue</div>
! <div class="line">Los Angeles, CA 90089</div>
<div class="line"><br /></div>
<div class="line">phone - +1 213 821-5627</div>
***************
*** 482,487 ****
</div>
</div>
! <div class="section" id="citations">
! <h1><a name="citations">6. Citations</a></h1>
<table class="docutils footnote" frame="void" id="id4" rules="none">
<colgroup><col class="label" /><col /></colgroup>
--- 477,482 ----
</div>
</div>
! <div class="section">
! <h1><a id="citations" name="citations">6. Citations</a></h1>
<table class="docutils footnote" frame="void" id="id4" rules="none">
<colgroup><col class="label" /><col /></colgroup>
Index: tep125.html
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/doc/html/tep125.html,v
retrieving revision 1.3
retrieving revision 1.4
diff -C2 -d -r1.3 -r1.4
*** tep125.html 21 Apr 2007 07:04:39 -0000 1.3
--- tep125.html 14 Aug 2007 18:58:00 -0000 1.4
***************
*** 4,8 ****
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
! <meta name="generator" content="Docutils 0.3.6: http://docutils.sourceforge.net/" />
<title>TinyOS 802.15.4 Frames</title>
<meta name="author" content="Jonathan Hui, Philip Levis, and David Moss" />
--- 4,8 ----
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
! <meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
<title>TinyOS 802.15.4 Frames</title>
<meta name="author" content="Jonathan Hui, Philip Levis, and David Moss" />
***************
*** 42,50 ****
margin-bottom: 0.5em }
- /* Uncomment (& remove this text!) to get bold-faced definition list terms
- dt {
- font-weight: bold }
- */
-
div.abstract {
margin: 2em 5em }
--- 42,45 ----
***************
*** 284,287 ****
--- 279,283 ----
</head>
<body>
+ <div class="document" id="tinyos-802-15-4-frames">
<h1 class="title">TinyOS 802.15.4 Frames</h1>
<table class="docinfo" frame="void" rules="none">
***************
*** 311,315 ****
</tbody>
</table>
- <div class="document" id="tinyos-802-15-4-frames">
<div class="note">
<p class="first admonition-title">Note</p>
--- 307,310 ----
***************
*** 319,329 ****
TEP 1.</p>
</div>
! <div class="section" id="abstract">
! <h1><a name="abstract">Abstract</a></h1>
<p>This memo documents the frame format for 802.15.4 packets in TinyOS
2.0.</p>
</div>
! <div class="section" id="introduction">
! <h1><a name="introduction">1. Introduction</a></h1>
<p>802.15.4 is a data-link and physical packet format for
low-power wireless networks that is used in many TinyOS platforms.
--- 314,324 ----
TEP 1.</p>
</div>
! <div class="section">
! <h1><a id="abstract" name="abstract">Abstract</a></h1>
<p>This memo documents the frame format for 802.15.4 packets in TinyOS
2.0.</p>
</div>
! <div class="section">
! <h1><a id="introduction" name="introduction">1. Introduction</a></h1>
<p>802.15.4 is a data-link and physical packet format for
low-power wireless networks that is used in many TinyOS platforms.
***************
*** 334,339 ****
networks[1]_.</p>
</div>
! <div class="section" id="id1">
! <h1><a name="id1">2. 802.15.4</a></h1>
<p>802.15.4 supports several different source and destination addressing
modes, and so has a variable sized packet header.[2]_ A TinyOS device MUST
--- 329,334 ----
networks[1]_.</p>
</div>
! <div class="section">
! <h1><a id="id1" name="id1">2. 802.15.4</a></h1>
<p>802.15.4 supports several different source and destination addressing
modes, and so has a variable sized packet header.[2]_ A TinyOS device MUST
***************
*** 341,346 ****
A TinyOS device MAY support additional 802.15.4 frame formats.</p>
</div>
! <div class="section" id="frame-format">
! <h1><a name="frame-format">3. Frame Format</a></h1>
<p>TinyOS has two 802.15.4 frame formats. The first format, the T-Frame, is
for TinyOS networks which do not share their channel with other wireless
--- 336,341 ----
A TinyOS device MAY support additional 802.15.4 frame formats.</p>
</div>
! <div class="section">
! <h1><a id="frame-format" name="frame-format">3. Frame Format</a></h1>
<p>TinyOS has two 802.15.4 frame formats. The first format, the T-Frame, is
for TinyOS networks which do not share their channel with other wireless
***************
*** 373,384 ****
<p>The AM type 6lowpan is reserved. A TinyOS program MUST NOT use it.</p>
</div>
! <div class="section" id="implementation">
! <h1><a name="implementation">4. Implementation</a></h1>
<p>An implementation of the T-Frame can be found in tinyos-2.x/tos/chips/cc2420.</p>
! <p>An implementation of the I-Frame will soon be found in
tinyos-2.x/tos/chips/cc2420.</p>
</div>
! <div class="section" id="author-addresses">
! <h1><a name="author-addresses">5. Author Addresses</a></h1>
<div class="line-block">
<div class="line"><br /></div>
--- 368,379 ----
<p>The AM type 6lowpan is reserved. A TinyOS program MUST NOT use it.</p>
</div>
! <div class="section">
! <h1><a id="implementation" name="implementation">4. Implementation</a></h1>
<p>An implementation of the T-Frame can be found in tinyos-2.x/tos/chips/cc2420.</p>
! <p>An implementation of the I-Frame will soon be found in
tinyos-2.x/tos/chips/cc2420.</p>
</div>
! <div class="section">
! <h1><a id="author-addresses" name="author-addresses">5. Author Addresses</a></h1>
<div class="line-block">
<div class="line"><br /></div>
Index: overview.html
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/doc/html/overview.html,v
retrieving revision 1.8
retrieving revision 1.9
diff -C2 -d -r1.8 -r1.9
*** overview.html 11 Jun 2007 20:42:35 -0000 1.8
--- overview.html 14 Aug 2007 18:58:00 -0000 1.9
***************
*** 0 ****
--- 1,740 ----
+ <?xml version="1.0" encoding="utf-8" ?>
+ <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+ <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
+ <title>TinyOS 2.0 Overview</title>
+ <meta name="author" content="Philip Levis" />
+ <meta name="date" content="Oct 30 2006" />
+ <style type="text/css">
+
+ /*
+ :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 }
+
+ .hidden {
+ display: none }
+
+ a.toc-backref {
+ text-decoration: none ;
+ color: black }
+
+ blockquote.epigraph {
+ margin: 2em 5em ; }
+
+ dd {
+ margin-bottom: 0.5em }
+
+ div.abstract {
+ margin: 2em 5em }
+
+ 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 {
+ 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,
+ div.warning p.admonition-title {
+ color: red ;
+ 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 }
+
+ div.dedication {
+ margin: 2em 5em ;
+ text-align: center ;
+ font-style: italic }
+
+ div.dedication p.topic-title {
+ font-weight: bold ;
+ font-style: normal }
+
+ div.figure {
+ margin-left: 2em }
+
+ div.footer, div.header {
+ font-size: smaller }
+
+ div.line-block {
+ display: block ;
+ margin-top: 1em ;
+ margin-bottom: 1em }
+
+ div.line-block div.line-block {
+ margin-top: 0 ;
+ margin-bottom: 0 ;
+ margin-left: 1.5em }
+
+ div.sidebar {
+ margin-left: 1em ;
+ border: medium outset ;
+ padding: 0em 1em ;
+ background-color: #ffffee ;
+ width: 40% ;
+ float: right ;
+ clear: right }
+
+ div.sidebar p.rubric {
+ font-family: sans-serif ;
+ font-size: medium }
+
+ div.system-messages {
+ margin: 5em }
+
+ div.system-messages h1 {
+ color: red }
+
+ div.system-message {
+ border: medium outset ;
+ padding: 1em }
+
+ div.system-message p.system-message-title {
+ color: red ;
+ font-weight: bold }
+
+ div.topic {
+ 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 }
+
+ ol.arabic {
+ list-style: decimal }
+
+ ol.loweralpha {
+ list-style: lower-alpha }
+
+ ol.upperalpha {
+ list-style: upper-alpha }
+
+ ol.lowerroman {
+ list-style: lower-roman }
+
+ ol.upperroman {
+ list-style: upper-roman }
+
+ p.attribution {
+ text-align: right ;
+ margin-left: 50% }
+
+ p.caption {
+ font-style: italic }
+
+ p.credits {
+ font-style: italic ;
+ font-size: smaller }
+
+ p.label {
+ white-space: nowrap }
+
+ p.rubric {
+ font-weight: bold ;
+ font-size: larger ;
+ color: maroon ;
+ text-align: center }
+
+ p.sidebar-title {
+ font-family: sans-serif ;
+ font-weight: bold ;
+ font-size: larger }
+
+ p.sidebar-subtitle {
+ font-family: sans-serif ;
+ font-weight: bold }
+
+ p.topic-title {
+ font-weight: bold }
+
+ pre.address {
+ margin-bottom: 0 ;
+ margin-top: 0 ;
+ 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 }
+
+ span.classifier {
+ font-family: sans-serif ;
+ font-style: oblique }
+
+ span.classifier-delimiter {
+ font-family: sans-serif ;
+ font-weight: bold }
+
+ span.interpreted {
+ font-family: sans-serif }
+
+ 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 }
+
+ 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 {
+ font: Courier,monospaced;
+ font-size: 12px;
+ background-color: #eeeeee }
+
+ ul.auto-toc {
+ list-style-type: none }
+
+ </style>
+ </head>
+ <body>
+ <div class="document" id="tinyos-2-0-overview">
+ <h1 class="title">TinyOS 2.0 Overview</h1>
+ <table class="docinfo" frame="void" rules="none">
+ <col class="docinfo-name" />
+ <col class="docinfo-content" />
+ <tbody valign="top">
+ <tr><th class="docinfo-name">Author:</th>
+ <td>Philip Levis</td></tr>
+ <tr><th class="docinfo-name">Date:</th>
+ <td>Oct 30 2006</td></tr>
+ </tbody>
+ </table>
+ <div class="note">
+ <p class="first admonition-title">Note</p>
+ <p class="last">This document gives a brief overview of TinyOS 2.0, highlighting how
+ and where it departs from 1.1 and 1.0. Further detail on these changes
+ is detailed in TEP (TinyOS Enhancement Proposal) documents.</p>
+ </div>
+ <div class="section">
+ <h1><a id="introduction" name="introduction">1. Introduction</a></h1>
+ <p>TinyOS 2.0 is a clean slate redesign and re-implementation of TinyOS.
+ Its development was motivated by our belief that many aspects of 1.x
+ strain to meet requirements and uses that were not foreseen
+ when it was designed and implemented. The structure and interfaces 1.x
+ defines have several fundamental limitations. While these limitations
+ can be worked around, this practice has led to tightly coupled
+ components, hard to find interactions, and a very steep learning curve
+ for a newcomer to sensor network programming.</p>
+ <p>TinyOS 2.0 is not backwards compatible with 1.x: code written for the
+ latter will not compile for the former. However, one important aspect
+ of 2.0's design is to minimize the difficulty of upgrading
+ code. Therefore, while porting a 1.x application to 2.0 will require
+ some work, it should not be very much.</p>
+ <p>This document provides a high-level overview of 2.0 and describes some
+ of the ways in which it departs from 1.x. It covers the basic TinyOS
+ abstractions, such as hardware abstractions, communication, timers,
+ the scheduler, booting and initialization. Further detail on each of
+ these can be found in TEPs (TinyOS Enhancement Proposals), which
+ document and describe these abstractions.</p>
+ </div>
+ <div class="section">
+ <h1><a id="platforms-hardware-abstraction" name="platforms-hardware-abstraction">2. Platforms/Hardware Abstraction</a></h1>
+ <p>Platforms exist in the <tt class="docutils literal"><span class="pre">tos/platforms</span></tt> subdirectory. In TinyOS 2.0, a
+ <em>platform</em> is a collection of <em>chips</em> and some glue code that connects
+ them together. For example, the mica2 platform is the CC1000 radio
+ chip and the ATmega128 microcontroller, while the micaZ platform is
+ the CC2420 radio and the ATmega128 microcontroller, and the Teloi
+ platforms are the CC2420 radio and the MSP430 microcontroller. Chip
+ code exists in <tt class="docutils literal"><span class="pre">tos/chips</span></tt>. A platform directory generally has a
+ <tt class="docutils literal"><span class="pre">.platform</span></tt> file, which has options to pass to the nesC compiler. For
+ example, the mica2 .platform file tells ncc to look in <tt class="docutils literal"><span class="pre">chips/cc1000</span></tt>
+ and <tt class="docutils literal"><span class="pre">chips/atm128</span></tt> directories, as well as to use avr-gcc to compile a
+ mote binary (Teloi platforms tell it to use msp430-gcc).</p>
+ <p>Hardware abstractions in TinyOS 2.0 generally follow a three-level
+ abstaction heirarchy, called the HAA (Hardware Abstraction
+ Architecture).</p>
+ <p>At the bottom of the HAA is the HPL (Hardware Presentation Layer). The
+ HPL is a thin software layer on top of the raw hardware, presenting
+ hardare such as IO pins or registers as nesC interfaces. The HPL
+ generally has no state besides the hardware itself (it has no
+ variables). HPL components usually have the prefix <tt class="docutils literal"><span class="pre">Hpl</span></tt>, followed by
+ the name of the chip. For example, the HPL components of the CC1000
+ begin with <tt class="docutils literal"><span class="pre">HplCC1000</span></tt>.</p>
+ <p>The middle of the HAA is the HAL (Hardware Abstraction Layer). The HAL
+ builds on top of the HPL and provides higher-level abstractions that
+ are easier to use than the HPL but still provide the full
+ functionality of the underlying hardware. The HAL components usually have
+ a prefix of the chip name. For example, the HAL components of the CC1000
+ begin with <tt class="docutils literal"><span class="pre">CC1000</span></tt>.</p>
+ <p>The top of the HAA is the HIL (Hardware Independent Layer). The HIL
+ builds on top of the HAL and provides abstractions that are hardware
+ independent. This generalization means that the HIL usually does not
+ provide all of the functionality that the HAL can. HIL components have
+ no naming prefix, as they represent abstractions that applications can
+ use and safely compile on multiple platforms. For example, the HIL
+ component of the CC1000 on the mica2 is <tt class="docutils literal"><span class="pre">ActiveMessageC</span></tt>, representing
+ a full active message communication layer.</p>
+ <p>The HAA is described in TEP 2: Hardware Abstraction Architecture[<a class="reference" href="#tep2">TEP2</a>].</p>
+ <p>Currently (as of the 2.0 release in November 2006), TinyOS 2.0 supports
+ the following platforms:</p>
+ <blockquote>
+ <ul class="simple">
+ <li>eyesIFXv2</li>
+ <li>intelmote2</li>
+ <li>mica2</li>
+ <li>mica2dot</li>
+ <li>micaZ</li>
+ <li>telosb</li>
+ <li>tinynode</li>
+ <li>btnode3</li>
+ </ul>
+ </blockquote>
+ <p>The btnode3 platform is not included in the RPM.</p>
+ </div>
+ <div class="section">
+ <h1><a id="scheduler" name="scheduler">3. Scheduler</a></h1>
+ <p>As with TinyOS 1.x, TinyOS 2.0 scheduler has a non-preemptive FIFO
+ policy. However, tasks in 2.0 operate slightly differently than in
+ 1.x.</p>
+ <p>In TinyOS 1.x, there is a shared task queue for all tasks, and a
+ component can post a task multiple times. If the task queue is full,
+ the post operation fails. Experience with networking stacks showed
+ this to be problematic, as the task might signal completion of a
+ split-phase operation: if the post fails, the component above might
+ block forever, waiting for the completion event.</p>
+ <p>In TinyOS 2.x, every task has its own reserved slot in the task queue,
+ and a task can only be posted once. A post fails if and only if the
+ task has already been posted. If a component needs to post a task
+ multiple times, it can set an internal state variable so that when
+ the task executes, it reposts itself.</p>
+ <p>This slight change in semantics greatly simplifies a lot of component
+ code. Rather than test to see if a task is posted already before
+ posting it, a component can just post the task. Components do not have
+ to try to recover from failed posts and retry. The cost is one byte of
+ state per task. Even in large systems such as TinyDB, this cost is
+ under one hundred bytes (in TinyDB is is approximately 50).</p>
+ <p>Applications can also replace the scheduler, if they wish. This allows
+ programmers to try new scheduling policies, such as priority- or
+ deadline-based. It is important to maintain non-preemptiveness,
+ however, or the scheduler will break all nesC's static concurrency
+ analysis. Details on the new scheduler and how to extend it can be found
+ in TEP 106: Schedulers and Tasks[<a class="reference" href="#tep106">TEP106</a>].</p>
+ </div>
+ <div class="section">
+ <h1><a id="booting-initialization" name="booting-initialization">4. Booting/Initialization</a></h1>
+ <p>TinyOS 2.0 has a different boot sequence than 1.x. The 1.x interface
+ <tt class="docutils literal"><span class="pre">StdControl</span></tt> has been split into two interfaces: <tt class="docutils literal"><span class="pre">Init</span></tt> and
+ <tt class="docutils literal"><span class="pre">StdControl</span></tt>. The latter only has two commands: <tt class="docutils literal"><span class="pre">start</span></tt> and <tt class="docutils literal"><span class="pre">stop</span></tt>.
+ In TinyOS 1.x, wiring components to the boot sequence would cause them
+ to be powered up and started at boot. That is no longer the case: the
+ boot sequence only initializes components. When it has completed
+ initializing the scheduler, hardware, and software, the boot sequence
+ signals the <tt class="docutils literal"><span class="pre">Boot.booted</span></tt> event. The top-level application component
+ handles this event and start services accordingly. Details on
+ the new boot sequence can be found in TEP 107: TinyOS 2.x Boot
+ Sequence[<a class="reference" href="#tep107">TEP107</a>].</p>
+ </div>
+ <div class="section">
+ <h1><a id="virtualization" name="virtualization">5. Virtualization</a></h1>
+ <p>TinyOS 2.0 is written with nesC 1.2, which introduces the concept
+ of a 'generic' or instantiable component. Generic modules allow
+ TinyOS to have reusable data structures, such as bit vectors and
+ queues, which simplify development. More importantly, generic
+ configurations allow services to encapsulate complex wiring
+ relationships for clients that need them.</p>
+ <p>In practice, this means that many basic TinyOS services are now
+ <em>virtualized.</em> Rather than wire to a component with a parameterized
+ interface (e.g., GenericComm or TimerC in 1.x), a program instantiates
+ a service component that provides the needed interface. This
+ service component does all of the wiring underneath (e.g., in the
+ case of timers, to a unique) automatically, reducing wiring
+ mistakes and simplifying use of the abstraction.</p>
+ </div>
+ <div class="section">
+ <h1><a id="timers" name="timers">6. Timers</a></h1>
+ <p>TinyOS 2.0 provides a much richer set of timer interfaces than
+ 1.x. Experience has shown that timers are one of the most critical
+ abstractions a mote OS can provide, and so 2.0 expands the fidelity
+ and form that timers take. Depending on the hardware resources of a
+ platform, a component can use 32KHz as well as millisecond granularity
+ timers, and the timer system may provide one or two high-precision
+ timers that fire asynchronously (they have the async
+ keyword). Components can query their timers for how much time
+ remainins before they fire, and can start timers in the future (e.g.,
+ 'start firing a timer at 1Hz starting 31ms from now'). TEP 102:
+ Timers[<a class="reference" href="#tep102">TEP102</a>] defines what HIL components a platform must provide
+ in order to support standard TinyOS timers. Platforms are
+ required to provide millisecond granularity timers, and can provide
+ finer granularity timers (e.g., 32kHz) if needed.</p>
+ <p>Timers present a good example of virtualization in 2.0. In 1.x,
+ a program instantiates a timer by wiring to TimerC:</p>
+ <pre class="literal-block">
+ components App, TimerC;
+ App.Timer -> TimerC.Timer[unique("Timer")];
+ </pre>
+ <p>In 2.0, a program instantiates a timer:</p>
+ <pre class="literal-block">
+ components App, new TimerMilliC();
+ App.Timer -> TimerMilliC;
+ </pre>
+ </div>
+ <div class="section">
+ <h1><a id="communication" name="communication">7. Communication</a></h1>
+ <p>In TinyOS 2.0, the message buffer type is <tt class="docutils literal"><span class="pre">message_t</span></tt>, and it is a
+ buffer that is large enough to hold a packet from any of a node's
+ communication interfaces. The structure itself is completely opaque:
+ components cannot reference its fields. Instead, all buffer accesses
+ go through interfaces. For example, to get the destination address of
+ an AM packet named <tt class="docutils literal"><span class="pre">msg</span></tt>, a component calls <tt class="docutils literal"><span class="pre">AMPacket.destination(msg)</span></tt>.</p>
+ <p>Send interfaces distinguish the addressing mode of communication
+ abstractions. For example, active message communication has the
+ <tt class="docutils literal"><span class="pre">AMSend</span></tt> interface, as sending a packet require an AM destination
+ address. In contrast, broadcasting and collection tree abstractions
+ have the address-free <tt class="docutils literal"><span class="pre">Send</span></tt> interface.</p>
+ <p>Active messages are the network HIL. A platform's <tt class="docutils literal"><span class="pre">ActiveMessageC</span></tt>
+ component defines which network interface is the standard
+ communication medium. For example, a mica2 defines the CC1000 active
+ message layer as ActiveMessageC, while the TMote defines the CC2420
+ active message layer as ActiveMessageC.</p>
+ <p>There is no longer a TOS_UART_ADDRESS for active message
+ communication. Instead, a component should wire to
+ SerialActiveMessageC, which provides active message communication over
+ the serial port.</p>
+ <p>Active message communication is virtualized through four generic
+ components, which take the AM type as a parameter: AMSenderC,
+ AMReceiverC, AMSnooperC, and AMSnoopingReceiverC. AMSenderC is
+ virtualized in that the call to send() does not fail if some
+ other component is sending (as it does with GenericComm in 1.x). Instead,
+ it fails only if that particular AMSenderC already has a packet
+ outstanding or if the radio is not in a sending state. Underneath,
+ the active message system queues and sends these outstanding packets.
+ This is different than the QueuedSendC approach of 1.x, in which there
+ is an N-deep queue that is shared among all senders. With N AMSenderC
+ components, there is an N-deep queue where each sender has a single
+ reserved entry. This means that each AMSenderC receives
+ 1/n of the available post-MAC transmission opportunities, where
+ n is the number of AMSenderC components with outstanding packets.
+ In the worst case, n is the number of components; even when every
+ protocol and component that sends packets is trying to send a packet,
+ each one will receive its fair share of transmission opportunities.</p>
+ <p>Further information on message_t can be found in TEP 111:
+ message_t[<a class="reference" href="#tep111">TEP111</a>], while further information on AM can be
+ found in TEP 116: Packet Protocols[<a class="reference" href="#tep116">TEP116</a>].</p>
+ <p>The current TinyOS release has a low-power stack for the CC1000
+ radio (mica2 platform) and an experimental low-power stack for
+ the CC2420 radio (micaz, telosb, and intelmote2 platforms).</p>
+ </div>
+ <div class="section">
+ <h1><a id="sensors" name="sensors">8. Sensors</a></h1>
+ <p>In TinyOS 2.0, named sensor components comprise the HIL of a
+ platform's sensors. TEP 114 describes a set of HIL data acquisition
+ interfaces, such as Read, ReadStream, and Get, which sensors
+ provide according to their acquisition capabilities.</p>
+ <p>If a component needs
+ high-frequency or very accurate sampling, it must use the HAL, which
+ gives it the full power of the underlying platform (highly accurate
+ platform-independent sampling is not really feasible, due to the
+ particulars of individual platforms). <tt class="docutils literal"><span class="pre">Read</span></tt> assumes that the
+ request can tolerate some latencies (for example, it might schedule
+ competing requests using a FIFO policy).</p>
+ <p>Details on the ADC subsystem can be found in
+ TEP 101: Analog-to-Digital Converters[<a class="reference" href="#tep101">TEP101</a>]; details on
+ the organization of sensor boards can be found in TEP 109:
+ Sensorboards[<a class="reference" href="#tep109">TEP109</a>], and the details of the HIL sensor interfaces
+ can be found in TEP 114: Source and Sink Independent Drivers[<a class="reference" href="#tep114">TEP114</a>].</p>
+ </div>
+ <div class="section">
+ <h1><a id="error-codes" name="error-codes">9. Error Codes</a></h1>
+ <p>The standard TinyOS 1.x return code is <tt class="docutils literal"><span class="pre">result_t</span></tt>, whose value is
+ either SUCCESS (a non-zero value) or FAIL (a zero value). While this
+ makes conditionals on calls very easy to write (e.g., <tt class="docutils literal"><span class="pre">if</span> <span class="pre">(call</span>
+ <span class="pre">A.b())</span></tt>), it does not allow the callee to distinguish causes of error
+ to the caller. In TinyOS 2.0, <tt class="docutils literal"><span class="pre">result_t</span></tt> is replaced by <tt class="docutils literal"><span class="pre">error_t</span></tt>,
+ whose values include SUCCESS, FAIL, EBUSY, and ECANCEL. Interface
+ commands and events define which error codes they may return and why.</p>
+ <p>From the perspective of porting code, this is the most significant
+ different in 2.0. Calls that were once:</p>
+ <pre class="literal-block">
+ if (call X.y()) {
+ busy = TRUE;
+ }
+ </pre>
+ <p>now have their meanings reversed. In 1.x, the busy statement will execute
+ if the call succeeds, while in 2.0 it will execute if the call fails.
+ This encourages a more portable, upgradable, and readable approach:</p>
+ <pre class="literal-block">
+ if (call X.y() == SUCCESS) {
+ busy = TRUE;
+ }
+ </pre>
+ </div>
+ <div class="section">
+ <h1><a id="arbitration" name="arbitration">10. Arbitration</a></h1>
+ <p>While basic abstractions, such as packet communication and timers,
+ can be virtualized, experiences with 1.x showed that some cannot
+ without either adding significant complexity or limiting the system.
+ The most pressing example of this is a shared bus on a microcontroller.
+ Many different systems -- sensors, storage, the radio -- might need
+ to use the bus at the same time, so some way of arbitrating access
+ is needed.</p>
+ <p>To support these kinds of abstractions, TinyOS 2.0 introduces
+ the Resource interface, which components use to request and
+ acquire shared resources, and arbiters, which provide a policy for
+ arbitrating access between multiple clients. For some abstractions,
+ the arbiter also provides a power management policy, as it can tell
+ when the system is no longer needed and can be safely turned off.</p>
+ <p>TEP 108: Resource Arbitration[<a class="reference" href="#tep108">TEP108</a>] describes the Resource interface
+ and how arbiters work.</p>
+ </div>
+ <div class="section">
+ <h1><a id="power-management" name="power-management">11. Power Management</a></h1>
+ <p>Power management in 2.0 is divided into two parts: the power state
+ of the microcontroller and the power state of devices. The former,
+ discussed in TEP 112: Microcontroller Power Management[<a class="reference" href="#tep112">TEP112</a>],
+ is computed in a chip-specific manner by examining which devices
+ and interrupt souces are active. The latter, discussed in
+ TEP 115: Power Management of Non-Virtualised Devices{<a class="reference" href="#tep115">TEP115</a>], is handled
+ through resource abiters. Fully virtualized services have their
+ own, individual power management policies.</p>
+ <p>TinyOS 2.0 provides low-power stacks for the CC1000 (mica2)
+ and CC2420 (micaz, telosb, imote2) radios. Both use a low-power
+ listening apporach, where transmitters send long preambles or
+ repeatedly send packets and receivers wake up periodically to
+ sense the channel to hear if there is a packet being
+ transmitted. The low-power stack CC1000 is standard, while
+ the CC2420 stack is experimental. That is, the default CC1000
+ stack (chips/cc1000) has low-power-listening, while the default
+ CC2420 stack (chips/cc2420) does not. To use the low-power CC2420
+ stack, you must include chips/cc2420_lpl in your application Makefile.</p>
+ </div>
+ <div class="section">
+ <h1><a id="network-protocols" name="network-protocols">12. Network Protocols</a></h1>
+ <p>TinyOS 2.0 provides simple reference implementations of two of
+ the most basic protocols used in mote networks: dissemination
+ and collection. Dissemination reliably delivers small (fewer
+ than 20 byte) data items to every node in a network, while
+ collection builds a routing tree rooted at a sink node. Together,
+ these two protocols enable a wide range of data collection
+ applications. Collection has advanced significantly since the
+ most recent beta release; experimental tests in multiple
+ network conditions have seen very high (>98%) deliver rates
+ as long as the network is not saturated.</p>
+ </div>
+ <div class="section">
+ <h1><a id="conclusion" name="conclusion">13. Conclusion</a></h1>
+ <p>TinyOS 2.0 represents the next step of TinyOS development. Building on
+ user experiences over the past few years, it has taken the basic
+ TinyOS architecture and pushed it forward in several directions,
+ hopefully leading to simpler and easier application development. It is
+ still under active development: future prereleases will include
+ non-volatile storage, basic multihop protocols (collection routing,
+ dissemination), and further power management abstractions.</p>
+ </div>
+ <div class="section">
+ <h1><a id="acknowledgments" name="acknowledgments">14. Acknowledgments</a></h1>
+ <p>TinyOS 2.0 is the result of a lot of hard work from a lot of people,
+ including (but not limited to) David Gay, Philip Levis, Cory Sharp,
+ Vlado Handziski, Jan Hauer, Kevin Klues, Joe Polastre, Jonathan Hui,
+ Prabal Dutta,
+ Gilman Tolle, Martin Turon, Phil Buonodonna, Ben Greenstein, David Culler,
+ Kristin Wright, Ion Yannopoulos, Henri Dubois-Ferriere, Jan Beutel,
+ Robert Szewczyk, Rodrigo Fonseca, Kyle Jamieson, Omprakash Gnawali,
+ David Moss, and Kristin Wright.</p>
+ </div>
+ <div class="section">
+ <h1><a id="author-s-address" name="author-s-address">15. Author's Address</a></h1>
+ <div class="line-block">
+ <div class="line">Philip Levis</div>
+ <div class="line">358 Gates</div>
+ <div class="line">Computer Systems Laboratory</div>
+ <div class="line">Stanford University</div>
+ <div class="line">Stanford, CA 94305</div>
+ <div class="line"><br /></div>
+ <div class="line">phone - +1 650 725 9046</div>
+ <div class="line"><br /></div>
+ <div class="line">email - <a class="reference" href="mailto:pal@cs.stanford.edu">pal@cs.stanford.edu</a></div>
+ </div>
+ </div>
+ <div class="section">
+ <h1><a id="citations" name="citations">16. Citations</a></h1>
+ <table class="docutils citation" frame="void" id="tep1" rules="none">
+ <colgroup><col class="label" /><col /></colgroup>
+ <tbody valign="top">
+ <tr><td class="label"><a name="tep1">[TEP1]</a></td><td>TEP 1: TEP Structure and Keywords. <a class="reference" href="http://tinyos.cvs.sourceforge.net/">http://tinyos.cvs.sourceforge.net/</a><em>checkout</em>/tinyos/tinyos-2.x/doc/html/tep1.html?pathrev=tinyos-2_0_devel-BRANCH</td></tr>
+ </tbody>
+ </table>
+ <table class="docutils citation" frame="void" id="tep2" rules="none">
+ <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. <a class="reference" href="http://tinyos.cvs.sourceforge.net/">http://tinyos.cvs.sourceforge.net/</a><em>checkout</em>/tinyos/tinyos-2.x/doc/html/tep2.html?pathrev=tinyos-2_0_devel-BRANCH</td></tr>
+ </tbody>
+ </table>
+ <table class="docutils citation" frame="void" id="tep3" rules="none">
+ <colgroup><col class="label" /><col /></colgroup>
+ <tbody valign="top">
+ <tr><td class="label"><a name="tep3">[TEP3]</a></td><td>TEP 3: Coding Standard. <a class="reference" href="http://tinyos.cvs.sourceforge.net/">http://tinyos.cvs.sourceforge.net/</a><em>checkout</em>/tinyos/tinyos-2.x/doc/html/tep3.html?pathrev=tinyos-2_0_devel-BRANCH</td></tr>
+ </tbody>
+ </table>
+ <table class="docutils citation" frame="void" id="tep101" rules="none">
+ <colgroup><col class="label" /><col /></colgroup>
+ <tbody valign="top">
+ <tr><td class="label"><a name="tep101">[TEP101]</a></td><td>TEP 101: Analog-to-Digital Converters. <a class="reference" href="http://tinyos.cvs.sourceforge.net/">http://tinyos.cvs.sourceforge.net/</a><em>checkout</em>/tinyos/tinyos-2.x/doc/html/tep101.html?pathrev=tinyos-2_0_devel-BRANCH</td></tr>
+ </tbody>
+ </table>
+ <table class="docutils citation" frame="void" id="tep102" rules="none">
+ <colgroup><col class="label" /><col /></colgroup>
+ <tbody valign="top">
+ <tr><td class="label"><a name="tep102">[TEP102]</a></td><td>TEP 102: Timers. <a class="reference" href="http://tinyos.cvs.sourceforge.net/">http://tinyos.cvs.sourceforge.net/</a><em>checkout</em>/tinyos/tinyos-2.x/doc/html/tep102.html?pathrev=tinyos-2_0_devel-BRANCH</td></tr>
+ </tbody>
+ </table>
+ <table class="docutils citation" frame="void" id="tep106" rules="none">
+ <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. <a class="reference" href="http://tinyos.cvs.sourceforge.net/">http://tinyos.cvs.sourceforge.net/</a><em>checkout</em>/tinyos/tinyos-2.x/doc/html/tep106.html?pathrev=tinyos-2_0_devel-BRANCH</td></tr>
+ </tbody>
+ </table>
+ <table class="docutils citation" frame="void" id="tep107" rules="none">
+ <colgroup><col class="label" /><col /></colgroup>
+ <tbody valign="top">
+ <tr><td class="label"><a name="tep107">[TEP107]</a></td><td>TEP 107: Boot Sequence. <a class="reference" href="http://tinyos.cvs.sourceforge.net/">http://tinyos.cvs.sourceforge.net/</a><em>checkout</em>/tinyos/tinyos-2.x/doc/html/tep107.html?pathrev=tinyos-2_0_devel-BRANCH</td></tr>
+ </tbody>
+ </table>
+ <table class="docutils citation" frame="void" id="tep108" rules="none">
+ <colgroup><col class="label" /><col /></colgroup>
+ <tbody valign="top">
+ <tr><td class="label"><a name="tep108">[TEP108]</a></td><td>TEP 108: message_t. <a class="reference" href="http://tinyos.cvs.sourceforge.net/">http://tinyos.cvs.sourceforge.net/</a><em>checkout</em>/tinyos/tinyos-2.x/doc/html/tep108.html?pathrev=tinyos-2_0_devel-BRANCH</td></tr>
+ </tbody>
+ </table>
+ <table class="docutils citation" frame="void" id="tep109" rules="none">
+ <colgroup><col class="label" /><col /></colgroup>
+ <tbody valign="top">
+ <tr><td class="label"><a name="tep109">[TEP109]</a></td><td>TEP 109: Sensorboards. <a class="reference" href="http://tinyos.cvs.sourceforge.net/">http://tinyos.cvs.sourceforge.net/</a><em>checkout</em>/tinyos/tinyos-2.x/doc/html/tep109.html?pathrev=tinyos-2_0_devel-BRANCH</td></tr>
+ </tbody>
+ </table>
+ <table class="docutils citation" frame="void" id="tep110" rules="none">
+ <colgroup><col class="label" /><col /></colgroup>
+ <tbody valign="top">
+ <tr><td class="label"><a name="tep110">[TEP110]</a></td><td>TEP 110: Service Distributions. <a class="reference" href="http://tinyos.cvs.sourceforge.net/">http://tinyos.cvs.sourceforge.net/</a><em>checkout</em>/tinyos/tinyos-2.x/doc/html/tep110.html?pathrev=tinyos-2_0_devel-BRANCH</td></tr>
+ </tbody>
+ </table>
+ <table class="docutils citation" frame="void" id="tep111" rules="none">
+ <colgroup><col class="label" /><col /></colgroup>
+ <tbody valign="top">
+ <tr><td class="label"><a name="tep111">[TEP111]</a></td><td>TEP 111: message_t. <a class="reference" href="http://tinyos.cvs.sourceforge.net/">http://tinyos.cvs.sourceforge.net/</a><em>checkout</em>/tinyos/tinyos-2.x/doc/html/tep111.html?pathrev=tinyos-2_0_devel-BRANCH</td></tr>
+ </tbody>
+ </table>
+ <table class="docutils citation" frame="void" id="tep112" rules="none">
+ <colgroup><col class="label" /><col /></colgroup>
+ <tbody valign="top">
+ <tr><td class="label"><a name="tep112">[TEP112]</a></td><td>TEP 112: Microcontroller Power Management. <a class="reference" href="http://tinyos.cvs.sourceforge.net/">http://tinyos.cvs.sourceforge.net/</a><em>checkout</em>/tinyos/tinyos-2.x/doc/html/tep112.html?pathrev=tinyos-2_0_devel-BRANCH</td></tr>
+ </tbody>
+ </table>
+ <table class="docutils citation" frame="void" id="tep113" rules="none">
+ <colgroup><col class="label" /><col /></colgroup>
+ <tbody valign="top">
+ <tr><td class="label"><a name="tep113">[TEP113]</a></td><td>TEP 113: Serial Communication. <a class="reference" href="http://tinyos.cvs.sourceforge.net/">http://tinyos.cvs.sourceforge.net/</a><em>checkout</em>/tinyos/tinyos-2.x/doc/html/tep113.html?pathrev=tinyos-2_0_devel-BRANCH</td></tr>
+ </tbody>
+ </table>
+ <table class="docutils citation" frame="void" id="tep114" rules="none">
+ <colgroup><col class="label" /><col /></colgroup>
+ <tbody valign="top">
+ <tr><td class="label"><a name="tep114">[TEP114]</a></td><td>TEP 114: SIDs: Source and Sink Independent Drivers. <a class="reference" href="http://tinyos.cvs.sourceforge.net/">http://tinyos.cvs.sourceforge.net/</a><em>checkout</em>/tinyos/tinyos-2.x/doc/html/tep114.html?pathrev=tinyos-2_0_devel-BRANCH</td></tr>
+ </tbody>
+ </table>
+ <table class="docutils citation" frame="void" id="tep115" rules="none">
+ <colgroup><col class="label" /><col /></colgroup>
+ <tbody valign="top">
+ <tr><td class="label"><a name="tep115">[TEP115]</a></td><td>TEP 115: Power Management of Non-Virtualised Devices. <a class="reference" href="http://tinyos.cvs.sourceforge.net/">http://tinyos.cvs.sourceforge.net/</a><em>checkout</em>/tinyos/tinyos-2.x/doc/html/tep115.html?pathrev=tinyos-2_0_devel-BRANCH</td></tr>
+ </tbody>
+ </table>
+ <table class="docutils citation" frame="void" id="tep116" rules="none">
+ <colgroup><col class="label" /><col /></colgroup>
+ <tbody valign="top">
+ <tr><td class="label"><a name="tep116">[TEP116]</a></td><td>TEP 116: Packet Protocols. <a class="reference" href="http://tinyos.cvs.sourceforge.net/">http://tinyos.cvs.sourceforge.net/</a><em>checkout</em>/tinyos/tinyos-2.x/doc/html/tep116.html?pathrev=tinyos-2_0_devel-BRANCH</td></tr>
+ </tbody>
+ </table>
+ </div>
+ </div>
+ </body>
+ </html>
Index: tep112.html
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/doc/html/tep112.html,v
retrieving revision 1.9
retrieving revision 1.10
diff -C2 -d -r1.9 -r1.10
*** tep112.html 21 Apr 2007 07:04:39 -0000 1.9
--- tep112.html 14 Aug 2007 18:58:00 -0000 1.10
***************
*** 4,8 ****
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
! <meta name="generator" content="Docutils 0.3.6: http://docutils.sourceforge.net/" />
<title>Microcontroller Power Management</title>
<meta name="author" content="Robert Szewczyk, Philip Levis, Martin Turon, Lama Nachman, Philip Buonadonna, Vlado Handziski" />
--- 4,8 ----
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
! <meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
<title>Microcontroller Power Management</title>
<meta name="author" content="Robert Szewczyk, Philip Levis, Martin Turon, Lama Nachman, Philip Buonadonna, Vlado Handziski" />
***************
*** 42,50 ****
margin-bottom: 0.5em }
- /* Uncomment (& remove this text!) to get bold-faced definition list terms
- dt {
- font-weight: bold }
- */
-
div.abstract {
margin: 2em 5em }
--- 42,45 ----
***************
*** 284,287 ****
--- 279,283 ----
</head>
<body>
+ <div class="document" id="microcontroller-power-management">
<h1 class="title">Microcontroller Power Management</h1>
<table class="docinfo" frame="void" rules="none">
***************
*** 311,315 ****
</tbody>
</table>
- <div class="document" id="microcontroller-power-management">
<div class="note">
<p class="first admonition-title">Note</p>
--- 307,310 ----
***************
*** 319,329 ****
TEP 1.</p>
</div>
! <div class="section" id="abstract">
! <h1><a name="abstract">Abstract</a></h1>
<p>This memo documents how TinyOS manages the lower power state of a
microcontroller.</p>
</div>
! <div class="section" id="introduction">
! <h1><a name="introduction">1. Introduction</a></h1>
<p>Microcontrollers often have several power states, with varying power
draws, wakeup latencies, and peripheral support. The microcontroller
--- 314,324 ----
TEP 1.</p>
</div>
! <div class="section">
! <h1><a id="abstract" name="abstract">Abstract</a></h1>
<p>This memo documents how TinyOS manages the lower power state of a
microcontroller.</p>
</div>
! <div class="section">
! <h1><a id="introduction" name="introduction">1. Introduction</a></h1>
<p>Microcontrollers often have several power states, with varying power
draws, wakeup latencies, and peripheral support. The microcontroller
***************
*** 341,346 ****
management.</p>
</div>
! <div class="section" id="background">
! <h1><a name="background">2. Background</a></h1>
<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
--- 336,341 ----
management.</p>
</div>
! <div class="section">
! <h1><a id="background" name="background">2. Background</a></h1>
<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
***************
*** 394,399 ****
state.</p>
</div>
! <div class="section" id="id1">
! <h1><a name="id1">3. Microcontroller Power Management</a></h1>
<p>TinyOS 2.x uses three basic mechanisms to manage and control
microcontroller power states: a dirty bit, a chip-specific low power
--- 389,394 ----
state.</p>
</div>
! <div class="section">
! <h1><a id="id1" name="id1">3. Microcontroller Power Management</a></h1>
<p>TinyOS 2.x uses three basic mechanisms to manage and control
microcontroller power states: a dirty bit, a chip-specific low power
***************
*** 458,463 ****
<p>McuSleepC MAY have additional interfaces.</p>
</div>
! <div class="section" id="the-dirty-bit">
! <h1><a name="the-dirty-bit">3.1 The Dirty Bit</a></h1>
<p>Whenever a Hardware Presentation Layer (HPL, see TEP 2: Hardware
Abstraction Architecture[<a class="reference" href="#id2">1</a>]) component changes an aspect of
--- 453,458 ----
<p>McuSleepC MAY have additional interfaces.</p>
</div>
! <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[<a class="reference" href="#id2">1</a>]) component changes an aspect of
***************
*** 469,474 ****
McuSleep.sleep() being called.</p>
</div>
! <div class="section" id="low-power-state-calculation">
! <h1><a name="low-power-state-calculation">3.2 Low Power State Calculation</a></h1>
<p>McuSleepC is responsible for calculating the lowest power state that
it can safely put the microcontroller into without disrupting the
--- 464,469 ----
McuSleep.sleep() being called.</p>
</div>
! <div class="section">
! <h1><a id="low-power-state-calculation" name="low-power-state-calculation">3.2 Low Power State Calculation</a></h1>
<p>McuSleepC is responsible for calculating the lowest power state that
it can safely put the microcontroller into without disrupting the
***************
*** 550,555 ****
</table>
</div>
! <div class="section" id="power-state-override">
! <h1><a name="power-state-override">3.3 Power State Override</a></h1>
<p>When McuSleepC computes the best low power state, it MUST call
<tt class="docutils literal"><span class="pre">PowerOverride.lowestState().</span></tt> McuSleepC SHOULD have a default
--- 545,550 ----
</table>
</div>
! <div class="section">
! <h1><a id="power-state-override" name="power-state-override">3.3 Power State Override</a></h1>
<p>When McuSleepC computes the best low power state, it MUST call
<tt class="docutils literal"><span class="pre">PowerOverride.lowestState().</span></tt> McuSleepC SHOULD have a default
***************
*** 574,579 ****
timer stack for the Atmega128 microcontroller family.</p>
</div>
! <div class="section" id="peripherals-and-subsystems">
! <h1><a name="peripherals-and-subsystems">4. Peripherals and Subsystems</a></h1>
<p>At the HIL level, TinyOS subsystems generally have a simple,
imperative power management interface. Depending on the latencies
--- 569,574 ----
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>
<p>At the HIL level, TinyOS subsystems generally have a simple,
imperative power management interface. Depending on the latencies
***************
*** 588,609 ****
subsystem will be notified of a significant change and act
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" id="implementation">
! <h1><a 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" id="author-s-address">
! <h1><a name="author-s-address">6. Author's Address</a></h1>
<div class="line-block">
<div class="line">Robert Szewczyk</div>
--- 583,604 ----
subsystem will be notified of a significant change and act
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">
! <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>
***************
*** 660,665 ****
</div>
</div>
! <div class="section" id="citations">
! <h1><a name="citations">6. Citations</a></h1>
<table class="docutils footnote" frame="void" id="id2" rules="none">
<colgroup><col class="label" /><col /></colgroup>
--- 655,660 ----
</div>
</div>
! <div class="section">
! <h1><a id="citations" name="citations">6. Citations</a></h1>
<table class="docutils footnote" frame="void" id="id2" rules="none">
<colgroup><col class="label" /><col /></colgroup>
Index: tep109.html
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/doc/html/tep109.html,v
retrieving revision 1.8
retrieving revision 1.9
diff -C2 -d -r1.8 -r1.9
*** tep109.html 21 Apr 2007 07:04:39 -0000 1.8
--- tep109.html 14 Aug 2007 18:58:00 -0000 1.9
***************
*** 4,8 ****
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
! <meta name="generator" content="Docutils 0.3.6: http://docutils.sourceforge.net/" />
<title>Sensors and Sensor Boards</title>
<meta name="author" content="David Gay, Phil Levis, Wei Hong, Joe Polastre, and Gilman Tolle" />
--- 4,8 ----
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
! <meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
<title>Sensors and Sensor Boards</title>
<meta name="author" content="David Gay, Phil Levis, Wei Hong, Joe Polastre, and Gilman Tolle" />
***************
*** 42,50 ****
margin-bottom: 0.5em }
- /* Uncomment (& remove this text!) to get bold-faced definition list terms
- dt {
- font-weight: bold }
- */
-
div.abstract {
margin: 2em 5em }
--- 42,45 ----
***************
*** 284,287 ****
--- 279,283 ----
</head>
<body>
+ <div class="document" id="sensors-and-sensor-boards">
<h1 class="title">Sensors and Sensor Boards</h1>
<table class="docinfo" frame="void" rules="none">
***************
*** 307,311 ****
</tbody>
</table>
- <div class="document" id="sensors-and-sensor-boards">
<div class="note">
<p class="first admonition-title">Note</p>
--- 303,306 ----
***************
*** 315,320 ****
TEP 1.</p>
</div>
! <div class="section" id="abstract">
! <h1><a name="abstract">Abstract</a></h1>
<p>This memo documents how sensor drivers are organized in TinyOS and how
sets of sensor drivers are combined into sensor boards and sensor
--- 310,315 ----
TEP 1.</p>
</div>
! <div class="section">
! <h1><a id="abstract" name="abstract">Abstract</a></h1>
<p>This memo documents how sensor drivers are organized in TinyOS and how
sets of sensor drivers are combined into sensor boards and sensor
***************
*** 322,327 ****
that provide access to sensors.</p>
</div>
! <div class="section" id="principles">
! <h1><a name="principles">1. Principles</a></h1>
<p>This section describes the basic organization principles for sensor
drivers in TinyOS.</p>
--- 317,322 ----
that provide access to sensors.</p>
</div>
! <div class="section">
! <h1><a id="principles" name="principles">1. Principles</a></h1>
<p>This section describes the basic organization principles for sensor
drivers in TinyOS.</p>
***************
*** 375,380 ****
interpret the value.</p>
</div>
! <div class="section" id="sensor-hil-components">
! <h1><a name="sensor-hil-components">2. Sensor HIL Components</a></h1>
<p>A sensor HIL component MUST provide:</p>
<ul class="simple">
--- 370,375 ----
interpret the value.</p>
</div>
! <div class="section">
! <h1><a id="sensor-hil-components" name="sensor-hil-components">2. Sensor HIL Components</a></h1>
<p>A sensor HIL component MUST provide:</p>
<ul class="simple">
***************
*** 468,473 ****
</pre>
</div>
! <div class="section" id="sensor-hal-components">
! <h1><a name="sensor-hal-components">3. Sensor HAL Components</a></h1>
<p>Sensors with a richer interface than would be supported by the SID
interfaces MAY provide a HAL component in addition to a HIL
--- 463,468 ----
</pre>
</div>
! <div class="section">
! <h1><a id="sensor-hal-components" name="sensor-hal-components">3. Sensor HAL Components</a></h1>
<p>Sensors with a richer interface than would be supported by the SID
interfaces MAY provide a HAL component in addition to a HIL
***************
*** 498,503 ****
</pre>
</div>
! <div class="section" id="directory-organization-guidelines">
! <h1><a name="directory-organization-guidelines">4. Directory Organization Guidelines</a></h1>
<p>Because the same physical sensor can be attached to TinyOS platforms
in many different ways, the organization of sensor drivers SHOULD
--- 493,498 ----
</pre>
</div>
! <div class="section">
! <h1><a id="directory-organization-guidelines" name="directory-organization-guidelines">4. Directory Organization Guidelines</a></h1>
<p>Because the same physical sensor can be attached to TinyOS platforms
in many different ways, the organization of sensor drivers SHOULD
***************
*** 568,573 ****
receives enough <cite>-I</cite> directives to locate all of the necessary pieces.</p>
</div>
! <div class="section" id="authors-addresses">
! <h1><a name="authors-addresses">5. Authors' Addresses</a></h1>
<div class="line-block">
<div class="line">David Gay</div>
--- 563,568 ----
receives enough <cite>-I</cite> directives to locate all of the necessary pieces.</p>
</div>
! <div class="section">
! <h1><a id="authors-addresses" name="authors-addresses">5. Authors' Addresses</a></h1>
<div class="line-block">
<div class="line">David Gay</div>
***************
*** 612,617 ****
</div>
</div>
! <div class="section" id="citations">
! <h1><a name="citations">6. Citations</a></h1>
<table class="docutils citation" frame="void" id="tep2" rules="none">
<colgroup><col class="label" /><col /></colgroup>
--- 607,612 ----
</div>
</div>
! <div class="section">
! <h1><a id="citations" name="citations">6. Citations</a></h1>
<table class="docutils citation" frame="void" id="tep2" rules="none">
<colgroup><col class="label" /><col /></colgroup>
***************
*** 633,640 ****
</table>
</div>
! <div class="section" id="appendix-a-sensor-driver-examples">
! <h1><a name="appendix-a-sensor-driver-examples">Appendix A: Sensor Driver Examples</a></h1>
! <div class="section" id="analog-adc-connected-sensor">
! <h2><a name="analog-adc-connected-sensor">1. Analog ADC-Connected Sensor</a></h2>
<p>The Analog sensor requires two components</p>
<ul class="simple">
--- 628,635 ----
</table>
</div>
! <div class="section">
! <h1><a id="appendix-a-sensor-driver-examples" name="appendix-a-sensor-driver-examples">Appendix A: Sensor Driver Examples</a></h1>
! <div class="section">
! <h2><a id="analog-adc-connected-sensor" name="analog-adc-connected-sensor">1. Analog ADC-Connected Sensor</a></h2>
<p>The Analog sensor requires two components</p>
<ul class="simple">
***************
*** 697,702 ****
</pre>
</div>
! <div class="section" id="binary-pin-connected-sensor">
! <h2><a name="binary-pin-connected-sensor">2. Binary Pin-Connected Sensor</a></h2>
<p>The Binary sensor gets a bit more complex, because it has three
components:</p>
--- 692,697 ----
</pre>
</div>
! <div class="section">
! <h2><a id="binary-pin-connected-sensor" name="binary-pin-connected-sensor">2. Binary Pin-Connected Sensor</a></h2>
<p>The Binary sensor gets a bit more complex, because it has three
components:</p>
***************
*** 738,742 ****
uses interface GeneralIO;
! uses interface GpioInterrupt;
}
implementation {
--- 733,737 ----
uses interface GeneralIO;
! uses interface GpioInterrupt;
}
implementation {
***************
*** 774,780 ****
bool pinHigh;
pinHigh = m_pinHigh;
!
signal Notify.notify( pinHigh );
!
if ( pinHigh ) {
call GpioInterrupt.enableFallingEdge();
--- 769,775 ----
bool pinHigh;
pinHigh = m_pinHigh;
!
signal Notify.notify( pinHigh );
!
if ( pinHigh ) {
call GpioInterrupt.enableFallingEdge();
***************
*** 810,815 ****
</pre>
</div>
! <div class="section" id="digital-bus-connected-sensor">
! <h2><a name="digital-bus-connected-sensor">3. Digital Bus-Connected Sensor</a></h2>
<p>The Digital sensor is the most complex out of the set, and includes
six components:</p>
--- 805,810 ----
</pre>
</div>
! <div class="section">
! <h2><a id="digital-bus-connected-sensor" name="digital-bus-connected-sensor">3. Digital Bus-Connected Sensor</a></h2>
<p>The Digital sensor is the most complex out of the set, and includes
six components:</p>
***************
*** 834,838 ****
tos/platforms/telosa/chips/sht11/SensirionSht11C.nc
! generic configuration SensirionSht11C() {
provides interface Read<uint16_t> as Temperature;
provides interface DeviceMetadata as TemperatureDeviceMetadata;
--- 829,833 ----
tos/platforms/telosa/chips/sht11/SensirionSht11C.nc
! generic configuration SensirionSht11C() {
provides interface Read<uint16_t> as Temperature;
provides interface DeviceMetadata as TemperatureDeviceMetadata;
***************
*** 867,871 ****
provides interface Read<uint16_t> as Humidity;
provides interface DeviceMetadata as HumidityDeviceMetadata;
!
uses interface Resource as TempResource;
uses interface Resource as HumResource;
--- 862,866 ----
provides interface Read<uint16_t> as Humidity;
provides interface DeviceMetadata as HumidityDeviceMetadata;
!
uses interface Resource as TempResource;
uses interface Resource as HumResource;
***************
*** 944,948 ****
SensirionSht11LogicP.CLOCK -> HplSensirionSht11C.SCK;
SensirionSht11LogicP.InterruptDATA -> HplSensirionSht11C.InterruptDATA;
!
components new TimerMilliC();
SensirionSht11LogicP.Timer -> TimerMilliC;
--- 939,943 ----
SensirionSht11LogicP.CLOCK -> HplSensirionSht11C.SCK;
SensirionSht11LogicP.InterruptDATA -> HplSensirionSht11C.InterruptDATA;
!
components new TimerMilliC();
SensirionSht11LogicP.Timer -> TimerMilliC;
***************
*** 983,987 ****
implementation {
components HplMsp430GeneralIOC;
!
components new Msp430GpioC() as DATAM;
DATAM -> HplMsp430GeneralIOC.Port15;
--- 978,982 ----
implementation {
components HplMsp430GeneralIOC;
!
components new Msp430GpioC() as DATAM;
DATAM -> HplMsp430GeneralIOC.Port15;
***************
*** 1010,1014 ****
components new FcfsArbiterC( "Sht11.Resource" ) as Arbiter;
Resource = Arbiter;
!
components new SplitControlPowerManagerC();
SplitControlPowerManagerC.SplitControl -> HplSensirionSht11P;
--- 1005,1009 ----
components new FcfsArbiterC( "Sht11.Resource" ) as Arbiter;
Resource = Arbiter;
!
components new SplitControlPowerManagerC();
SplitControlPowerManagerC.SplitControl -> HplSensirionSht11P;
***************
*** 1037,1041 ****
return SUCCESS;
}
!
event void Timer.fired() {
signal SplitControl.startDone( SUCCESS );
--- 1032,1036 ----
return SUCCESS;
}
!
event void Timer.fired() {
signal SplitControl.startDone( SUCCESS );
Index: tep114.html
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/doc/html/tep114.html,v
retrieving revision 1.8
retrieving revision 1.9
diff -C2 -d -r1.8 -r1.9
*** tep114.html 21 Apr 2007 07:04:39 -0000 1.8
--- tep114.html 14 Aug 2007 18:58:00 -0000 1.9
***************
*** 4,8 ****
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
! <meta name="generator" content="Docutils 0.3.6: http://docutils.sourceforge.net/" />
<title>SIDs: Source and Sink Independent Drivers</title>
<meta name="author" content="Gilman Tolle, Philip Levis, and David Gay" />
--- 4,8 ----
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
! <meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
<title>SIDs: Source and Sink Independent Drivers</title>
<meta name="author" content="Gilman Tolle, Philip Levis, and David Gay" />
***************
*** 42,50 ****
margin-bottom: 0.5em }
- /* Uncomment (& remove this text!) to get bold-faced definition list terms
- dt {
- font-weight: bold }
- */
-
div.abstract {
margin: 2em 5em }
--- 42,45 ----
***************
*** 284,287 ****
--- 279,283 ----
</head>
<body>
+ <div class="document" id="sids-source-and-sink-independent-drivers">
<h1 class="title">SIDs: Source and Sink Independent Drivers</h1>
<table class="docinfo" frame="void" rules="none">
***************
*** 311,315 ****
</tbody>
</table>
- <div class="document" id="sids-source-and-sink-independent-drivers">
<div class="note">
<p class="first admonition-title">Note</p>
--- 307,310 ----
***************
*** 319,329 ****
TEP 1.</p>
</div>
! <div class="section" id="abstract">
! <h1><a name="abstract">Abstract</a></h1>
! <p>This memo documents a set of hardware- and sensor-independent interfaces
for data sources and sinks in TinyOS 2.x.</p>
</div>
! <div class="section" id="introduction">
! <h1><a name="introduction">1. Introduction</a></h1>
<p>Sensing is an integral part of any sensor network application. Having
a wide variety of sensor interfaces usually does not impose a large
--- 314,324 ----
TEP 1.</p>
</div>
! <div class="section">
! <h1><a id="abstract" name="abstract">Abstract</a></h1>
! <p>This memo documents a set of hardware- and sensor-independent interfaces
for data sources and sinks in TinyOS 2.x.</p>
</div>
! <div class="section">
! <h1><a id="introduction" name="introduction">1. Introduction</a></h1>
<p>Sensing is an integral part of any sensor network application. Having
a wide variety of sensor interfaces usually does not impose a large
***************
*** 336,341 ****
and sensor-independent as well as sensor-specific interfaces.</p>
</div>
! <div class="section" id="sensors-in-tinyos-1-x">
! <h1><a name="sensors-in-tinyos-1-x">2. Sensors in TinyOS 1.x</a></h1>
<p>Early TinyOS sensors were generally analog. To sample one of these
sensors, an application makes an analog-to-digital conversion using
--- 331,336 ----
and sensor-independent as well as sensor-specific interfaces.</p>
</div>
! <div class="section">
! <h1><a id="sensors-in-tinyos-1-x" name="sensors-in-tinyos-1-x">2. Sensors in TinyOS 1.x</a></h1>
<p>Early TinyOS sensors were generally analog. To sample one of these
sensors, an application makes an analog-to-digital conversion using
***************
*** 381,386 ****
telescoping sensor abstraction allows both classes of use.</p>
</div>
! <div class="section" id="sensors-in-tinyos-2-x">
! <h1><a name="sensors-in-tinyos-2-x">3. Sensors in TinyOS 2.x</a></h1>
<p>TinyOS 2.x has several sensor-independent interfaces, which cover a
range of common use cases. These interfaces can be used to write a
--- 376,381 ----
telescoping sensor abstraction allows both classes of use.</p>
</div>
! <div class="section">
! <h1><a id="sensors-in-tinyos-2-x" name="sensors-in-tinyos-2-x">3. Sensors in TinyOS 2.x</a></h1>
<p>TinyOS 2.x has several sensor-independent interfaces, which cover a
range of common use cases. These interfaces can be used to write a
***************
*** 390,395 ****
SHOULD provide one or more of the interfaces described in this
section, depending on its expected uses and underlying data model.</p>
! <div class="section" id="split-phase-small-scalar-i-o">
! <h2><a name="split-phase-small-scalar-i-o">3.1 Split-Phase Small Scalar I/O</a></h2>
<p>The first set of interfaces can be used for low-rate scalar I/O:</p>
<pre class="literal-block">
--- 385,390 ----
SHOULD provide one or more of the interfaces described in this
section, depending on its expected uses and underlying data model.</p>
! <div class="section">
! <h2><a id="split-phase-small-scalar-i-o" name="split-phase-small-scalar-i-o">3.1 Split-Phase Small Scalar I/O</a></h2>
<p>The first set of interfaces can be used for low-rate scalar I/O:</p>
<pre class="literal-block">
***************
*** 433,438 ****
readings.</p>
</div>
! <div class="section" id="split-phase-large-scalar-i-o">
! <h2><a name="split-phase-large-scalar-i-o">3.2 Split-Phase Large Scalar I/O</a></h2>
<p>If the SID's data object is too big to be passed efficienctly on the
stack, it can provide read/write interfaces that pass parameters by
--- 428,433 ----
readings.</p>
</div>
! <div class="section">
! <h2><a id="split-phase-large-scalar-i-o" name="split-phase-large-scalar-i-o">3.2 Split-Phase Large Scalar I/O</a></h2>
<p>If the SID's data object is too big to be passed efficienctly on the
stack, it can provide read/write interfaces that pass parameters by
***************
*** 475,483 ****
<p>Examples of sensors that are suited to this set of interfaces include
those that generate multiple simultaneous readings for which
! passing by value is inefficient, such as a two-axis digital
accelerometer.</p>
</div>
! <div class="section" id="single-phase-scalar-i-o">
! <h2><a name="single-phase-scalar-i-o">3.4 Single-Phase Scalar I/O</a></h2>
<p>Some devices may have their state cached or readily available. In
these cases, the device can provide a single-phase instead of
--- 470,478 ----
<p>Examples of sensors that are suited to this set of interfaces include
those that generate multiple simultaneous readings for which
! passing by value is inefficient, such as a two-axis digital
accelerometer.</p>
</div>
! <div class="section">
! <h2><a id="single-phase-scalar-i-o" name="single-phase-scalar-i-o">3.4 Single-Phase Scalar I/O</a></h2>
<p>Some devices may have their state cached or readily available. In
these cases, the device can provide a single-phase instead of
***************
*** 517,522 ****
</pre>
</div>
! <div class="section" id="notification-based-scalar-i-o">
! <h2><a name="notification-based-scalar-i-o">3.5 Notification-Based Scalar I/O</a></h2>
<p>Some sensor devices represent triggers, rather than request-driven
data acquisition. Examples of such sensors include switches,
--- 512,517 ----
</pre>
</div>
! <div class="section">
! <h2><a id="notification-based-scalar-i-o" name="notification-based-scalar-i-o">3.5 Notification-Based Scalar I/O</a></h2>
<p>Some sensor devices represent triggers, rather than request-driven
data acquisition. Examples of such sensors include switches,
***************
*** 541,546 ****
<p>The val parameter is used as defined in the Read interface.</p>
</div>
! <div class="section" id="split-phase-streaming-i-o">
! <h2><a name="split-phase-streaming-i-o">3.7 Split-Phase Streaming I/O</a></h2>
<p>Some sensors can provide a continuous stream of readings, and some
actuators can accept a continuous stream of new data. Depending on the
--- 536,541 ----
<p>The val parameter is used as defined in the Read interface.</p>
</div>
! <div class="section">
! <h2><a id="split-phase-streaming-i-o" name="split-phase-streaming-i-o">3.7 Split-Phase Streaming I/O</a></h2>
<p>Some sensors can provide a continuous stream of readings, and some
actuators can accept a continuous stream of new data. Depending on the
***************
*** 560,568 ****
command error_t read( uint32_t usPeriod );
! event void bufferDone( error_t result,
val_t* buf, uint16_t count );
event void readDone( error_t result );
! }
</pre>
<p>The postBuffer command takes an array parameterized by the sample
--- 555,563 ----
command error_t read( uint32_t usPeriod );
! event void bufferDone( error_t result,
val_t* buf, uint16_t count );
event void readDone( error_t result );
! }
</pre>
<p>The postBuffer command takes an array parameterized by the sample
***************
*** 595,599 ****
command error_t write( uint32_t period );
! event void bufferDone( error_t result,
val_t* buf, uint16_t count );
--- 590,594 ----
command error_t write( uint32_t period );
! event void bufferDone( error_t result,
val_t* buf, uint16_t count );
***************
*** 605,610 ****
</div>
</div>
! <div class="section" id="summary">
! <h1><a name="summary">4. Summary</a></h1>
<p>According to the design principles described in the HAA[_haa], authors
should write device drivers that provide rich, device-specific
--- 600,605 ----
</div>
</div>
! <div class="section">
! <h1><a id="summary" name="summary">4. Summary</a></h1>
<p>According to the design principles described in the HAA[_haa], authors
should write device drivers that provide rich, device-specific
***************
*** 616,621 ****
connect a sensor into a more general system.</p>
</div>
! <div class="section" id="author-s-address">
! <h1><a name="author-s-address">5. Author's Address</a></h1>
<div class="line-block">
<div class="line">Gilman Tolle</div>
--- 611,616 ----
connect a sensor into a more general system.</p>
</div>
! <div class="section">
! <h1><a id="author-s-address" name="author-s-address">5. Author's Address</a></h1>
<div class="line-block">
<div class="line">Gilman Tolle</div>
***************
*** 648,653 ****
</div>
</div>
! <div class="section" id="citations">
! <h1><a name="citations">6. Citations</a></h1>
<table class="docutils footnote" frame="void" id="id2" rules="none">
<colgroup><col class="label" /><col /></colgroup>
--- 643,648 ----
</div>
</div>
! <div class="section">
! <h1><a id="citations" name="citations">6. Citations</a></h1>
<table class="docutils footnote" frame="void" id="id2" rules="none">
<colgroup><col class="label" /><col /></colgroup>
Index: tep108.html
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/doc/html/tep108.html,v
retrieving revision 1.10
retrieving revision 1.11
diff -C2 -d -r1.10 -r1.11
*** tep108.html 21 Apr 2007 07:04:39 -0000 1.10
--- tep108.html 14 Aug 2007 18:58:00 -0000 1.11
***************
*** 4,14 ****
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
! <meta name="generator" content="Docutils 0.3.6: http://docutils.sourceforge.net/" />
<title>Resource Arbitration</title>
! <meta name="author" content="Kevin Klues" />
! <meta name="author" content="Philip Levis" />
! <meta name="author" content="David Gay" />
! <meta name="author" content="David Culler" />
! <meta name="author" content="Vlado Handziski" />
<style type="text/css">
[...1406 lines suppressed...]
! interface. In this way, different instances of the Msp430Usart0C
! can each have different configurations associated with them, but
still provide the same functionality.</p>
! <p>Take a look in the tinyos-2.x source tree under
! tinyos-2.x/tos/chips/msp430/usart to see the full implementation of
these components along with the corresponding Uart implementation.</p>
</div>
--- 1336,1347 ----
</pre>
<p>The implementation of the ResourceConfigure interface is
! provided by both the Msp430SpiNoDma0P and the Msp430I2C0P. In the
two different components, the same Msp430Usart0C component is used,
but wired to the proper implementation of the ResourceConfigure
! interface. In this way, different instances of the Msp430Usart0C
! can each have different configurations associated with them, but
still provide the same functionality.</p>
! <p>Take a look in the tinyos-2.x source tree under
! tinyos-2.x/tos/chips/msp430/usart to see the full implementation of
these components along with the corresponding Uart implementation.</p>
</div>
Index: tep115.html
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/doc/html/tep115.html,v
retrieving revision 1.9
retrieving revision 1.10
diff -C2 -d -r1.9 -r1.10
*** tep115.html 21 Apr 2007 07:04:39 -0000 1.9
--- tep115.html 14 Aug 2007 18:58:00 -0000 1.10
***************
*** 4,8 ****
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
! <meta name="generator" content="Docutils 0.3.6: http://docutils.sourceforge.net/" />
<title>Power Management of Non-Virtualised Devices</title>
<meta name="author" content="Kevin Klues, Vlado Handziski, Jan-Hinrich Hauer, Phil Levis" />
--- 4,8 ----
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
! <meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
<title>Power Management of Non-Virtualised Devices</title>
<meta name="author" content="Kevin Klues, Vlado Handziski, Jan-Hinrich Hauer, Phil Levis" />
***************
*** 42,50 ****
margin-bottom: 0.5em }
- /* Uncomment (& remove this text!) to get bold-faced definition list terms
- dt {
- font-weight: bold }
- */
-
div.abstract {
margin: 2em 5em }
--- 42,45 ----
***************
*** 284,287 ****
--- 279,283 ----
</head>
<body>
+ <div class="document" id="power-management-of-non-virtualised-devices">
<h1 class="title">Power Management of Non-Virtualised Devices</h1>
<table class="docinfo" frame="void" rules="none">
***************
*** 307,316 ****
<tr class="field"><th class="docinfo-name">Draft-Modified:</th><td class="field-body">2007-02-21</td>
</tr>
! <tr class="field"><th class="docinfo-name">Draft-Discuss:</th><td class="field-body">TinyOS Developer List
<tinyos-devel at mail.millennium.berkeley.edu></td>
</tr>
</tbody>
</table>
- <div class="document" id="power-management-of-non-virtualised-devices">
<div class="note">
<p class="first admonition-title">Note</p>
--- 303,311 ----
<tr class="field"><th class="docinfo-name">Draft-Modified:</th><td class="field-body">2007-02-21</td>
</tr>
! <tr class="field"><th class="docinfo-name">Draft-Discuss:</th><td class="field-body">TinyOS Developer List
<tinyos-devel at mail.millennium.berkeley.edu></td>
</tr>
</tbody>
</table>
<div class="note">
<p class="first admonition-title">Note</p>
***************
*** 320,330 ****
1.</p>
</div>
! <div class="section" id="abstract">
! <h1><a name="abstract">Abstract</a></h1>
<p>This memo documents how TinyOS 2.x manages the power state of physical
(not virtualised) abstractions.</p>
</div>
! <div class="section" id="introduction">
! <h1><a 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
--- 315,325 ----
1.</p>
</div>
! <div class="section">
! <h1><a id="abstract" name="abstract">Abstract</a></h1>
<p>This memo documents how TinyOS 2.x manages the power state of physical
(not virtualised) abstractions.</p>
</div>
! <div class="section">
! <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
***************
*** 355,360 ****
them must be explicitly requested and released by their users.</p>
</div>
! <div class="section" id="power-management-models">
! <h1><a name="power-management-models">2. Power Management Models</a></h1>
<p>There are two different models to managing the power state of a
peripheral in TinyOS: <em>explicit power management</em> and <em>implicit
--- 350,355 ----
them must be explicitly requested and released by their users.</p>
</div>
! <div class="section">
! <h1><a id="power-management-models" name="power-management-models">2. Power Management Models</a></h1>
<p>There are two different models to managing the power state of a
peripheral in TinyOS: <em>explicit power management</em> and <em>implicit
***************
*** 384,388 ****
the ADC should be on; if there are no requests of the ADC, this implies
it should be off. Therefore shared devices do not need to provide a
! power control interface. They can use an implicit power management policy.
Section 4.2 discusses this in more detail.:</p>
<pre class="literal-block">
--- 379,383 ----
the ADC should be on; if there are no requests of the ADC, this implies
it should be off. Therefore shared devices do not need to provide a
! power control interface. They can use an implicit power management policy.
Section 4.2 discusses this in more detail.:</p>
<pre class="literal-block">
***************
*** 390,394 ****
| |
Data Interface Resource
! | |
-----------------------------------------------------------------------
| Shared Device (implicitly power managed) |
--- 385,389 ----
| |
Data Interface Resource
! | |
-----------------------------------------------------------------------
| Shared Device (implicitly power managed) |
***************
*** 411,416 ****
</pre>
</div>
! <div class="section" id="explicit-power-management">
! <h1><a name="explicit-power-management">3. Explicit Power Management</a></h1>
<p>Just as in TinyOS 1.x, TinyOS 2.x has <tt class="docutils literal"><span class="pre">StdControl</span></tt> and <tt class="docutils literal"><span class="pre">SplitControl</span></tt>
interfaces in order to control the on and off
--- 406,411 ----
</pre>
</div>
! <div class="section">
! <h1><a id="explicit-power-management" name="explicit-power-management">3. Explicit Power Management</a></h1>
<p>Just as in TinyOS 1.x, TinyOS 2.x has <tt class="docutils literal"><span class="pre">StdControl</span></tt> and <tt class="docutils literal"><span class="pre">SplitControl</span></tt>
interfaces in order to control the on and off
***************
*** 423,430 ****
nature of the code (sync or async) executing any of the interfaces
commands.</p>
! <div class="section" id="power-management-with-stdcontrol">
! <h2><a name="power-management-with-stdcontrol">3.1 Power Management with <tt class="docutils literal"><span class="pre">StdControl</span></tt></a></h2>
<p>Whenever the powerup and powerdown times of a non-virtualised device
! are negligible, they SHOULD provide the <tt class="docutils literal"><span class="pre">StdControl</span></tt> interface as
defined below:</p>
<pre class="literal-block">
--- 418,425 ----
nature of the code (sync or async) executing any of the interfaces
commands.</p>
! <div class="section">
! <h2><a id="power-management-with-stdcontrol" name="power-management-with-stdcontrol">3.1 Power Management with <tt class="docutils literal"><span class="pre">StdControl</span></tt></a></h2>
<p>Whenever the powerup and powerdown times of a non-virtualised device
! are negligible, they SHOULD provide the <tt class="docutils literal"><span class="pre">StdControl</span></tt> interface as
defined below:</p>
<pre class="literal-block">
***************
*** 453,457 ****
interfaces implemented by the device to succeed.</p>
<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
--- 448,452 ----
interfaces implemented by the device to succeed.</p>
<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
***************
*** 467,473 ****
</colgroup>
<thead valign="bottom">
! <tr><th>Call</th>
! <th>Device On</th>
! <th>Device Off</th>
</tr>
</thead>
--- 462,468 ----
</colgroup>
<thead valign="bottom">
! <tr><th class="head">Call</th>
! <th class="head">Device On</th>
! <th class="head">Device Off</th>
</tr>
</thead>
***************
*** 498,503 ****
</pre>
</div>
! <div class="section" id="power-management-with-splitcontrol">
! <h2><a 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>
--- 493,498 ----
</pre>
</div>
! <div class="section">
! <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>
***************
*** 527,542 ****
<tt class="docutils literal"><span class="pre">SplitControl.stopDone(SUCCESS)</span></tt> or <tt class="docutils literal"><span class="pre">SplitControl.stopDone(FAIL)</span></tt>.</p>
<p>Upon signaling a <tt class="docutils literal"><span class="pre">SplitControl.startDone(SUCCESS)</span></tt>, a device MUST
! be completely powered on, and operation requests through calls to commands
of other interfaces implemented by the device MAY succeed.</p>
! <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
! powered on, and operation requests through calls to commands of other
interfaces implemented by the device MAY succeed.</p>
! <p>If a device is powered down and a successful call to <tt class="docutils literal"><span class="pre">SplitControl.start()</span></tt>
! signals a <tt class="docutils literal"><span class="pre">SplitControl.startDone(FAIL)</span></tt>, the device MUST still be fully
! powered down, and operation requests through calls to commands of other
interfaces implemented by the device MUST return EOFF or FAIL.</p>
<p>If a device is not able to complete the <tt class="docutils literal"><span class="pre">SplitControl.start()</span></tt> or
--- 522,537 ----
<tt class="docutils literal"><span class="pre">SplitControl.stopDone(SUCCESS)</span></tt> or <tt class="docutils literal"><span class="pre">SplitControl.stopDone(FAIL)</span></tt>.</p>
<p>Upon signaling a <tt class="docutils literal"><span class="pre">SplitControl.startDone(SUCCESS)</span></tt>, a device MUST
! be completely powered on, and operation requests through calls to commands
of other interfaces implemented by the device MAY succeed.</p>
! <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
! powered on, and operation requests through calls to commands of other
interfaces implemented by the device MAY succeed.</p>
! <p>If a device is powered down and a successful call to <tt class="docutils literal"><span class="pre">SplitControl.start()</span></tt>
! signals a <tt class="docutils literal"><span class="pre">SplitControl.startDone(FAIL)</span></tt>, the device MUST still be fully
! powered down, and operation requests through calls to commands of other
interfaces implemented by the device MUST return EOFF or FAIL.</p>
<p>If a device is not able to complete the <tt class="docutils literal"><span class="pre">SplitControl.start()</span></tt> or
***************
*** 566,574 ****
</colgroup>
<thead valign="bottom">
! <tr><th>Call</th>
! <th>Device On</th>
! <th>Device Off</th>
! <th>Starting</th>
! <th>Stopping</th>
</tr>
</thead>
--- 561,569 ----
</colgroup>
<thead valign="bottom">
! <tr><th class="head">Call</th>
! <th class="head">Device On</th>
! <th class="head">Device Off</th>
! <th class="head">Starting</th>
! <th class="head">Stopping</th>
</tr>
</thead>
***************
*** 612,617 ****
</pre>
</div>
! <div class="section" id="power-management-with-asyncstdcontrol">
! <h2><a name="power-management-with-asyncstdcontrol">3.3 Power Management with <tt class="docutils literal"><span class="pre">AsyncStdControl</span></tt></a></h2>
<p>The commands and the events of the <em>``StdControl``</em> and the <em>``SplitControl``</em>
interfaces are synchronous and can not be called from within
--- 607,612 ----
</pre>
</div>
! <div class="section">
! <h2><a id="power-management-with-asyncstdcontrol" name="power-management-with-asyncstdcontrol">3.3 Power Management with <tt class="docutils literal"><span class="pre">AsyncStdControl</span></tt></a></h2>
<p>The commands and the events of the <em>``StdControl``</em> and the <em>``SplitControl``</em>
interfaces are synchronous and can not be called from within
***************
*** 642,671 ****
<p class="first admonition-title">Note</p>
<p class="last">The <tt class="docutils literal"><span class="pre">AsyncStdControl</span></tt> interface should be provided whenever it might be
! necessary to allow a device to be powered on or off while running in
! async context. If it is anticipated that a device <em>will</em> not (or more
likely <em>should</em> not) be powered on or off while in asynchronous context,
! then the <tt class="docutils literal"><span class="pre">StdControl</span></tt> interface SHOULD be provided instead. Components
that wish to power the device on or off from within async context would
! then be required to post a task before doing so. In practice,
! <tt class="docutils literal"><span class="pre">AsyncStdControl</span></tt> is provided by low-level hardware resources, while
! <tt class="docutils literal"><span class="pre">StdControl</span></tt> is provided by higher level services built on top of these
resources.</p>
</div>
</div>
</div>
! <div class="section" id="implicit-power-management">
! <h1><a name="implicit-power-management">4. Implicit Power Management</a></h1>
<p>While explicit power management provides the mechanism for changing
power states, it does not specify a policy.
This does not represent a large problem for the simple case
! of <em>dedicated</em> devices, but can become crucial for non-trivial cases
! involving complex interdependencies between devices controlled by multiple
clients.</p>
! <p>For example, if component <em>A</em> is a client of both component <em>B</em>
and component <em>C</em>, what happens with <em>B</em> and <em>C</em> if
<tt class="docutils literal"><span class="pre">StdControl.stop()</span></tt> is called on component <em>A</em> ? Should components
! <em>B</em> and <em>C</em> also be stopped? What about the reverse case where both
! <em>B</em> and <em>C</em> are clients of the single shared component, <em>A</em>? If
! devices <em>B</em> and <em>C</em> are shut off, should <em>A</em> be shut off as well?
How can one decide when it is appropriate to cascade such powerup
and powerdown requests?</p>
--- 637,666 ----
<p class="first admonition-title">Note</p>
<p class="last">The <tt class="docutils literal"><span class="pre">AsyncStdControl</span></tt> interface should be provided whenever it might be
! necessary to allow a device to be powered on or off while running in
! async context. If it is anticipated that a device <em>will</em> not (or more
likely <em>should</em> not) be powered on or off while in asynchronous context,
! then the <tt class="docutils literal"><span class="pre">StdControl</span></tt> interface SHOULD be provided instead. Components
that wish to power the device on or off from within async context would
! then be required to post a task before doing so. In practice,
! <tt class="docutils literal"><span class="pre">AsyncStdControl</span></tt> is provided by low-level hardware resources, while
! <tt class="docutils literal"><span class="pre">StdControl</span></tt> is provided by higher level services built on top of these
resources.</p>
</div>
</div>
</div>
! <div class="section">
! <h1><a id="implicit-power-management" name="implicit-power-management">4. Implicit Power Management</a></h1>
<p>While explicit power management provides the mechanism for changing
power states, it does not specify a policy.
This does not represent a large problem for the simple case
! of <em>dedicated</em> devices, but can become crucial for non-trivial cases
! involving complex interdependencies between devices controlled by multiple
clients.</p>
! <p>For example, if component <em>A</em> is a client of both component <em>B</em>
and component <em>C</em>, what happens with <em>B</em> and <em>C</em> if
<tt class="docutils literal"><span class="pre">StdControl.stop()</span></tt> is called on component <em>A</em> ? Should components
! <em>B</em> and <em>C</em> also be stopped? What about the reverse case where both
! <em>B</em> and <em>C</em> are clients of the single shared component, <em>A</em>? If
! devices <em>B</em> and <em>C</em> are shut off, should <em>A</em> be shut off as well?
How can one decide when it is appropriate to cascade such powerup
and powerdown requests?</p>
***************
*** 674,693 ****
platforms, one of the SPI buses is shared between the radio and the
flash device. On some of them, issuing <tt class="docutils literal"><span class="pre">StdControl.stop()</span></tt> on the
! radio results in a series of cascaded calls that result in SPI bus
! becoming disabled, rendering the communication with the flash impossible.
! Of course, the right policy would involve tracking the clients of the
! SPI bus and powering it off only once both the radio and the flash
devices were no longer using it. Conversely, the SPI bus should be
powered on whenever there is at least one active client.</p>
! <p>The selection of the right power management policy to use is a complex
! task that depends on the nature of the devices in use, their
! interdependency, as well as on any specific application requirements.
! 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 <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" id="power-management-policies">
! <h2><a name="power-management-policies">4.1. Power Management Policies</a></h2>
<p>Just as generic arbiters are offered in TinyOS 2.x to provide the
arbitration functionality required by shared resources, generic power
--- 669,688 ----
platforms, one of the SPI buses is shared between the radio and the
flash device. On some of them, issuing <tt class="docutils literal"><span class="pre">StdControl.stop()</span></tt> on the
! radio results in a series of cascaded calls that result in SPI bus
! becoming disabled, rendering the communication with the flash impossible.
! Of course, the right policy would involve tracking the clients of the
! SPI bus and powering it off only once both the radio and the flash
devices were no longer using it. Conversely, the SPI bus should be
powered on whenever there is at least one active client.</p>
! <p>The selection of the right power management policy to use is a complex
! task that depends on the nature of the devices in use, their
! interdependency, as well as on any specific application requirements.
! 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 <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>
<p>Just as generic arbiters are offered in TinyOS 2.x to provide the
arbitration functionality required by shared resources, generic power
***************
*** 719,743 ****
gain ownership over the resource device.</p>
<p>Once it owns the device, the <em>Power Manager</em> is free to execute its
! power-management policy using the StdControl-like interface provided by the
! underlying resource. Different power managers can implement different
policies. In the simplest case, this would involve an immediate power-down
! via one of the <tt class="docutils literal"><span class="pre">stop()</span></tt> commands. When the power-state transition
! involves non-negligible costs in terms of wake-up latency or power
! consumption, the <em>PowerManager</em> might revert to a more intelligent
! strategy that tries to reduce these effects. As pointed out in the
! introduction, one such strategy might involve the use of a timer to defer
! the power-down of the resource to some later point in time, giving any
! resource clients a window of opportunity to put in requests before the
device is fully shut down.</p>
! <p>Regardless of the power management policy in use, the <em>Power Manager</em>
! remains owner of the resource as long as the resource is not requested
by one of its clients. Whenever a client puts in a request, the
! <em>Power Manager</em> will receive a <tt class="docutils literal"><span class="pre">ResourceDefaultOwner.requested()</span></tt> event
! (or <tt class="docutils literal"><span class="pre">immediateRequested()</span></tt> event) from the arbiter it is associated with.
! 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
--- 714,738 ----
gain ownership over the resource device.</p>
<p>Once it owns the device, the <em>Power Manager</em> is free to execute its
! power-management policy using the StdControl-like interface provided by the
! underlying resource. Different power managers can implement different
policies. In the simplest case, this would involve an immediate power-down
! via one of the <tt class="docutils literal"><span class="pre">stop()</span></tt> commands. When the power-state transition
! involves non-negligible costs in terms of wake-up latency or power
! consumption, the <em>PowerManager</em> might revert to a more intelligent
! strategy that tries to reduce these effects. As pointed out in the
! introduction, one such strategy might involve the use of a timer to defer
! the power-down of the resource to some later point in time, giving any
! resource clients a window of opportunity to put in requests before the
device is fully shut down.</p>
! <p>Regardless of the power management policy in use, the <em>Power Manager</em>
! remains owner of the resource as long as the resource is not requested
by one of its clients. Whenever a client puts in a request, the
! <em>Power Manager</em> will receive a <tt class="docutils literal"><span class="pre">ResourceDefaultOwner.requested()</span></tt> event
! (or <tt class="docutils literal"><span class="pre">immediateRequested()</span></tt> event) from the arbiter it is associated with.
! 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
***************
*** 751,755 ****
the bottom of a large set of nested resource clients has been fully released,
the power mananger will be able to power down the resource appropriately.</p>
! <p>Using the model described above, a resource that uses one of these policies
according to the <em>implicitly power management</em> model could be built as shown below:</p>
<pre class="literal-block">
--- 746,750 ----
the bottom of a large set of nested resource clients has been fully released,
the power mananger will be able to power down the resource appropriately.</p>
! <p>Using the model described above, a resource that uses one of these policies
according to the <em>implicitly power management</em> model could be built as shown below:</p>
<pre class="literal-block">
***************
*** 765,769 ****
implementation {
...
! }
generic module PowerManagerC(uint8_t POWERDOWN_DELAY) {
--- 760,764 ----
implementation {
...
! }
generic module PowerManagerC(uint8_t POWERDOWN_DELAY) {
***************
*** 795,804 ****
Init = MyFlashP;
! Resource = FcfsArbiter;
FlashCommands = MyFlashP;
PowerManagerC.ResourceDefaultUser -> FcfsArbiter;
PowerManagerC.SplitControl -> MyFlashP;
!
}
</pre>
--- 790,799 ----
Init = MyFlashP;
! Resource = FcfsArbiter;
FlashCommands = MyFlashP;
PowerManagerC.ResourceDefaultUser -> FcfsArbiter;
PowerManagerC.SplitControl -> MyFlashP;
!
}
</pre>
***************
*** 815,837 ****
of the device. Notice how the <em>Power Manager</em> is wired to both the
<tt class="docutils literal"><span class="pre">ResourceDefaultUser</span></tt> interface provided by the arbiter, and the
! <tt class="docutils literal"><span class="pre">SplitControl</span></tt> interface provided by the flash. All clients of this flash
device are directly connected to the resource interface provided by
the arbiter. As outlined above, the <tt class="docutils literal"><span class="pre">PowerManagerC</span></tt> component will use
! the events signaled through the <tt class="docutils literal"><span class="pre">ResourceDefaultUser</span></tt> interface to determine
when to make calls to power the device up and power it down through
the <tt class="docutils literal"><span class="pre">SplitControl</span></tt> interface.</p>
</div>
! <div class="section" id="example-power-managers-powermanagerc-and-deferredpowermanagerc">
! <h2><a name="example-power-managers-powermanagerc-and-deferredpowermanagerc">4.2. Example Power Managers: PowerManagerC and DeferredPowerManagerC</a></h2>
<p>TinyOS 2.x currently has two default power management policies
! that it provides. These policies are implemented by the various
! components located under tinyos-2.x/lib/power. The first policy
is implemented using an <em>immediate</em> power control scheme, whereby
devices are powered on and off immediately after they have been
requested and released. The second policy is implemented using
! 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>
interfaces.</p>
--- 810,832 ----
of the device. Notice how the <em>Power Manager</em> is wired to both the
<tt class="docutils literal"><span class="pre">ResourceDefaultUser</span></tt> interface provided by the arbiter, and the
! <tt class="docutils literal"><span class="pre">SplitControl</span></tt> interface provided by the flash. All clients of this flash
device are directly connected to the resource interface provided by
the arbiter. As outlined above, the <tt class="docutils literal"><span class="pre">PowerManagerC</span></tt> component will use
! the events signaled through the <tt class="docutils literal"><span class="pre">ResourceDefaultUser</span></tt> interface to determine
when to make calls to power the device up and power it down through
the <tt class="docutils literal"><span class="pre">SplitControl</span></tt> interface.</p>
</div>
! <div class="section">
! <h2><a id="example-power-managers-powermanagerc-and-deferredpowermanagerc" name="example-power-managers-powermanagerc-and-deferredpowermanagerc">4.2. Example Power Managers: PowerManagerC and DeferredPowerManagerC</a></h2>
<p>TinyOS 2.x currently has two default power management policies
! that it provides. These policies are implemented by the various
! components located under tinyos-2.x/lib/power. The first policy
is implemented using an <em>immediate</em> power control scheme, whereby
devices are powered on and off immediately after they have been
requested and released. The second policy is implemented using
! 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>
interfaces.</p>
***************
*** 855,860 ****
</div>
</div>
! <div class="section" id="author-s-address">
! <h1><a name="author-s-address">5. Author's Address</a></h1>
<div class="line-block">
<div class="line">Kevin Klues</div>
--- 850,855 ----
</div>
</div>
! <div class="section">
! <h1><a id="author-s-address" name="author-s-address">5. Author's Address</a></h1>
<div class="line-block">
<div class="line">Kevin Klues</div>
***************
*** 890,898 ****
<div class="line"><br /></div>
<div class="line">phone - +1 650 725 9046</div>
! <div class="line">email - <a class="reference" href="mailto:pal@cs.stanford.edu">pal@cs.stanford.edu</a> </div>
</div>
</div>
! <div class="section" id="citations">
! <h1><a name="citations">6. Citations</a></h1>
<table class="docutils citation" frame="void" id="tep102" rules="none">
<colgroup><col class="label" /><col /></colgroup>
--- 885,893 ----
<div class="line"><br /></div>
<div class="line">phone - +1 650 725 9046</div>
! <div class="line">email - <a class="reference" href="mailto:pal@cs.stanford.edu">pal@cs.stanford.edu</a></div>
</div>
</div>
! <div class="section">
! <h1><a id="citations" name="citations">6. Citations</a></h1>
<table class="docutils citation" frame="void" id="tep102" rules="none">
<colgroup><col class="label" /><col /></colgroup>
Index: tep117.html
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/doc/html/tep117.html,v
retrieving revision 1.8
retrieving revision 1.9
diff -C2 -d -r1.8 -r1.9
*** tep117.html 31 May 2007 06:24:51 -0000 1.8
--- tep117.html 14 Aug 2007 18:58:00 -0000 1.9
***************
*** 42,50 ****
margin-bottom: 0.5em }
- /* Uncomment (& remove this text!) to get bold-faced definition list terms
- dt {
- font-weight: bold }
- */
-
div.abstract {
margin: 2em 5em }
--- 42,45 ----
Index: tep120.html
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/doc/html/tep120.html,v
retrieving revision 1.9
retrieving revision 1.10
diff -C2 -d -r1.9 -r1.10
*** tep120.html 21 Jun 2007 19:38:42 -0000 1.9
--- tep120.html 14 Aug 2007 18:58:00 -0000 1.10
***************
*** 42,50 ****
margin-bottom: 0.5em }
- /* Uncomment (& remove this text!) to get bold-faced definition list terms
- dt {
- font-weight: bold }
- */
-
div.abstract {
margin: 2em 5em }
--- 42,45 ----
***************
*** 315,321 ****
<tr class="field"><th class="docinfo-name">Draft-Created:</th><td class="field-body">17-April-2006</td>
</tr>
! <tr class="field"><th class="docinfo-name">Draft-Version:</th><td class="field-body">1.6</td>
</tr>
! <tr class="field"><th class="docinfo-name">Draft-Modified:</th><td class="field-body">2007-05-15</td>
</tr>
<tr class="field"><th class="docinfo-name">Draft-Discuss:</th><td class="field-body">TinyOS Alliance <tinyos-alliance at mail.millennium.berkeley.edu></td>
--- 310,316 ----
<tr class="field"><th class="docinfo-name">Draft-Created:</th><td class="field-body">17-April-2006</td>
</tr>
! <tr class="field"><th class="docinfo-name">Draft-Version:</th><td class="field-body">1.7</td>
</tr>
! <tr class="field"><th class="docinfo-name">Draft-Modified:</th><td class="field-body">2007-06-21</td>
</tr>
<tr class="field"><th class="docinfo-name">Draft-Discuss:</th><td class="field-body">TinyOS Alliance <tinyos-alliance at mail.millennium.berkeley.edu></td>
Index: porting.html
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/doc/html/porting.html,v
retrieving revision 1.6
retrieving revision 1.7
diff -C2 -d -r1.6 -r1.7
*** porting.html 21 Apr 2007 07:04:39 -0000 1.6
--- porting.html 14 Aug 2007 18:58:00 -0000 1.7
***************
*** 4,8 ****
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
! <meta name="generator" content="Docutils 0.3.6: http://docutils.sourceforge.net/" />
<title>Porting TinyOS 1.x Code to TinyOS 2.0</title>
<meta name="author" content="Tahir Azim and Philip Levis" />
--- 4,8 ----
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
! <meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
<title>Porting TinyOS 1.x Code to TinyOS 2.0</title>
<meta name="author" content="Tahir Azim and Philip Levis" />
***************
*** 43,51 ****
margin-bottom: 0.5em }
- /* Uncomment (& remove this text!) to get bold-faced definition list terms
- dt {
- font-weight: bold }
- */
-
div.abstract {
margin: 2em 5em }
--- 43,46 ----
***************
*** 285,288 ****
--- 280,284 ----
</head>
<body>
+ <div class="document" id="porting-tinyos-1-x-code-to-tinyos-2-0">
<h1 class="title">Porting TinyOS 1.x Code to TinyOS 2.0</h1>
<table class="docinfo" frame="void" rules="none">
***************
*** 296,303 ****
</tbody>
</table>
- <div class="document" id="porting-tinyos-1-x-code-to-tinyos-2-0">
<div class="note">
<p class="first admonition-title">Note</p>
! <p class="last">This document provides a few important points that describe
major steps required for porting TinyOS 1.x code to TinyOS 2.0.
It is based on Tahir Azim's experience porting Beacon Vector
--- 292,298 ----
</tbody>
</table>
<div class="note">
<p class="first admonition-title">Note</p>
! <p class="last">This document provides a few important points that describe
major steps required for porting TinyOS 1.x code to TinyOS 2.0.
It is based on Tahir Azim's experience porting Beacon Vector
***************
*** 306,311 ****
some help or guidance.</p>
</div>
! <div class="section" id="porting-points">
! <h1><a name="porting-points">1. Porting Points</a></h1>
<p>As these observations come from porting a network protocol, they are
rather protocol-centric and do not consider other abstractions such
--- 301,306 ----
some help or guidance.</p>
</div>
! <div class="section">
! <h1><a id="porting-points" name="porting-points">1. Porting Points</a></h1>
<p>As these observations come from porting a network protocol, they are
rather protocol-centric and do not consider other abstractions such
***************
*** 323,327 ****
<p>In TinyOS 2.x, SUCCESS is equal to a zero error code, while other error codes are non-zero. So calls like this should be changed to make sure they test the result for equality with SUCCESS:</p>
<pre class="literal-block">
! if (call Packet... () == SUCCESS ) {
//SUCCESS!: do this...
}
--- 318,322 ----
<p>In TinyOS 2.x, SUCCESS is equal to a zero error code, while other error codes are non-zero. So calls like this should be changed to make sure they test the result for equality with SUCCESS:</p>
<pre class="literal-block">
! if (call Packet... () == SUCCESS ) {
//SUCCESS!: do this...
}
***************
*** 343,348 ****
</blockquote>
</div>
! <div class="section" id="author-s-address">
! <h1><a name="author-s-address">2. Author's Address</a></h1>
<div class="line-block">
<div class="line">Tahir Azim</div>
--- 338,343 ----
</blockquote>
</div>
! <div class="section">
! <h1><a id="author-s-address" name="author-s-address">2. Author's Address</a></h1>
<div class="line-block">
<div class="line">Tahir Azim</div>
***************
*** 365,370 ****
</div>
</div>
! <div class="section" id="citations">
! <h1><a name="citations">3. Citations</a></h1>
<table class="docutils footnote" frame="void" id="id1" rules="none">
<colgroup><col class="label" /><col /></colgroup>
--- 360,365 ----
</div>
</div>
! <div class="section">
! <h1><a id="citations" name="citations">3. Citations</a></h1>
<table class="docutils footnote" frame="void" id="id1" rules="none">
<colgroup><col class="label" /><col /></colgroup>
Index: tep116.html
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/doc/html/tep116.html,v
retrieving revision 1.12
retrieving revision 1.13
diff -C2 -d -r1.12 -r1.13
*** tep116.html 21 Apr 2007 07:04:39 -0000 1.12
--- tep116.html 14 Aug 2007 18:58:00 -0000 1.13
***************
*** 4,8 ****
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
! <meta name="generator" content="Docutils 0.3.6: http://docutils.sourceforge.net/" />
<title>Packet Protocols</title>
<meta name="author" content="Philip Levis" />
--- 4,8 ----
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
! <meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
<title>Packet Protocols</title>
<meta name="author" content="Philip Levis" />
***************
*** 42,50 ****
margin-bottom: 0.5em }
- /* Uncomment (& remove this text!) to get bold-faced definition list terms
- dt {
- font-weight: bold }
- */
-
div.abstract {
margin: 2em 5em }
--- 42,45 ----
***************
*** 284,287 ****
--- 279,283 ----
</head>
<body>
+ <div class="document" id="packet-protocols">
<h1 class="title">Packet Protocols</h1>
<table class="docinfo" frame="void" rules="none">
***************
*** 311,315 ****
</tbody>
</table>
- <div class="document" id="packet-protocols">
<div class="note">
<p class="first admonition-title">Note</p>
--- 307,310 ----
***************
*** 319,331 ****
TEP 1.</p>
</div>
! <div class="section" id="abstract">
! <h1><a name="abstract">Abstract</a></h1>
! <p>The memo documents the interfaces used by packet protocol components in
! TinyOS 2.x as well as the structure and implementation of ActiveMessageC,
the basic data-link HIL component. It also documents the virtualized
active message interfaces AMSenderC and AMReceiverC.</p>
</div>
! <div class="section" id="introduction">
! <h1><a name="introduction">1. Introduction</a></h1>
<p>Sensor nodes are network-centric devices. Much of their software
complexity comes from network protocols and their interactions.
--- 314,326 ----
TEP 1.</p>
</div>
! <div class="section">
! <h1><a id="abstract" name="abstract">Abstract</a></h1>
! <p>The memo documents the interfaces used by packet protocol components in
! TinyOS 2.x as well as the structure and implementation of ActiveMessageC,
the basic data-link HIL component. It also documents the virtualized
active message interfaces AMSenderC and AMReceiverC.</p>
</div>
! <div class="section">
! <h1><a id="introduction" name="introduction">1. Introduction</a></h1>
<p>Sensor nodes are network-centric devices. Much of their software
complexity comes from network protocols and their interactions.
***************
*** 333,337 ****
a single-hop, unreliable packet. Active messages have a destination
address, provide synchronous acknowledgements, and can be of
! variable length up to a fixed maximum size. They also have a
type field, which is essentially a protocol identifier for
components built on top of this abstraction.</p>
--- 328,332 ----
a single-hop, unreliable packet. Active messages have a destination
address, provide synchronous acknowledgements, and can be of
! variable length up to a fixed maximum size. They also have a
type field, which is essentially a protocol identifier for
components built on top of this abstraction.</p>
***************
*** 353,361 ****
<p>This component, while simple, has several issues. First, it has the
activity() commmand, which does not have a single caller in the entire
! TinyOS tree. This command requires GenericComm to allocate a
timer, wasting CPU cycles and RAM.</p>
<p>Second, it does not allow a node to receive packets besides
those destined to it. Several network
! protocols (e.g., MintRoute <a class="footnote-reference" href="#id6" id="id1" name="id1">[1]</a>, TAG <a class="footnote-reference" href="#id7" id="id2" name="id2">[2]</a>) take advantage
of snooping on these packets for a variety of improvements in efficiency or
performance. This has led to the creation of GenericCommPromiscuous,
--- 348,356 ----
<p>This component, while simple, has several issues. First, it has the
activity() commmand, which does not have a single caller in the entire
! TinyOS tree. This command requires GenericComm to allocate a
timer, wasting CPU cycles and RAM.</p>
<p>Second, it does not allow a node to receive packets besides
those destined to it. Several network
! protocols (e.g., MintRoute <a class="footnote-reference" href="#id6" id="id1" name="id1">[1]</a>, TAG <a class="footnote-reference" href="#id7" id="id2" name="id2">[2]</a>) take advantage
of snooping on these packets for a variety of improvements in efficiency or
performance. This has led to the creation of GenericCommPromiscuous,
***************
*** 365,369 ****
one of the two implementations is a global decision across
an application. There is a way to enable both reception
! semantics at the same time for a different protocols,
but they require a creative use of default event handlers.</p>
<p>Third, it assumes that components will directly access the packet
--- 360,364 ----
one of the two implementations is a global decision across
an application. There is a way to enable both reception
! semantics at the same time for a different protocols,
but they require a creative use of default event handlers.</p>
<p>Third, it assumes that components will directly access the packet
***************
*** 379,403 ****
HIL.</p>
</div>
! <div class="section" id="communication-interfaces">
! <h1><a name="communication-interfaces">2. Communication interfaces</a></h1>
<p>Packet-level communication has three basic classes of interfaces.
! <em>Packet</em> interfaces are for accessing message fields and payloads.
<em>Send</em> interfaces are for transmitting packets, and are
! distinguished by their addressing scheme.
The <em>Receive</em> interface is for handling packet reception events.
Finally, depending on whether the protocol has a dispatch identifier
field, the Receive and Send interfaces may be parameterized in order
to support multiple higher-level clients.</p>
! <div class="section" id="packet-interfaces">
! <h2><a name="packet-interfaces">2.1 Packet interfaces</a></h2>
! <p>The basic TinyOS 2.x message buffer type is message_t, which is
described in TEP 111. message_t right-justifies data-link
! headers to the data payload so that higher-level components can
pass buffers between different data link layers without having
! to move data payloads. This means that the data payload of a
data link frame is always at a fixed offset of a message_t.</p>
<p>Once protocols layer on top of each other, the data
payload for components on top of the data link layer are
! no longer at a fixed offset. Where a component can put its
header or data depends on what headers underlying components
introduce. Therefore, in order to be able to find out where
--- 374,398 ----
HIL.</p>
</div>
! <div class="section">
! <h1><a id="communication-interfaces" name="communication-interfaces">2. Communication interfaces</a></h1>
<p>Packet-level communication has three basic classes of interfaces.
! <em>Packet</em> interfaces are for accessing message fields and payloads.
<em>Send</em> interfaces are for transmitting packets, and are
! distinguished by their addressing scheme.
The <em>Receive</em> interface is for handling packet reception events.
Finally, depending on whether the protocol has a dispatch identifier
field, the Receive and Send interfaces may be parameterized in order
to support multiple higher-level clients.</p>
! <div class="section">
! <h2><a id="packet-interfaces" name="packet-interfaces">2.1 Packet interfaces</a></h2>
! <p>The basic TinyOS 2.x message buffer type is message_t, which is
described in TEP 111. message_t right-justifies data-link
! headers to the data payload so that higher-level components can
pass buffers between different data link layers without having
! to move data payloads. This means that the data payload of a
data link frame is always at a fixed offset of a message_t.</p>
<p>Once protocols layer on top of each other, the data
payload for components on top of the data link layer are
! no longer at a fixed offset. Where a component can put its
header or data depends on what headers underlying components
introduce. Therefore, in order to be able to find out where
***************
*** 422,426 ****
<tt class="docutils literal"><span class="pre">setPayLoadLength.</span></tt> As Send interfaces always include a length
parameter in their send call, this command is not required for
! sending, and so is never called in common use cases. Instead,
it is a way for queues and other packet buffering components
to store the full state of a packet without requiring additional
--- 417,421 ----
<tt class="docutils literal"><span class="pre">setPayLoadLength.</span></tt> As Send interfaces always include a length
parameter in their send call, this command is not required for
! sending, and so is never called in common use cases. Instead,
it is a way for queues and other packet buffering components
to store the full state of a packet without requiring additional
***************
*** 431,439 ****
in the send case, a component needs to know how much data it can put
in the packet.</p>
! <p>The Packet interface assumes that headers have a fixed size.
! It is difficult to return a pointer into the data region when its
position will only be known once the header values are bound.</p>
<p>Generally, an incoming call to the Packet interface of a protocol
! has an accompanying outgoing call to the Packet interface of the
component below it. The one exception to this is the data link
layer. For example, if there is a network that introduces
--- 426,434 ----
in the send case, a component needs to know how much data it can put
in the packet.</p>
! <p>The Packet interface assumes that headers have a fixed size.
! It is difficult to return a pointer into the data region when its
position will only be known once the header values are bound.</p>
<p>Generally, an incoming call to the Packet interface of a protocol
! has an accompanying outgoing call to the Packet interface of the
component below it. The one exception to this is the data link
layer. For example, if there is a network that introduces
***************
*** 476,491 ****
*len -= SEQNO_OFFSET;
}
! return payload + SEQNO_OFFSET;
! }
}
</pre>
<p>The above example is incomplete: it does not include the code for
the send path that increments sequence numbers.</p>
! <p>In practice, calls to Packet are very efficient even if they
pass through many components before reaching the data link
layer. nesC's inlining means that in almost all cases
there will not actually be any function calls, and since payload
position and length calculations all use constant offsets,
! the compiler generally uses constant folding to generate a
fixed offset.</p>
<p>The Packet interface provides access to the one field all packet
--- 471,486 ----
*len -= SEQNO_OFFSET;
}
! return payload + SEQNO_OFFSET;
! }
}
</pre>
<p>The above example is incomplete: it does not include the code for
the send path that increments sequence numbers.</p>
! <p>In practice, calls to Packet are very efficient even if they
pass through many components before reaching the data link
layer. nesC's inlining means that in almost all cases
there will not actually be any function calls, and since payload
position and length calculations all use constant offsets,
! the compiler generally uses constant folding to generate a
fixed offset.</p>
<p>The Packet interface provides access to the one field all packet
***************
*** 493,497 ****
header and footer fields, and may need to provide access to these
fields. If a packet communication component provides access to header
! and/or footer fields, it MUST do so through an interface. The interface
SHOULD have a name of the form <em>XPacket</em>, where <em>X</em> is a name that
describes the communication layer. For example, active message components
--- 488,492 ----
header and footer fields, and may need to provide access to these
fields. If a packet communication component provides access to header
! and/or footer fields, it MUST do so through an interface. The interface
SHOULD have a name of the form <em>XPacket</em>, where <em>X</em> is a name that
describes the communication layer. For example, active message components
***************
*** 521,531 ****
locations.</p>
</div>
! <div class="section" id="sending-interfaces">
! <h2><a name="sending-interfaces">2.2 Sending interfaces</a></h2>
<p>There are multiple sending interfaces, corresponding to different
addressing modes. For example, address-free protocols, such as
collection routing, provide the basic <tt class="docutils literal"><span class="pre">Send</span></tt> interface. Active
message communication has a destination of an AM address, so
! it provides the <tt class="docutils literal"><span class="pre">AMSend</span></tt> interface. This, for example, is the
basic, address-free Send interface:</p>
<pre class="literal-block">
--- 516,526 ----
locations.</p>
</div>
! <div class="section">
! <h2><a id="sending-interfaces" name="sending-interfaces">2.2 Sending interfaces</a></h2>
<p>There are multiple sending interfaces, corresponding to different
addressing modes. For example, address-free protocols, such as
collection routing, provide the basic <tt class="docutils literal"><span class="pre">Send</span></tt> interface. Active
message communication has a destination of an AM address, so
! it provides the <tt class="docutils literal"><span class="pre">AMSend</span></tt> interface. This, for example, is the
basic, address-free Send interface:</p>
<pre class="literal-block">
***************
*** 533,537 ****
command error_t send(message_t* msg, uint8_t len);
command error_t cancel(message_t* msg);
! event void sendDone(message_t* msg, error_t error);
command uint8_t maxPayloadLength();
--- 528,532 ----
command error_t send(message_t* msg, uint8_t len);
command error_t cancel(message_t* msg);
! event void sendDone(message_t* msg, error_t error);
command uint8_t maxPayloadLength();
***************
*** 547,551 ****
command uint8_t maxPayloadLength();
! command void* getPayload(message_t* msg);
}
</pre>
--- 542,546 ----
command uint8_t maxPayloadLength();
! command void* getPayload(message_t* msg);
}
</pre>
***************
*** 561,565 ****
maximum transfer unit (MTU), the send command MUST return ESIZE.</p>
<p>The <tt class="docutils literal"><span class="pre">Send</span></tt> and <tt class="docutils literal"><span class="pre">AMSend</span></tt> interfaces have an explicit queue of
! depth one. A call to <tt class="docutils literal"><span class="pre">send</span></tt> on either of these interfaces MUST
return EBUSY if a prior call to <tt class="docutils