[Tinyos-beta-commits] CVS: tinyos-1.x/beta/teps/html tep108.html,
NONE, 1.1 tep109.html, NONE, 1.1 tep110.html, NONE,
1.1 tep111.html, NONE, 1.1 tep112.html, NONE, 1.1 tep113.html,
NONE, 1.1 tep1.html, 1.9, 1.10 tep101.html, 1.10,
1.11 tep102.html, 1.9, 1.10 tep103.html, 1.5, 1.6 tep104.html,
1.5, 1.6 tep105.html, 1.5, 1.6 tep106.html, 1.6,
1.7 tep107.html, 1.4, 1.5 tep2.html, 1.5, 1.6 tep3.html, 1.6, 1.7
Phil Levis
scipio at users.sourceforge.net
Tue Sep 20 09:30:26 PDT 2005
- Previous message: [Tinyos-beta-commits] CVS: tinyos-1.x/beta/platform/pxa27x
PXA27XQuickCaptInt.h, NONE, 1.1 PXA27XQuickCaptInt.nc, NONE,
1.1 PXA27XQuickCaptIntC.nc, NONE, 1.1 PXA27XQuickCaptIntM.nc,
NONE, 1.1 PXA27XI2CM.nc, 1.1, 1.2 pxa27x_registers.h, 1.11, 1.12
- Next message: [Tinyos-beta-commits]
CVS: tinyos-1.x/beta/teps/txt tep102.txt, 1.14, 1.15
- Messages sorted by:
[ date ]
[ thread ]
[ subject ]
[ author ]
Update of /cvsroot/tinyos/tinyos-1.x/beta/teps/html
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv29699/html
Modified Files:
tep1.html tep101.html tep102.html tep103.html tep104.html
tep105.html tep106.html tep107.html tep2.html tep3.html
Added Files:
tep108.html tep109.html tep110.html tep111.html tep112.html
tep113.html
Log Message:
Generated HTML.
--- NEW FILE: tep108.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.3.9: http://docutils.sourceforge.net/" />
<title>Resource Arbitration</title>
<meta name="author" content="David Gay" />
<meta name="author" content="David Culler" />
<meta name="author" content="Philip Levis" />
<meta name="author" content="Kevin Klues" />
<style type="text/css">
/*
:Author: David Goodger
:Contact: goodger at users.sourceforge.net
:date: $Date: 2005/09/20 16:30:23 $
: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 }
/* Uncomment (& remove this text!) to get bold-faced definition list terms
dt {
font-weight: bold }
*/
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 {
background-color: #eeeeee }
ul.auto-toc {
list-style-type: none }
</style>
</head>
<body>
<div class="document" id="resource-arbitration">
<h1 class="title">Resource Arbitration</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">108</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 Gay</td></tr>
<tr><th class="docinfo-name">Author:</th>
<td>David Culler</td></tr>
<tr><th class="docinfo-name">Author:</th>
<td>Philip Levis</td></tr>
<tr><th class="docinfo-name">Author:</th>
<td>Kevin Klues</td></tr>
<tr class="field"><th class="docinfo-name">Draft-Created:</th><td class="field-body">28-Mar-2005</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">2005-07-06</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" id="abstract">
<h1><a name="abstract">Abstract</a></h1>
<p>This memo documents the general resource sharing mechanisms for TinyOS
2.x. These mechanisms are used to allow multiple software components to
arbitrate the use of both hardware buses, software components, etc.</p>
</div>
<div class="section" id="introduction">
<h1><a name="introduction">1. Introduction</a></h1>
<p>Components that wish to use a shared resource, such as a hardware bus,
memory or the services offered by another component need a way to arbitrate
use of these resources.</p>
<p>In TinyOS 1.x, this arbitration was performed on a first-come, first-served
basis by having requests for, e.g., a service X return FAIL if it was
currently in use. Users of X could monitor service completion events if
they wished to retry a failed request. This approach has several drawbacks:</p>
<ul class="simple">
<li>If you need to make several requests of X, you have to handle the
possibility of failure at any stage. This complicates implementations by
adding extra internal states.</li>
<li>You have no control over timing of a sequence of operations. This is a
problem for, e.g., timing-sensitive use of an A/D converter.</li>
<li>If a hardware resource supports reservation, you cannot express this
via this software interface. For instance, I2C buses have a concept of
"repeated start" when doing multiple bus transactions, but it was not
clear how to use this in TinyOS 1.x's I2C abstraction.</li>
<li>Most TinyOS 1.x services did not provide a very convenient way of
monitoring X's availability for the purpose of retries, nor very
clear documentation of which requests could happen simultaneously.</li>
</ul>
<p>In light of all these problems, TinyOS 2.x introduces resource reservation
mechanisms for use by components providing access to shared resources.</p>
</div>
<div class="section" id="resource-sharing-in-tinyos-2-x">
<h1><a name="resource-sharing-in-tinyos-2-x">2. Resource sharing in TinyOS 2.x</a></h1>
<p>A single approach to resource sharing is not appropriate for all
circumstances. For instance, requiring resource reservation allows programs
to have better timing guarantees for access to an A/D converter. But if
a program does not need precise timing guarantees (e.g., when measuring
temperature in a biological monitoring application), this extra resource
reservation step complicates code.</p>
<p>Thus, TinyOS services should offer resource sharing mechanisms appropriate
to their goals and level of abstraction. However, to preserve simplicity
and consistency there should only be a few different resource sharing
approaches, which we outline here.</p>
<ul class="simple">
<li>Resource reservation: the service must be reserved before use, via the</li>
</ul>
<div class="system-message">
<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep108.txt</tt>, line 76)</p>
Bullet list ends without a blank line; unexpected unindent.</div>
<p>Resource interface. This approach is described in Section 3. Because many
services will have similar approaches to resource sharing (e.g.,
round-robin, or priority-based), TinyOS includes default arbiters
implementing various resource sharing policies. These arbiters are
described in Section 4.</p>
<ul class="simple">
<li>Request queuing: requests from different clients are queued and handled</li>
</ul>
<div class="system-message">
<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep108.txt</tt>, line 83)</p>
Bullet list ends without a blank line; unexpected unindent.</div>
<p>in some (service-dependent) order. This approach is described in Section 5.</p>
<ul class="simple">
<li>Resource virtualisation: the service is virtualised so as to support an</li>
</ul>
<div class="system-message">
<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep108.txt</tt>, line 86)</p>
Bullet list ends without a blank line; unexpected unindent.</div>
<p>arbitrary number of clients - a typical example is the Timer service. From
a programming perspective, this behaves similarly to resource queuing and
is therefore also described in Section 5.</p>
<p>Note that request queuing and resource virtualisation may need to store
significant amounts of per-client state. We expect that lower-level
services will use the resource reservation approach, while higher level
ones will prefer queuing or virtualisation. These higher-level services
will typically be built on top of the lower-level, resource-reservation
based services.</p>
</div>
<div class="section" id="resource-reservation-interface">
<h1><a name="resource-reservation-interface">3. Resource Reservation Interface</a></h1>
<p>The resource interface is defined as follows:</p>
<blockquote>
<dl class="docutils">
<dt>interface Resource {</dt>
<dd><dl class="first docutils">
<dt>/**</dt>
<dd><ul class="first simple">
<li>Request access to a shared resource. You must call release()</li>
<li>when you are done with it.</li>
<li>@return SUCCESS Request accepted. The granted() event will</li>
<li>be signaled when you have the resource.</li>
<li>EBUSY You have already requested this resource via this</li>
<li>interface.</li>
</ul>
<div class="system-message">
<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep108.txt</tt>, line 110)</p>
Bullet list ends without a blank line; unexpected unindent.</div>
<p><a href="#id1" name="id2"><span class="problematic" id="id2">*</span></a>/</p>
<div class="last system-message" id="id1">
<p class="system-message-title">System Message: <a name="id1">WARNING/2</a> (<tt class="docutils">txt/tep108.txt</tt>, line 110); <em><a href="#id2">backlink</a></em></p>
Inline emphasis start-string without end-string.</div>
</dd>
</dl>
<div class="system-message">
<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep108.txt</tt>, line 111)</p>
Definition list ends without a blank line; unexpected unindent.</div>
<p>async command error_t request();</p>
<dl class="docutils">
<dt>/**</dt>
<dd><ul class="first simple">
<li>Request immediate access to a shared resource. You must call</li>
<li>release() when you are done with it.</li>
<li>@return SUCCESS You now have the resource.</li>
<li>EBUSY The resource is busy.</li>
</ul>
<div class="system-message">
<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep108.txt</tt>, line 118)</p>
Bullet list ends without a blank line; unexpected unindent.</div>
<p><a href="#id3" name="id4"><span class="problematic" id="id4">*</span></a>/</p>
<div class="last system-message" id="id3">
<p class="system-message-title">System Message: <a name="id3">WARNING/2</a> (<tt class="docutils">txt/tep108.txt</tt>, line 118); <em><a href="#id4">backlink</a></em></p>
Inline emphasis start-string without end-string.</div>
</dd>
</dl>
<div class="system-message">
<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep108.txt</tt>, line 119)</p>
Definition list ends without a blank line; unexpected unindent.</div>
<p>async command error_t immediateRequest();</p>
<dl class="docutils">
<dt>/**</dt>
<dd><ul class="first simple">
<li>You have received access to this resource. Note that this event</li>
<li>is NOT signaled when immediateRequest() succeeds.</li>
</ul>
<div class="system-message">
<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep108.txt</tt>, line 124)</p>
Bullet list ends without a blank line; unexpected unindent.</div>
<p><a href="#id5" name="id6"><span class="problematic" id="id6">*</span></a>/</p>
<div class="last system-message" id="id5">
<p class="system-message-title">System Message: <a name="id5">WARNING/2</a> (<tt class="docutils">txt/tep108.txt</tt>, line 124); <em><a href="#id6">backlink</a></em></p>
Inline emphasis start-string without end-string.</div>
</dd>
</dl>
<div class="system-message">
<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep108.txt</tt>, line 125)</p>
Definition list ends without a blank line; unexpected unindent.</div>
<p>event void granted();</p>
<dl class="docutils">
<dt>/**</dt>
<dd><ul class="first simple">
<li>Release a shared resource you previously acquired.</li>
</ul>
<div class="system-message">
<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep108.txt</tt>, line 129)</p>
Bullet list ends without a blank line; unexpected unindent.</div>
<p><a href="#id7" name="id8"><span class="problematic" id="id8">*</span></a>/</p>
<div class="last system-message" id="id7">
<p class="system-message-title">System Message: <a name="id7">WARNING/2</a> (<tt class="docutils">txt/tep108.txt</tt>, line 129); <em><a href="#id8">backlink</a></em></p>
Inline emphasis start-string without end-string.</div>
</dd>
</dl>
<div class="system-message">
<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep108.txt</tt>, line 130)</p>
Definition list ends without a blank line; unexpected unindent.</div>
<p>async command void release();</p>
<dl class="docutils">
<dt>/**</dt>
<dd><ul class="first simple">
<li>Some other component has requested this resource. You might</li>
<li>want to consider releasing it.</li>
</ul>
<div class="system-message">
<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep108.txt</tt>, line 135)</p>
Bullet list ends without a blank line; unexpected unindent.</div>
<p><a href="#id9" name="id10"><span class="problematic" id="id10">*</span></a>/</p>
<div class="last system-message" id="id9">
<p class="system-message-title">System Message: <a name="id9">WARNING/2</a> (<tt class="docutils">txt/tep108.txt</tt>, line 135); <em><a href="#id10">backlink</a></em></p>
Inline emphasis start-string without end-string.</div>
</dd>
</dl>
<div class="system-message">
<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep108.txt</tt>, line 136)</p>
Definition list ends without a blank line; unexpected unindent.</div>
<p class="last">event void requested();</p>
</dd>
</dl>
<div class="system-message">
<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep108.txt</tt>, line 137)</p>
Definition list ends without a blank line; unexpected unindent.</div>
<p>}</p>
</blockquote>
<p>This Resource interface is offered as a parameterised interface by services
which wish to provide access to a shared resource. The interface's
parameter represents client ids. A component SomeNameC must #define
SOME_NAME_RESOURCE to a string which can be passed to the special unique()
function to obtain a client id. For instance, the I2C service might look
like this:</p>
<blockquote>
<p>#include "I2CPacketC.h"
configuration I2CPacketC {</p>
<div class="system-message">
<p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">txt/tep108.txt</tt>, line 148)</p>
Unexpected indentation.</div>
<blockquote>
<dl class="docutils">
<dt>provides {</dt>
<dd><dl class="first docutils">
<dt>/**</dt>
<dd><ul class="first simple">
<li>For reserving the I2C bus. 'id' is the client id, obtained</li>
<li>via unique(I2C_RESOURCE)</li>
</ul>
<div class="system-message">
<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep108.txt</tt>, line 152)</p>
Bullet list ends without a blank line; unexpected unindent.</div>
<p><a href="#id11" name="id12"><span class="problematic" id="id12">*</span></a>/</p>
<div class="last system-message" id="id11">
<p class="system-message-title">System Message: <a name="id11">WARNING/2</a> (<tt class="docutils">txt/tep108.txt</tt>, line 152); <em><a href="#id12">backlink</a></em></p>
Inline emphasis start-string without end-string.</div>
</dd>
</dl>
<div class="system-message">
<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep108.txt</tt>, line 153)</p>
Definition list ends without a blank line; unexpected unindent.</div>
<p>interface Resource[uint8_t id];</p>
<dl class="docutils">
<dt>/**</dt>
<dd><ul class="first simple">
<li>Actual I2C packet interface. 'busId' is the I2C</li>
<li>bus identifer of the device you wish to use.</li>
</ul>
<div class="system-message">
<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep108.txt</tt>, line 158)</p>
Bullet list ends without a blank line; unexpected unindent.</div>
<p><a href="#id13" name="id14"><span class="problematic" id="id14">*</span></a>/</p>
<div class="last system-message" id="id13">
<p class="system-message-title">System Message: <a name="id13">WARNING/2</a> (<tt class="docutils">txt/tep108.txt</tt>, line 158); <em><a href="#id14">backlink</a></em></p>
Inline emphasis start-string without end-string.</div>
</dd>
</dl>
<div class="system-message">
<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep108.txt</tt>, line 159)</p>
Definition list ends without a blank line; unexpected unindent.</div>
<p class="last">interface I2CPacket[uint8_t busId];</p>
</dd>
</dl>
<div class="system-message">
<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep108.txt</tt>, line 160)</p>
Definition list ends without a blank line; unexpected unindent.</div>
<p>}</p>
</blockquote>
<div class="system-message">
<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep108.txt</tt>, line 161)</p>
Block quote ends without a blank line; unexpected unindent.</div>
<p>} ...</p>
</blockquote>
<dl class="docutils">
<dt>where I2CPacketC.h contains the #define for the resource:</dt>
<dd><p class="first">#ifndef I2CPACKETC_H
#define I2CPACKETC_H</p>
<p>#define I2CPACKET_RESOURCE "I2CPacket.Resource"</p>
<p class="last">#endif</p>
</dd>
</dl>
<p>The #define for the unique string must be placed in a separate file
because of the way nesC files are preprocessed: referring to I2CPacketC
isn't enough to ensure that macros #define'd in I2CPacketC are visible
in the referring component.</p>
<dl class="docutils">
<dt>Clients of the I2C service would use it as follows:</dt>
<dd><dl class="first docutils">
<dt>module I2CUserM {</dt>
<dd>uses interface Resource as I2CResource;
uses interface I2CPacket;</dd>
</dl>
<div class="system-message">
<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep108.txt</tt>, line 180)</p>
Definition list ends without a blank line; unexpected unindent.</div>
<p>} ...</p>
<p>#include "I2CPacketC.h"
configuration I2CUserC { }
implementation {</p>
<div class="system-message">
<p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">txt/tep108.txt</tt>, line 186)</p>
Unexpected indentation.</div>
<blockquote>
<p>components I2CUserM, I2CPacketC;</p>
<p>I2CUserM.I2CResource -> I2CPacketC.Resource[unique(I2C_RESOURCE)];
I2CUserM.I2CPacket -> I2CPacket.I2CPacket[0x73]; // using I2C device 0x73</p>
</blockquote>
<div class="system-message">
<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep108.txt</tt>, line 190)</p>
Block quote ends without a blank line; unexpected unindent.</div>
<p class="last">}</p>
</dd>
</dl>
<p>A final note: in some cases, resource reservation will correspond to
hardware resource reservation (e.g., for I2C). In other cases --- where
there is no hardware, for a bus which cannot be reserved, etc --- resource
reservation is purely a reservation of the software component itself.</p>
<div class="section" id="cross-component-reservation">
<h2><a name="cross-component-reservation">3.1 Cross-component reservation</a></h2>
<p>In some cases, it is desireable to share reservation of resources across
components. For example, on the TI MSP 430, the same pins can be used as
an I2C bus, a UART, or an SPI connection. Clearly, on this chip, a reservation
of the I2C bus implicitly reserves the corresponding UART and SPI. This can
be accomplished in the framework described above by:
1) using the same unique string for all three resources
2) wiring the three parameterised Resource interfaces to the same arbiter</p>
<p>This could be done as follows (the UART and SPI components are omitted, they
are similar to I2CC):
I2CC.nc (a low-level I2C component):
#define I2C_RESOURCE MSP_BUS_RESOURCE
configuration I2CC {</p>
<div class="system-message">
<p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">txt/tep108.txt</tt>, line 213)</p>
Unexpected indentation.</div>
<blockquote>
provides interface Resource[uint8_t clientId];
provides interface I2C;</blockquote>
<div class="system-message">
<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep108.txt</tt>, line 215)</p>
Block quote ends without a blank line; unexpected unindent.</div>
<p>}
implementation {</p>
<div class="system-message">
<p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">txt/tep108.txt</tt>, line 217)</p>
Unexpected indentation.</div>
<blockquote>
<p>components MspBusC, I2CM;</p>
<p>Resource = MspBusC.Resource;
I2C = I2CM.I2C;</p>
</blockquote>
<div class="system-message">
<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep108.txt</tt>, line 221)</p>
Block quote ends without a blank line; unexpected unindent.</div>
<p>}</p>
<p>MspBusC (the arbiter for the MSP bus):
#define MSP_BUS_RESOURCE "MspBus.Resource"
configuration {</p>
<div class="system-message">
<p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">txt/tep108.txt</tt>, line 226)</p>
Unexpected indentation.</div>
<blockquote>
provides interface Resource[uint8_t clientId];</blockquote>
<div class="system-message">
<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep108.txt</tt>, line 227)</p>
Block quote ends without a blank line; unexpected unindent.</div>
<p>} ...</p>
</div>
</div>
<div class="section" id="default-arbiters">
<h1><a name="default-arbiters">4. Default arbiters</a></h1>
<p>Each service could provide its own implementation of the Resource
interface, but this would be a waste of programmer effort and would lead to
inconsistent resource sharing policies across services. Instead, TinyOS
includes a number of default resource arbiters, in the form of generic
components, which implement the Resource interface. All of these arbiters
also provide a ResourceUser interface which can be interrogated to find the
current set of resource allocation:</p>
<dl class="docutils">
<dt>interface ResourceUser {</dt>
<dd><dl class="first docutils">
<dt>/**</dt>
<dd><ul class="first simple">
<li>Check whether resource is allocated.</li>
<li>@returns TRUE if the resource is currently allocated, FALSE otherwise.</li>
</ul>
<div class="system-message">
<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep108.txt</tt>, line 244)</p>
Bullet list ends without a blank line; unexpected unindent.</div>
<p><a href="#id15" name="id16"><span class="problematic" id="id16">*</span></a>/</p>
<div class="last system-message" id="id15">
<p class="system-message-title">System Message: <a name="id15">WARNING/2</a> (<tt class="docutils">txt/tep108.txt</tt>, line 244); <em><a href="#id16">backlink</a></em></p>
Inline emphasis start-string without end-string.</div>
</dd>
</dl>
<div class="system-message">
<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep108.txt</tt>, line 245)</p>
Definition list ends without a blank line; unexpected unindent.</div>
<p>command bool inUse();</p>
<dl class="docutils">
<dt>/**</dt>
<dd><ul class="first simple">
<li>Return id of client currently using the resource. Meaningless if</li>
<li>inUse() returns FALSE.</li>
</ul>
<div class="system-message">
<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep108.txt</tt>, line 250)</p>
Bullet list ends without a blank line; unexpected unindent.</div>
<p><a href="#id17" name="id18"><span class="problematic" id="id18">*</span></a>/</p>
<div class="last system-message" id="id17">
<p class="system-message-title">System Message: <a name="id17">WARNING/2</a> (<tt class="docutils">txt/tep108.txt</tt>, line 250); <em><a href="#id18">backlink</a></em></p>
Inline emphasis start-string without end-string.</div>
</dd>
</dl>
<div class="system-message">
<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep108.txt</tt>, line 251)</p>
Definition list ends without a blank line; unexpected unindent.</div>
<p class="last">command uint8_t user();</p>
</dd>
</dl>
<div class="system-message">
<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep108.txt</tt>, line 252)</p>
Definition list ends without a blank line; unexpected unindent.</div>
<p>}</p>
<p>ResourceUser can be used by the service implementation, e.g., to refuse
requests when it is not allocated. Or to allow implicit per-request
resource allocation in the style of TinyOS 1.x.</p>
<p>The RoundRobinArbiter provides round-robin arbitration:
generic component RoundRobinArbiter {</p>
<div class="system-message">
<p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">txt/tep108.txt</tt>, line 260)</p>
Unexpected indentation.</div>
<blockquote>
provides interface Resource[uin8_t id];
provides interface ResourceUser;</blockquote>
<div class="system-message">
<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep108.txt</tt>, line 262)</p>
Block quote ends without a blank line; unexpected unindent.</div>
<p>}</p>
<dl class="docutils">
<dt>[[There will be other arbiters here, I presume. For instance, priority-based.</dt>
<dd>Or for services which support >1 outstanding request.]]</dd>
</dl>
</div>
<div class="section" id="request-queuing-and-resource-virtualisation">
<h1><a name="request-queuing-and-resource-virtualisation">5. Request queuing and resource virtualisation</a></h1>
<p>A service which is queued or provides virtualisation is implemented by
parameterising the service interface (in contrast, the resource reservation
approach parameterises the Resource interface). As with Resource, each
client obtains an id via unique(). The service must support one outstanding
request for each unique id; a second request (before completion of the
first) on the same instance of a parameterised interface returns EBUSY.</p>
<p>As an example, the Timer services looks as follows:</p>
<p>#define TIMER_SERVICE "TimerC"
configuration TimerC {</p>
<div class="system-message">
<p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">txt/tep108.txt</tt>, line 281)</p>
Unexpected indentation.</div>
<blockquote>
provides interface Timer<TMilli>[uint8_t id];
provides interface Timer<TM32khz>[uint8_t id];</blockquote>
<div class="system-message">
<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep108.txt</tt>, line 283)</p>
Block quote ends without a blank line; unexpected unindent.</div>
<p>} ...</p>
<p>and clients use it as follows:
module TimerUserM {</p>
<div class="system-message">
<p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">txt/tep108.txt</tt>, line 287)</p>
Unexpected indentation.</div>
<blockquote>
uses interface Timer<TMilli> as MyTimer;</blockquote>
<div class="system-message">
<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep108.txt</tt>, line 288)</p>
Block quote ends without a blank line; unexpected unindent.</div>
<p>} ...</p>
<p>configuration TimerUserC { }
implementation {</p>
<div class="system-message">
<p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">txt/tep108.txt</tt>, line 292)</p>
Unexpected indentation.</div>
<blockquote>
<p>components TimerUserM, TimerC;</p>
<p>TimerUserM.MyTimer -> TimerC.Timer[unique(TIMER_SERVICE)];</p>
</blockquote>
<div class="system-message">
<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep108.txt</tt>, line 295)</p>
Block quote ends without a blank line; unexpected unindent.</div>
<p>}</p>
<p>The difference between queuing of requests and virtualisation is only
in the internal implementation of a service, and is thus beyond the
scope of this document.</p>
<p>We also note that some queued/virtualised services may wish to also support
reservation, e.g., an A/D conveter which wants to support low-latency
requests. Such components will use the same id for their service and
resource interfaces, e.g.:
#define ADC_RESOURCE "Adc.resource"
#define ADC_SERVICE ADC_RESOURCE
configuration ADCC {</p>
<div class="system-message">
<p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">txt/tep108.txt</tt>, line 308)</p>
Unexpected indentation.</div>
<blockquote>
provides interface ADC[uint8_t id];
provides interface Resource[uint8_t id];</blockquote>
<div class="system-message">
<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep108.txt</tt>, line 310)</p>
Block quote ends without a blank line; unexpected unindent.</div>
<p>} ...</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">David Gay</div>
<div class="line">2150 Shattuck Ave, Suite 1300</div>
<div class="line">Intel Research</div>
<div class="line">Berkeley, CA 94704</div>
<div class="line"><br /></div>
<div class="line">phone - +1 510 495 3055</div>
<div class="line">email - <a class="reference" href="mailto:david.e.gay@intel.com">david.e.gay@intel.com</a></div>
<div class="line"><br /></div>
<div class="line">David Culler</div>
<div class="line">627 Soda Hall</div>
<div class="line">UC Berkeley</div>
<div class="line">Berkeley, CA 94720</div>
<div class="line"><br /></div>
<div class="line">phone - +1 510 643 7572</div>
<div class="line">email - <a class="reference" href="mailto:culler@cs.berkeley.edu">culler@cs.berkeley.edu</a></div>
<div class="line"><br /></div>
<div class="line">Philip Levis</div>
<div class="line">467 Soda Hall</div>
<div class="line">UC Berkeley</div>
<div class="line">Berkeley, CA 94720</div>
<div class="line"><br /></div>
<div class="line">phone - +1 510 290 5283</div>
<div class="line">email - <a class="reference" href="mailto:pal@cs.berkeley.edu">pal@cs.berkeley.edu</a></div>
<div class="line"><br /></div>
<div class="line">Kevin Klues</div>
<div class="line">Sekr FT5</div>
<div class="line">Einsteinufer 25</div>
<div class="line">10587 Berlin</div>
<div class="line">GERMANY</div>
<div class="line"><br /></div>
<div class="line">phone - +49-30-314-23813</div>
<div class="line">email - <a class="reference" href="mailto:klues@tkn.tu-berlin.de">klues@tkn.tu-berlin.de</a></div>
</div>
</div>
</div>
</body>
</html>
--- NEW FILE: tep109.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.3.9: http://docutils.sourceforge.net/" />
<title>Sensor Boards</title>
<meta name="author" content="David Gay, Phil Levis, Wei Hong, and Joe Polastre" />
<style type="text/css">
/*
:Author: David Goodger
:Contact: goodger at users.sourceforge.net
:date: $Date: 2005/09/20 16:30:23 $
: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 }
/* Uncomment (& remove this text!) to get bold-faced definition list terms
dt {
font-weight: bold }
*/
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 {
background-color: #eeeeee }
ul.auto-toc {
list-style-type: none }
</style>
</head>
<body>
<div class="document" id="sensor-boards">
<h1 class="title">Sensor Boards</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">109</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 Gay, Phil Levis, Wei Hong, and Joe Polastre</td></tr>
<tr class="field"><th class="docinfo-name">Draft-Created:</th><td class="field-body">19-Apr-2005</td>
</tr>
<tr class="field"><th class="docinfo-name">Draft-Version:</th><td class="field-body">1.5</td>
</tr>
<tr class="field"><th class="docinfo-name">Draft-Modified:</th><td class="field-body">2005-07-06</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" id="abstract">
<h1><a name="abstract">Abstract</a></h1>
<p>This memo documents how sensor boards are organized in TinyOS, and the
general principles followed by the components that provide access to
its sensors.</p>
</div>
<div class="section" id="introduction">
<h1><a name="introduction">1. Introduction</a></h1>
<p>This document defines the default organization of a sensor board in
TinyOS. There likely will be sensor boards that cannot conform
to this specification, but following as closely to its spirit as possible
will simplify generic applications that use a range of sensor boards.</p>
<p>This document assumes that sensors return uninterpreted 16-bit values, and,
optionally uninterpreted, arbitrary-size calibration data. Conversion of
sensor values to something with actual physical meaning is beyond the
(current) scope of this document.</p>
</div>
<div class="section" id="directory-organization">
<h1><a name="directory-organization">2. Directory Organization</a></h1>
<ul class="simple">
<li>A sensor board MUST have a unique name, composed of letters, numbers and</li>
</ul>
<div class="system-message">
<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep109.txt</tt>, line 48)</p>
Bullet list ends without a blank line; unexpected unindent.</div>
<p>underscores. Case is significant, but two sensor boards MUST differ in more
than case. This is necessary to support platforms where filename case
differences are not significant. We will use SBOARD to denote the sensor board
name in the rest of this document.</p>
<ul class="simple">
<li>Each sensor board MUST have its own directory named SBOARD; default TinyOS</li>
</ul>
<div class="system-message">
<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep109.txt</tt>, line 54)</p>
Bullet list ends without a blank line; unexpected unindent.</div>
<p>sensor boards are placed in tinyos-2.x/tos/sensorboards, but
sensor board directories can be placed anywhere as long as the nesC compiler
receives a <a href="#id1" name="id2"><span class="problematic" id="id2">`</span></a>-I' directive pointing to the sensor board's directory.</p>
<div class="system-message" id="id1">
<p class="system-message-title">System Message: <a name="id1">WARNING/2</a> (<tt class="docutils">txt/tep109.txt</tt>, line 54); <em><a href="#id2">backlink</a></em></p>
Inline interpreted text or phrase reference start-string without end-string.</div>
<ul>
<li><p class="first">Each sensor board directory MUST contain a <a href="#id3" name="id4"><span class="problematic" id="id4">`</span></a>.sensor' file. This file</p>
<div class="system-message" id="id3">
<p class="system-message-title">System Message: <a name="id3">WARNING/2</a> (<tt class="docutils">txt/tep109.txt</tt>, line 58); <em><a href="#id4">backlink</a></em></p>
<p>Inline interpreted text or phrase reference start-string without end-string.</p>
</div>
</li>
</ul>
<div class="system-message">
<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep109.txt</tt>, line 59)</p>
Bullet list ends without a blank line; unexpected unindent.</div>
<p>is a perl script which contains any additional compiler settings needed for
this sensor board (this file will be empty in many cases).</p>
<ul class="simple">
<li>If the sensor board wishes to define any C types or constants, it SHOULD</li>
</ul>
<div class="system-message">
<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep109.txt</tt>, line 63)</p>
Bullet list ends without a blank line; unexpected unindent.</div>
<p>place these in a file named SBOARD.h in the sensor board's directory.</p>
<ul class="simple">
<li>The sensor board directory SHOULD contain sensor board components</li>
</ul>
<div class="system-message">
<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep109.txt</tt>, line 66)</p>
Bullet list ends without a blank line; unexpected unindent.</div>
<p>for accessing each sensor on the sensor board. The conventions for these
components are detailed in Section 3.</p>
<ul class="simple">
<li>A sensor board MAY include additional components providing alternative or</li>
</ul>
<div class="system-message">
<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep109.txt</tt>, line 70)</p>
Bullet list ends without a blank line; unexpected unindent.</div>
<p>higher-level interfaces to the sensors (e.g., for TinyDB). These components
are beyond the scope of this document. Future versions of this TEP
are likely to discuss TinyDB attributes.</p>
<ul class="simple">
<li>Finally, the sensor board MAY contain any number of components,</li>
</ul>
<div class="system-message">
<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep109.txt</tt>, line 75)</p>
Bullet list ends without a blank line; unexpected unindent.</div>
<p>interfaces, C files, etc for internal use. To avoid name collisions, all
externally visible names (interface types, components, C constants and
types) used for internal purposes SHOULD be prefixed with SBOARD.</p>
<p>A simple example: the basic sensor board is named <a href="#id5" name="id6"><span class="problematic" id="id6">`</span></a>basicsb', it's directory
is <a href="#id7" name="id8"><span class="problematic" id="id8">`</span></a>tinyos-2.x/tos/sensorboards/basicsb'. It has no <a href="#id9" name="id10"><span class="problematic" id="id10">`</span></a>basicsb.h' file and
its <a href="#id11" name="id12"><span class="problematic" id="id12">`</span></a>.sensor' file is empty. It has two components, <a href="#id13" name="id14"><span class="problematic" id="id14">`</span></a>Photo' and <a href="#id15" name="id16"><span class="problematic" id="id16">`</span></a>Temp'
representing its light and temperature sensors.</p>
<div class="system-message" id="id5">
<p class="system-message-title">System Message: <a name="id5">WARNING/2</a> (<tt class="docutils">txt/tep109.txt</tt>, line 79); <em><a href="#id6">backlink</a></em></p>
Inline interpreted text or phrase reference start-string without end-string.</div>
<div class="system-message" id="id7">
<p class="system-message-title">System Message: <a name="id7">WARNING/2</a> (<tt class="docutils">txt/tep109.txt</tt>, line 79); <em><a href="#id8">backlink</a></em></p>
Inline interpreted text or phrase reference start-string without end-string.</div>
<div class="system-message" id="id9">
<p class="system-message-title">System Message: <a name="id9">WARNING/2</a> (<tt class="docutils">txt/tep109.txt</tt>, line 79); <em><a href="#id10">backlink</a></em></p>
Inline interpreted text or phrase reference start-string without end-string.</div>
<div class="system-message" id="id11">
<p class="system-message-title">System Message: <a name="id11">WARNING/2</a> (<tt class="docutils">txt/tep109.txt</tt>, line 79); <em><a href="#id12">backlink</a></em></p>
Inline interpreted text or phrase reference start-string without end-string.</div>
<div class="system-message" id="id13">
<p class="system-message-title">System Message: <a name="id13">WARNING/2</a> (<tt class="docutils">txt/tep109.txt</tt>, line 79); <em><a href="#id14">backlink</a></em></p>
Inline interpreted text or phrase reference start-string without end-string.</div>
<div class="system-message" id="id15">
<p class="system-message-title">System Message: <a name="id15">WARNING/2</a> (<tt class="docutils">txt/tep109.txt</tt>, line 79); <em><a href="#id16">backlink</a></em></p>
Inline interpreted text or phrase reference start-string without end-string.</div>
</div>
<div class="section" id="sensor-board-components">
<h1><a name="sensor-board-components">3. Sensor Board Components</a></h1>
<p>We have not yet selected any naming conventions for sensor board
components. Please select reasonable namesldots</p>
<p>A sensor board component MUST provide:
- An <a href="#id17" name="id18"><span class="problematic" id="id18">`</span></a>Init' interface.
- A <a href="#id19" name="id20"><span class="problematic" id="id20">`</span></a>StdControl' or <a href="#id21" name="id22"><span class="problematic" id="id22">`</span></a>SplitControl' interface for power management.
- A non-empty set of <a href="#id23" name="id24"><span class="problematic" id="id24">`</span></a>DataAcquire' interfaces for sampling.</p>
<div class="system-message" id="id17">
<p class="system-message-title">System Message: <a name="id17">WARNING/2</a> (<tt class="docutils">txt/tep109.txt</tt>, line 92); <em><a href="#id18">backlink</a></em></p>
Inline interpreted text or phrase reference start-string without end-string.</div>
<div class="system-message" id="id19">
<p class="system-message-title">System Message: <a name="id19">WARNING/2</a> (<tt class="docutils">txt/tep109.txt</tt>, line 92); <em><a href="#id20">backlink</a></em></p>
Inline interpreted text or phrase reference start-string without end-string.</div>
<div class="system-message" id="id21">
<p class="system-message-title">System Message: <a name="id21">WARNING/2</a> (<tt class="docutils">txt/tep109.txt</tt>, line 92); <em><a href="#id22">backlink</a></em></p>
Inline interpreted text or phrase reference start-string without end-string.</div>
<div class="system-message" id="id23">
<p class="system-message-title">System Message: <a name="id23">WARNING/2</a> (<tt class="docutils">txt/tep109.txt</tt>, line 92); <em><a href="#id24">backlink</a></em></p>
Inline interpreted text or phrase reference start-string without end-string.</div>
<p>A sensor board component MAY provide:
- Some <a href="#id25" name="id26"><span class="problematic" id="id26">`</span></a>CalibrationData' interfaces for obtaining calibration data.</p>
<div class="system-message" id="id25">
<p class="system-message-title">System Message: <a name="id25">WARNING/2</a> (<tt class="docutils">txt/tep109.txt</tt>, line 97); <em><a href="#id26">backlink</a></em></p>
Inline interpreted text or phrase reference start-string without end-string.</div>
<div class="system-message">
<p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">txt/tep109.txt</tt>, line 99)</p>
Unexpected indentation.</div>
<blockquote>
A calibration interface for a sensor accessed via interface X should
be called XCalibration.</blockquote>
<div class="system-message">
<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep109.txt</tt>, line 101)</p>
Block quote ends without a blank line; unexpected unindent.</div>
<ul>
<li><p class="first">Some <a href="#id27" name="id28"><span class="problematic" id="id28">`</span></a>ADCSingle' and <a href="#id29" name="id30"><span class="problematic" id="id30">`</span></a>ADCMultiple' interfaces, for high-speed or
low-latency data acquisition.</p>
<div class="system-message" id="id27">
<p class="system-message-title">System Message: <a name="id27">WARNING/2</a> (<tt class="docutils">txt/tep109.txt</tt>, line 101); <em><a href="#id28">backlink</a></em></p>
<p>Inline interpreted text or phrase reference start-string without end-string.</p>
</div>
<div class="system-message" id="id29">
<p class="system-message-title">System Message: <a name="id29">WARNING/2</a> (<tt class="docutils">txt/tep109.txt</tt>, line 101); <em><a href="#id30">backlink</a></em></p>
<p>Inline interpreted text or phrase reference start-string without end-string.</p>
</div>
</li>
<li><p class="first">Any other appropriate interface.</p>
</li>
</ul>
<p>The <a href="#id31" name="id32"><span class="problematic" id="id32">`</span></a>CalibrationData' interface is shown below, while <a href="#id33" name="id34"><span class="problematic" id="id34">`</span></a>DataAcquire',
<a href="#id35" name="id36"><span class="problematic" id="id36">`</span></a>ADCSingle' and <a href="#id37" name="id38"><span class="problematic" id="id38">`</span></a>ADCMultiple' are in TEP 101. The <a href="#id39" name="id40"><span class="problematic" id="id40">`</span></a>DataAcquire' interface
returns uinterpreted 16-bit data. This might represent an A/D conversion
result, a counter, etc. The optional calibration interface returns
uninterpreted, arbitrary-size data.</p>
<div class="system-message" id="id31">
<p class="system-message-title">System Message: <a name="id31">WARNING/2</a> (<tt class="docutils">txt/tep109.txt</tt>, line 105); <em><a href="#id32">backlink</a></em></p>
Inline interpreted text or phrase reference start-string without end-string.</div>
<div class="system-message" id="id33">
<p class="system-message-title">System Message: <a name="id33">WARNING/2</a> (<tt class="docutils">txt/tep109.txt</tt>, line 105); <em><a href="#id34">backlink</a></em></p>
Inline interpreted text or phrase reference start-string without end-string.</div>
<div class="system-message" id="id35">
<p class="system-message-title">System Message: <a name="id35">WARNING/2</a> (<tt class="docutils">txt/tep109.txt</tt>, line 105); <em><a href="#id36">backlink</a></em></p>
Inline interpreted text or phrase reference start-string without end-string.</div>
<div class="system-message" id="id37">
<p class="system-message-title">System Message: <a name="id37">WARNING/2</a> (<tt class="docutils">txt/tep109.txt</tt>, line 105); <em><a href="#id38">backlink</a></em></p>
Inline interpreted text or phrase reference start-string without end-string.</div>
<div class="system-message" id="id39">
<p class="system-message-title">System Message: <a name="id39">WARNING/2</a> (<tt class="docutils">txt/tep109.txt</tt>, line 105); <em><a href="#id40">backlink</a></em></p>
Inline interpreted text or phrase reference start-string without end-string.</div>
<p>A sensor board component SHOULD be as lightweight as possible - it should
just provide basic access to the physical sensors and SHOULD NOT attempt to do
calibration, signal processing, etc. If such functionality is desired, it
SHOULD be provided in separate components.</p>
<blockquote>
<dl class="docutils">
<dt>interface CalibrationData {</dt>
<dd><p class="first">/* Collect uninterpreted calibration data from a sensor <a href="#id41" name="id42"><span class="problematic" id="id42">*</span></a>/</p>
<div class="system-message" id="id41">
<p class="system-message-title">System Message: <a name="id41">WARNING/2</a> (<tt class="docutils">txt/tep109.txt</tt>, line 117); <em><a href="#id42">backlink</a></em></p>
Inline emphasis start-string without end-string.</div>
<dl class="docutils">
<dt>/** Request calibration data</dt>
<dd><ul class="first simple">
<li>@return SUCCESS if request accepted, FAIL if it is refused</li>
<li>data error will be signaled if SUCCESS is returned</li>
</ul>
<div class="system-message">
<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep109.txt</tt>, line 122)</p>
Bullet list ends without a blank line; unexpected unindent.</div>
<p><a href="#id43" name="id44"><span class="problematic" id="id44">*</span></a>/</p>
<div class="last system-message" id="id43">
<p class="system-message-title">System Message: <a name="id43">WARNING/2</a> (<tt class="docutils">txt/tep109.txt</tt>, line 122); <em><a href="#id44">backlink</a></em></p>
Inline emphasis start-string without end-string.</div>
</dd>
</dl>
<div class="system-message">
<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep109.txt</tt>, line 123)</p>
Definition list ends without a blank line; unexpected unindent.</div>
<p>command result_t get();</p>
<dl class="docutils">
<dt>/** Returns calibration data</dt>
<dd><ul class="first simple">
<li>@param x Pointer to (uinterpreted) calibration data. This data</li>
<li>must not be modified.</li>
<li>@param len Length of calibration data</li>
<li>@return Ignored.</li>
</ul>
<div class="system-message">
<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep109.txt</tt>, line 130)</p>
Bullet list ends without a blank line; unexpected unindent.</div>
<p><a href="#id45" name="id46"><span class="problematic" id="id46">*</span></a>/</p>
<div class="last system-message" id="id45">
<p class="system-message-title">System Message: <a name="id45">WARNING/2</a> (<tt class="docutils">txt/tep109.txt</tt>, line 130); <em><a href="#id46">backlink</a></em></p>
Inline emphasis start-string without end-string.</div>
</dd>
</dl>
<div class="system-message">
<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep109.txt</tt>, line 131)</p>
Definition list ends without a blank line; unexpected unindent.</div>
<p>event result_t data(const void <a href="#id47" name="id48"><span class="problematic" id="id48">*</span></a>x, uint8_t len);</p>
<div class="last system-message" id="id47">
<p class="system-message-title">System Message: <a name="id47">WARNING/2</a> (<tt class="docutils">txt/tep109.txt</tt>, line 131); <em><a href="#id48">backlink</a></em></p>
Inline emphasis start-string without end-string.</div>
</dd>
</dl>
<div class="system-message">
<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep109.txt</tt>, line 132)</p>
Definition list ends without a blank line; unexpected unindent.</div>
<p>}</p>
</blockquote>
<p>Some common setups for sensor board components are:</p>
<ul>
<li><p class="first">A single <a href="#id49" name="id50"><span class="problematic" id="id50">`</span></a>DataAcquire' interface. This is probably the most common case, where</p>
<div class="system-message" id="id49">
<p class="system-message-title">System Message: <a name="id49">WARNING/2</a> (<tt class="docutils">txt/tep109.txt</tt>, line 137); <em><a href="#id50">backlink</a></em></p>
<p>Inline interpreted text or phrase reference start-string without end-string.</p>
</div>
</li>
</ul>
<div class="system-message">
<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep109.txt</tt>, line 138)</p>
Bullet list ends without a blank line; unexpected unindent.</div>
<p>a single component corresponds to a single physical sensor, e.g., for
light, temperature, pressure and there is no expectation of high sample
rates.</p>
<ul>
<li><p class="first">Multiple <a href="#id51" name="id52"><span class="problematic" id="id52">`</span></a>DataAcquire' interfaces. Some sensors</p>
<div class="system-message" id="id51">
<p class="system-message-title">System Message: <a name="id51">WARNING/2</a> (<tt class="docutils">txt/tep109.txt</tt>, line 142); <em><a href="#id52">backlink</a></em></p>
<p>Inline interpreted text or phrase reference start-string without end-string.</p>
</div>
</li>
</ul>
<div class="system-message">
<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep109.txt</tt>, line 143)</p>
Bullet list ends without a blank line; unexpected unindent.</div>
<p>might be strongly related, e.g., the axes of an accelerometer. A single
component could then provide a sensor interface for each axis. For
instance, a 2-axis accelerometer which can be sampled at high speed, and which
has some calibration data might be declared with:</p>
<div class="system-message">
<p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">txt/tep109.txt</tt>, line 147)</p>
Unexpected indentation.</div>
<blockquote>
<dl class="docutils">
<dt>configuration Accelerometer2D {</dt>
<dd><dl class="first docutils">
<dt>provides {</dt>
<dd><p class="first">interface StdControl
interface DataAcquire as AccelX;
interface ADCSingle as AccelXSingle;
interface ADCMultiple as AccelXMultiple;
interface CalibrationData as AccelXCalibration;</p>
<p class="last">interface DataAcquire as AccelY;
interface ADCSingle as AccelYSingle;
interface ADCMultiple as AccelYMultiple;
interface CalibrationData as AccelYCalibration;</p>
</dd>
</dl>
<div class="system-message">
<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep109.txt</tt>, line 159)</p>
Definition list ends without a blank line; unexpected unindent.</div>
<p class="last">}</p>
</dd>
</dl>
<div class="system-message">
<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep109.txt</tt>, line 160)</p>
Definition list ends without a blank line; unexpected unindent.</div>
<p>}</p>
</blockquote>
<ul>
<li><p class="first">A parameterised <a href="#id53" name="id54"><span class="problematic" id="id54">`</span></a>DataAcquire' interface. If a sensor board has multiple</p>
<div class="system-message" id="id53">
<p class="system-message-title">System Message: <a name="id53">WARNING/2</a> (<tt class="docutils">txt/tep109.txt</tt>, line 162); <em><a href="#id54">backlink</a></em></p>
<p>Inline interpreted text or phrase reference start-string without end-string.</p>
</div>
</li>
</ul>
<div class="system-message">
<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep109.txt</tt>, line 163)</p>
Bullet list ends without a blank line; unexpected unindent.</div>
<p>similar sensors, it may make sense to provide a single component to access
all of these, using a parameterised <a href="#id55" name="id56"><span class="problematic" id="id56">`</span></a>DataAcquire' interface. For instance,
a general purpose sensor board with multiple A/D channels might provide an
<a href="#id57" name="id58"><span class="problematic" id="id58">`</span></a>DataAcquire' interface parameterised by the A/D channel id.</p>
<div class="system-message" id="id55">
<p class="system-message-title">System Message: <a name="id55">WARNING/2</a> (<tt class="docutils">txt/tep109.txt</tt>, line 163); <em><a href="#id56">backlink</a></em></p>
Inline interpreted text or phrase reference start-string without end-string.</div>
<div class="system-message" id="id57">
<p class="system-message-title">System Message: <a name="id57">WARNING/2</a> (<tt class="docutils">txt/tep109.txt</tt>, line 163); <em><a href="#id58">backlink</a></em></p>
Inline interpreted text or phrase reference start-string without end-string.</div>
<ul class="simple">
<li>In all of these examples, if high-speed sampling makes sensor for the</li>
</ul>
<div class="system-message">
<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep109.txt</tt>, line 169)</p>
Bullet list ends without a blank line; unexpected unindent.</div>
<p>sensor (e.g., a microphone), and the sensor is connected in a way that
supports high-frequency and/or low-latency access (e.g., via an
on-microcontroller A/D converter), the component should offer
'ADCSingle' and 'ADCMultiple' interfaces.</p>
<p>Sensor board components MUST respect the following conventions
on the use of the <a href="#id59" name="id60"><span class="problematic" id="id60">`</span></a>Init', <a href="#id61" name="id62"><span class="problematic" id="id62">`</span></a>StdControl', and <a href="#id63" name="id64"><span class="problematic" id="id64">`</span></a>SplitControl'
interfaces. These are given assuming <a href="#id65" name="id66"><span class="problematic" id="id66">`</span></a>StdControl' is used, but the
behaviour with <a href="#id67" name="id68"><span class="problematic" id="id68">`</span></a>SplitControl' is identical except that <a href="#id69" name="id70"><span class="problematic" id="id70">`</span></a>start' and <a href="#id71" name="id72"><span class="problematic" id="id72">`</span></a>stop'
are not considered complete until the <a href="#id73" name="id74"><span class="problematic" id="id74">`</span></a>startDone' and <a href="#id75" name="id76"><span class="problematic" id="id76">`</span></a>stopDone' events are
signaled. The conventions are:</p>
<div class="system-message" id="id59">
<p class="system-message-title">System Message: <a name="id59">WARNING/2</a> (<tt class="docutils">txt/tep109.txt</tt>, line 174); <em><a href="#id60">backlink</a></em></p>
Inline interpreted text or phrase reference start-string without end-string.</div>
<div class="system-message" id="id61">
<p class="system-message-title">System Message: <a name="id61">WARNING/2</a> (<tt class="docutils">txt/tep109.txt</tt>, line 174); <em><a href="#id62">backlink</a></em></p>
Inline interpreted text or phrase reference start-string without end-string.</div>
<div class="system-message" id="id63">
<p class="system-message-title">System Message: <a name="id63">WARNING/2</a> (<tt class="docutils">txt/tep109.txt</tt>, line 174); <em><a href="#id64">backlink</a></em></p>
Inline interpreted text or phrase reference start-string without end-string.</div>
<div class="system-message" id="id65">
<p class="system-message-title">System Message: <a name="id65">WARNING/2</a> (<tt class="docutils">txt/tep109.txt</tt>, line 174); <em><a href="#id66">backlink</a></em></p>
Inline interpreted text or phrase reference start-string without end-string.</div>
<div class="system-message" id="id67">
<p class="system-message-title">System Message: <a name="id67">WARNING/2</a> (<tt class="docutils">txt/tep109.txt</tt>, line 174); <em><a href="#id68">backlink</a></em></p>
Inline interpreted text or phrase reference start-string without end-string.</div>
<div class="system-message" id="id69">
<p class="system-message-title">System Message: <a name="id69">WARNING/2</a> (<tt class="docutils">txt/tep109.txt</tt>, line 174); <em><a href="#id70">backlink</a></em></p>
Inline interpreted text or phrase reference start-string without end-string.</div>
<div class="system-message" id="id71">
<p class="system-message-title">System Message: <a name="id71">WARNING/2</a> (<tt class="docutils">txt/tep109.txt</tt>, line 174); <em><a href="#id72">backlink</a></em></p>
Inline interpreted text or phrase reference start-string without end-string.</div>
<div class="system-message" id="id73">
<p class="system-message-title">System Message: <a name="id73">WARNING/2</a> (<tt class="docutils">txt/tep109.txt</tt>, line 174); <em><a href="#id74">backlink</a></em></p>
Inline interpreted text or phrase reference start-string without end-string.</div>
<div class="system-message" id="id75">
<p class="system-message-title">System Message: <a name="id75">WARNING/2</a> (<tt class="docutils">txt/tep109.txt</tt>, line 174); <em><a href="#id76">backlink</a></em></p>
Inline interpreted text or phrase reference start-string without end-string.</div>
<ol class="arabic">
<li><p class="first"><a href="#id77" name="id78"><span class="problematic" id="id78">`</span></a>Init.init': must be called at mote boot time.</p>
<div class="system-message" id="id77">
<p class="system-message-title">System Message: <a name="id77">WARNING/2</a> (<tt class="docutils">txt/tep109.txt</tt>, line 181); <em><a href="#id78">backlink</a></em></p>
<p>Inline interpreted text or phrase reference start-string without end-string.</p>
</div>
</li>
<li><dl class="first docutils">
<dt><a href="#id79" name="id80"><span class="problematic" id="id80">`</span></a>StdControl.start': ensure the sensor corresponding to this component is</dt>
<dd><div class="first system-message" id="id79">
<p class="system-message-title">System Message: <a name="id79">WARNING/2</a> (<tt class="docutils">txt/tep109.txt</tt>, line 191); <em><a href="#id80">backlink</a></em></p>
<p>Inline interpreted text or phrase reference start-string without end-string.</p>
</div>
<p>ready for use. For instance, this should power-up the sensor if
necessary. The application can call <a href="#id81" name="id82"><span class="problematic" id="id82">`</span></a>getData' once <a href="#id83" name="id84"><span class="problematic" id="id84">`</span></a>StdControl.start'
completes.</p>
<div class="system-message" id="id81">
<p class="system-message-title">System Message: <a name="id81">WARNING/2</a> (<tt class="docutils">txt/tep109.txt</tt>, line 184); <em><a href="#id82">backlink</a></em></p>
<p>Inline interpreted text or phrase reference start-string without end-string.</p>
</div>
<div class="system-message" id="id83">
<p class="system-message-title">System Message: <a name="id83">WARNING/2</a> (<tt class="docutils">txt/tep109.txt</tt>, line 184); <em><a href="#id84">backlink</a></em></p>
<p>Inline interpreted text or phrase reference start-string without end-string.</p>
</div>
<p>If a sensor takes a while to power-up, the sensor board implementer can
either use a <a href="#id85" name="id86"><span class="problematic" id="id86">`</span></a>SplitControl' interface and signal <a href="#id87" name="id88"><span class="problematic" id="id88">`</span></a>startDone'
when the sensor is ready for use, or delay <a href="#id89" name="id90"><span class="problematic" id="id90">`</span></a>dataReady' events
until the sensor is ready. The former choice is preferable.</p>
<div class="system-message" id="id85">
<p class="system-message-title">System Message: <a name="id85">WARNING/2</a> (<tt class="docutils">txt/tep109.txt</tt>, line 188); <em><a href="#id86">backlink</a></em></p>
<p>Inline interpreted text or phrase reference start-string without end-string.</p>
</div>
<div class="system-message" id="id87">
<p class="system-message-title">System Message: <a name="id87">WARNING/2</a> (<tt class="docutils">txt/tep109.txt</tt>, line 188); <em><a href="#id88">backlink</a></em></p>
<p>Inline interpreted text or phrase reference start-string without end-string.</p>
</div>
<div class="last system-message" id="id89">
<p class="system-message-title">System Message: <a name="id89">WARNING/2</a> (<tt class="docutils">txt/tep109.txt</tt>, line 188); <em><a href="#id90">backlink</a></em></p>
<p>Inline interpreted text or phrase reference start-string without end-string.</p>
</div>
</dd>
</dl>
</li>
</ol>
<p>3) <a href="#id91" name="id92"><span class="problematic" id="id92">`</span></a>StdControl.stop': put the sensor in a low-power mode.
<a href="#id93" name="id94"><span class="problematic" id="id94">`</span></a>StdControl.start' must be called before any further readings
are taken. The behaviour of calls to <a href="#id95" name="id96"><span class="problematic" id="id96">`</span></a>StdControl.stop' during
sampling (i.e., when an <a href="#id97" name="id98"><span class="problematic" id="id98">`</span></a>dataReady' event is going to be
signaled) is undefined.</p>
<div class="system-message" id="id91">
<p class="system-message-title">System Message: <a name="id91">WARNING/2</a> (<tt class="docutils">txt/tep109.txt</tt>, line 193); <em><a href="#id92">backlink</a></em></p>
Inline interpreted text or phrase reference start-string without end-string.</div>
<div class="system-message" id="id93">
<p class="system-message-title">System Message: <a name="id93">WARNING/2</a> (<tt class="docutils">txt/tep109.txt</tt>, line 193); <em><a href="#id94">backlink</a></em></p>
Inline interpreted text or phrase reference start-string without end-string.</div>
<div class="system-message" id="id95">
<p class="system-message-title">System Message: <a name="id95">WARNING/2</a> (<tt class="docutils">txt/tep109.txt</tt>, line 193); <em><a href="#id96">backlink</a></em></p>
Inline interpreted text or phrase reference start-string without end-string.</div>
<div class="system-message" id="id97">
<p class="system-message-title">System Message: <a name="id97">WARNING/2</a> (<tt class="docutils">txt/tep109.txt</tt>, line 193); <em><a href="#id98">backlink</a></em></p>
Inline interpreted text or phrase reference start-string without end-string.</div>
</div>
<div class="section" id="sensor-file">
<h1><a name="sensor-file"><a href="#id99" name="id100"><span class="problematic" id="id100">`</span></a>.sensor' File</a></h1>
<div class="system-message" id="id99">
<p class="system-message-title">System Message: <a name="id99">WARNING/2</a> (<tt class="docutils">txt/tep109.txt</tt>, line 199); <em><a href="#id100">backlink</a></em></p>
Inline interpreted text or phrase reference start-string without end-string.</div>
<p>This file is a perl script which gets executed as part of the <a href="#id101" name="id102"><span class="problematic" id="id102">`</span></a>ncc'
nesC compiler frontend. It can add or modify any compile-time options
necessary for a particular sensor board. It MAY modify the following perl
variables, and MUST NOT modify any others:</p>
<div class="system-message" id="id101">
<p class="system-message-title">System Message: <a name="id101">WARNING/2</a> (<tt class="docutils">txt/tep109.txt</tt>, line 202); <em><a href="#id102">backlink</a></em></p>
Inline interpreted text or phrase reference start-string without end-string.</div>
<ul>
<li><p class="first">@new_args: This is the array of arguments which will be
passed to nescc. For instance, you might add an include directive
to @new_args with</p>
<div class="system-message">
<p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">txt/tep109.txt</tt>, line 210)</p>
<p>Unexpected indentation.</p>
</div>
<blockquote>
<p>push @new_args, '-Isomedir'</p>
</blockquote>
</li>
<li><p class="first">@commonboards: This can be set to a list of sensor board names which
should be added to the include path list. These sensor boards must be
in tinyos-2.x/tos/sensorboards.</p>
</li>
</ul>
</div>
<div class="section" id="example-micasb">
<h1><a name="example-micasb">Example: micasb</a></h1>
<p>The mica sensor board (micasb) has five sensors (and one actuator, the
sounder):
Name | Component | Sensor Interfaces | Other Interfaces
----------------------------------------------------------------
Accelerometer | Accel | AccelX |</p>
<div class="system-message">
<p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">txt/tep109.txt</tt>, line 223)</p>
Unexpected indentation.</div>
<blockquote>
<div class="line-block">
<div class="line">| AccelY | </div>
</div>
</blockquote>
<div class="system-message">
<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep109.txt</tt>, line 224)</p>
Block quote ends without a blank line; unexpected unindent.</div>
<dl class="docutils">
<dt>Magnetometer | Mag | MagX | MagSetting</dt>
<dd><div class="first last line-block">
<div class="line">| MagY | </div>
</div>
</dd>
<dt>Microphone | Mic | MicADC | Mic</dt>
<dd><div class="first last line-block">
<div class="line">| | MicInterrupt </div>
</div>
</dd>
</dl>
<div class="system-message">
<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep109.txt</tt>, line 228)</p>
Definition list ends without a blank line; unexpected unindent.</div>
<p>Light | Photo | PhotoADC |
Temperature | Temp | TempADC |</p>
<p>Each physical sensor is represented by a separate component. Specific
sensors that have more than one axis of measurement (e.g., Accel and
Mag) provide more than one <a href="#id103" name="id104"><span class="problematic" id="id104">`</span></a>DataAcquire' interface on a single component. Some
sensors, such as the magnetometer and microphone, have additional
functionality provided through sensor-specific interfaces.</p>
<div class="system-message" id="id103">
<p class="system-message-title">System Message: <a name="id103">WARNING/2</a> (<tt class="docutils">txt/tep109.txt</tt>, line 231); <em><a href="#id104">backlink</a></em></p>
Inline interpreted text or phrase reference start-string without end-string.</div>
<p>Although light and temperature are represented by separate components,
in reality they share a single ADC pin. The two components Photo and
Temp sit on top of the PhotoTemp component, which controls access to
the shared pin, and orchestrates which sensor is currently connected
to it. From a programmer's perspective, they appear as individual
sensors, even though their underlying implementation is a bit more
complex.</p>
<p>The board's micasb.h file contains private configuration data
(pin usage, ADC ports, etc).</p>
<p>The mica sensor board has an empty .sensor file.</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">David Gay</div>
<div class="line">2150 Shattuck Ave, Suite 1300</div>
<div class="line">Intel Research</div>
<div class="line">Berkeley, CA 94704</div>
<div class="line"><br /></div>
<div class="line">phone - +1 510 495 3055</div>
<div class="line"><br /></div>
<div class="line">email - <a class="reference" href="mailto:david.e.gay@intel.com">david.e.gay@intel.com</a></div>
<div class="line"><br /></div>
<div class="line">Wei Hong</div>
<div class="line">2150 Shattuck Ave, Suite 1300</div>
<div class="line">Intel Research</div>
<div class="line">Berkeley, CA 94704</div>
<div class="line"><br /></div>
<div class="line">phone - +1 510 495 3058</div>
<div class="line"><br /></div>
<div class="line">email - <a class="reference" href="mailto:wei.hong@intel.com">wei.hong@intel.com</a></div>
<div class="line"><br /></div>
<div class="line">Philip Levis</div>
<div class="line">358 Gates Hall</div>
<div class="line">Computer Science Department</div>
<div class="line">353 Serra Mall</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 class="line"><br /></div>
<div class="line">Joe Polastre</div>
<div class="line">467 Soda Hall</div>
<div class="line">UC Berkeley</div>
<div class="line">Berkeley, CA 94720</div>
<div class="line"><br /></div>
<div class="line">email - <a class="reference" href="mailto:polastre@cs.berkeley.edu">polastre@cs.berkeley.edu</a></div>
</div>
</div>
</div>
</body>
</html>
--- NEW FILE: tep110.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.3.9: http://docutils.sourceforge.net/" />
<title>Service Distributions</title>
<meta name="author" content="Philip Levis" />
<style type="text/css">
/*
:Author: David Goodger
:Contact: goodger at users.sourceforge.net
:date: $Date: 2005/09/20 16:30:23 $
: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 }
/* Uncomment (& remove this text!) to get bold-faced definition list terms
dt {
font-weight: bold }
*/
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 {
background-color: #eeeeee }
ul.auto-toc {
list-style-type: none }
</style>
</head>
<body>
<div class="document" id="service-distributions">
<h1 class="title">Service Distributions</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">110</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>Philip Levis</td></tr>
<tr class="field"><th class="docinfo-name">Draft-Created:</th><td class="field-body">20-Jun-2005</td>
</tr>
<tr class="field"><th class="docinfo-name">Draft-Version:</th><td class="field-body">1.3</td>
</tr>
<tr class="field"><th class="docinfo-name">Draft-Modified:</th><td class="field-body">2005-09-03</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" id="abstract">
<h1><a name="abstract">Abstract</a></h1>
<p>This memo describes the structure and implementation of TinyOS 2.x
service distributions, collections of components designed to work
as a cohesive whole for application builders. It documents one
example distribution, OSKI.</p>
</div>
<div class="section" id="introduction">
<h1><a name="introduction">1. Introduction</a></h1>
<p>The TinyOS component model allows flexible composition, but that
flexibility is often limited by reasons which are not explicitly
stated in components. These implicit assumptions can manifest as buggy
behavior. In TinyOS 1.x, on the Telos platform, if a program
simultaneously initializes non-volatile storage and the radio, one of
them will fail: a program has to initialize them serially. They can
also manifest as compile-time errors: if two separate communication
services happen to receive packets of the same AM type, the nesC
compiler will issue a warning due to the buffer swap semantics.</p>
<p>On one hand, the flexbility components provide allows expert users to
build complex and intricate applications. On the other, it can make
managing complexity and intricacy very difficult when building very
simple and basic applications. To promote this latter class of
development, TinyOS 2.x has the notion of "distributions," which are
collections of system abstractions that are designed to be used
together. As long as a user implements an application in terms of the
distribution, the underlying components will operate correctly and
there will be no unforseen failures.</p>
<p>This memo documents an example distribution, named OSKI (Operating
System Key Interfaces). It describes the services OSKI provides and
how their implementations are structured to simplify application
writing.</p>
</div>
<div class="section" id="distributions">
<h1><a name="distributions">2. Distributions</a></h1>
<p>A distribution presents <em>services</em> to the programmer. A service is a
set of generic (instantiable) components that represent API
abstractions. To use an abstraction, a programmer instantiates the
generic. For example, OSKI has the <tt class="docutils literal"><span class="pre">AMSenderC</span></tt> abstraction for
sending active messages. The AMSender generic component takes a single
parameter, the AM type. For example, if a programmer wants a component
named AppM to send active messages of type 32, the configuration would
look something like this:</p>
<div class="line-block">
<div class="line">configuration AppC {}</div>
<div class="line">implementation {</div>
<div class="line-block">
<div class="line">components AppM, new AMSenderC(32);</div>
<div class="line">AppM.AMSend -> AMSenderC;</div>
</div>
<div class="line">}</div>
</div>
<p>Services often present abstractions at a fine grain. For example, the
active message service has AMSender, AMReceiver, and AMSnooper, each
of which is a separate abstraction.</p>
<div class="section" id="controlling-a-service">
<h2><a name="controlling-a-service">2.1 Controlling a Service</a></h2>
<p>Every service has two abstractions: <tt class="docutils literal"><span class="pre">ServiceC</span></tt>, for powering it on
and off, and <tt class="docutils literal"><span class="pre">ServiceNotifierC</span></tt>, for learning when the service's
power state has changed. For example, active messages have the
<tt class="docutils literal"><span class="pre">AMServiceC</span></tt> and <tt class="docutils literal"><span class="pre">AMServiceNotifierC</span></tt> abstractions. A service
abstraction provides the <tt class="docutils literal"><span class="pre">Service</span></tt> interface</p>
<div class="line-block">
<div class="line">interface Service {</div>
<div class="line-block">
<div class="line">command void start();</div>
<div class="line">command void stop();</div>
<div class="line">command bool isRunning();</div>
</div>
<div class="line">}</div>
</div>
<p>while a notifier abstraction provides the <tt class="docutils literal"><span class="pre">ServiceNotify</span></tt> interface</p>
<div class="line-block">
<div class="line">interface ServiceNotify {</div>
<div class="line-block">
<div class="line">event void started();</div>
<div class="line">event void stopped();</div>
</div>
<div class="line">}</div>
</div>
<p>For example, if a routing layer wants to be able to turn the active
message layer on and off, then it needs to instantiate an AMServiceC.
However, many components may be using active messages and have their
own instances of AMServiceC; while routing might consider it
acceptable to turn off active messages, other components might
not. Therefore, a service abstraction does not necessarily represent
explicit control; instead, each service has a <em>policy</em> for how it
deals with control requests. When a service changes its activity
state, it MUST signal all instances of its ServiceNotifierC.</p>
<p>For example, the active messages service has an "OR" policy; the
service remains active if <em>any</em> of its ServiceC instances are in the
on state, and goes inactive if and only if <em>all</em> of its ServiceC
instances are in the off state. This is an example timeline for
active messages being used by two components, RouterA and RouterB:</p>
<ol class="arabic simple">
<li>System boots: active messages are off.</li>
<li>RouterA calls <tt class="docutils literal"><span class="pre">Service.start()</span></tt>. The AM layer is turned on.</li>
<li>All AMServiceNotifierC abstractions signal <tt class="docutils literal"><span class="pre">ServiceNotify.started().</span></tt></li>
<li>RouterB calls <tt class="docutils literal"><span class="pre">Service.start()</span></tt>.</li>
<li>RouterA calls <tt class="docutils literal"><span class="pre">Service.stop()</span></tt>. RouterB is still using active messages, so the layer stays on.</li>
<li>RouterB calls <tt class="docutils literal"><span class="pre">Service.stop()</span></tt>. The AM layer is turned off.</li>
<li>All AMServiceNotifierC abstractions signal <tt class="docutils literal"><span class="pre">ServiceNotify.stopped().</span></tt></li>
</ol>
<p>By default, a service that has a control interface MUST be off. For an
application to use the service, at least one component has to call
<tt class="docutils literal"><span class="pre">Service.start()</span></tt>.</p>
</div>
<div class="section" id="service-initialization">
<h2><a name="service-initialization">2.2 Service Initialization</a></h2>
<p>Because distributions are collections of services that are designed to
work together, they can avoid many of the common issues that arise
when composing TinyOS programs. For example, user code does not have
to initialize a service; this is done automatically by the
distribution. If a user component instantiates a service abstraction,
the distribution MUST make sure that the service is properly
initialized. Section 4 goes into an example implementation of how a
distribution can achieve this.</p>
</div>
</div>
<div class="section" id="oski-services">
<h1><a name="oski-services">3. OSKI Services</a></h1>
<p>This section briefly describes the services that OSKI, an example
distribution provides. It is intended to give a feel for how a
distribution presents its abstractions.</p>
<div class="section" id="timers">
<h2><a name="timers">3.1 Timers</a></h2>
<p>OSKI provides timers at one fidelity: milliseconds. Timers do not have
a Service abstraction, as their use implicitly defines whether the
service is active or not (the timer service is off if there are no
pending timers). The <tt class="docutils literal"><span class="pre">OSKITimerMsC</span></tt> component provides the
abstraction: it provides a single interface, <tt class="docutils literal"><span class="pre">Timer<TMilli></span></tt>.</p>
<p>This is an example code snippet for instantiating a timer in a
configuration:</p>
<div class="line-block">
<div class="line">configuration ExampleC {</div>
<div class="line-block">
<div class="line">uses interface Timer<TMilli>;</div>
</div>
<div class="line">}</div>
<div class="line"><br /></div>
<div class="line">configuration TimerExample {}</div>
<div class="line">implementation {</div>
<div class="line-block">
<div class="line">components ExampleC, new OSKITimerMsC() as T;</div>
<div class="line">ExampleC.Timer -> T;</div>
</div>
<div class="line">}</div>
</div>
</div>
<div class="section" id="active-messages">
<h2><a name="active-messages">3.2 Active Messages</a></h2>
<p>OSKI provides four functional active messaging abstractions:
<tt class="docutils literal"><span class="pre">AMSender</span></tt>, <tt class="docutils literal"><span class="pre">AMReceiver</span></tt>, <tt class="docutils literal"><span class="pre">AMSnooper</span></tt>, and
<tt class="docutils literal"><span class="pre">AMSnoopingReceiver</span></tt>. Each one takes an <tt class="docutils literal"><span class="pre">am_id_t</span></tt> as a parameter,
indicating the AM type. Following the general TinyOS 2.x approach to
networking, all active message abstractions provide the <tt class="docutils literal"><span class="pre">Packet</span></tt> and
<tt class="docutils literal"><span class="pre">AMPacket</span></tt> interfaces.</p>
<dl class="docutils">
<dt>AMSender</dt>
<dd>This abstraction is for sending active messages. In addition to Packet
and AMPacket, it provides the AMSend interface.</dd>
<dt>AMReceiver</dt>
<dd>This abstraction is for receiving active messages addressed to the
node or to the broadcast address. In addition to Packet and AMPacket,
it provides the Receive interface.</dd>
<dt>AMSnooper</dt>
<dd>This abstraction is for receiving active messages addressed to other
nodes ("snooping" on traffic). In addition to Packet and AMPacket,
it provides the Receive interface.</dd>
<dt>AMSnoopingReceiver</dt>
<dd>A union of the functionality of AMReceiver and AMSnooper, this
abstraction allows a component to receive <em>all</em> active messages
that it hears. The AMPacket interface allows a component to determine
whether such a message is destined for it. In addition to
Packet and AMPacket, this component provides the Receive interface.</dd>
</dl>
<p>This snippet of code is an example of a configuration that composes a
routing layer with needed active message abstractions. This
implementation snoops on data packets sent by other nodes to improve
its topology formation:</p>
<div class="line-block">
<div class="line">configuration RouterC {</div>
<div class="line-block">
<div class="line">uses interface AMSend as DataSend;</div>
<div class="line">uses interface AMSend as ControlSend;</div>
<div class="line">uses interface Receive as DataReceive;</div>
<div class="line">uses interface Receive as BeaconReceive;</div>
</div>
<div class="line">}</div>
<div class="line"><br /></div>
<div class="line">configuration RoutingExample {</div>
<div class="line-block">
<div class="line">components RouterC;</div>
<div class="line">components new AMSender(5) as CSender;</div>
<div class="line">components new AMSender(6) as DSender;</div>
<div class="line">components new AMReceiver(5) as CReceiver;</div>
<div class="line">components new AMSnoopingReceiver(6) as DReceiver;</div>
<div class="line"><br /></div>
<div class="line">RouterC.DataSend -> DSender;</div>
<div class="line">RouterC.ControlSend -> CSender;</div>
<div class="line">RouterC.DataReceive -> DReceiver;</div>
<div class="line">RouterC.ControlReceive -> CReceiver;</div>
</div>
<div class="line">}</div>
</div>
<p>The active messages layer has control abstractions, named <tt class="docutils literal"><span class="pre">AMServiceC</span></tt>
and <tt class="docutils literal"><span class="pre">AMServiceNotifierC</span></tt>. Active messages follow an OR policy.</p>
</div>
<div class="section" id="broadcasts">
<h2><a name="broadcasts">3.3 Broadcasts</a></h2>
<p>In addition to active messages, OSKI provides a broadcasting service.
Unlike active messages, which are addressed in terms of AM addresses,
broadcasts are address-free. Broadcast communication has two
abstractions: <tt class="docutils literal"><span class="pre">BroadcastSenderC</span></tt> and <tt class="docutils literal"><span class="pre">BroadcastReceiverC</span></tt>, both of
which take a parameter, a broadcast message type. This parameter is
similar to the AM type in active messages. Both abstractions provide
the Packet interface. The broadcast service has control abstractions,
named <tt class="docutils literal"><span class="pre">BroadcastServiceC</span></tt> and <tt class="docutils literal"><span class="pre">BroadcastServiceNotifierC</span></tt>, which
follow an OR policy.</p>
</div>
<div class="section" id="tree-collection-convergecast">
<h2><a name="tree-collection-convergecast">3.4 Tree Collection/Convergecast</a></h2>
<p><a href="#id1" name="id2"><span class="problematic" id="id2">**</span></a>NOTE: These services are not supported as of the 2.x prerelease.
They will be supported by the first full release.*</p>
<div class="system-message" id="id1">
<p class="system-message-title">System Message: <a name="id1">WARNING/2</a> (<tt class="docutils">txt/tep110.txt</tt>, line 249); <em><a href="#id2">backlink</a></em></p>
Inline strong start-string without end-string.</div>
<p>OSKI's third communication service is tree-based collection routing.
This service has four abstractions:</p>
<dl class="docutils">
<dt>CollectionSenderC</dt>
<dd>This abstraction is for sending packets up the collection tree,
to the collection root. It provides the Send and Packet interfaces.</dd>
<dt>CollectionReceiverC</dt>
<dd>This abstraction is for a collection end-point (a tree root). It
provides the Receive, Packet, and CollectionPacket interfaces.</dd>
<dt>CollectionInterceptorC</dt>
<dd>This abstraction represents a node's ability to view and possibly
suppress packets it has received for forwarding. It provides
the Intercept, CollectionPacket, and Packet interfaces.</dd>
<dt>CollectionSnooperC</dt>
<dd>This abstraction allows a node to overhear routing packets
sent to other nodes to forward. It provides the Receive,
CollectionPacket, and Packet interfaces.</dd>
</dl>
<p>All of the collection routing communication abstractions take a
parameter, similar to active messages and broadcasts, so multiple
components can independelty use collection routing. In addition to
communication, collection routing has an additional abstraction:</p>
<dl class="docutils">
<dt>CollectionControlC</dt>
<dd>This abstraction controls whether a node is a collection root
or not.</dd>
</dl>
<p>Finally, collection routing has <tt class="docutils literal"><span class="pre">CollectionServiceC</span></tt> and
<tt class="docutils literal"><span class="pre">CollectionServiceNotifierC</span></tt> abstractions, which follow an OR
policy.</p>
</div>
<div class="section" id="uart">
<h2><a name="uart">3.5 UART</a></h2>
<p><strong>NOTE: These services are not supported as of the 2.x prerelease.
They will be supported by the first full release.
They will be fully defined pending discussion/codification of
UART interfaces.</strong></p>
</div>
</div>
<div class="section" id="oski-service-structure-and-design">
<h1><a name="oski-service-structure-and-design">4. OSKI Service Structure and Design</a></h1>
<p>Presenting services through abstractions hides the underlying wiring
details and gives a distribution a great deal of implementation
freedom. One issue that arises, however, is initialization. If a user
component instantiates a service, then a distribution MUST make sure
the service is initialized properly. OSKI achieves this by
encapsulating a complete service as a working component; abstractions
export the service's interfaces.</p>
<div class="section" id="example-timers">
<h2><a name="example-timers">4.1 Example: Timers</a></h2>
<p>For example, the timer service provides a single abstraction,
OskiTimerMilliC, which is a generic component. OskiTimerMilliC provides a
single instance of the Timer<TMilli> interface. It is implemented as a
wrapper around the underlying timer service, a component named
<tt class="docutils literal"><span class="pre">TimerMilliImplP</span></tt>, which provides a parameterized interface and
follows the Service Instance design pattern[sipattern]_:</p>
<div class="line-block">
<div class="line">generic configuration OskiTimerMilliC() {</div>
<div class="line-block">
<div class="line">provides interface Timer<TMilli>;</div>
</div>
<div class="line">}</div>
<div class="line">implementation {</div>
<div class="line-block">
<div class="line">components TimerMilliImplP;</div>
<div class="line">Timer = TimerMilliImplP.TimerMilli[unique("TimerMilliC.TimerMilli")];</div>
</div>
<div class="line">}</div>
</div>
<p>TimerMilliImplP is a fully composed and working service. It takes
a platform's timer implementation and makes sure it is initialized through
the TinyOS boot sequence[boot]_:</p>
<div class="line-block">
<div class="line">configuration TimerMilliImplP {</div>
<div class="line-block">
<div class="line">provides interface Timer<TMilli> as TimerMilli[uint8_t id];</div>
</div>
<div class="line">}</div>
<div class="line">implementation {</div>
<div class="line-block">
<div class="line">components TimerMilliC, Main;</div>
<div class="line">Main.SoftwareInit -> TimerMilliC;</div>
<div class="line">TimerMilli = TimerMilliC;</div>
</div>
<div class="line">}</div>
</div>
<p>This composition means that if any component instantiates a timer,
then TimerMilliImplP will be included in the component graph. If
TimerMilliImplP is included, the TimerMilliP (the actual platform HIL
implementation) will be properly initialized at system boot time. In
this case, the order of initialization isn't important; in cases where
there are services that have to be initialized in a particular
sequence to ensure proper ordering, the Impl components can
orchestrate that order. For example, a distribution can wire
Main.SoftwareInit to a DistributionInit component, which calls
sub-Inits in a certain order; when a service is included, it wires
itself to one of the sub-Inits.</p>
<p>The user does not have to worry about unique strings to manage the
underlying Service Instance pattern: the abstractions take care of
that.</p>
</div>
<div class="section" id="example-active-messages">
<h2><a name="example-active-messages">4.2 Example: Active Messages</a></h2>
<p>Active messaging reprsent a slightly more complex service, as it has
several abstractions and a control interface. However, it follows the
same basic pattern: abstractions are generics that export wirings to
the underlying service, named <tt class="docutils literal"><span class="pre">ActiveMessageImplP</span></tt>:</p>
<div class="line-block">
<div class="line">configuration ActiveMessageImplP {</div>
<div class="line-block">
<div class="line">provides {</div>
<div class="line-block">
<div class="line">interface SplitControl; </div>
<div class="line">interface AMSend[am_id_t id];</div>
<div class="line">interface Receive[am_id_t id];</div>
<div class="line">interface Receive as Snoop[am_id_t id];</div>
<div class="line">interface Packet;</div>
<div class="line">interface AMPacket;</div>
</div>
<div class="line">}</div>
</div>
<div class="line">}</div>
<div class="line"><br /></div>
<div class="line">implementation {</div>
<div class="line-block">
<div class="line">components ActiveMessageC, Main;</div>
<div class="line"><br /></div>
<div class="line">Main.SoftwareInit -> ActiveMessageC;</div>
<div class="line"><br /></div>
<div class="line">SplitControl = ActiveMessageC;</div>
<div class="line">AMSend = ActiveMessageC;</div>
<div class="line">Receive = ActiveMessageC.Receive;</div>
<div class="line">Snoop = ActiveMessageC.Snoop;</div>
<div class="line">Packet = ActiveMessageC;</div>
<div class="line">AMPacket = ActiveMessageC;</div>
</div>
<div class="line">}</div>
</div>
<p>For example, this is the AMSender abstraction:</p>
<div class="line-block">
<div class="line">generic configuration AMSenderC(am_id_t AMId) {</div>
<div class="line-block">
<div class="line">provides {</div>
<div class="line-block">
<div class="line">interface AMSend;</div>
<div class="line">interface Packet;</div>
<div class="line">interface AMPacket;</div>
</div>
<div class="line">}</div>
</div>
<div class="line">}</div>
<div class="line"><br /></div>
<div class="line">implementation {</div>
<div class="line-block">
<div class="line">components ActiveMessageImplP as Impl;</div>
<div class="line"><br /></div>
<div class="line">AMSend = Impl.AMSend[AMId];</div>
<div class="line">Packet = Impl;</div>
<div class="line">AMPacket = Impl;</div>
</div>
<div class="line">}</div>
</div>
<p>AMReceiver is similar, except that it wires to the Receive interface,
while AMSnooper wires to the Snoop interface, and AMSnoopingReceiver
provides a single Receive that exports both Snoop and Receive (the
unidirectional nature of the Receive interface makes this simple to
achieve, as it represents only fan-in and no fan-out).</p>
<p>ActiveMessageImplP does not provide a Service interface; it provides
the SplitControl interface of the underlying active message
layer. OSKI layers a <em>ServiceController</em> on top of SplitControl. As
the active message service follows an OR policy, OSKI uses a
<tt class="docutils literal"><span class="pre">ServiceOrControllerM</span></tt>, which is a generic component with the
following signature:</p>
<div class="line-block">
<div class="line">generic module ServiceOrControllerM(char strID[]) {</div>
<div class="line-block">
<div class="line">provides {</div>
<div class="line-block">
<div class="line">interface Service[uint8_t id];</div>
<div class="line">interface ServiceNotify;</div>
</div>
<div class="line">}</div>
<div class="line">uses {</div>
<div class="line-block">
<div class="line">interface SplitControl;</div>
</div>
<div class="line">}</div>
</div>
<div class="line">}</div>
</div>
<p>ServiceOrControllerM follows the Service Instance pattern[sipattern];
it calls its underlying SplitControl based on the state of each of its
instances of the Service interface. The parameter denotes the string
used to generate the unique service IDs. The active messages service
controller implementation, AMServiceImplP, instantiates a
ServiceOrControllerM, wires it to ActiveMessageImplP:</p>
<div class="line-block">
<div class="line">configuration AMServiceImplP {</div>
<div class="line-block">
<div class="line">provides interface Service[uint8_t id];</div>
<div class="line">provides interface ServiceNotify;</div>
</div>
<div class="line">}</div>
<div class="line">implementation {</div>
<div class="line-block">
<div class="line">components ActiveMessageImplP;</div>
<div class="line">components new ServiceOrControllerM("AMServiceImplP.Service");</div>
<div class="line"><br /></div>
<div class="line">Service = ServiceOrControllerM;</div>
<div class="line">ServiceOrControllerM.SplitControl -> ActiveMessageImplP;</div>
<div class="line">ServiceNotify = ServiceOrControllerM;</div>
</div>
<div class="line">}</div>
</div>
<p>AMServiceC then provides an instance of AMServiceImplP.Service:</p>
<div class="line-block">
<div class="line">generic configuration AMServiceC() {</div>
<div class="line-block">
<div class="line">provides interface Service;</div>
</div>
<div class="line">}</div>
<div class="line"><br /></div>
<div class="line">implementation {</div>
<div class="line-block">
<div class="line">components AMServiceImplP;</div>
<div class="line"><br /></div>
<div class="line">Service = AMServiceImplP.Service[unique("AMServiceImplP.Service")];</div>
</div>
</div>
<div class="system-message">
<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep110.txt</tt>, line 457)</p>
Line block ends without a blank line.</div>
<p><a href="#id3" name="id4"><span class="problematic" id="id4">|</span></a>}</p>
<div class="system-message" id="id3">
<p class="system-message-title">System Message: <a name="id3">WARNING/2</a> (<tt class="docutils">txt/tep110.txt</tt>, line 457); <em><a href="#id4">backlink</a></em></p>
Inline substitution_reference start-string without end-string.</div>
<p>Note that the two strings are the same, so that the uniqueCount() in
the ServiceOrControllerM is correct based on the number of instances
of AMServiceC. As with timers, encapsulating the service instance
pattern in generic components relieves the programmer of having to
deal with unique strings, a common source of bugs in TinyOS 1.x code.</p>
</div>
<div class="section" id="oski-requirements">
<h2><a name="oski-requirements">4.3 OSKI Requirements</a></h2>
<p>OSKI is a layer on top of system components: it presents a more
usable, less error-prone, and simpler interface to common TinyOS
functionality. For OSKI to work properly, a platform MUST be compliant
with the following TEPs:</p>
<blockquote>
o TEP 102: Timers
o TEP 106: Schedulers and Tasks
o TEP 107: TinyOS 2.x Boot Sequence
o TEP 1XX: Active Messages
o TEP 1XX: Collection Routing</blockquote>
<p>Not following some of these TEPS MAY lead to OSKI services being
inoperable, exhibit strange behavior, or being uncompilable.</p>
</div>
</div>
<div class="section" id="distribution-interfaces">
<h1><a name="distribution-interfaces">5. Distribution Interfaces</a></h1>
<p>The basic notion of a distribution is that it provides a self-contained,
tested, and complete (for an application domain) programming interface
to TinyOS. Layers can be added on top of a distribution, but as a
distribution is a self-contained set of abstractions, adding new
services can lead to failures. A distribution represents a hard line
above which all other code operates. One SHOULD NOT add new services,
as they can disrupt the underlying organization. Of course, one MAY
create a new distribution that extends an existing one, but this is
in and of itself a new distribution.</p>
<p>Generally, as distributions are intended to be higher-level abstractions,
they SHOULD NOT provide any asynchronous (async) events. They can,
of course, provide async commands. The idea is that no code written on
top of a distribution should be asynchronous, due to the complexity
introduced by having to manage concurrency. Distributions are usually
platform independent; if an application needs async events, then
chances are it is operating close to the hardware, and so is not
platform independent.</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">467 Soda Hall</div>
<div class="line">UC Berkeley</div>
<div class="line">Berkeley, CA 94720</div>
<div class="line"><br /></div>
<div class="line">phone - +1 510 290 5283</div>
<div class="line"><br /></div>
<div class="line">email - <a class="reference" href="mailto:pal@cs.berkeley.edu">pal@cs.berkeley.edu</a></div>
</div>
</div>
<div class="section" id="citations">
<h1><a name="citations">7. Citations</a></h1>
<table class="docutils citation" frame="void" id="rst" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a name="rst">[rst]</a></td><td>reStructuredText Markup Specification. <<a class="reference" href="http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html">http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html</a>></td></tr>
</tbody>
</table>
<table class="docutils citation" frame="void" id="sipattern" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a name="sipattern">[sipattern]</a></td><td>The Service Instance Pattern. In <em>Software Design Patterns for TinyOS.</em> David Gay, Philip Levis, and David Culler. Published in Proceedings of the ACM SIGPLAN/SIGBED 2005 Conference on Languages, Compilers, and Tools for Embedded Systems (LCTES'05).</td></tr>
</tbody>
</table>
<table class="docutils citation" frame="void" id="boot" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a name="boot">[boot]</a></td><td>TEP 107: TinyOS 2.x Boot Sequence.</td></tr>
</tbody>
</table>
</div>
</div>
</body>
</html>
--- NEW FILE: tep111.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.3.9: http://docutils.sourceforge.net/" />
<title>message_t</title>
<meta name="author" content="Philip Levis" />
<style type="text/css">
/*
:Author: David Goodger
:Contact: goodger at users.sourceforge.net
:date: $Date: 2005/09/20 16:30:23 $
: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 }
/* Uncomment (& remove this text!) to get bold-faced definition list terms
dt {
font-weight: bold }
*/
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 {
background-color: #eeeeee }
ul.auto-toc {
list-style-type: none }
</style>
</head>
<body>
<div class="document" id="message-t">
<h1 class="title">message_t</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">111</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>Philip Levis</td></tr>
<tr class="field"><th class="docinfo-name">Draft-Created:</th><td class="field-body">11-Jul-2005</td>
</tr>
<tr class="field"><th class="docinfo-name">Draft-Version:</th><td class="field-body">1.1</td>
</tr>
<tr class="field"><th class="docinfo-name">Draft-Modified:</th><td class="field-body">2005-08-13</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" id="abstract">
<h1><a name="abstract">Abstract</a></h1>
<p>This memo covers the TinyOS 2.x message buffer abstraction, <tt class="docutils literal"><span class="pre">message_t</span></tt>.
It describes the message buffer design considerations, how and where
<tt class="docutils literal"><span class="pre">message_t</span></tt> is specified, and how data link layers should access it.</p>
</div>
<div class="section" id="introduction">
<h1><a name="introduction">1. Introduction</a></h1>
<p>In TinyOS 1.x, a message buffer is a TOS_Msg. A buffer contains an
active message (AM) packet as well as packet metadata, such as timestamps,
acknowledgement bits, and signal strength if the packet was received.
TOS_Msg is a fixed size structure whose size is defined by the maximum
AM payload length (the default is 29 bytes). Fixed sized buffers allows
TinyOS 1.x to have zero-copy semantics: when a component receives a
buffer, rather than copy out the contents it can return a pointer
to a new buffer for the underlying layer to use for the next received
packet.</p>
<p>One issue that arises is what defines the TOS_Msg structure, as different
link layers may require different layouts. For example, 802.15.4 radio
hardware (such as the CC2420, used in the Telos and micaZ platforms)
may require 802.15.4 headers, while a software stack built on top of
byte radios (such as the CC1000, used in the mica2 platform) can specify
its own packet format. This means that TOS_Msg may be different on
different platforms.</p>
<p>The solution to this problem in TinyOS 1.x is for there to be a standard
definition of TOS_Msg, which a platform (e.g., the micaZ) can
redefine to match its radio. For example, a mica2 mote uses the standard
definition, which is</p>
<div class="line-block">
<div class="line"><tt class="docutils literal"><span class="pre">typedef</span> <span class="pre">struct</span> <span class="pre">TOS_Msg</span> <span class="pre">{</span></tt></div>
<div class="line">`` /* The following fields are transmitted/received on the radio. <a href="#id1" name="id2"><span class="problematic" id="id2">*</span></a>/``</div>
<div class="line">`` uint16_t addr;``</div>
<div class="line">`` uint8_t type;``</div>
<div class="line">`` uint8_t group;``</div>
<div class="line">`` uint8_t length;``</div>
<div class="line">`` int8_t data[TOSH_DATA_LENGTH];``</div>
<div class="line">`` uint16_t crc;``</div>
<div class="line"><br /></div>
<div class="line">`` /* The following fields are not actually transmitted or received ``</div>
<div class="line">`` * on the radio! They are used for internal accounting only.``</div>
<div class="line">`` * The reason they are in this structure is that the AM interface``</div>
<div class="line">`` * requires them to be part of the TOS_Msg that is passed to``</div>
<div class="line">`` * send/receive operations.``</div>
<div class="line">`` <a href="#id3" name="id4"><span class="problematic" id="id4">*</span></a>/``</div>
<div class="line">`` uint16_t strength;``</div>
<div class="line">`` uint8_t ack;``</div>
<div class="line">`` uint16_t time;``</div>
<div class="line">`` uint8_t sendSecurityMode;``</div>
<div class="line">`` uint8_t receiveSecurityMode;``</div>
<div class="line"><tt class="docutils literal"><span class="pre">}</span> <span class="pre">TOS_Msg;</span></tt></div>
</div>
<div class="system-message" id="id1">
<p class="system-message-title">System Message: <a name="id1">WARNING/2</a> (<tt class="docutils">txt/tep111.txt</tt>, line 58); <em><a href="#id2">backlink</a></em></p>
Inline emphasis start-string without end-string.</div>
<div class="system-message" id="id3">
<p class="system-message-title">System Message: <a name="id3">WARNING/2</a> (<tt class="docutils">txt/tep111.txt</tt>, line 71); <em><a href="#id4">backlink</a></em></p>
Inline emphasis start-string without end-string.</div>
<p>while on a mote with a CC420 radio (e.g., micaZ), TOS_Msg is defined as:</p>
<div class="line-block">
<div class="line"><tt class="docutils literal"><span class="pre">typedef</span> <span class="pre">struct</span> <span class="pre">TOS_Msg</span> <span class="pre">{</span></tt></div>
<div class="line">`` /* The following fields are transmitted/received on the radio. <a href="#id5" name="id6"><span class="problematic" id="id6">*</span></a>/``</div>
<div class="line">`` uint8_t length;``</div>
<div class="line">`` uint8_t fcfhi;``</div>
<div class="line">`` uint8_t fcflo;``</div>
<div class="line">`` uint8_t dsn;``</div>
<div class="line">`` uint16_t destpan;``</div>
<div class="line">`` uint16_t addr;``</div>
<div class="line">`` uint8_t type;``</div>
<div class="line">`` uint8_t group;``</div>
<div class="line">`` int8_t data[TOSH_DATA_LENGTH];``</div>
<div class="line"><a href="#id7" name="id8"><span class="problematic" id="id8">``</span></a><a href="#id9" name="id10"><span class="problematic" id="id10">``</span></a></div>
<div class="line">`` /* The following fields are not actually transmitted or received ``</div>
<div class="line">`` * on the radio! They are used for internal accounting only.``</div>
<div class="line">`` * The reason they are in this structure is that the AM interface``</div>
<div class="line">`` * requires them to be part of the TOS_Msg that is passed to``</div>
<div class="line">`` * send/receive operations.``</div>
<div class="line">`` <a href="#id11" name="id12"><span class="problematic" id="id12">*</span></a>/``</div>
<div class="line">`` uint8_t strength;``</div>
<div class="line">`` uint8_t lqi;``</div>
<div class="line">`` bool crc;``</div>
<div class="line">`` uint8_t ack;``</div>
<div class="line">`` uint16_t time;``</div>
<div class="line"><tt class="docutils literal"><span class="pre">}</span> <span class="pre">TOS_Msg;</span></tt></div>
</div>
<div class="system-message" id="id5">
<p class="system-message-title">System Message: <a name="id5">WARNING/2</a> (<tt class="docutils">txt/tep111.txt</tt>, line 82); <em><a href="#id6">backlink</a></em></p>
Inline emphasis start-string without end-string.</div>
<div class="system-message" id="id7">
<p class="system-message-title">System Message: <a name="id7">WARNING/2</a> (<tt class="docutils">txt/tep111.txt</tt>, line 92); <em><a href="#id8">backlink</a></em></p>
Inline literal start-string without end-string.</div>
<div class="system-message" id="id9">
<p class="system-message-title">System Message: <a name="id9">WARNING/2</a> (<tt class="docutils">txt/tep111.txt</tt>, line 92); <em><a href="#id10">backlink</a></em></p>
Inline literal start-string without end-string.</div>
<div class="system-message" id="id11">
<p class="system-message-title">System Message: <a name="id11">WARNING/2</a> (<tt class="docutils">txt/tep111.txt</tt>, line 98); <em><a href="#id12">backlink</a></em></p>
Inline emphasis start-string without end-string.</div>
<p>There are two basic problems with this approach. First, exposing all of
the link layer fields leads components to directly access the packet
structure. This introduces dependencies between higher level components
and the structure layout. For example, many network services built on
top of data link layers care whether sent packets are acknowledged. They
therefore check the <tt class="docutils literal"><span class="pre">ack</span></tt> field of TOS_Msg. If a link layer does not
provide acknowledgements, it must still include the <tt class="docutils literal"><span class="pre">ack</span></tt> field
and always set it to 0, wasting a byte of RAM per buffer.</p>
<p>Second, this model does not easily support multiple data link layers.
Radio chip implementations assume that the fields they require are
defined in the structure and directly access them. If a platform
has two different link layers (e.g., a CC1000 <em>and</em> a CC2420 radio),
then a TOS_Msg needs to allocate the right amount of space for both
of their headers while allowing implementations to directly access
header fields. This is very difficult to do in C.</p>
<p>The <tt class="docutils literal"><span class="pre">data</span></tt> payload is especially problematic. Many
components refer to this field, so it must be at a fixed offset.
Depending on the underlying link layer, the header fields
preceding it might have different lengths, and packet-level radios
often require packets to be contiguous memory regions. Overall, these
complexities make specifying the format of TOS_Msg very difficult.</p>
</div>
<div class="section" id="id13">
<h1><a name="id13">2. message_t</a></h1>
<p>In TinyOS 2.x, the standard message buffer is <tt class="docutils literal"><span class="pre">message_t</span></tt>. The
message_t structure is defined in <tt class="docutils literal"><span class="pre">tos/types/TOSMsg.h</span></tt>:</p>
<div class="line-block">
<div class="line"><tt class="docutils literal"><span class="pre">typedef</span> <span class="pre">nx_struct</span> <span class="pre">message_t</span> <span class="pre">{</span></tt></div>
<div class="line">`` TOSRadioHeader header;``</div>
<div class="line">`` nx_uint8_t data[TOSH_DATA_LENGTH];``</div>
<div class="line">`` TOSRadioFooter footer;``</div>
<div class="line">`` TOSRadioMetadata metadata;``</div>
<div class="line"><tt class="docutils literal"><span class="pre">}</span> <span class="pre">message_t;</span></tt></div>
</div>
<p>This format keeps data at a fixed offset, which is important when
passing a message buffer between two different link layers. If
the data payload is at different offsets for different link layers,
then passing a packet between two link layers requires a <tt class="docutils literal"><span class="pre">memmove(3)</span></tt>
operation (essentially, a copy).</p>
<p>The header, footer, and metadata fields are all opaque. Higher
level components access their fields through interfaces. Section
3 discusses this in greater depth.</p>
<p>Every link layer defines its header, footer, and metadata
structures. For example, the CC1000 radio implementation defines its
structures in <tt class="docutils literal"><span class="pre">CC1000Msg.h</span></tt>:</p>
<div class="line-block">
<div class="line"><tt class="docutils literal"><span class="pre">typedef</span> <span class="pre">nx_struct</span> <span class="pre">CC1KHeader</span> <span class="pre">{</span></tt></div>
<div class="line">`` nx_am_addr_t addr;``</div>
<div class="line">`` nx_uint8_t length;``</div>
<div class="line">`` nx_am_group_t group;``</div>
<div class="line">`` nx_am_id_t type;``</div>
<div class="line"><tt class="docutils literal"><span class="pre">}</span> <span class="pre">CC1KHeader;</span></tt></div>
<div class="line"><a href="#id14" name="id15"><span class="problematic" id="id15">``</span></a><a href="#id16" name="id17"><span class="problematic" id="id17">``</span></a></div>
<div class="line"><tt class="docutils literal"><span class="pre">typedef</span> <span class="pre">nx_struct</span> <span class="pre">CC1KFooter</span> <span class="pre">{</span></tt></div>
<div class="line">`` nxle_uint16_t crc; ``</div>
<div class="line"><tt class="docutils literal"><span class="pre">}</span> <span class="pre">CC1KFooter;</span></tt></div>
<div class="line"><a href="#id18" name="id19"><span class="problematic" id="id19">``</span></a><a href="#id20" name="id21"><span class="problematic" id="id21">``</span></a></div>
<div class="line"><tt class="docutils literal"><span class="pre">typedef</span> <span class="pre">nx_struct</span> <span class="pre">CC1KMetadata</span> <span class="pre">{</span></tt></div>
<div class="line">`` nx_uint16_t strength;``</div>
<div class="line">`` nx_uint8_t ack;``</div>
<div class="line">`` nx_uint16_t time;``</div>
<div class="line">`` nx_uint8_t sendSecurityMode;``</div>
<div class="line">`` nx_uint8_t receiveSecurityMode; ``</div>
<div class="line"><tt class="docutils literal"><span class="pre">}</span> <span class="pre">CC1KMetadata;</span></tt></div>
</div>
<div class="system-message" id="id14">
<p class="system-message-title">System Message: <a name="id14">WARNING/2</a> (<tt class="docutils">txt/tep111.txt</tt>, line 163); <em><a href="#id15">backlink</a></em></p>
Inline literal start-string without end-string.</div>
<div class="system-message" id="id16">
<p class="system-message-title">System Message: <a name="id16">WARNING/2</a> (<tt class="docutils">txt/tep111.txt</tt>, line 163); <em><a href="#id17">backlink</a></em></p>
Inline literal start-string without end-string.</div>
<div class="system-message" id="id18">
<p class="system-message-title">System Message: <a name="id18">WARNING/2</a> (<tt class="docutils">txt/tep111.txt</tt>, line 167); <em><a href="#id19">backlink</a></em></p>
Inline literal start-string without end-string.</div>
<div class="system-message" id="id20">
<p class="system-message-title">System Message: <a name="id20">WARNING/2</a> (<tt class="docutils">txt/tep111.txt</tt>, line 167); <em><a href="#id21">backlink</a></em></p>
Inline literal start-string without end-string.</div>
<p>Each link layer defines its structres, but a <strong>platform</strong> is responsible
for defining <tt class="docutils literal"><span class="pre">TOSRadioHeader</span></tt>, <tt class="docutils literal"><span class="pre">TOSRadioFooter</span></tt>, and <tt class="docutils literal"><span class="pre">TOSRadioMetadata</span></tt>.
This is because a platform may have multiple link layers, and so only
it can resolve which structures are needed. These definitions MUST be
in a file in a platform directory named <tt class="docutils literal"><span class="pre">RadioTOSMsg.h</span></tt>.
The mica2 platform is a simple example, as it has only a CC1000 radio.
Its RadioTOSMsg.h looks like this:</p>
<div class="line-block">
<div class="line"><tt class="docutils literal"><span class="pre">typedef</span> <span class="pre">CC1KHeader</span> <span class="pre">TOSRadioHeader;</span></tt></div>
<div class="line"><tt class="docutils literal"><span class="pre">typedef</span> <span class="pre">CC1KFooter</span> <span class="pre">TOSRadioFooter;</span></tt></div>
<div class="line"><tt class="docutils literal"><span class="pre">typedef</span> <span class="pre">CC1KMetadata</span> <span class="pre">TOSRadioMetadata;</span></tt></div>
</div>
<p>For a more complex example, consider a fictional platform named 'megamica'
that has both a CC1000 and a CC2420 radio. Its RadioTOSMsg.h looks like this:</p>
<div class="line-block">
<div class="line"><tt class="docutils literal"><span class="pre">typedef</span> <span class="pre">union</span> <span class="pre">MegaMicaHeader</span> <span class="pre">{</span></tt></div>
<div class="line">`` CC1KHeader cc1k;``</div>
<div class="line">`` CC2420Header cc2420;``</div>
<div class="line"><tt class="docutils literal"><span class="pre">}</span> <span class="pre">MegaMicaHeader;</span></tt></div>
<div class="line"><br /></div>
<div class="line"><tt class="docutils literal"><span class="pre">typedef</span> <span class="pre">union</span> <span class="pre">MegaMicaFooter</span> <span class="pre">{</span></tt></div>
<div class="line">`` CC1KFooter cc1k;``</div>
<div class="line">`` CC2420Footer cc2420;``</div>
<div class="line"><tt class="docutils literal"><span class="pre">}</span> <span class="pre">MegaMicaFooter;</span></tt></div>
<div class="line"><br /></div>
<div class="line"><tt class="docutils literal"><span class="pre">typedef</span> <span class="pre">union</span> <span class="pre">MegaMicaMetadata</span> <span class="pre">{</span></tt></div>
<div class="line">`` CC1KMetadata cc1k;``</div>
<div class="line">`` CC2420Metadata cc2420;``</div>
<div class="line"><tt class="docutils literal"><span class="pre">}</span> <span class="pre">MegaMicaMetadata;</span></tt></div>
<div class="line"><br /></div>
<div class="line"><tt class="docutils literal"><span class="pre">typedef</span> <span class="pre">MegaMicaHeader</span> <span class="pre">TOSRadioHeader;</span></tt></div>
<div class="line"><tt class="docutils literal"><span class="pre">typedef</span> <span class="pre">MegaMicaFooter</span> <span class="pre">TOSRadioFooter;</span></tt></div>
<div class="line"><tt class="docutils literal"><span class="pre">typedef</span> <span class="pre">MegaMicaMetadata</span> <span class="pre">TOSRadioMetadata;</span></tt></div>
</div>
<p>If a platform has more than one link layer, it SHOULD define each of the
message_t fields to be a union of the underlying link layer structures.
This ensures that enough space is allocated for all underlying link layers.</p>
</div>
<div class="section" id="accessing-message-t-fields">
<h1><a name="accessing-message-t-fields">3. Accessing message_t fields</a></h1>
<p>A TinyOS component MUST NOT access any message_t fields directly besides
its top-level structures:</p>
<blockquote>
o TOSRadioHeader
o data
o TOSRadioFooter
o TOSRadioMetadata</blockquote>
<p>That is, a TinyOS component MUST NOT access any sub-fields of these
structures. Components above the link layer MUST access packet fields
through a nesC interface. For example, active messages have an interface
named <tt class="docutils literal"><span class="pre">AMPacket</span></tt> which provides access commands to AM fields. In
TinyOS 1.x, a component would directly access <tt class="docutils literal"><span class="pre">TOS_Msg.addr</span></tt>;
in TinyOS 2.x, a component calls <tt class="docutils literal"><span class="pre">AMPacket.getAddress(msg)</span></tt>.</p>
<div class="section" id="tosradioheader">
<h2><a name="tosradioheader">3.1 TOSRadioHeader</a></h2>
<p>Link layer components MAY handle packet fields differently than other
components, as they are aware of the actual packet format. They can
therefore implement the interfaces that provide access to the fields
for other components.</p>
<p>Link layer components MUST NOT directly access sub-fields
of message_t. There are two reasons for this. First, whether
each type is their link type or a union of link types is unknown,
as it can change depending on the platform.
Each of these cases has different C syntax, and in the union case the
name of the field is unknown.</p>
<p>Second, although the structures ensure that enough space is allocated,
C's placement of the structures is not necessarily correct.
Defining a message_t header as a union of the underlying link layer headers
means that, in terms of C structures, a packet may not be contiguous. For
example, consider this case:</p>
<div class="line-block">
<div class="line"><tt class="docutils literal"><span class="pre">typedef</span> <span class="pre">struct</span> <span class="pre">HeaderA</span> <span class="pre">{</span></tt></div>
<div class="line">`` uint8_t a;``</div>
<div class="line"><tt class="docutils literal"><span class="pre">}</span></tt></div>
<div class="line"><tt class="docutils literal"><span class="pre">typedef</span> <span class="pre">struct</span> <span class="pre">HeaderB</span> <span class="pre">{</span></tt></div>
<div class="line">`` uint16_t b;``</div>
<div class="line"><tt class="docutils literal"><span class="pre">}</span></tt></div>
<div class="line"><tt class="docutils literal"><span class="pre">typedef</span> <span class="pre">union</span> <span class="pre">MyHeader</span> <span class="pre">{</span></tt></div>
<div class="line">`` HeaderA A;``</div>
<div class="line">`` HeaderB B;``</div>
<div class="line"><tt class="docutils literal"><span class="pre">}</span></tt></div>
<div class="line"><tt class="docutils literal"><span class="pre">typedef</span> <span class="pre">MyHeader</span> <span class="pre">TOSRadioHeader;</span></tt></div>
</div>
<p>Given nesC nx_struct layout, when TOSRadioHeader is specified as a union
of HeaderA and HeaderB, there will be a padding byte after <tt class="docutils literal"><span class="pre">HeaderA.a</span></tt>.
However, some radios require that packets passed to them are contiguous.</p>
<p>The packet for a link layer does not necessarily start at the beginning
of the message_t. Instead, is starts at a negative offset from the
data field. When a link layer component needs to read or write protocol
header fields, it MUST compute the location of the header as a negative
offset from the data field. The padding bytes that C introduces for
the different sized headers are at the beginning of message_t, not
between the header and payload. For example, let us suppose that HeaderA
has an interface <tt class="docutils literal"><span class="pre">APacket</span></tt>, which provides a command <tt class="docutils literal"><span class="pre">a</span></tt> that
returns the field <tt class="docutils literal"><span class="pre">a</span></tt> of HeaderA. Its code looks like this:</p>
<div class="line-block">
<div class="line"><a href="#id22" name="id23"><span class="problematic" id="id23">``</span></a>command uint8_t APacket.a(message_t* msg) { ``</div>
<div class="line">`` HeaderA* hdr = (HeaderA*)(msg->data - sizeof(HeaderA));``</div>
<div class="line">`` return hdr->a;``</div>
<div class="line"><tt class="docutils literal"><span class="pre">}</span></tt></div>
</div>
<div class="system-message" id="id22">
<p class="system-message-title">System Message: <a name="id22">WARNING/2</a> (<tt class="docutils">txt/tep111.txt</tt>, line 279); <em><a href="#id23">backlink</a></em></p>
Inline literal start-string without end-string.</div>
<p>We can trust the C compiler to optimize the call into a static offset
memory load.</p>
<p>The following code is incorrect, as it directly casts the header field.
It is an example of what components MUST NOT do:</p>
<div class="line-block">
<div class="line"><a href="#id24" name="id25"><span class="problematic" id="id25">``</span></a>command uint8_t APacket.a(message_t* msg) { ``</div>
<div class="line">`` HeaderA* hdr = (HeaderA*)(msg->header);``</div>
<div class="line">`` return hdr->a;``</div>
<div class="line"><tt class="docutils literal"><span class="pre">}</span></tt></div>
</div>
<div class="system-message" id="id24">
<p class="system-message-title">System Message: <a name="id24">WARNING/2</a> (<tt class="docutils">txt/tep111.txt</tt>, line 290); <em><a href="#id25">backlink</a></em></p>
Inline literal start-string without end-string.</div>
<p>The following example is also incorrect, as it directly accesses the
header structure. It is an example of what components MUST NOT do.</p>
<div class="line-block">
<div class="line"><a href="#id26" name="id27"><span class="problematic" id="id27">``</span></a>command uint8_t APacket.a(message_t* msg) { ``</div>
<div class="line">`` return msg->header.A.a;``</div>
<div class="line"><tt class="docutils literal"><span class="pre">}</span></tt></div>
</div>
<div class="system-message" id="id26">
<p class="system-message-title">System Message: <a name="id26">WARNING/2</a> (<tt class="docutils">txt/tep111.txt</tt>, line 298); <em><a href="#id27">backlink</a></em></p>
Inline literal start-string without end-string.</div>
</div>
<div class="section" id="tosradiofooter">
<h2><a name="tosradiofooter">3.2 TOSRadioFooter</a></h2>
<p>The TOSRadioFooter field ensures that message_t has enough space
to store the footers for all underlying link layers when there
are MTU-sized packets. Like headers, footers are not necessarily
stored where the C structs indicate they are: instead, their
placement is implementation dependent. For example, a link
layer can store a full packet as a contiguous area of memory. In
this case, a short packet will store the footer within the <tt class="docutils literal"><span class="pre">data</span></tt>
field of the structure.</p>
<p>The placement of the packet footer is implementation dependent.</p>
<p>The footer starts at the start of the footer field, and metadata begins
at the start of the metadata field. However, data link components MUST
NOT directly access these fields, as their structure is platform
dependent. A component MUST cast these fields to link specific structures.</p>
<p>Following these rules means that a packet is</p>
<p>The basic issue driving these design considerations is that
the C naming layout of message_t fields is platform specific. As a
data link implementation may be used on many platforms, an implementation
cannot depend on a particular C naming. An implementation can depend on
there being enough space for its header and footer in message_t.</p>
<p>Following this approach means that the packet header and data payload
are contiguous in memory, which allows other communication abstractions
(such as a UART) to easily encapsulate a packet.</p>
</div>
</div>
<div class="section" id="author-s-address">
<h1><a name="author-s-address">4. Author's Address</a></h1>
<div class="line-block">
<div class="line">Philip Levis</div>
<div class="line">467 Soda Hall</div>
<div class="line">UC Berkeley</div>
<div class="line">Berkeley, CA 94720</div>
<div class="line"><br /></div>
<div class="line">phone - +1 510 290 5283</div>
<div class="line"><br /></div>
<div class="line">email - <a class="reference" href="mailto:pal@cs.berkeley.edu">pal@cs.berkeley.edu</a></div>
</div>
</div>
<div class="section" id="citations">
<h1><a name="citations">7. Citations</a></h1>
<table class="docutils citation" frame="void" id="rst" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a name="rst">[rst]</a></td><td>reStructuredText Markup Specification. <<a class="reference" href="http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html">http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html</a>></td></tr>
</tbody>
</table>
<table class="docutils citation" frame="void" id="sipattern" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a name="sipattern">[sipattern]</a></td><td>The Service Instance Pattern. In <em>Software Design Patterns for TinyOS.</em> David Gay, Philip Levis, and David Culler. Published in Proceedings of the ACM SIGPLAN/SIGBED 2005 Conference on Languages, Compilers, and Tools for Embedded Systems (LCTES'05).</td></tr>
</tbody>
</table>
<table class="docutils citation" frame="void" id="boot" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a name="boot">[boot]</a></td><td>TEP 107: TinyOS 2.x Boot Sequence.</td></tr>
</tbody>
</table>
</div>
</div>
</body>
</html>
--- NEW FILE: tep112.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.3.9: 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" />
<style type="text/css">
/*
:Author: David Goodger
:Contact: goodger at users.sourceforge.net
:date: $Date: 2005/09/20 16:30:23 $
: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 }
/* Uncomment (& remove this text!) to get bold-faced definition list terms
dt {
font-weight: bold }
*/
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 {
background-color: #eeeeee }
ul.auto-toc {
list-style-type: none }
</style>
</head>
<body>
<div class="document" id="microcontroller-power-management">
<h1 class="title">Microcontroller Power Management</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">112</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>Robert Szewczyk, Philip Levis, Martin Turon, Lama Nachman, Philip Buonadonna, Vlado Handziski</td></tr>
<tr class="field"><th class="docinfo-name">Draft-Created:</th><td class="field-body">19-Sep-2005</td>
</tr>
<tr class="field"><th class="docinfo-name">Draft-Version:</th><td class="field-body">1.3</td>
</tr>
<tr class="field"><th class="docinfo-name">Draft-Modified:</th><td class="field-body">2005-09-19</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="system-message">
<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep112.txt</tt>, line 1)</p>
<p>Title overline too short.</p>
<pre class="literal-block">
============================
Microcontroller Power Management
============================
</pre>
</div>
<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" 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
should always be in the lowest possible power state that can satisfy
application requirements. Determining this state accurately requires
knowing a great deal about the power state of many subsystems and
their peripherals. Additionally, state transitions are common. Every
time a microcontroller handles an interrupt, it moves from a low power
state to an active state, and whenever the TinyOS scheduler finds the
task queue empty it returns the microcontroller to a low power state.
TinyOS 2.x uses three mechanisms to decide what low power state it
puts a microcontroller into: status and control registers, a dirty
bit, and a power state override. This memo documents these mechanisms
and how they work, as well as the basics of subsystem power
management.</p>
</div>
<div class="section" id="background">
<h1><a name="background">2. Background</a></h1>
<p>The TinyOS scheduler[_tep106] puts a processor into a sleep state when
the task queue is empty. However, processors can have a spectrum of
power states. For example, the MSP430 has one active mode (issuing
instructions) and five low-power modes. The low power modes range from
LPM0, which disables only the CPU and main system clock, to LPM4,
which disables the CPU, all clocks, and the oscillator, expecting to
be woken by an external interrupt source. The power draws of these low
power modes can differ by a factor of 350 or more (75 uA for LPM0 at
3V, 0.2 uA for LPM4). Correctly choosing the right microcontroller low
power state can greatly increase system lifetime.</p>
<p>TinyOS 1.x platforms manage MCU power in several different ways, but
there are commonalities in the approaches. The mica platforms, for
example, have a component named HPLPowerManagement, which has a
commands for enabling and disabling low power modes, as well as a
command (adjustPower()) to tell it to compute the low power state
based on the configuration of its various control and status
registers, storing the result in the Atmega128's MCU control
register. When TinyOS tells the microcontroller to go to sleep, it
uses the control register to decide exactly which power state to go
into. In contrast, MSP430 based platforms such as Telos and eyes
compute the low power state every time the scheduler tells the system
to go to sleep.</p>
<p>Each of the two approaches has benefits and drawbacks. The 1.x mica
approach is efficient, in that it only calculates the low power state
when told to. However, this leaves the decision of when to calculate
the low power state to other components, which is an easy way to
introduce bugs. The lack of a well-defined hardware abstraction
architecture in 1.x exacerbates this problem. In contrast, the MSP430
approach is simpler, in that the system will always enter the right
power state without any external prompting. However, it is
correspondingly costly, introducing 40-60 cycles of overhead to every
interrupt that wakes the system up, which can be a bottleneck on the rate
at which the system can handle interrupts.</p>
<p>Both of these approaches assume that TinyOS can determine the correct
low power state by examining control and status registers. For
example, the MSP430 defaults to low power mode 3 (LPM3) unless it
detects that Timer A, the USARTs, or the ADC is active, in which case
it uses low power mode 1 (LPM1). From the perspective of what
peripherals and subsystems might wake the node up or must continue
operating while the MCU sleeps, this is true. However, power modes
introduce wakeup latency, a factor which could be of interest to
higher-level components. While wakeup latency is not a significant
issue on very low power microcontrollers, such as the Atmega128 and
MSP430, more powerful processors, such as the Xscale family (the basis
of platforms such as the imote2) can power states with wakeup
latencies as large as 5ms. For some application domains, this latency
could be a serious issue. Higher level components therefore need a way
to give the TinyOS microcontroller power manager information on their
requirements, which it considers when calculating the right low power
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
state calculation function, and a power state override function. The
dirty bit tells TinyOS when it needs to calculate a new low power
state, the function performs the calculation, and the override allows
higher level components to introduce additional requirements, if
needed.</p>
<p>These three mechanisms all operate in the TinyOS core scheduling loop,
described in TEP 106: Schedulers and Tasks[_tep106]. This loop is
called from the boot sequence, which is described in TEP 107: Boot
Sequence[_tep107]. The command in question is
<tt class="docutils literal"><span class="pre">Scheduler.runNextTask()</span></tt>, when its sleep parameter is TRUE (i.e.,
<tt class="docutils literal"><span class="pre">call</span> <span class="pre">Scheduler.runNextTask(TRUE)</span></tt>).</p>
<p>If this command is called when the task queue is empty, the TinyOS
scheduler puts the microcontroller to sleep. It does so through
the <tt class="docutils literal"><span class="pre">McuSleep</span></tt> interface:</p>
<div class="line-block">
<div class="line"><tt class="docutils literal"><span class="pre">interface</span> <span class="pre">McuSleep</span> <span class="pre">{</span></tt></div>
<div class="line-block">
<div class="line"><tt class="docutils literal"><span class="pre">async</span> <span class="pre">command</span> <span class="pre">void</span> <span class="pre">sleep();</span></tt></div>
</div>
<div class="line"><tt class="docutils literal"><span class="pre">}</span></tt></div>
</div>
<p><tt class="docutils literal"><span class="pre">McuSleep.sleep()</span></tt> puts the microcontroller into a low power sleep
state, to be woken by an interrupt. This command deprecates the
<tt class="docutils literal"><span class="pre">__nesc_atomic_sleep()</span></tt> call of TinyOS 1.x. Note that, as the 1.x
call suggests, putting the microcontroller to sleep MUST have certain
atomicity properties. The command is called from within an atomic
section, and MUST atomically re-enable interrupts and go to sleep. An
issue arises if the system handles an interrupt after it re-enables
interrupts but before it sleeps: the interrupt may post a task, but
the task will not be run until the microcontroller wakes up from sleep.</p>
<p>Microcontrollers generally have hardware mechanisms to support this
requirement. For example, on the Atmega128, the <tt class="docutils literal"><span class="pre">sei</span></tt> instruction
does not re-enable interrupts until two cycles after it is issued (so
the sequence <tt class="docutils literal"><span class="pre">sei</span> <span class="pre">sleep</span></tt> runs atomically).</p>
<p>A component named <tt class="docutils literal"><span class="pre">McuSleepC</span></tt> provides the McuSleep interface, and
<tt class="docutils literal"><span class="pre">TinySchedulerC</span></tt> MUST automatically wire it to the scheduler
implementation. McuSleepC is a chip- or platform-specific component,
whose signature MUST include the following interfaces:</p>
<div class="line-block">
<div class="line"><tt class="docutils literal"><span class="pre">component</span> <span class="pre">McuSleepC</span> <span class="pre">{</span></tt></div>
<div class="line-block">
<div class="line"><tt class="docutils literal"><span class="pre">provides</span> <span class="pre">interface</span> <span class="pre">McuSleep;</span></tt></div>
<div class="line"><tt class="docutils literal"><span class="pre">provides</span> <span class="pre">interface</span> <span class="pre">PowerState;</span></tt></div>
<div class="line"><tt class="docutils literal"><span class="pre">uses</span> <span class="pre">interface</span> <span class="pre">PowerOverride;</span></tt></div>
</div>
<div class="line"><tt class="docutils literal"><span class="pre">}</span></tt></div>
<div class="line"><br /></div>
<div class="line"><tt class="docutils literal"><span class="pre">interface</span> <span class="pre">McuPowerState</span> <span class="pre">{</span></tt></div>
<div class="line-block">
<div class="line"><tt class="docutils literal"><span class="pre">async</span> <span class="pre">command</span> <span class="pre">void</span> <span class="pre">update();</span></tt></div>
</div>
<div class="line"><tt class="docutils literal"><span class="pre">}</span></tt></div>
<div class="line"><br /></div>
<div class="line"><tt class="docutils literal"><span class="pre">interface</span> <span class="pre">McuPowerOverride</span> <span class="pre">{</span></tt></div>
<div class="line-block">
<div class="line"><tt class="docutils literal"><span class="pre">async</span> <span class="pre">command</span> <span class="pre">mcu_power_t</span> <span class="pre">lowestState();</span></tt></div>
</div>
<div class="line"><tt class="docutils literal"><span class="pre">}</span></tt></div>
</div>
<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[_tep2]) component changes an aspect of
hardware configuration that might change the possible low power state
of the microcontroller, it MUST call McuPowerState.update(). This is
the first power management mechanism, a <em>dirty bit</em>. If
McuPowerState.update() is called, then McuSleepC MUST recompute the
low power state before the next time it goes to sleep as a result of
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
operation of TinyOS subsystems. McuSleepC SHOULD minimize how often it
must perform this calculation: it is an inherently atomic calculation,
and so if performed very often (e.g., on every interrupt) can
introduce significant overhead and jitter.</p>
<p>MCU power states MUST be represented as an enum in the standard chip
implementation header file. This file MUST also define a type
<tt class="docutils literal"><span class="pre">mcu_power_t</span></tt> and a combine function that given two power state
values returns one that provides the union of their functionality.</p>
<p>For example, consider a hypothetical microcontroller with three low
power states, (LPM0, LPM1, LPM2) and two hardware resources such as
clocks (HR0, HR1). In LPM0, both HR0 and HR1 are active. In LPM1, HR0
is inactive but HR1 is active. In LPM2, both HR0 and HR1 are inactive.
The following table describes the results of a proper combine function
(essentially a MAX):</p>
<table border="1" class="docutils">
<colgroup>
<col width="25%" />
<col width="25%" />
<col width="25%" />
<col width="25%" />
</colgroup>
<tbody valign="top">
<tr><td> </td>
<td>LPM0</td>
<td>LPM1</td>
<td>LPM2</td>
</tr>
<tr><td>LPM0</td>
<td>LPM0</td>
<td>LPM0</td>
<td>LPM0</td>
</tr>
<tr><td>LPM1</td>
<td>LPM0</td>
<td>LPM1</td>
<td>LPM1</td>
</tr>
<tr><td>LPM2</td>
<td>LPM0</td>
<td>LPM1</td>
<td>LPM2</td>
</tr>
</tbody>
</table>
<p>In contrast, if in LPM2, HR0 is active but HR1 is inactive, the
combine function would look like this:</p>
<table border="1" class="docutils">
<colgroup>
<col width="25%" />
<col width="25%" />
<col width="25%" />
<col width="25%" />
</colgroup>
<tbody valign="top">
<tr><td> </td>
<td>LPM0</td>
<td>LPM1</td>
<td>LPM2</td>
</tr>
<tr><td>LPM0</td>
<td>LPM0</td>
<td>LPM0</td>
<td>LPM0</td>
</tr>
<tr><td>LPM1</td>
<td>LPM0</td>
<td>LPM1</td>
<td>LPM0</td>
</tr>
<tr><td>LPM2</td>
<td>LPM0</td>
<td>LPM0</td>
<td>LPM2</td>
</tr>
</tbody>
</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
implementation of this command, which returns the lowest power state
the MCU is capable of. The return value of this command is a
<tt class="docutils literal"><span class="pre">mcu_power_t.</span></tt> McuSleepC MUST respect the requirements of the return
of this call and combine it properly with the low power state it
computes.</p>
<p>The PowerOverride functionality exists in case higher-level components
have some knowledge or requirements that cannot be captured in
hardware status and configuration registers, such as a maximum
tolerable wakeup latency. Because it can overrides all of the MCU
power conservation mechanisms, it SHOULD be used sparingly, if at
all. Because it is called in an atomic section during the core
scheduling loop, implementations of PowerOverride.lowestState() SHOULD
be an efficient function, and SHOULD NOT be longer than twenty or
thirty cycles; implementations SHOULD be a simple return of a cached
variable. Wiring arbitrarily to this command is an easy way to cause
TinyOS to behave badly. The presence of a combine function for
mcu_power_t means that this command can have fan-out calls.</p>
</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
involved, this interface is either <tt class="docutils literal"><span class="pre">StdControl</span></tt> or <tt class="docutils literal"><span class="pre">SplitControl</span></tt>.
These interfaces are imperative in that when any component calls
<tt class="docutils literal"><span class="pre">StdControl.stop</span></tt> on another component, it causes the subsystem that
component represents to enter an inactive, low-power state.</p>
<p>From the perspective of MCU power management, this transition causes a
change in status and control registers (e.g., a clock is
disabled). Following the requirements in 3.1, the MCU power management
subsystem will be notified of a significant change and act
appropriately when the system next goes to sleep.</p>
<p>These imperative appraoches are flexible and powerful, but are also
very error prone, partially due to their deep semantics. For example,
depending on the circumstances, an application calling StdControl.stop
on a routing layer may or may not also want to turn off the underlying
radio. StdControl and SplitControl provide a <em>mechanism</em> to control
subsystem power states, but no real <em>policy</em> for arbitrating
conflicting requirements from components built on top of them.</p>
<p>Service distributions (described in TEP 110[_tep110]) are responsible
for providing policies on top of these low-level mechanisms. OSKI, for
example, the sample distribution described in TEP 110, uses an
OR-policy: a subsystem is active if any of its clients want it active,
and inactive iff all of its clients want it inactive. Other
distributions can provide alternative power management policies in top
of the basic HIL mechanisms.</p>
</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>
<div class="line">358 Gates</div>
<div class="line">Computer Science 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">email - <a class="reference" href="mailto:pal@cs.stanford.edu">pal@cs.stanford.edu</a></div>
<div class="line"><br /></div>
<div class="line"><br /></div>
<div class="line">Martin Turon</div>
<div class="line">PO Box 8525</div>
<div class="line">Berkeley, CA 94707</div>
<div class="line"><br /></div>
<div class="line">phone - +1 408 965 3355</div>
<div class="line">email - <a class="reference" href="mailto:mturon@xbow.com">mturon@xbow.com</a></div>
<div class="line"><br /></div>
<div class="line"><br /></div>
<div class="line">Phil Buonadonna</div>
<div class="line">Arched Rock Corp.</div>
<div class="line">2168 Shattuck Ave. 2nd Floor</div>
<div class="line">Berkeley, CA 94704</div>
<div class="line"><br /></div>
<div class="line">phone - +1 510 981 8714</div>
<div class="line">email - <a class="reference" href="mailto:pbuonadonna@archedrock.com">pbuonadonna@archedrock.com</a></div>
<div class="line"><br /></div>
<div class="line"><br /></div>
<div class="line">Vlado Handziski</div>
<div class="line">Sekr FT5</div>
<div class="line">Einsteinufer 25</div>
<div class="line">10587 Berlin</div>
<div class="line">GERMANY</div>
<div class="line"><br /></div>
<div class="line">email - <a class="reference" href="mailto:handzisk@tkn.tu-berlin.de">handzisk@tkn.tu-berlin.de</a></div>
<div class="line"><br /></div>
</div>
</div>
<div class="section" id="citations">
<h1><a name="citations">6. Citations</a></h1>
<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.</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: TinyOS 2.x Boot Sequence.</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.</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.</td></tr>
</tbody>
</table>
</div>
</div>
</body>
</html>
--- NEW FILE: tep113.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.3.9: http://docutils.sourceforge.net/" />
<title>Serial Communication</title>
<meta name="author" content="Ben Greenstein and Philip Levis" />
<style type="text/css">
/*
:Author: David Goodger
:Contact: goodger at users.sourceforge.net
:date: $Date: 2005/09/20 16:30:23 $
: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 }
/* Uncomment (& remove this text!) to get bold-faced definition list terms
dt {
font-weight: bold }
*/
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 {
background-color: #eeeeee }
ul.auto-toc {
list-style-type: none }
</style>
</head>
<body>
<div class="document" id="serial-communication">
<h1 class="title">Serial Communication</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">113</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>Ben Greenstein and Philip Levis</td></tr>
<tr class="field"><th class="docinfo-name">Draft-Created:</th><td class="field-body">11-Jul-2005</td>
</tr>
<tr class="field"><th class="docinfo-name">Draft-Version:</th><td class="field-body">1.1</td>
</tr>
<tr class="field"><th class="docinfo-name">Draft-Modified:</th><td class="field-body">2005-09-05</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" 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
exchange. The system is broken into three levels (encoding, framing,
and dispatch) to allow easy experimentation and replacement. It can
also handle multiple packet formats: unlike 1.x, 2.x serial packets
are not bound to the mote's radio packet format. Additionally, one of
the supported packet formats is platform independent, so PC-side
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 latop with a wired
connection. While the interface on the PC side can vary from a serial
cable to a USB device to IP, the mote generally talks to a serial port
(UART). In TinyOS 1.x, the UART packet format is platform-specific,
pushing a good deal of complexity into the protocol and PC-side tools
in order to discover and properly handle platform diversity. TinyOS
2.0 introduces the notion of packet format dispatch, so a mote can
support multiple UART packet formats simultaneously. This allows
transparent bridging (e.g., an 802.15.4 base station) to exist in
parallel with platform-independent communication, which allows
simplifies the PC toolchain. This memo documents the protocols and
structure of the 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>
<blockquote>
<p>o the raw UART,</p>
<p>o the encoder/framer,</p>
<p>o the protocol,</p>
<p>o and the dispatcher.</p>
</blockquote>
<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.
</pre>
<p>The bottom three provide a byte-level interface: only the Dispatcher
provides a packet-level interface. The top three are all
platform-independent: only the UART is platform-specific code.</p>
<p>The lowest level of the stack is the raw UART. This HIL component
provides functionality for configuring the UART (speed, stop bytes,
etc.) as well as sending/receiving bytes.</p>
<p>The Encoder/Framer sits above the raw UART. This component translates
raw data bytes into packet bytes using a serial protocol's
encoding. The Encoder/Framer assumes that a protocol's encoding has
two kinds of bytes: delimiters and data bytes, and signals each in
separate events to the component above.</p>
<p>The Protocol component handles data and delimiter byte events. It is
responsible for reading in and sending all protocol control
packets. If the Protocol component starts receiving a data packet, it
signals to the Dispatcher that a packet has started and signals the
data bytes. When the data packet completes, the Protocol signals to
the Dispatcher that the packet is complete and whether it passed the
protocol-level CRC.</p>
<p>The Dispatcher component handles data packet bytes and delimiters. It
is responsible for reading data bytes into a message_t and signaling
packet reception to components above it. The dispatcher can support
multiple packet formats. Based on how message_t works (see TEP
111[<a class="reference" href="#tep111">tep111</a>]), this boils down to knowing where in a message_t a
particular packet format begins (based on its header size). Section
3.4 describes how the default TinyOS 2.x implementation,
<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 structure. This section describes its actual implementation,
including SerialActiveMessageC, which sits on top of the Dispatcher.
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
<tt class="docutils literal"><span class="pre">SerialByteComm</span></tt> interface:</p>
<pre class="literal-block">
interface SerialByteComm {
async command error_t put(uint8_t data);
async event void get(uint8_t data);
async event void putDone();
}
</pre>
<p>It also provides interfaces for configuring the serial port. <em>NOTE:
These are not codified yet, and so working out the UART HIL seems like
a good idea.</em></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>
interface:</p>
<pre class="literal-block">
interface SerialFrameComm {
async command error_t putDelimiter();
async command error_t putData(uint8_t data);
async command void resetSend();
async command void resetReceive();
async event void delimiterReceived();
async event void dataReceived(uint8_t data);
async event void putDone();
}
</pre>
<p>As its name suggests, it uses the same encoding as the HDLC[<a class="reference" href="#hdlc">HDLC</a>]
protocol. <tt class="docutils literal"><span class="pre">0x7e</span></tt> is reserved as a frame delimiter byte, and <tt class="docutils literal"><span class="pre">0x7d</span></tt>
is reserved as an escape byte. HdlcTranslateC maintains ten bits of
state. The receive and send paths each have one bit to store whether
they are using an escape byte, and the transmit path has a byte for
when it sends an escaped byte.</p>
<p>When HdlcTranslateC receives a delimiter byte, it signals
delimiterReceived(). When HdlcTranslateC receives an escape byte, it
sets the receiveEscape flag to true. When it receives any other byte,
it tests to see if the receiveEscape flag is set; if so, it XORs the
data byte with <tt class="docutils literal"><span class="pre">0x20</span></tt> and clears the flag. It signals dataReceived()
with the byte. The most common use of escape byte is to transmit data
bytes corresponding to the delimiter byte or escape byte. For example,
<tt class="docutils literal"><span class="pre">0x7e</span></tt> becomes <tt class="docutils literal"><span class="pre">0x7d</span> <span class="pre">0x5e</span></tt>.</p>
<p>HdlcTranslateC performs similar actions on the transmit side. When
told to transmit the delimiter or escape byte as a data byte, it sets
the transmitEscape flag to true, stores the data byte XOR <tt class="docutils literal"><span class="pre">0x20</span></tt>,
and sends an escape byte. When the escape byte is sent, it sends the
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
management are left to higher layers in the serial stack. The protocol
is currently stop-and-wait in the host-to-mote direction and best
effort in the mote-to-host direction. The first performance upgrade of
this module will be to implement sliding window reliability in both
directions.</p>
<p>SerialP provides two byte-level interfaces to the upper layer for
sending and receiving packets, respectively called SendBytePacket and
ReceiveBytePacket.</p>
<p>On the sending side, SerialP is responsible for encapsulation of upper
layer packets. An upper layer component such as SerialDispatcherC
initiates the sending of a packet by calling startSend, passing the
first byte to send. SerialP collects subsequent bytes by signalling
nextByte. Within the nextByte handler or between calls to nextByte,
the upper layer should indicate the end-of-packet by calling
completeSend. If completeSend is called from within a nextByte
handler, SerialP will ignore the return of the call to nextByte.</p>
<pre class="literal-block">
interface SendBytePacket {
async command error_t startSend(uint8_t first_byte);
async command error_t completeSend();
async event uint8_t nextByte();
async event void sendCompleted(error_t error);
}
</pre>
<p>SerialP maintains a small window of bytes that have been received by
the upper layer and not yet sent to the UART. Depending on the timing
requirements of the underlying UART, the size of this window can be
changed. SerialP uses repeated calls to nextByte to keep this window
filled.</p>
<p>SerialP uses SerialFrameComm to send a delimiter between frames,
a serial-level type field, the bytes of the packet, and a two-byte
frame CRC. For mote-to-host gap detection and link reliability, a
sequence number may also be sent (not currently activated).</p>
<p>After sending an entire frame and receiving the last putDone event
from below, SerialP signals sendCompleted to indicate the success or
failure of a requested transmission.</p>
<p>Packet reception is also managed by SerialP and the interface
provided to the upper layer is ReceiveBytePacket:</p>
<pre class="literal-block">
interface ReceiveBytePacket {
async event error_t startPacket();
async event void byteReceived(uint8_t b);
async event void endPacket(error_t result);
}
</pre>
<p>Upon receiving an interframe delimiter and a new frame's header,
SerialP signals the upper layer indicating that a packet is
arriving. For each byte received, SerialP signals byteReceived. (Note:
SerialP signals on byte k-2 when byte k arrives, because the
implementation precludes it from knowing when it has encountered the
2-byte CRC in the frame footer until after it has received it. Lagging
behind by two bytes makes it possible to hide all frame details from
the upper layer.) Once SerialP receives the complete frame it signals
endPacket with a value of SUCCESS. If instead it loses sync during
reception it signals endPacket with FAIL.</p>
<p>SerialP acknowledges frames it receives. Acknowledgements have a
higher priority than data transmissions and consequently, data frames
may be slightly delayed. However, acknowledgement information is
stored in a queue separate from the data buffer, so a data packet to
be transmitted may begin spooling into SerialP while SerialP is
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,
and provides parameterized Send and Receive interfaces. The parameter
in the Send and Receive interfaces (<tt class="docutils literal"><span class="pre">uart_id_t</span></tt>) determines the
packet format contained in the message_t.</p>
<p>SerialDispatcherC places a one-byte header, the packet format
identifier, on the packets sent and received through SerialP.
SerialDispatcherC uses a parameterized SerialPacketInfo interface to
be able to handle various packet formats:</p>
<pre class="literal-block">
interface SerialPacketInfo {
async command uint8_t offset();
async command uint8_t dataLinkLength(message_t* msg, uint8_t upperLen);
async command uint8_t upperLength(message_t* msg, uint8_t dataLinkLen);
}
</pre>
<p>When SerialDispatcherC receives the first data byte of a packet from
SerialP, it stores it as the packet type and calls
SerialPacketInfo.offset() to determine where in a message_t that
packet format begins. It then spools data bytes in, filling them into
its message_t buffer. Similarly, on the send side, it first sends the
type byte and spools out data bytes starting from the index denoted by
the call to offset(). SerialDispatcherC uses the two length commands,
dataLinkLength and upperLength, to translate between the two notions
of packet length: above, length refers to the payload excluding
header, while below it refers to the payload plus header.</p>
<p>A component that provides communication over the serial port with
uart_id_t <em>U</em> MUST wire a component implementing SerialPacketInfo to
SerialDispatcherC with uart_id_t <em>U</em>. The file <tt class="docutils literal"><span class="pre">Serial.h</span></tt> contains
reserved uart_id_t's for supported packet formats. Currently, only
platform independent active messages
(<tt class="docutils literal"><span class="pre">TOS_SERIAL_ACTIVE_MESSAGE_ID</span></tt>, described in Section 3.5), 802.15.4
active messages (<tt class="docutils literal"><span class="pre">TOS_SERIAL_802_15_4_ID</span></tt>), mica2 CC1000 packets
(<tt class="docutils literal"><span class="pre">TOS_SERIAL_CC1000_ID</span></tt>) and the error code
<tt class="docutils literal"><span class="pre">TOS_SERIAL_UNKNOWN_ID</span></tt> are reserved. New packet formats MUST NOT
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
stack. SerialActiveMessageC is a configuration that wires
SerialActiveMessageP to SerialDispatcherC with uart_id_t
TOS_SERIAL_ACTIVE_MESSAGE_ID and wires SerialPacketInfoActiveMessageP
to SerialDispatcherC with uart_id_t TOS_SERIAL_ACTIVE_MESSAGE_ID:</p>
<pre class="literal-block">
includes Serial;``
configuration SerialActiveMessageC {
provides {
interface Init;
interface AMSend[am_id_t id];
interface Receive[am_id_t id];
interface Packet;
interface AMPacket;
}
uses interface Leds;
}
implementation {
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;
}
</pre>
<p>SerialActiveMessageP is a generic component so that it can be used to
sit on top of any packet-level communication layer. It does not filter
packets based on destination address or group. It assumes that if the
packet was received over the serial port, it was destined to the
node. This saves PC-side tools from having to discover or consider the
ID and group of a mote.</p>
<p>Platform-independent active messages do not have a CRC (they assumes
the serial stack CRC is sufficient), and have the following header:</p>
<pre class="literal-block">
typedef nx_struct SerialAMHeader {
nx_am_addr_t addr;
nx_uint8_t length;
nx_am_group_t group;
nx_am_id_t type;
} SerialAMHeader;
</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>
<pre class="literal-block">
____________________________________________
| | | | | | | |
| | | | | | | |
|_|_|_|_|_______________________________|__|_|
F P S D Payload CR F
F = Framing byte, denoting start of packet: HdlcTranslateC
P = Protocol byte: SerialP
S = Sequence number byte: SerialP
D = Packet format dispatch byte: SerialDispatcherC
Payload = Data payload (stored in SerialDispatcherC): SerialDispatcherC
CR = Two-byte CRC over S to end of Payload: SerialP
F = Framing byte denoting end of packet: HdlcTranslateC
</pre>
<p>Payload is a contiguous packet that SerialDispatcherC reads in. Note
that any data bytes (P - CR) equal to 0x7e or 0x7d will be escaped to
0x7d 0x5e or 0x7d 0x5d accordingly. For example, a platform
independent AM packet of type 6, group 0x7d, and length 5 to
destination 0xbeef with a payload of 1 2 3 4 5 would look like this:</p>
<p><tt class="docutils literal"><span class="pre">7e</span> <span class="pre">40</span> <span class="pre">09</span> <span class="pre">00</span> <span class="pre">be</span> <span class="pre">ef</span> <span class="pre">05</span> <span class="pre">7d</span> <span class="pre">5d</span> <span class="pre">06</span> <span class="pre">01</span> <span class="pre">02</span> <span class="pre">03</span> <span class="pre">04</span> <span class="pre">05</span></tt></p>
<p>Note that the group 0x7d is escaped to 0x7d 0x5d. The protocol field
(P) is 0x40 (64), corresponding to <tt class="docutils literal"><span class="pre">SERIAL_PROTO_ACK</span></tt> (in Serial.h).</p>
</div>
</div>
<div class="section" id="author-s-address">
<h1><a name="author-s-address">4. 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 Science 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">email - <a class="reference" href="mailto:pal@cs.stanford.edu">pal@cs.stanford.edu</a></div>
<div class="line"><br /></div>
<div class="line"><br /></div>
<div class="line">Ben Greenstein</div>
<div class="line">Center for Embedded Networked Sensing</div>
<div class="line">UCLA 3563 Boelter Hall</div>
<div class="line">Los Angeles, CA 90095-1596</div>
<div class="line"><br /></div>
<div class="line">phone - +1 310 206 3925</div>
<div class="line">email - <a class="reference" href="mailto:ben@cs.ucla.edu">ben@cs.ucla.edu</a></div>
</div>
</div>
<div class="section" id="citations">
<h1><a name="citations">7. Citations</a></h1>
<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://cvs.sourceforge.net/viewcvs.py/tinyos/tinyos-1.x/beta/teps/txt/tep2.txt?view=markup">http://cvs.sourceforge.net/viewcvs.py/tinyos/tinyos-1.x/beta/teps/txt/tep2.txt?view=markup</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 name="tep111">[TEP111]</a></td><td>TEP 111: message_t. <a class="reference" href="http://cvs.sourceforge.net/viewcvs.py/tinyos/tinyos-1.x/beta/teps/txt/tep111.txt?view=markup">http://cvs.sourceforge.net/viewcvs.py/tinyos/tinyos-1.x/beta/teps/txt/tep111.txt?view=markup</a></td></tr>
</tbody>
</table>
<table class="docutils citation" frame="void" id="hdlc" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a name="hdlc">[HDLC]</a></td><td>International Organization For Standardization, ISO Standard 3309-1979, "Data communication - High-level data link control procedures - Frame structure", 1979.</td></tr>
</tbody>
</table>
<table class="docutils citation" frame="void" id="rfc1662" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a name="rfc1662">[RFC1662]</a></td><td>PPP in HDLC-like Framing, Internet Engineering Task Force (IETF), 1994</td></tr>
</tbody>
</table>
</div>
</div>
</body>
</html>
Index: tep1.html
===================================================================
RCS file: /cvsroot/tinyos/tinyos-1.x/beta/teps/html/tep1.html,v
retrieving revision 1.9
retrieving revision 1.10
diff -C2 -d -r1.9 -r1.10
*** tep1.html 6 Jun 2005 21:30:38 -0000 1.9
--- tep1.html 20 Sep 2005 16:30:23 -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>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.3.9: http://docutils.sourceforge.net/" />
<title>TEP Structure and Keywords</title>
<meta name="author" content="Philip Levis" />
***************
*** 281,284 ****
--- 281,285 ----
</head>
<body>
+ <div class="document" id="tep-structure-and-keywords">
<h1 class="title">TEP Structure and Keywords</h1>
<table class="docinfo" frame="void" rules="none">
***************
*** 308,312 ****
</tbody>
</table>
- <div class="document" id="tep-structure-and-keywords">
<div class="note">
<p class="first admonition-title">Note</p>
--- 309,312 ----
Index: tep101.html
===================================================================
RCS file: /cvsroot/tinyos/tinyos-1.x/beta/teps/html/tep101.html,v
retrieving revision 1.10
retrieving revision 1.11
diff -C2 -d -r1.10 -r1.11
*** tep101.html 6 Jul 2005 03:43:57 -0000 1.10
--- tep101.html 20 Sep 2005 16:30:23 -0000 1.11
***************
*** 4,10 ****
<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>Analog-to-Digital Converters (ADCs)</title>
! <meta name="author" content="Jan-Hinrich Hauer, Philip Levis, Vlado Handziski, David Gay" />
<style type="text/css">
--- 4,13 ----
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
! <meta name="generator" content="Docutils 0.3.9: http://docutils.sourceforge.net/" />
<title>Analog-to-Digital Converters (ADCs)</title>
! <meta name="author" content="Jan-Hinrich Hauer" />
! <meta name="author" content="Philip Levis" />
! <meta name="author" content="Vlado Handziski" />
! <meta name="author" content="David Gay" />
<style type="text/css">
***************
*** 298,307 ****
</tr>
<tr><th class="docinfo-name">Author:</th>
! <td>Jan-Hinrich Hauer, Philip Levis, Vlado Handziski, David Gay</td></tr>
<tr class="field"><th class="docinfo-name">Draft-Created:</th><td class="field-body">20-Dec-2004</td>
</tr>
! <tr class="field"><th class="docinfo-name">Draft-Version:</th><td class="field-body">1.11</td>
</tr>
! <tr class="field"><th class="docinfo-name">Draft-Modified:</th><td class="field-body">2005-06-08</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>
--- 301,316 ----
</tr>
<tr><th class="docinfo-name">Author:</th>
! <td>Jan-Hinrich Hauer</td></tr>
! <tr><th class="docinfo-name">Author:</th>
! <td>Philip Levis</td></tr>
! <tr><th class="docinfo-name">Author:</th>
! <td>Vlado Handziski</td></tr>
! <tr><th class="docinfo-name">Author:</th>
! <td>David Gay</td></tr>
<tr class="field"><th class="docinfo-name">Draft-Created:</th><td class="field-body">20-Dec-2004</td>
</tr>
! <tr class="field"><th class="docinfo-name">Draft-Version:</th><td class="field-body">1.15</td>
</tr>
! <tr class="field"><th class="docinfo-name">Draft-Modified:</th><td class="field-body">2005-07-11</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>
***************
*** 484,490 ****
</colgroup>
<thead valign="bottom">
! <tr><th> </th>
! <th>Atmel Atmega 128</th>
! <th>TI MSP430 ADC12</th>
</tr>
</thead>
--- 493,499 ----
</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>
***************
*** 552,557 ****
conversion mode</li>
<li>free running mode
! (repeated single
! channel conversion)</li>
</ul>
</td>
--- 561,568 ----
conversion mode</li>
<li>free running mode
! (channels and
! reference voltages
! can be switched
! between samples)</li>
</ul>
</td>
***************
*** 728,759 ****
<li>The ADC on ATmega128:</li>
</ol>
! <p>In the current implementation on the Atmel an ADC channel is
! exhaustively defined by the port numer, i.e. there is no
! configuration mechanism (e.g. like for the MSP430):</p>
! <pre class="literal-block">
! configuration HALADCC
! {
! provides {
! interface Init;
! interface StdControl;
! interface Resource[uint8_t client];
! interface ATm128ADC[uint8_t port];
! }
! }
!
! interface ATm128ADC
! {
! async command error_t getData();
! async command error_t getContinuousData();
! async event error_t dataReady(uint16_t data);
! }
! </pre>
! <p>The Resource interface is specified in TEP 108. Before any call
! on the ATm128ADC interface can succeed, the ADC MUST be
! reserved via the Resource interface. After an application has
! performed all desired operations on the ADC, it then MUST
! release the ADC via the Resource interface. In the meantime
! the ADC will be blocked for all other applications, therefore an
! application SHOULD minimize this reservation period.</p>
</blockquote>
</li>
--- 739,1024 ----
<li>The ADC on ATmega128:</li>
</ol>
! <p>The HAL for the ATmega128 offers two interfaces: ATm128ADCSingle is
! for collecting single samples from a given channel, and
! ATm128ADCMultiple is for collecting multiple samples from one or
! more channels, using the ATmega128's A/D free-running mode. Rather
! than using a configuration mechanism, the commands of these
! interfaces have explicit parameters for setting all A/D conversion
! parameters:</p>
! <blockquote>
! <p>configuration HALADCC
! {</p>
! <div class="system-message">
! <p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">txt/tep101.txt</tt>, line 397)</p>
! <p>Unexpected indentation.</p>
! </div>
! <blockquote>
! <dl class="docutils">
! <dt>provides {</dt>
! <dd><p class="first last">interface Init;
! interface StdControl;
! interface Resource[uint8_t client];
! interface ATm128ADCSingle[uint8_t channel];
! interface ATm128ADCMultiple;</p>
! </dd>
! </dl>
! <div class="system-message">
! <p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep101.txt</tt>, line 403)</p>
! <p>Definition list ends without a blank line; unexpected unindent.</p>
! </div>
! <p>}</p>
! </blockquote>
! <div class="system-message">
! <p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep101.txt</tt>, line 404)</p>
! <p>Block quote ends without a blank line; unexpected unindent.</p>
! </div>
! <p>}</p>
! <p>interface ATm128ADCSingle
! {</p>
! <div class="system-message">
! <p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">txt/tep101.txt</tt>, line 408)</p>
! <p>Unexpected indentation.</p>
! </div>
! <blockquote>
! <dl class="docutils">
! <dt>/**</dt>
! <dd><ul class="first simple">
! <li>Initiates an ADC conversion on a given channel.</li>
! <li></li>
! <li>@param refVoltage Select reference voltage for A/D conversion. See</li>
! <li>the ATM128_ADC_VREF_xxx constants in ATm128ADC.h</li>
! <li>@param leftJustify TRUE to place A/D result in high-order bits</li>
! <li>(i.e., shifted left by 6 bits), low to place it in the low-order bits</li>
! <li>@param prescaler Prescaler value for the A/D conversion clock. Normally</li>
! <li>this should be ATM128_ADC_PRESCALE to guarantee full precision. Other</li>
! <li>prescalers can be used to get faster conversions. See the ATmega128</li>
! <li>manual for details.</li>
! <li>@return TRUE if the conversion will be precise, FALSE if it will be</li>
! <li>imprecise (due to a change in refernce voltage, or switching to a</li>
! <li>differential input channel)</li>
! </ul>
! <div class="system-message">
! <p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep101.txt</tt>, line 422)</p>
! <p>Bullet list ends without a blank line; unexpected unindent.</p>
! </div>
! <p><a href="#id4" name="id5"><span class="problematic" id="id5">*</span></a>/</p>
! <div class="last system-message" id="id4">
! <p class="system-message-title">System Message: <a name="id4">WARNING/2</a> (<tt class="docutils">txt/tep101.txt</tt>, line 422); <em><a href="#id5">backlink</a></em></p>
! <p>Inline emphasis start-string without end-string.</p>
! </div>
! </dd>
! <dt>async command bool getData(uint8_t refVoltage, bool leftJustify,</dt>
! <dd><p class="first last">uint8_t prescaler);</p>
! </dd>
! <dt>/**</dt>
! <dd><ul class="first simple">
! <li>Indicates a sample has been recorded by the ADC as the result</li>
! <li>of a <code>getData()</code> command.</li>
! <li></li>
! <li>@param data a 2 byte unsigned data value sampled by the ADC.</li>
! <li>@param precise if the conversion precise, FALSE if it wasn't. This</li>
! <li>values matches the result from the <code>getData</code> call.</li>
! </ul>
! <div class="system-message">
! <p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep101.txt</tt>, line 433)</p>
! <p>Bullet list ends without a blank line; unexpected unindent.</p>
! </div>
! <p><a href="#id6" name="id7"><span class="problematic" id="id7">*</span></a>/</p>
! <div class="last system-message" id="id6">
! <p class="system-message-title">System Message: <a name="id6">WARNING/2</a> (<tt class="docutils">txt/tep101.txt</tt>, line 433); <em><a href="#id7">backlink</a></em></p>
! <p>Inline emphasis start-string without end-string.</p>
! </div>
! </dd>
! </dl>
! <div class="system-message">
! <p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep101.txt</tt>, line 434)</p>
! <p>Definition list ends without a blank line; unexpected unindent.</p>
! </div>
! <p>async event void dataReady(uint16_t data, bool precise);</p>
! <dl class="docutils">
! <dt>/**</dt>
! <dd><ul class="first simple">
! <li>Cancel an outstanding getData operation. Use with care, to</li>
! <li>avoid problems with races between the dataReady event and cancel.</li>
! <li>@return TRUE if a conversion was in-progress or an interrupt</li>
! <li>was pending. dataReady will not be signaled. FALSE if the</li>
! <li>conversion was already complete. dataReady will be (or has</li>
! <li>already been) signaled.</li>
! </ul>
! <div class="system-message">
! <p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep101.txt</tt>, line 443)</p>
! <p>Bullet list ends without a blank line; unexpected unindent.</p>
! </div>
! <p><a href="#id8" name="id9"><span class="problematic" id="id9">*</span></a>/</p>
! <div class="last system-message" id="id8">
! <p class="system-message-title">System Message: <a name="id8">WARNING/2</a> (<tt class="docutils">txt/tep101.txt</tt>, line 443); <em><a href="#id9">backlink</a></em></p>
! <p>Inline emphasis start-string without end-string.</p>
! </div>
! </dd>
! </dl>
! <div class="system-message">
! <p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep101.txt</tt>, line 444)</p>
! <p>Definition list ends without a blank line; unexpected unindent.</p>
! </div>
! <p>async command bool cancel();</p>
! </blockquote>
! <div class="system-message">
! <p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep101.txt</tt>, line 445)</p>
! <p>Block quote ends without a blank line; unexpected unindent.</p>
! </div>
! <p>}</p>
! <p>interface ATm128ADCMultiple
! {</p>
! <div class="system-message">
! <p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">txt/tep101.txt</tt>, line 449)</p>
! <p>Unexpected indentation.</p>
! </div>
! <blockquote>
! <dl class="docutils">
! <dt>/**</dt>
! <dd><ul class="first simple">
! <li>Initiates free-running ADC conversions, with the ability to switch</li>
! <li>channels and reference-voltage with a one sample delay.</li>
! <li></li>
! <li>@param channel Initial A/D conversion channel. The channel can</li>
! <li>be changed in the dataReady event, though these changes happen</li>
! <li>with a one-sample delay (this is a hardware restriction).</li>
! <li>@param refVoltage Initial A/D reference voltage. See the</li>
! <li>ATM128_ADC_VREF_xxx constants in ATm128ADC.h. Like the channel,</li>
! <li>the reference voltage can be changed in the dataReady event with</li>
! <li>a one-sample delay.</li>
! <li>@param leftJustify TRUE to place A/D result in high-order bits</li>
! <li>(i.e., shifted left by 6 bits), low to place it in the low-order bits</li>
! <li>@param prescaler Prescaler value for the A/D conversion clock. Normally</li>
! <li>this should be ATM128_ADC_PRESCALE to guarantee full precision. Other</li>
! <li>prescalers can be used to get faster conversions. See the ATmega128</li>
! <li>manual for details.</li>
! <li>@return TRUE if the conversion will be precise, FALSE if it will be</li>
! <li>imprecise (due to a change in reference voltage, or switching to a</li>
! <li>differential input channel)</li>
! </ul>
! <div class="system-message">
! <p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep101.txt</tt>, line 469)</p>
! <p>Bullet list ends without a blank line; unexpected unindent.</p>
! </div>
! <p><a href="#id10" name="id11"><span class="problematic" id="id11">*</span></a>/</p>
! <div class="last system-message" id="id10">
! <p class="system-message-title">System Message: <a name="id10">WARNING/2</a> (<tt class="docutils">txt/tep101.txt</tt>, line 469); <em><a href="#id11">backlink</a></em></p>
! <p>Inline emphasis start-string without end-string.</p>
! </div>
! </dd>
! <dt>async command bool getData(uint8_t channel, uint8_t refVoltage,</dt>
! <dd><p class="first last">bool leftJustify, uint8_t prescaler);</p>
! </dd>
! <dt>/**</dt>
! <dd><ul class="first simple">
! <li>Returns the next sample in a free-running conversion. Allow the user</li>
! <li>to switch channels and/or reference voltages with a one sample delay.</li>
! <li></li>
! <li>@param data a 2 byte unsigned data value sampled by the ADC.</li>
! <li>@param precise if this conversion was precise, FALSE if it wasn't</li>
! <li>(we assume that the second conversion after a change of reference</li>
! <li>voltage or after switching to a differential channel is precise)</li>
! <li>@param channel Channel this sample was from.</li>
! <li>@param newChannel Change this parameter to switch to a new channel</li>
! <li>for the second next sample.</li>
! <li>@param newRefVoltage Change this parameter to change the reference</li>
! <li>voltage for the second next sample.</li>
! <li></li>
! <li>@return TRUE to continue sampling, FALSE to stop.</li>
! </ul>
! <div class="system-message">
! <p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep101.txt</tt>, line 488)</p>
! <p>Bullet list ends without a blank line; unexpected unindent.</p>
! </div>
! <p><a href="#id12" name="id13"><span class="problematic" id="id13">*</span></a>/</p>
! <div class="last system-message" id="id12">
! <p class="system-message-title">System Message: <a name="id12">WARNING/2</a> (<tt class="docutils">txt/tep101.txt</tt>, line 488); <em><a href="#id13">backlink</a></em></p>
! <p>Inline emphasis start-string without end-string.</p>
! </div>
! </dd>
! <dt>async event bool dataReady(uint16_t data, bool precise, uint8_t channel,</dt>
! <dd><p class="first">uint8_t <a href="#id14" name="id15"><span class="problematic" id="id15">*</span></a>newChannel, uint8_t <a href="#id16" name="id17"><span class="problematic" id="id17">*</span></a>newRefVoltage);</p>
! <div class="system-message" id="id14">
! <p class="system-message-title">System Message: <a name="id14">WARNING/2</a> (<tt class="docutils">txt/tep101.txt</tt>, line 490); <em><a href="#id15">backlink</a></em></p>
! <p>Inline emphasis start-string without end-string.</p>
! </div>
! <div class="last system-message" id="id16">
! <p class="system-message-title">System Message: <a name="id16">WARNING/2</a> (<tt class="docutils">txt/tep101.txt</tt>, line 490); <em><a href="#id17">backlink</a></em></p>
! <p>Inline emphasis start-string without end-string.</p>
! </div>
! </dd>
! </dl>
! </blockquote>
! <div class="system-message">
! <p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep101.txt</tt>, line 491)</p>
! <p>Block quote ends without a blank line; unexpected unindent.</p>
! </div>
! <p>}</p>
! </blockquote>
! <p>The Resource interface is specified in TEP 108. Before any call is
! made to the ATm128ADCSingle or ATm128ADCMultiple interfaces, the ADC
! MUST be reserved via the Resource interface. After an application
! has performed all desired operations on the ADC, it then MUST
! release the ADC via the Resource interface. In the meantime the ADC
! will be blocked for all other applications, therefore an application
! SHOULD minimize this reservation period. The ADC MUST NOT be released
! or stopped while an A/D conversion is in progress. Each platform MUST
! define an ATM128_ADC_PRESCALE constant which gives maximum A/D conversion
! precision (see the ATmega128 manual for details).</p>
! <p>The ATm128ADCSingle interface allows cancellation of outstanding
! conversions; the ATm128ADCMultiple does not (because it is hard to
! tell if there will be 0 or 1 more ADC samples after cancellation
! when using the ATmega128 free-running A/D conversion mode).</p>
! <p>Because of the possibility that samples may be imprecise after
! switching channels and/or reference voltages, and because there
! is a one sample delay on swithcing channels and reference voltages,
! ATm128ADCMultiple is complex. Two straightforward uses are:</p>
! <ol class="upperalpha">
! <li><p class="first">Acquire N samples from channel C:
! 1. call getData to start sampling on channel C at the desired rate</p>
! <div class="system-message">
! <p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">txt/tep101.txt</tt>, line 516)</p>
! <p>Unexpected indentation.</p>
! </div>
! <blockquote>
! <p>(note that the choice of prescalers is very limited, so you
! don't have many choices for sampling rate)</p>
! </blockquote>
! <div class="system-message">
! <p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep101.txt</tt>, line 518)</p>
! <p>Block quote ends without a blank line; unexpected unindent.</p>
! </div>
! <ol class="arabic simple" start="2">
! <li>ignore the first dataReady event</li>
! <li>use the results of the next N dataReady() events, return FALSE
! on the last one</li>
! </ol>
! </li>
! <li><p class="first">Acquire one sample each from channels C1, ..., Cn (this pseudocode
! assumes that none of these channels are differential)
! 1. call getData to start sampling on channel C1
! 2. on the ith dataReady event switch to channel Ci+1 by changing</p>
! <div class="system-message">
! <p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">txt/tep101.txt</tt>, line 526)</p>
! <p>Unexpected indentation.</p>
! </div>
! <blockquote>
! <p><a href="#id18" name="id19"><span class="problematic" id="id19">*</span></a>newChannel</p>
! <div class="system-message" id="id18">
! <p class="system-message-title">System Message: <a name="id18">WARNING/2</a> (<tt class="docutils">txt/tep101.txt</tt>, line 526); <em><a href="#id19">backlink</a></em></p>
! <p>Inline emphasis start-string without end-string.</p>
! </div>
! </blockquote>
! <div class="system-message">
! <p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep101.txt</tt>, line 527)</p>
! <p>Block quote ends without a blank line; unexpected unindent.</p>
! </div>
! <ol class="arabic simple" start="3">
! <li>the data passed to the ith dataReady event is for channel Ci-1
! (the data from the first dataReady event is ignored)</li>
! </ol>
! </li>
! </ol>
</blockquote>
</li>
***************
*** 855,860 ****
0-7 and MSP430ADC12ChannelConfigM MUST return the corresponding
configuration data for the platform or sensorboard.</p>
! <p>ii. For the ADC on the ATmega128 in the current implementation
! a port number exhaustively defines all relevant settings.</p>
</blockquote>
</li>
--- 1120,1209 ----
0-7 and MSP430ADC12ChannelConfigM MUST return the corresponding
configuration data for the platform or sensorboard.</p>
! <p>ii. Like the MSP430, the ATmega128 uses a configuration interface
! to acquire the per-channel settings. This interface is parameterised
! by channel number:</p>
! <blockquote>
! <dl class="docutils">
! <dt>configuration ADCC {</dt>
! <dd><dl class="first docutils">
! <dt>provides {</dt>
! <dd><p class="first last">interface Init;
! interface StdControl;
! interface Resource[uint8_t client];
! interface AcquireData[uint8_t port];
! interface AcquireDataNow[uint8_t port];
! interface AcquireDataBuffered[uint8_t port];</p>
! </dd>
! </dl>
! <div class="system-message">
! <p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep101.txt</tt>, line 635)</p>
! <p>Definition list ends without a blank line; unexpected unindent.</p>
! </div>
! <p class="last">}
! uses interface ATm128ADCConfig[uint8_t port];</p>
! </dd>
! </dl>
! <div class="system-message">
! <p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep101.txt</tt>, line 637)</p>
! <p>Definition list ends without a blank line; unexpected unindent.</p>
! </div>
! <p>}</p>
! <dl class="docutils">
! <dt>interface ATm128ADCConfig {</dt>
! <dd><dl class="first docutils">
! <dt>/**</dt>
! <dd><ul class="first simple">
! <li>Return the reference voltage to use for this channel</li>
! </ul>
! <div class="system-message">
! <p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep101.txt</tt>, line 642)</p>
! <p>Bullet list ends without a blank line; unexpected unindent.</p>
! </div>
! <p><a href="#id20" name="id21"><span class="problematic" id="id21">*</span></a>/</p>
! <div class="last system-message" id="id20">
! <p class="system-message-title">System Message: <a name="id20">WARNING/2</a> (<tt class="docutils">txt/tep101.txt</tt>, line 642); <em><a href="#id21">backlink</a></em></p>
! <p>Inline emphasis start-string without end-string.</p>
! </div>
! </dd>
! </dl>
! <div class="system-message">
! <p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep101.txt</tt>, line 643)</p>
! <p>Definition list ends without a blank line; unexpected unindent.</p>
! </div>
! <p>async command uint8_t getRefVoltage();</p>
! <dl class="docutils">
! <dt>/**</dt>
! <dd><ul class="first simple">
! <li>Return the prescaler value to use for this channel</li>
! </ul>
! <div class="system-message">
! <p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep101.txt</tt>, line 647)</p>
! <p>Bullet list ends without a blank line; unexpected unindent.</p>
! </div>
! <p><a href="#id22" name="id23"><span class="problematic" id="id23">*</span></a>/</p>
! <div class="last system-message" id="id22">
! <p class="system-message-title">System Message: <a name="id22">WARNING/2</a> (<tt class="docutils">txt/tep101.txt</tt>, line 647); <em><a href="#id23">backlink</a></em></p>
! <p>Inline emphasis start-string without end-string.</p>
! </div>
! </dd>
! </dl>
! <div class="system-message">
! <p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep101.txt</tt>, line 648)</p>
! <p>Definition list ends without a blank line; unexpected unindent.</p>
! </div>
! <p class="last">async command uint8_t getPrescaler();</p>
! </dd>
! </dl>
! <div class="system-message">
! <p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep101.txt</tt>, line 649)</p>
! <p>Definition list ends without a blank line; unexpected unindent.</p>
! </div>
! <p>}</p>
! </blockquote>
! <p>If the ATm128ADCConfig interface is not wired for a particular port,
! the default values of ATM128_ADC_VREF_OFF (use external AREF pin)
! and ATM128_ADC_PRESCALE are used. If the ATmega128 HAL1 indicates
! that the conversion may be imprecise, the conversion will be
! repeated automatically.</p>
</blockquote>
</li>
***************
*** 881,885 ****
mentioned in the <a class="reference" href="#introduction">Introduction</a>. Instead named sensor wrappers
provide platform independent access to the ADC which is covered in TEP
! 109 <a class="citation-reference" href="#tep109" id="id4" name="id4">[tep109]</a>.</p>
</div>
<div class="section" id="implementation">
--- 1230,1234 ----
mentioned in the <a class="reference" href="#introduction">Introduction</a>. Instead named sensor wrappers
provide platform independent access to the ADC which is covered in TEP
! 109 <a class="citation-reference" href="#tep109" id="id24" name="id24">[tep109]</a>.</p>
</div>
<div class="section" id="implementation">
***************
*** 935,939 ****
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
! <tr><td class="label"><a name="tep109">[tep109]</a></td><td><em>(<a class="fn-backref" href="#id1">1</a>, <a class="fn-backref" href="#id2">2</a>, <a class="fn-backref" href="#id4">3</a>)</em> TEP 109: Sensorboards. David Gay, Wei Hong, Philip Levis, and Joe Polastre.</td></tr>
</tbody>
</table>
--- 1284,1288 ----
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
! <tr><td class="label"><a name="tep109">[tep109]</a></td><td><em>(<a class="fn-backref" href="#id1">1</a>, <a class="fn-backref" href="#id2">2</a>, <a class="fn-backref" href="#id24">3</a>)</em> TEP 109: Sensorboards. David Gay, Wei Hong, Philip Levis, and Joe Polastre.</td></tr>
</tbody>
</table>
Index: tep102.html
===================================================================
RCS file: /cvsroot/tinyos/tinyos-1.x/beta/teps/html/tep102.html,v
retrieving revision 1.9
retrieving revision 1.10
diff -C2 -d -r1.9 -r1.10
*** tep102.html 6 Jun 2005 21:30:38 -0000 1.9
--- tep102.html 20 Sep 2005 16:30:23 -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>Timers</title>
<meta name="author" content="Cory Sharp" />
--- 4,8 ----
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
! <meta name="generator" content="Docutils 0.3.9: http://docutils.sourceforge.net/" />
<title>Timers</title>
<meta name="author" content="Cory Sharp" />
***************
*** 281,284 ****
--- 281,285 ----
</head>
<body>
+ <div class="document" id="timers">
<h1 class="title">Timers</h1>
<table class="docinfo" frame="void" rules="none">
***************
*** 300,306 ****
<tr class="field"><th class="docinfo-name">Draft-Created:</th><td class="field-body">22-Sep-2004</td>
</tr>
! <tr class="field"><th class="docinfo-name">Draft-Version:</th><td class="field-body">1.10</td>
</tr>
! <tr class="field"><th class="docinfo-name">Draft-Modified:</th><td class="field-body">2005-05-20</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>
--- 301,307 ----
<tr class="field"><th class="docinfo-name">Draft-Created:</th><td class="field-body">22-Sep-2004</td>
</tr>
! <tr class="field"><th class="docinfo-name">Draft-Version:</th><td class="field-body">1.14</td>
</tr>
! <tr class="field"><th class="docinfo-name">Draft-Modified:</th><td class="field-body">2005-09-01</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>
***************
*** 308,312 ****
</tbody>
</table>
- <div class="document" id="timers">
<div class="note">
<p class="first admonition-title">Note</p>
--- 309,312 ----
***************
*** 404,409 ****
period, whichever is convenient.</p>
</div>
! <div class="section" id="interfaces">
! <h1><a name="interfaces">Interfaces</a></h1>
<p>This TEP proposes these timer interfaces:</p>
<pre class="literal-block">
--- 404,498 ----
period, whichever is convenient.</p>
</div>
! <div class="section" id="hpl-layer">
! <h1><a name="hpl-layer">HPL Layer</a></h1>
! <p>At the lowest level, the HPLTimerC wraps all the hardware registers
! that control the hardware subsystem. The specifics of these interfaces
! are dependant on the chip that contains the timer subsystem. But certain
! guidelines and design paterns can be followed:</p>
! <blockquote>
! HplTimer<width> - get/set current time, overflow event, control, init
! HplCompare<width> - get/set compare time, fired event, control
! HplCapture<width> - get/set capture time, captured event, control, config</blockquote>
! <p>Note that on a platform that has multiple timers of variable width, it
! is helpful to abstract the width out of the interface at the HPL level
! if possible. This simplifies higher level interfaces by allowing them to
! wire to any timer in the system trivially.</p>
! <p>One sample set of HPL level interfaces follows:</p>
! <blockquote>
! <p>interface HplTimer<timer_size>
! {</p>
! <div class="system-message">
! <p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">txt/tep102.txt</tt>, line 145)</p>
! Unexpected indentation.</div>
! <blockquote>
! <p>/// Timer value register: Direct access
! async command timer_size get();
! async command void set( timer_size t );</p>
! <p>/// Interrupt signals
! async event void overflow(); //<! Signalled on overflow interrupt</p>
! <p>/// Interrupt flag utilites: Bit level set/clr
! async command void reset(); //<! Clear the overflow interrupt flag
! async command void start(); //<! Enable the overflow interrupt
! async command void stop(); //<! Turn off overflow interrupts
! async command bool test(); //<! Did overflow interrupt occur?
! async command bool isOn(); //<! Is overflow interrupt on?</p>
! <p>/// Clock initialization interface
! async command void off(); //<! Turn off the clock
! async command void setScale( uint8_t scale); //<! Turn on the clock
! async command uint8_t getScale(); //<! Get prescaler setting</p>
! </blockquote>
! <div class="system-message">
! <p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep102.txt</tt>, line 163)</p>
! Block quote ends without a blank line; unexpected unindent.</div>
! <p>}</p>
! <p>interface HplCompare<size_type>
! {</p>
! <div class="system-message">
! <p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">txt/tep102.txt</tt>, line 167)</p>
! Unexpected indentation.</div>
! <blockquote>
! <p>/// Compare value register: Direct access
! async command size_type get();
! async command void set(size_type t);</p>
! <p>/// Interrupt signals
! async event void fired(); //<! Signalled on compare interrupt</p>
! <p>/// Interrupt flag utilites: Bit level set/clr
! async command void reset(); //<! Clear the compare interrupt flag
! async command void start(); //<! Enable the compare interrupt
! async command void stop(); //<! Turn off comparee interrupts
! async command bool test(); //<! Did compare interrupt occur?
! async command bool isOn(); //<! Is compare interrupt on?</p>
! </blockquote>
! <div class="system-message">
! <p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep102.txt</tt>, line 180)</p>
! Block quote ends without a blank line; unexpected unindent.</div>
! <p>}</p>
! <p>interface HplCapture<size_type>
! {</p>
! <div class="system-message">
! <p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">txt/tep102.txt</tt>, line 184)</p>
! Unexpected indentation.</div>
! <blockquote>
! <p>/// Capture value register: Direct access
! async command size_type get();
! async command void set(size_type t);</p>
! <p>/// Interrupt signals
! async event void captured(size_type t); //<! Signalled on capture int</p>
! <p>/// Interrupt flag utilites: Bit level set/clr
! async command void reset(); //<! Clear the capture interrupt flag
! async command void start(); //<! Enable the capture interrupt
! async command void stop(); //<! Turn off capture interrupts
! async command bool test(); //<! Did capture interrupt occur?
! async command bool isOn(); //<! Is capture interrupt on?</p>
! <p>async command void setEdge(bool up); //<! True = detect rising edge</p>
! </blockquote>
! <div class="system-message">
! <p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep102.txt</tt>, line 199)</p>
! Block quote ends without a blank line; unexpected unindent.</div>
! <p>}</p>
! </blockquote>
! </div>
! <div class="section" id="hal-interfaces">
! <h1><a name="hal-interfaces">HAL: Interfaces</a></h1>
<p>This TEP proposes these timer interfaces:</p>
<pre class="literal-block">
***************
*** 418,424 ****
and Counter interfaces are used by the TinyOS timer system and
advanced user components.</p>
<div class="section" id="alarm">
<h2><a name="alarm">Alarm</a></h2>
! <p>All commands and events of the Alarm interface are asynchronous (or
in "interrupt context"). The Alarm interface provides a set of
"basic" commands for common usage and provides a set of "extended"
--- 507,547 ----
and Counter interfaces are used by the TinyOS timer system and
advanced user components.</p>
+ <div class="section" id="counter">
+ <h2><a name="counter">Counter</a></h2>
+ <p>A Counter component will increase the width of a low-level hardware timer
+ by wrapping the overflow event and incrementing its higher order bits.
+ These higher order bits are considered extra state over the HPL register
+ layer, and therefore qualify all Counters as HAL components.
+ The Counter interface returns the current time and provides commands
+ and an event for managing overflow conditions. These overflow
+ commands and events are necessary for properly deriving larger width
+ Counters from smaller widths.</p>
+ <pre class="literal-block">
+ interface Counter<precision_tag,size_type>
+ {
+ async command size_type get();
+ async command bool isOverflowPending();
+ async command void clearOverflow();
+ async event void overflow();
+ }
+ </pre>
+ <dl class="docutils">
+ <dt>get() </dt>
+ <dd>return the current time.</dd>
+ <dt>isOverflowPending() </dt>
+ <dd>return TRUE if an overflow interrupt will occur after the outermost
+ atomic block is exits. FALSE otherwise.</dd>
+ <dt>clearOverflow() </dt>
+ <dd>cancel the pending overflow interrupt.</dd>
+ <dt>overflow() </dt>
+ <dd>signals that an overflow in the current time. That is, the current
+ time has wrapped around from its maximum value to zero.</dd>
+ </dl>
+ </div>
<div class="section" id="alarm">
<h2><a name="alarm">Alarm</a></h2>
! <p>Alarm components are extensions of Counters that signal an event
! when their Compare register detects the alarm time has been hit.
! All commands and events of the Alarm interface are asynchronous (or
in "interrupt context"). The Alarm interface provides a set of
"basic" commands for common usage and provides a set of "extended"
***************
*** 480,511 ****
</dl>
</div>
- <div class="section" id="counter">
- <h2><a name="counter">Counter</a></h2>
- <p>The Counter interface returns the current time and provides commands
- and an event for managing overflow conditions. These overflow
- commands and events are necessary for properly deriving larger width
- Counters from smaller widths.</p>
- <pre class="literal-block">
- interface Counter<precision_tag,size_type>
- {
- async command size_type get();
- async command bool isOverflowPending();
- async command void clearOverflow();
- async event void overflow();
- }
- </pre>
- <dl class="docutils">
- <dt>get() </dt>
- <dd>return the current time.</dd>
- <dt>isOverflowPending() </dt>
- <dd>return TRUE if an overflow interrupt will occur after the outermost
- atomic block is exits. FALSE otherwise.</dd>
- <dt>clearOverflow() </dt>
- <dd>cancel the pending overflow interrupt.</dd>
- <dt>overflow() </dt>
- <dd>signals that an overflow in the current time. That is, the current
- time has wrapped around from its maximum value to zero.</dd>
- </dl>
- </div>
<div class="section" id="localtime">
<h2><a name="localtime">LocalTime</a></h2>
--- 603,606 ----
***************
*** 586,591 ****
</div>
</div>
! <div class="section" id="platform-independent-components">
! <h1><a name="platform-independent-components">Platform independent components</a></h1>
<p>A number of platform independent generic components are provided by
the TinyOS timer system:</p>
--- 681,686 ----
</div>
</div>
! <div class="section" id="hil-platform-independent-components">
! <h1><a name="hil-platform-independent-components">HIL: Platform independent components</a></h1>
<p>A number of platform independent generic components are provided by
the TinyOS timer system:</p>
***************
*** 893,896 ****
--- 988,1031 ----
</blockquote>
</div>
+ <div class="section" id="platform-specific-mapping">
+ <h1><a name="platform-specific-mapping">Platform Specific Mapping</a></h1>
+ <blockquote>
+ <ol class="loweralpha">
+ <li><dl class="first docutils">
+ <dt>Mica2</dt>
+ <dd><p class="first last">Timer Size Clock Source Usage
+ ----- ---- ------------ -----
+ Timer0 8-bit 32khz Application (TimerMilli)
+ Timer1 16-bit CPU (7.4/8MHz) Not used
+ Timer2 8-bit CPU (7.4/8MHz) Not used
+ Timer3 16-bit CPU (7.4/8MHz) Not used</p>
+ </dd>
+ </dl>
+ </li>
+ <li><dl class="first docutils">
+ <dt>Mica2dot</dt>
+ <dd><p class="first last">Timer Size Clock Source Usage
+ ----- ---- ------------ -----
+ Timer0 8-bit 32khz Application (TimerMilli)
+ Timer1 16-bit CPU (4MHz) Not used
+ Timer2 8-bit CPU (4MHz) Not used
+ Timer3 16-bit CPU (4MHz) Not used</p>
+ </dd>
+ </dl>
+ </li>
+ <li><dl class="first docutils">
+ <dt>MicaZ</dt>
+ <dd><p class="first last">Timer Size Clock Source Usage
+ ----- ---- ------------ -----
+ Timer0 8-bit 32khz Application (TimerMilli)
+ Timer1 16-bit CPU (7.4/8MHz) [CaptureA] CC2420 SFD Pin
+ Timer2 8-bit CPU (7.4/8MHz) CC2420: high resolution (32uSec) timing
+ Timer3 16-bit CPU (7.4/8MHz) Not used</p>
+ </dd>
+ </dl>
+ </li>
+ </ol>
+ </blockquote>
+ </div>
<div class="section" id="implementation">
<h1><a name="implementation">Implementation</a></h1>
***************
*** 930,933 ****
--- 1065,1075 ----
<div class="line"><br /></div>
<div class="line">email - <a class="reference" href="mailto:cssharp@eecs.berkeley.edu">cssharp@eecs.berkeley.edu</a></div>
+ <div class="line"><br /></div>
+ <div class="line">Martin Turon</div>
+ <div class="line">P.O. Box 8525</div>
+ <div class="line">Berkeley, CA 94707</div>
+ <div class="line"><br /></div>
+ <div class="line">phone - +1 408 965 3355</div>
+ <div class="line">email - <a class="reference" href="mailto:mturon@xbow.com">mturon@xbow.com</a></div>
</div>
</div>
Index: tep103.html
===================================================================
RCS file: /cvsroot/tinyos/tinyos-1.x/beta/teps/html/tep103.html,v
retrieving revision 1.5
retrieving revision 1.6
diff -C2 -d -r1.5 -r1.6
*** tep103.html 6 Jun 2005 21:30:39 -0000 1.5
--- tep103.html 20 Sep 2005 16:30:23 -0000 1.6
***************
*** 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>Permanent Data Storage (Flash)</title>
<meta name="author" content="David Gay, Jonathan Hui" />
--- 4,8 ----
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
! <meta name="generator" content="Docutils 0.3.9: http://docutils.sourceforge.net/" />
<title>Permanent Data Storage (Flash)</title>
<meta name="author" content="David Gay, Jonathan Hui" />
***************
*** 281,284 ****
--- 281,285 ----
</head>
<body>
+ <div class="document" id="permanent-data-storage-flash">
<h1 class="title">Permanent Data Storage (Flash)</h1>
<table class="docinfo" frame="void" rules="none">
***************
*** 308,312 ****
</tbody>
</table>
- <div class="document" id="permanent-data-storage-flash">
<div class="note">
<p class="first admonition-title">Note</p>
--- 309,312 ----
Index: tep104.html
===================================================================
RCS file: /cvsroot/tinyos/tinyos-1.x/beta/teps/html/tep104.html,v
retrieving revision 1.5
retrieving revision 1.6
diff -C2 -d -r1.5 -r1.6
*** tep104.html 6 Jun 2005 21:30:39 -0000 1.5
--- tep104.html 20 Sep 2005 16:30:23 -0000 1.6
***************
*** 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>Radio Physical Layer</title>
<meta name="author" content="Kevin Klues" />
--- 4,8 ----
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
! <meta name="generator" content="Docutils 0.3.9: http://docutils.sourceforge.net/" />
<title>Radio Physical Layer</title>
<meta name="author" content="Kevin Klues" />
***************
*** 281,284 ****
--- 281,285 ----
</head>
<body>
+ <div class="document" id="radio-physical-layer">
<h1 class="title">Radio Physical Layer</h1>
<table class="docinfo" frame="void" rules="none">
***************
*** 306,310 ****
</tbody>
</table>
- <div class="document" id="radio-physical-layer">
<div class="note">
<p class="first admonition-title">Note</p>
--- 307,310 ----
Index: tep105.html
===================================================================
RCS file: /cvsroot/tinyos/tinyos-1.x/beta/teps/html/tep105.html,v
retrieving revision 1.5
retrieving revision 1.6
diff -C2 -d -r1.5 -r1.6
*** tep105.html 6 Jun 2005 21:30:39 -0000 1.5
--- tep105.html 20 Sep 2005 16:30:23 -0000 1.6
***************
*** 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>Radio Link Layer</title>
<meta name="author" content="Joe Polastre" />
--- 4,8 ----
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
! <meta name="generator" content="Docutils 0.3.9: http://docutils.sourceforge.net/" />
<title>Radio Link Layer</title>
<meta name="author" content="Joe Polastre" />
***************
*** 281,284 ****
--- 281,285 ----
</head>
<body>
+ <div class="document" id="radio-link-layer">
<h1 class="title">Radio Link Layer</h1>
<table class="docinfo" frame="void" rules="none">
***************
*** 308,312 ****
</tbody>
</table>
- <div class="document" id="radio-link-layer">
<div class="note">
<p class="first admonition-title">Note</p>
--- 309,312 ----
Index: tep106.html
===================================================================
RCS file: /cvsroot/tinyos/tinyos-1.x/beta/teps/html/tep106.html,v
retrieving revision 1.6
retrieving revision 1.7
diff -C2 -d -r1.6 -r1.7
*** tep106.html 6 Jun 2005 21:30:39 -0000 1.6
--- tep106.html 20 Sep 2005 16:30:23 -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>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.3.9: http://docutils.sourceforge.net/" />
<title>Schedulers and Tasks</title>
<meta name="author" content="Philip Levis and Cory Sharp" />
***************
*** 281,284 ****
--- 281,285 ----
</head>
<body>
+ <div class="document" id="schedulers-and-tasks">
<h1 class="title">Schedulers and Tasks</h1>
<table class="docinfo" frame="void" rules="none">
***************
*** 300,306 ****
<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.8</td>
</tr>
! <tr class="field"><th class="docinfo-name">Draft-Modified:</th><td class="field-body">2005-02-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>
--- 301,307 ----
<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.12</td>
</tr>
! <tr class="field"><th class="docinfo-name">Draft-Modified:</th><td class="field-body">2005-07-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>
***************
*** 308,312 ****
</tbody>
</table>
- <div class="document" id="schedulers-and-tasks">
<div class="note">
<p class="first admonition-title">Note</p>
--- 309,312 ----
***************
*** 318,322 ****
<div class="section" id="abstract">
<h1><a name="abstract">Abstract</a></h1>
! <p>This memo documents the structure and implementation of TinyOS tasks
and task schedulers in TinyOS 2.x.</p>
</div>
--- 318,322 ----
<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>
***************
*** 335,344 ****
<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)[1], which
enable a program to defer a computation or operation until a later
time. TinyOS tasks run to completion and do not pre-empt one
! another[2]. These two constraints mean that code called from tasks
runs synchonously with respect to other tasks. Put another way, tasks
! are atomic with respect to other tasks[3].</p>
<p>In TinyOS 1.x, the nesC language supports tasks through two
mechanisms, <tt class="docutils literal"><span class="pre">task</span></tt> declarations and <tt class="docutils literal"><span class="pre">post</span></tt> expressions:</p>
--- 335,344 ----
<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)[1]_, which
enable a program to defer a computation or operation until a later
time. TinyOS tasks run to completion and do not pre-empt one
! another. These two constraints mean that code called from tasks
runs synchonously with respect to other tasks. Put another way, tasks
! are atomic with respect to other tasks[2]_.</p>
<p>In TinyOS 1.x, the nesC language supports tasks through two
mechanisms, <tt class="docutils literal"><span class="pre">task</span></tt> declarations and <tt class="docutils literal"><span class="pre">post</span></tt> expressions:</p>
***************
*** 359,363 ****
posted multiple times. For example, if a task is posted twice in quick
succession and the first succeeds while the second fails, then the
! task will be run in the future; for this reason, even if a <tt class="docutils literal"><span class="pre">post</span></tt>
fails, the task may run.</p>
<p>The TinyOS 1.x scheduler is implemented as a set of C functions in the
--- 359,363 ----
posted multiple times. For example, if a task is posted twice in quick
succession and the first succeeds while the second fails, then the
! task will be run once in the future; for this reason, even if a <tt class="docutils literal"><span class="pre">post</span></tt>
fails, the task may run.</p>
<p>The TinyOS 1.x scheduler is implemented as a set of C functions in the
***************
*** 399,407 ****
buffer). As the <tt class="docutils literal"><span class="pre">sendDone()</span></tt> event was lost, this will never occur,
and the application stops sending network traffic.</p>
! <p>The solution to this 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. The TinyOS 1.x model
! prevents it from doing any better.</p>
</div>
<div class="section" id="tasks-in-tinyos-2-x">
--- 399,407 ----
buffer). As the <tt class="docutils literal"><span class="pre">sendDone()</span></tt> event was lost, this will never 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.
! The TinyOS 1.x model prevents it from doing any better.</p>
</div>
<div class="section" id="tasks-in-tinyos-2-x">
***************
*** 420,425 ****
<div class="line"><tt class="docutils literal"><span class="pre">interface</span> <span class="pre">TaskParameter</span> <span class="pre">{</span></tt></div>
<div class="line-block">
! <div class="line"><tt class="docutils literal"><span class="pre">async</span> <span class="pre">error_t</span> <span class="pre">command</span> <span class="pre">post(uint16_t</span> <span class="pre">param);</span></tt></div>
! <div class="line"><tt class="docutils literal"><span class="pre">event</span> <span class="pre">void</span> <span class="pre">run(uin16_t</span> <span class="pre">param);</span></tt></div>
</div>
<div class="line"><tt class="docutils literal"><span class="pre">}</span></tt></div>
--- 420,425 ----
<div class="line"><tt class="docutils literal"><span class="pre">interface</span> <span class="pre">TaskParameter</span> <span class="pre">{</span></tt></div>
<div class="line-block">
! <div class="line"><tt class="docutils literal"><span class="pre">async</span> <span class="pre">error_t</span> <span class="pre">command</span> <span class="pre">postTask(uint16_t</span> <span class="pre">param);</span></tt></div>
! <div class="line"><tt class="docutils literal"><span class="pre">event</span> <span class="pre">void</span> <span class="pre">runTask(uin16_t</span> <span class="pre">param);</span></tt></div>
</div>
<div class="line"><tt class="docutils literal"><span class="pre">}</span></tt></div>
***************
*** 427,437 ****
<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">run</span></tt> event with the passed parameter, which contains
the task's logic.</p>
<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. In TinyOS 2.x, a basic post will
only fail if the task has already been posted and has not started
! execution. A task can always run, but can only have one outstanding
post at any time. If a component needs to post task several times,
then the end of the task logic can repost itself as need be.</p>
--- 427,437 ----
<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.</p>
<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 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. If a component needs to post task several times,
then the end of the task logic can repost itself as need be.</p>
***************
*** 464,468 ****
<div class="line"><tt class="docutils literal"><span class="pre">}</span></tt></div>
</div>
! <p>The Scheduler interface has commands for initialization and running
tasks, and is used by TinyOS to execute tasks.</p>
<div class="line-block">
--- 464,474 ----
<div class="line"><tt class="docutils literal"><span class="pre">}</span></tt></div>
</div>
! <p>A scheduler MUST provide a parameterized TaskBasic interface.
! If a call to TaskBasic.postTask() returns SUCCESS, the scheduler MUST run it
! eventually. 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.</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>
<div class="line-block">
***************
*** 480,493 ****
scheduler should do if there are no tasks to execute. If sleep is
FALSE, then the command will return immediately with FALSE as a return
! value. If sleep is TRUE, then the command will not return until a task
is executed, and SHOULD put the CPU to sleep until a new task arrives.
Calls of runNextTask(FALSE) may return TRUE or FALSE; calls of
runNextTask(TRUE) always return TRUE.</p>
! <p>The TaskBasic interface is this:</p>
<div class="line-block">
<div class="line"><tt class="docutils literal"><span class="pre">interface</span> <span class="pre">TaskBasic</span> <span class="pre">{</span></tt></div>
<div class="line-block">
! <div class="line"><tt class="docutils literal"><span class="pre">async</span> <span class="pre">command</span> <span class="pre">error_t</span> <span class="pre">post();</span></tt></div>
! <div class="line"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">event</span> <span class="pre">run();</span></tt></div>
</div>
<div class="line"><tt class="docutils literal"><span class="pre">}</span></tt></div>
--- 486,499 ----
scheduler should do if there are no tasks to execute. If sleep is
FALSE, then the command will return immediately with FALSE as a return
! value. If sleep is TRUE, then the command MUST NOT return until a task
is executed, and SHOULD put the CPU to sleep until a new task arrives.
Calls of runNextTask(FALSE) may return TRUE or FALSE; calls of
runNextTask(TRUE) always return TRUE.</p>
! <p>This is the TaskBasic interface:</p>
<div class="line-block">
<div class="line"><tt class="docutils literal"><span class="pre">interface</span> <span class="pre">TaskBasic</span> <span class="pre">{</span></tt></div>
<div class="line-block">
! <div class="line"><tt class="docutils literal"><span class="pre">async</span> <span class="pre">command</span> <span class="pre">error_t</span> <span class="pre">postTask();</span></tt></div>
! <div class="line"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">event</span> <span class="pre">runTask();</span></tt></div>
</div>
<div class="line"><tt class="docutils literal"><span class="pre">}</span></tt></div>
***************
*** 497,503 ****
interface: the task body is the run event. When a component uses the
<tt class="docutils literal"><span class="pre">post</span></tt> keyword, it calls the post command. Each TaskBasic MUST be
! wired to the Scheduler with a unique identifier.</p>
<p>The SchedulerBasic implementation uses these identifiers as its queue
! entries.When TinyOS tells the Scheduler to run a task, it pulls the
next identifier off the queue and uses it dispatches on the
parameterized TaskBasic interface.</p>
--- 503,513 ----
interface: the task body is the run event. When a component uses the
<tt class="docutils literal"><span class="pre">post</span></tt> keyword, it calls the post 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">"BasicScheduler.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>
! keywords are used.</p>
<p>The SchedulerBasic implementation uses these identifiers as its queue
! entries. When TinyOS tells the Scheduler to run a task, it pulls the
next identifier off the queue and uses it dispatches on the
parameterized TaskBasic interface.</p>
***************
*** 523,528 ****
<div class="line"><tt class="docutils literal"><span class="pre">interface</span> <span class="pre">TaskEDF</span> <span class="pre">{</span></tt></div>
<div class="line-block">
! <div class="line"><tt class="docutils literal"><span class="pre">async</span> <span class="pre">command</span> <span class="pre">error_t</span> <span class="pre">post(uint16_t</span> <span class="pre">deadline);</span></tt></div>
! <div class="line"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">event</span> <span class="pre">run();</span></tt></div>
</div>
<div class="line"><tt class="docutils literal"><span class="pre">}</span></tt></div>
--- 533,538 ----
<div class="line"><tt class="docutils literal"><span class="pre">interface</span> <span class="pre">TaskEDF</span> <span class="pre">{</span></tt></div>
<div class="line-block">
! <div class="line"><tt class="docutils literal"><span class="pre">async</span> <span class="pre">command</span> <span class="pre">error_t</span> <span class="pre">postTask(uint16_t</span> <span class="pre">deadlineMs);</span></tt></div>
! <div class="line"><tt class="docutils literal"><span class="pre">event</span> <span class="pre">void</span> <span class="pre">runTask();</span></tt></div>
</div>
<div class="line"><tt class="docutils literal"><span class="pre">}</span></tt></div>
***************
*** 560,565 ****
</div>
<p>For a module to have an earliest deadline first task, it uses the
! TaskEDF interface. Its configuration SHOULD wire it to TinyScheduler,
! using a unique value generated from the key "TaskEDF." For example:</p>
<div class="line-block">
<div class="line"><tt class="docutils literal"><span class="pre">configuration</span> <span class="pre">SomethingC</span> <span class="pre">{</span></tt></div>
--- 570,578 ----
</div>
<p>For a module to have an earliest deadline first task, it uses the
! TaskEDF interface. Its configuration SHOULD wire it to TinyScheduler.
! The key used for task unique identifiers MUST be "TinyScheduler.TaskInterface",
! where <em>TaskInterface</em> is the name of the new task interface as presented
! by the scheduler. For example, the module SomethingM requires two EDF
! tasks:</p>
<div class="line-block">
<div class="line"><tt class="docutils literal"><span class="pre">configuration</span> <span class="pre">SomethingC</span> <span class="pre">{</span></tt></div>
***************
*** 571,577 ****
<div class="line-block">
<div class="line"><tt class="docutils literal"><span class="pre">components</span> <span class="pre">SomethingM,</span> <span class="pre">TinyScheduler;</span></tt></div>
! <div class="line"><tt class="docutils literal"><span class="pre">SomethingM.TaskEDF</span> <span class="pre">-></span> <span class="pre">TinyScheduler.TaskEDF["TaskEDF"];</span></tt></div>
! <div class="line"><tt class="docutils literal"><span class="pre">TaskBasic</span> <span class="pre">=</span> <span class="pre">SchedulerEDF;</span></tt></div>
! <div class="line"><tt class="docutils literal"><span class="pre">TaskEDF</span> <span class="pre">=</span> <span class="pre">SchedulerEDF;</span></tt></div>
</div>
<div class="line"><tt class="docutils literal"><span class="pre">}</span></tt></div>
--- 584,647 ----
<div class="line-block">
<div class="line"><tt class="docutils literal"><span class="pre">components</span> <span class="pre">SomethingM,</span> <span class="pre">TinyScheduler;</span></tt></div>
! <div class="line"><tt class="docutils literal"><span class="pre">SomethingM.SendTask</span> <span class="pre">-></span> <span class="pre">TinyScheduler.TaskEDF["TinyScheduler.TaskEDF"];</span></tt></div>
! <div class="line"><tt class="docutils literal"><span class="pre">SomethingM.SenseTask</span> <span class="pre">-></span> <span class="pre">TinyScheduler.TaskEDF["TinyScheduler.TaskEDF"];</span></tt></div>
! </div>
! <div class="line"><tt class="docutils literal"><span class="pre">}</span></tt></div>
! </div>
! <p>The module SomethingM also has a basic task. The nesC compiler
! automatically transforms task keywords into BasicTask interfaces and
! wires them appropriately. Therefore, for basic tasks, a component
! author can either use the <tt class="docutils literal"><span class="pre">task</span></tt> and <tt class="docutils literal"><span class="pre">post</span></tt> keywords or use a TaskBasic
! interface. A component SHOULD use the keywords whenever possible, and it
! MUST NOT mix the two syntaxes for a given task. This is an example
! implementation of SomethingM that uses keywords for basic tasks:</p>
! <div class="line-block">
! <div class="line"><tt class="docutils literal"><span class="pre">module</span> <span class="pre">SomethingM</span> <span class="pre">{</span></tt></div>
! <div class="line-block">
! <div class="line"><tt class="docutils literal"><span class="pre">uses</span> <span class="pre">interface</span> <span class="pre">TaskEDF</span> <span class="pre">as</span> <span class="pre">SendTask</span></tt></div>
! <div class="line"><tt class="docutils literal"><span class="pre">uses</span> <span class="pre">interface</span> <span class="pre">TaskEDF</span> <span class="pre">as</span> <span class="pre">SenseTask</span></tt></div>
! </div>
! <div class="line"><tt class="docutils literal"><span class="pre">}</span></tt></div>
! <div class="line"><tt class="docutils literal"><span class="pre">implementation</span> <span class="pre">{</span></tt></div>
! <div class="line-block">
! <div class="line"><tt class="docutils literal"><span class="pre">//</span> <span class="pre">The</span> <span class="pre">TaskBasic,</span> <span class="pre">written</span> <span class="pre">with</span> <span class="pre">keywords</span></tt></div>
! <div class="line"><tt class="docutils literal"><span class="pre">task</span> <span class="pre">void</span> <span class="pre">cleanupTask()</span> <span class="pre">{</span> <span class="pre">...</span> <span class="pre">some</span> <span class="pre">logic</span> <span class="pre">...</span> <span class="pre">}</span></tt></div>
! <div class="line"><tt class="docutils literal"><span class="pre">event</span> <span class="pre">void</span> <span class="pre">SendTask.runTask()</span> <span class="pre">{</span> <span class="pre">...</span> <span class="pre">some</span> <span class="pre">logic</span> <span class="pre">...</span> <span class="pre">}</span></tt></div>
! <div class="line"><tt class="docutils literal"><span class="pre">event</span> <span class="pre">void</span> <span class="pre">SenseTask.runTask()</span> <span class="pre">{</span> <span class="pre">...</span> <span class="pre">some</span> <span class="pre">logic</span> <span class="pre">...</span> <span class="pre">}</span></tt></div>
! <div class="line"><br /></div>
! <div class="line"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">internal_function()</span> <span class="pre">{</span></tt></div>
! <div class="line-block">
! <div class="line"><tt class="docutils literal"><span class="pre">call</span> <span class="pre">SenseTask.postTask(20);</span></tt></div>
! <div class="line"><tt class="docutils literal"><span class="pre">call</span> <span class="pre">SendTask.postTask(100);</span></tt></div>
! <div class="line"><tt class="docutils literal"><span class="pre">post</span> <span class="pre">cleanupTask();</span></tt></div>
! </div>
! <div class="line"><tt class="docutils literal"><span class="pre">}</span></tt></div>
! </div>
! <div class="line"><tt class="docutils literal"><span class="pre">}</span></tt></div>
! </div>
! <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
! tasks and high-priority tasks. The scheduler always selects a task
! for the high priority queue before the standard queue:</p>
! <div class="line-block">
! <div class="line"><tt class="docutils literal"><span class="pre">configuration</span> <span class="pre">TinyScheduler</span> <span class="pre">{</span></tt></div>
! <div class="line-block">
! <div class="line"><tt class="docutils literal"><span class="pre">provides</span> <span class="pre">interface</span> <span class="pre">Scheduler;</span></tt></div>
! <div class="line"><tt class="docutils literal"><span class="pre">provides</span> <span class="pre">interface</span> <span class="pre">TaskBasic[uint8_t</span> <span class="pre">taskID];</span></tt></div>
! <div class="line"><tt class="docutils literal"><span class="pre">provides</span> <span class="pre">interface</span> <span class="pre">TaskBasic[uint8_t</span> <span class="pre">taskID]</span> <span class="pre">as</span> <span class="pre">TaskHighPriority;</span></tt></div>
! </div>
! <div class="line"><tt class="docutils literal"><span class="pre">}</span></tt></div>
! </div>
! <p>A component that uses a high priority task would then wire to
! TaskHighPriority with the key "TinyScheduler.TaskHighPriority":</p>
! <div class="line-block">
! <div class="line"><tt class="docutils literal"><span class="pre">configuration</span> <span class="pre">SomethingElseC</span> <span class="pre">{</span></tt></div>
! <div class="line"><tt class="docutils literal"><span class="pre">}</span></tt></div>
! <div class="line"><tt class="docutils literal"><span class="pre">implementation</span> <span class="pre">{</span></tt></div>
! <div class="line-block">
! <div class="line"><tt class="docutils literal"><span class="pre">components</span> <span class="pre">TinyScheduler,</span> <span class="pre">SomethingElseM;</span></tt></div>
! <div class="line"><tt class="docutils literal"><span class="pre">SomethingElseM.RetransmitTask</span> <span class="pre">-></span> <span class="pre">TinyScheduler.TaskHighPriority[unique("TinyScheduler.TaskHighPriority")];</span></tt></div>
</div>
<div class="line"><tt class="docutils literal"><span class="pre">}</span></tt></div>
***************
*** 587,602 ****
<div class="line"><br /></div>
<div class="line">phone - +1 510 290 5283</div>
- <div class="line"><br /></div>
<div class="line">email - <a class="reference" href="mailto:pal@cs.berkeley.edu">pal@cs.berkeley.edu</a></div>
</div>
</div>
<div class="section" id="citations">
<h1><a name="citations">7. Citations</a></h1>
! <table class="docutils citation" frame="void" id="rst" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
! <tr><td class="label"><a name="rst">[rst]</a></td><td>reStructuredText Markup Specification. <<a class="reference" href="http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html">http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html</a>></td></tr>
</tbody>
</table>
</div>
</div>
--- 657,696 ----
<div class="line"><br /></div>
<div class="line">phone - +1 510 290 5283</div>
<div class="line">email - <a class="reference" href="mailto:pal@cs.berkeley.edu">pal@cs.berkeley.edu</a></div>
+ <div class="line"><br /></div>
+ <div class="line">Cory Sharp</div>
+ <div class="line">410 Soda Hall</div>
+ <div class="line">UC Berkeley</div>
+ <div class="line">Berkeley, CA 94720</div>
+ <div class="line"><br /></div>
+ <div class="line">email - <a class="reference" href="mailto:cssharp@eecs.berkeley.edu">cssharp@eecs.berkeley.edu</a></div>
</div>
</div>
<div class="section" id="citations">
<h1><a name="citations">7. 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>Erik Cota-Robles and James P. Held. "A Comparison of Windows</td></tr>
! </tbody>
! </table>
! <div class="system-message">
! <p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep106.txt</tt>, line 369)</p>
! Explicit markup ends without a blank line; unexpected unindent.</div>
! <p>Driver Model Latency Performance on Windows NT and Windows 98." In
! <em>Proceedings of the Third Symposium on Operating System Design
! and Implementation (OSDI).</em></p>
! <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>David Gay, Philip Levis, Rob von Behren, Matt Welsh, Eric Brewer</td></tr>
</tbody>
</table>
+ <div class="system-message">
+ <p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep106.txt</tt>, line 374)</p>
+ Explicit markup ends without a blank line; unexpected unindent.</div>
+ <p>and David Culler. "The <em>nesC</em> Language: A Holistic Approach to Networked
+ Embedded Systems." In <em>Proceedings of the ACM SIGPLAN 2003 Conference on
+ Programming Language Design and Implementation (PLDI).</em></p>
</div>
</div>
Index: tep107.html
===================================================================
RCS file: /cvsroot/tinyos/tinyos-1.x/beta/teps/html/tep107.html,v
retrieving revision 1.4
retrieving revision 1.5
diff -C2 -d -r1.4 -r1.5
*** tep107.html 6 Jun 2005 21:30:39 -0000 1.4
--- tep107.html 20 Sep 2005 16:30:23 -0000 1.5
***************
*** 4,9 ****
<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>Boot Sequence</title>
<meta name="author" content="Philip Levis" />
<style type="text/css">
--- 4,9 ----
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
! <meta name="generator" content="Docutils 0.3.9: http://docutils.sourceforge.net/" />
! <title>TinyOS 2.x Boot Sequence</title>
<meta name="author" content="Philip Levis" />
<style type="text/css">
***************
*** 281,285 ****
</head>
<body>
! <h1 class="title">Boot Sequence</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
--- 281,286 ----
</head>
<body>
! <div class="document" id="tinyos-2-x-boot-sequence">
! <h1 class="title">TinyOS 2.x Boot Sequence</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
***************
*** 300,306 ****
<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.2</td>
</tr>
! <tr class="field"><th class="docinfo-name">Draft-Modified:</th><td class="field-body">2005-02-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>
--- 301,307 ----
<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">2005-07-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>
***************
*** 308,312 ****
</tbody>
</table>
- <div class="document" id="boot-sequence">
<div class="note">
<p class="first admonition-title">Note</p>
--- 309,312 ----
***************
*** 404,413 ****
<p>The TinyOS 2.x boot sequence uses three interfaces:</p>
<blockquote>
! o Initialize, for initializing component/hardware state
o Scheduler, for initializing and running tasks
o Boot, for signalling that the system has successfully booted</blockquote>
! <p>The Initialize interface has a single command, init():</p>
<div class="line-block">
! <div class="line"><tt class="docutils literal"><span class="pre">interface</span> <span class="pre">Initialization</span> <span class="pre">{</span></tt></div>
<div class="line-block">
<div class="line"><tt class="docutils literal"><span class="pre">command</span> <span class="pre">error_t</span> <span class="pre">init();</span></tt></div>
--- 404,413 ----
<p>The TinyOS 2.x boot sequence uses three interfaces:</p>
<blockquote>
! o Init, for initializing component/hardware state
o Scheduler, for initializing and running tasks
o Boot, for signalling that the system has successfully booted</blockquote>
! <p>The Init interface has a single command, init():</p>
<div class="line-block">
! <div class="line"><tt class="docutils literal"><span class="pre">interface</span> <span class="pre">Init</span> <span class="pre">{</span></tt></div>
<div class="line-block">
<div class="line"><tt class="docutils literal"><span class="pre">command</span> <span class="pre">error_t</span> <span class="pre">init();</span></tt></div>
***************
*** 415,419 ****
<div class="line"><tt class="docutils literal"><span class="pre">}</span></tt></div>
</div>
! <p>It provides a synchronous interface, enabling initialization
ordering. Unlike normal execution, in which operations from a wide
range of components need to be interleaved effectively, initialization
--- 415,419 ----
<div class="line"><tt class="docutils literal"><span class="pre">}</span></tt></div>
</div>
! <p>Init provides a synchronous interface, enabling initialization
ordering. Unlike normal execution, in which operations from a wide
range of components need to be interleaved effectively, initialization
***************
*** 421,426 ****
until initialization is complete. If a particular component's
initialization requires waiting for interrupts or other asynchronous
! events, then it must explicitly wait for them (e.g., by sleeping or
! with a spin loop), and not return until complete. Otherwise the system
may start before initialization is complete.</p>
<p>The Scheduler interface is for initializing and controlling task
--- 421,426 ----
until initialization is complete. If a particular component's
initialization requires waiting for interrupts or other asynchronous
! events, then it must explicitly wait for them (e.g.,
! with a spin loop), MUST NOT return until complete. Otherwise the system
may start before initialization is complete.</p>
<p>The Scheduler interface is for initializing and controlling task
***************
*** 436,441 ****
</div>
</div>
! <div class="section" id="tinyos-2-x-boot-sequence">
! <h1><a name="tinyos-2-x-boot-sequence">4. TinyOS 2.x Boot Sequence</a></h1>
<p>The module RealMain implements the standard TinyOS 2.x boot sequence.
The configuration Main wires some of RealMain's interfaces to
--- 436,441 ----
</div>
</div>
! <div class="section" id="id1">
! <h1><a name="id1">4. TinyOS 2.x Boot Sequence</a></h1>
<p>The module RealMain implements the standard TinyOS 2.x boot sequence.
The configuration Main wires some of RealMain's interfaces to
***************
*** 449,454 ****
<div class="line-block">
<div class="line"><tt class="docutils literal"><span class="pre">interface</span> <span class="pre">Scheduler;</span></tt></div>
! <div class="line"><tt class="docutils literal"><span class="pre">interface</span> <span class="pre">Initialize</span> <span class="pre">as</span> <span class="pre">PlatformInit;</span></tt></div>
! <div class="line"><tt class="docutils literal"><span class="pre">interface</span> <span class="pre">Initialize</span> <span class="pre">as</span> <span class="pre">SoftwareInit;</span></tt></div>
</div>
<div class="line"><tt class="docutils literal"><span class="pre">}</span></tt></div>
--- 449,454 ----
<div class="line-block">
<div class="line"><tt class="docutils literal"><span class="pre">interface</span> <span class="pre">Scheduler;</span></tt></div>
! <div class="line"><tt class="docutils literal"><span class="pre">interface</span> <span class="pre">Init</span> <span class="pre">as</span> <span class="pre">PlatformInit;</span></tt></div>
! <div class="line"><tt class="docutils literal"><span class="pre">interface</span> <span class="pre">Init</span> <span class="pre">as</span> <span class="pre">SoftwareInit;</span></tt></div>
</div>
<div class="line"><tt class="docutils literal"><span class="pre">}</span></tt></div>
***************
*** 460,464 ****
<div class="line-block">
<div class="line"><tt class="docutils literal"><span class="pre">call</span> <span class="pre">Scheduler.init();</span></tt></div>
- <div class="line"><tt class="docutils literal"><span class="pre">__nesc_enable_interrupts();</span></tt></div>
<div class="line">`` ``</div>
<div class="line"><tt class="docutils literal"><span class="pre">call</span> <span class="pre">PlatformInit.init();</span></tt></div>
--- 460,463 ----
***************
*** 468,471 ****
--- 467,472 ----
<div class="line"><tt class="docutils literal"><span class="pre">while(call</span> <span class="pre">Scheduler.runNextTask(FALSE));</span></tt></div>
<div class="line">`` ``</div>
+ <div class="line"><tt class="docutils literal"><span class="pre">__nesc_enable_interrupts();</span></tt></div>
+ <div class="line">`` ``</div>
<div class="line"><tt class="docutils literal"><span class="pre">signal</span> <span class="pre">Boot.booted();</span></tt></div>
<div class="line"><tt class="docutils literal"><span class="pre">while(1)</span> <span class="pre">{</span></tt></div>
***************
*** 479,482 ****
--- 480,515 ----
<div class="line"><tt class="docutils literal"><span class="pre">}</span></tt></div>
</div>
+ <p>Interrupts are not enabled until all calls to Init.init have returned.
+ If a component's initialization needs to handle interrupts, it can
+ do one of two things:</p>
+ <blockquote>
+ <ol class="arabic simple">
+ <li>If a status flag for the interrupt exists, the Init.init()
+ implementations SHOULD use a spin loop to test for when
+ an interrupt has been issued.</li>
+ <li>If no such flag exists, the Init.init() implementation MAY
+ temporarily enable interrupts. It MUST NOT call any other
+ component or return until it has re-disabled interrupts.</li>
+ </ol>
+ </blockquote>
+ <p>As 2) means that interrupts may be temporarily enabled during
+ initialization, components that control interrupts SHOULD NOT
+ cause interrupts to fire after their Init.init() returns.
+ However, it is possible that other components will cause an
+ interrupt to fire due to hardware interactions or semantics.
+ Therefore, a component MUST properly handle interrupts at
+ all times.</p>
+ <p>Unless part of a hardware abstraction architecture (HAA)[tep2]_, the
+ Init.init() command MUST NOT call any commands or signal any
+ events, except for calling Init.init() on other components. An HAA
+ component MAY make other calls to initialize hardware state. A
+ component that is not part of an HAA SHOULD NOT call Init.init() on
+ other components unless it needs to enforce a temporal ordering on
+ initialization.</p>
+ <p>If a component A depends on another component, B,
+ which needs to be initialized, then A SHOULD wire B's Init directly
+ to the boot sequence, unless there is a temporal ordering requirement to
+ the initialization. The purpose of this convention is to simplify
+ component initialization and the initialization sequence.</p>
</div>
<div class="section" id="author-s-address">
***************
*** 495,502 ****
<div class="section" id="citations">
<h1><a name="citations">6. Citations</a></h1>
! <table class="docutils citation" frame="void" id="rst" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
! <tr><td class="label"><a name="rst">[rst]</a></td><td>reStructuredText Markup Specification. <<a class="reference" href="http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html">http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html</a>></td></tr>
</tbody>
</table>
--- 528,535 ----
<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>
<tbody valign="top">
! <tr><td class="label"><a name="tep2">[tep2]</a></td><td>TEP 2: Hardware Abstraction Architecture. Vladi Handziski, Joseph Polastre, Jan-Hinrich Hauer, Cory Sharp. Adam Wolisz and David Culler.</td></tr>
</tbody>
</table>
Index: tep2.html
===================================================================
RCS file: /cvsroot/tinyos/tinyos-1.x/beta/teps/html/tep2.html,v
retrieving revision 1.5
retrieving revision 1.6
diff -C2 -d -r1.5 -r1.6
*** tep2.html 6 Jun 2005 21:30:39 -0000 1.5
--- tep2.html 20 Sep 2005 16:30:23 -0000 1.6
***************
*** 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>Hardware Abstraction Architecture</title>
<meta name="author" content="Vlado Handziski, Joseph Polastre, Jan-Hinrich Hauer, Cory Sharp, Adam Wolisz and David Culler" />
--- 4,8 ----
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
! <meta name="generator" content="Docutils 0.3.9: http://docutils.sourceforge.net/" />
<title>Hardware Abstraction Architecture</title>
<meta name="author" content="Vlado Handziski, Joseph Polastre, Jan-Hinrich Hauer, Cory Sharp, Adam Wolisz and David Culler" />
***************
*** 281,284 ****
--- 281,285 ----
</head>
<body>
+ <div class="document" id="hardware-abstraction-architecture">
<h1 class="title">Hardware Abstraction Architecture</h1>
<table class="docinfo" frame="void" rules="none">
***************
*** 308,312 ****
</tbody>
</table>
- <div class="document" id="hardware-abstraction-architecture">
<div class="note">
<p class="first admonition-title">Note</p>
--- 309,312 ----
***************
*** 400,404 ****
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">
+-----------------------------+
| |
--- 400,404 ----
developer more freedom in the design and the implementation of
reusable applications.</p>
! <pre class="literal-block" id="fig-1">
+-----------------------------+
| |
***************
*** 594,598 ****
the <tt class="docutils literal"><span class="pre">MSP430ADC12Multiple</span></tt> interface of the <em>HAL</em> component as it
provides much finer control over the conversion process.</p>
! <a class="target" id="fig-2" name="fig-2"></a><pre class="literal-block">
StdControl
| ADCSingle
--- 594,598 ----
the <tt class="docutils literal"><span class="pre">MSP430ADC12Multiple</span></tt> interface of the <em>HAL</em> component as it
provides much finer control over the conversion process.</p>
! <pre class="literal-block" id="fig-2">
StdControl
| ADCSingle
Index: tep3.html
===================================================================
RCS file: /cvsroot/tinyos/tinyos-1.x/beta/teps/html/tep3.html,v
retrieving revision 1.6
retrieving revision 1.7
diff -C2 -d -r1.6 -r1.7
*** tep3.html 6 Jun 2005 21:30:39 -0000 1.6
--- tep3.html 20 Sep 2005 16:30:23 -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>Coding Standard</title>
<meta name="author" content="Ion Yannopoulos" />
--- 4,8 ----
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
! <meta name="generator" content="Docutils 0.3.9: http://docutils.sourceforge.net/" />
<title>Coding Standard</title>
<meta name="author" content="Ion Yannopoulos" />
***************
*** 281,284 ****
--- 281,285 ----
</head>
<body>
+ <div class="document" id="coding-standard">
<h1 class="title">Coding Standard</h1>
<table class="docinfo" frame="void" rules="none">
***************
*** 300,306 ****
<tr class="field"><th class="docinfo-name">Draft-Created:</th><td class="field-body">31-Dec-2004</td>
</tr>
! <tr class="field"><th class="docinfo-name">Draft-Version:</th><td class="field-body">1.10</td>
</tr>
! <tr class="field"><th class="docinfo-name">Draft-Modified:</th><td class="field-body">2005-06-06</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>
--- 301,307 ----
<tr class="field"><th class="docinfo-name">Draft-Created:</th><td class="field-body">31-Dec-2004</td>
</tr>
! <tr class="field"><th class="docinfo-name">Draft-Version:</th><td class="field-body">1.11</td>
</tr>
! <tr class="field"><th class="docinfo-name">Draft-Modified:</th><td class="field-body">2005-08-03</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>
***************
*** 308,312 ****
</tbody>
</table>
- <div class="document" id="coding-standard">
<div class="note">
<p class="first admonition-title">Note</p>
--- 309,312 ----
***************
*** 319,349 ****
<p class="topic-title first"><a name="contents">Contents</a></p>
<ul class="auto-toc simple">
! <li><a class="reference" href="#introduction" id="id10" name="id10">1 Introduction</a></li>
! <li><a class="reference" href="#general-conventions" id="id11" name="id11">2 General Conventions</a><ul class="auto-toc">
! <li><a class="reference" href="#general" id="id12" name="id12">2.1 General</a></li>
</ul>
</li>
! <li><a class="reference" href="#packages" id="id13" name="id13">3 Packages</a><ul class="auto-toc">
! <li><a class="reference" href="#directory-structure" id="id14" name="id14">3.1 Directory structure</a></li>
</ul>
</li>
! <li><a class="reference" href="#language-conventions" id="id15" name="id15">4 Language Conventions</a><ul class="auto-toc">
! <li><a class="reference" href="#nesc-convention" id="id16" name="id16">4.1 nesC convention</a><ul class="auto-toc">
! <li><a class="reference" href="#names" id="id17" name="id17">4.1.1 Names</a></li>
! <li><a class="reference" href="#id5" id="id18" name="id18">4.1.2 Packages</a></li>
! <li><a class="reference" href="#preprocessor" id="id19" name="id19">4.1.3 Preprocessor</a></li>
</ul>
</li>
! <li><a class="reference" href="#c-convention" id="id20" name="id20">4.2 C Convention</a></li>
! <li><a class="reference" href="#java-convention" id="id21" name="id21">4.3 Java convention</a></li>
! <li><a class="reference" href="#other-languages" id="id22" name="id22">4.4 Other languages</a></li>
</ul>
</li>
! <li><a class="reference" href="#author-s-address" id="id23" name="id23">5 Author's Address</a></li>
! <li><a class="reference" href="#citations" id="id24" name="id24">6 Citations</a></li>
</ul>
</div>
<div class="section" id="introduction">
! <h1><a class="toc-backref" href="#id10" name="introduction">1 Introduction</a></h1>
<dl class="docutils">
<dt>The purpose of a naming convention is twofold:</dt>
--- 319,349 ----
<p class="topic-title first"><a name="contents">Contents</a></p>
<ul class="auto-toc simple">
! <li><a class="reference" href="#introduction" id="id9" name="id9">1 Introduction</a></li>
! <li><a class="reference" href="#general-conventions" id="id10" name="id10">2 General Conventions</a><ul class="auto-toc">
! <li><a class="reference" href="#general" id="id11" name="id11">2.1 General</a></li>
</ul>
</li>
! <li><a class="reference" href="#packages" id="id12" name="id12">3 Packages</a><ul class="auto-toc">
! <li><a class="reference" href="#directory-structure" id="id13" name="id13">3.1 Directory structure</a></li>
</ul>
</li>
! <li><a class="reference" href="#language-conventions" id="id14" name="id14">4 Language Conventions</a><ul class="auto-toc">
! <li><a class="reference" href="#nesc-convention" id="id15" name="id15">4.1 nesC convention</a><ul class="auto-toc">
! <li><a class="reference" href="#names" id="id16" name="id16">4.1.1 Names</a></li>
! <li><a class="reference" href="#id7" id="id17" name="id17">4.1.2 Packages</a></li>
! <li><a class="reference" href="#preprocessor" id="id18" name="id18">4.1.3 Preprocessor</a></li>
</ul>
</li>
! <li><a class="reference" href="#c-convention" id="id19" name="id19">4.2 C Convention</a></li>
! <li><a class="reference" href="#java-convention" id="id20" name="id20">4.3 Java convention</a></li>
! <li><a class="reference" href="#other-languages" id="id21" name="id21">4.4 Other languages</a></li>
</ul>
</li>
! <li><a class="reference" href="#author-s-address" id="id22" name="id22">5 Author's Address</a></li>
! <li><a class="reference" href="#citations" id="id23" name="id23">6 Citations</a></li>
</ul>
</div>
<div class="section" id="introduction">
! <h1><a class="toc-backref" href="#id9" name="introduction">1 Introduction</a></h1>
<dl class="docutils">
<dt>The purpose of a naming convention is twofold:</dt>
***************
*** 363,373 ****
</div>
<div class="section" id="general-conventions">
! <h1><a class="toc-backref" href="#id11" name="general-conventions">2 General Conventions</a></h1>
<div class="section" id="general">
! <h2><a class="toc-backref" href="#id12" name="general">2.1 General</a></h2>
<blockquote>
<ul class="simple">
<li>Avoid the use of acronyms and abbreviations that are not well known.
Try not to abbreviate "just because".</li>
<li>If you need to abbreviate a word, do so consistently. Try to be
consistent with code outside your own.</li>
--- 363,376 ----
</div>
<div class="section" id="general-conventions">
! <h1><a class="toc-backref" href="#id10" name="general-conventions">2 General Conventions</a></h1>
<div class="section" id="general">
! <h2><a class="toc-backref" href="#id11" name="general">2.1 General</a></h2>
<blockquote>
<ul class="simple">
<li>Avoid the use of acronyms and abbreviations that are not well known.
Try not to abbreviate "just because".</li>
+ <li>Acronyms should be capitalized (as in Java), i.e., Adc, not ADC.
+ Exception: 2-letter acronyms should be all caps (e.g., AM for active
+ messages, not Am)</li>
<li>If you need to abbreviate a word, do so consistently. Try to be
consistent with code outside your own.</li>
***************
*** 383,387 ****
</div>
<div class="section" id="packages">
! <h1><a class="toc-backref" href="#id13" name="packages">3 Packages</a></h1>
<p>For the purposes of this document a package is a collection of related
source and other files, in whatever languages are needed. A package is
--- 386,390 ----
</div>
<div class="section" id="packages">
! <h1><a class="toc-backref" href="#id12" name="packages">3 Packages</a></h1>
<p>For the purposes of this document a package is a collection of related
source and other files, in whatever languages are needed. A package is
***************
*** 389,397 ****
such as a single directory. In TinyOS a package is most often a
directory with zero or more subdirectories.</p>
! <p>It should be possible to easily identify what package a name is in.
! Some languages have builtin support for packages, but nesC and C do not,
! so some conventions will be suggested to keep packages coherent.</p>
<div class="section" id="directory-structure">
! <h2><a class="toc-backref" href="#id14" name="directory-structure">3.1 Directory structure</a></h2>
<blockquote>
<ul>
--- 392,406 ----
such as a single directory. In TinyOS a package is most often a
directory with zero or more subdirectories.</p>
! <p>nesC and C do not currently provide any package support, thus names
! of types and components in different packages might accidentally
! clash. To make this less likely, judiciously use prefixes on groups
! of related files (often, but not always, part of a single package).
! See the examples below.</p>
! <p>In a package, we distinguish between public components (intended to
! be used and wired outside the package) and private components (only
! used and wired within the package). This distinction is not enforced
! by nesC.</p>
<div class="section" id="directory-structure">
! <h2><a class="toc-backref" href="#id13" name="directory-structure">3.1 Directory structure</a></h2>
<blockquote>
<ul>
***************
*** 399,412 ****
subdirectories as are necessary.</p>
</li>
! <li><p class="first">Each package should have a name, to be used as a prefix to identify
! it in code. This should usually be the same as the directory name,
! or very close to it:</p>
! <ul class="simple">
! <li>Core TinyOS components, types and interfaces do not have a prefix.</li>
! <li>Libraries must have a prefix corresponding to their directory name.</li>
! <li>Applications do not need a prefix but are encouraged to have one.</li>
! <li>Subdirectories do not need to be incorporated into the prefix.</li>
! <li>Any further namespacing is optional.</li>
! </ul>
</li>
<li><p class="first">The default packages in a TinyOS distribution are:</p>
--- 408,413 ----
subdirectories as are necessary.</p>
</li>
! <li><p class="first">The package's directory should match the package's prefix (if it
! uses one), but in lower-case.</p>
</li>
<li><p class="first">The default packages in a TinyOS distribution are:</p>
***************
*** 414,419 ****
<li><dl class="first docutils">
<dt><cite>tos/system/</cite>. Core TinyOS components. This directory's</dt>
! <dd><p class="first last">components are the ones necessary for TinyOS to actually run.
! [Should this be <cite>tos/components</cite>?]</p>
</dd>
</dl>
--- 415,419 ----
<li><dl class="first docutils">
<dt><cite>tos/system/</cite>. Core TinyOS components. This directory's</dt>
! <dd><p class="first last">components are the ones necessary for TinyOS to actually run.</p>
</dd>
</dl>
***************
*** 421,426 ****
<li><dl class="first docutils">
<dt><cite>tos/interfaces/</cite>. Core TinyOS interfaces, including</dt>
! <dd><p class="first last">hardware-independent abstractions. Expected to be heavily
! used not just by <cite>tos/system</cite> but throughout all other code.</p>
</dd>
</dl>
--- 421,431 ----
<li><dl class="first docutils">
<dt><cite>tos/interfaces/</cite>. Core TinyOS interfaces, including</dt>
! <dd><p class="first">hardware-independent abstractions. Expected to be heavily
! used not just by <cite>tos/system</cite> but throughout all other code.
! <a href="#id5" name="id6"><span class="problematic" id="id6">`</span></a>tos/interfaces' should only contain interfaces named in TEPs.</p>
! <div class="last system-message" id="id5">
! <p class="system-message-title">System Message: <a name="id5">WARNING/2</a> (<tt class="docutils">txt/tep3.txt</tt>, line 97); <em><a href="#id6">backlink</a></em></p>
! <p>Inline interpreted text or phrase reference start-string without end-string.</p>
! </div>
</dd>
</dl>
***************
*** 465,488 ****
</div>
<div class="section" id="language-conventions">
! <h1><a class="toc-backref" href="#id15" name="language-conventions">4 Language Conventions</a></h1>
<div class="section" id="nesc-convention">
! <h2><a class="toc-backref" href="#id16" name="nesc-convention">4.1 nesC convention</a></h2>
<div class="section" id="names">
! <h3><a class="toc-backref" href="#id17" name="names">4.1.1 Names</a></h3>
<blockquote>
<ul class="simple">
! <li>All nesC files have a <cite>.nc</cite> extension. The filename must match the
! interface or component name (the compiler requires it).</li>
<li>Directory names should be lowercase.</li>
<li>Interface and component names should be mixed case, starting upper
! case, prefixed by package.</li>
! <li>All configurations should be suffixed with 'C'.</li>
! <li>All modules should be suffixed with 'M'.</li>
! <li>Avoid interfaces ending in 'C' or 'M'.</li>
<li>If an interface and component are related it is useful if they have
the same name except for the suffix of the component.</li>
- <li>Modules are private. To make a module publically available, build a
- configuration for it. Wiring in a configuration should only be done
- to other configurations, to this module, or to private components.</li>
<li>Commands, events, tasks and functions should be mixed case, starting
lower case.</li>
--- 470,490 ----
</div>
<div class="section" id="language-conventions">
! <h1><a class="toc-backref" href="#id14" name="language-conventions">4 Language Conventions</a></h1>
<div class="section" id="nesc-convention">
! <h2><a class="toc-backref" href="#id15" name="nesc-convention">4.1 nesC convention</a></h2>
<div class="section" id="names">
! <h3><a class="toc-backref" href="#id16" name="names">4.1.1 Names</a></h3>
<blockquote>
<ul class="simple">
! <li>All nesC files must have a <cite>.nc</cite> extension. The nesC compiler requires
! that the filename match the interface or component name.</li>
<li>Directory names should be lowercase.</li>
<li>Interface and component names should be mixed case, starting upper
! case.</li>
! <li>All public components should be suffixed with 'C'.</li>
! <li>All private components should be suffixed with 'P'.</li>
! <li>Avoid interfaces ending in 'C' or 'P'.</li>
<li>If an interface and component are related it is useful if they have
the same name except for the suffix of the component.</li>
<li>Commands, events, tasks and functions should be mixed case, starting
lower case.</li>
***************
*** 490,542 ****
in a command should have names that are related to the commands.
Making the command past tense or appending <cite>'Done'</cite> are suggested.</li>
! <li>Constants should be all upper case, words separated by underscores.<ul>
! <li>Use of <cite>#define</cite> numeric constants is discouraged: use <cite>enum</cite>.</li>
! </ul>
! </li>
<li>Type arguments to generic components and interfaces should use the
same case as C types: all lower-case separated by underscores, ending
in '_t'.</li>
! <li>Module (global) variables should be mixed case, starting lower case.
! They should be distinguishable from local variables: the recommended
! practice is to prefix them with <cite>m_</cite>.</li>
</ul>
</blockquote>
</div>
! <div class="section" id="id5">
! <h3><a class="toc-backref" href="#id18" name="id5">4.1.2 Packages</a></h3>
<blockquote>
<ul class="simple">
! <li>nesC protects all C names declared in it with the component name.
! The only names that can collide in nesC are interfaces and components.
! Thus only these need package prefixes.</li>
! <li>Public interfaces and components must have a prefix indicating which
! package they belong to. Names are chosen as follows:<ul>
! <li>The TinyOS core (i.e. in <cite>system/</cite> and <cite>interfaces/</cite>) has no prefix.</li>
! <li>A platform, library (e.g. <cite>MSP430</cite>, <cite>Deluge</cite>, <cite>Mate</cite>) should have a
! prefix which matches the directory name.</li>
! <li>Applications do not need prefixes but large ones are encouraged to
! use one to avoid possible collisions with future core names.</li>
! <li>All HAL <a class="citation-reference" href="#tep-2" id="id6" name="id6">[TEP_2]</a> interfaces and components are public to their
! platform, and should be prefixed with their platform.</li>
! </ul>
! </li>
! <li>Private interfaces and components do not necessarily need a prefix.
! However given that each component is in the same namespace as every
! other component in all packages, and possible ambiguity with overridden
! components (see below), it is advised that a prefix be used anyway.<ul>
! <li>All HPL <a class="citation-reference" href="#tep-2" id="id7" name="id7">[TEP_2]</a> interfaces and components are private to their
! platform and so do not need the package prefix. They should however
! be prefixed with the letters 'HPL'.</li>
</ul>
</li>
! <li>It is permissible to have the same name as a component in another
! package if the purpose of the component is to act as a replacement
! for the original component (e.g. because the same interface has a
! different implementation on each platform.)<ul>
! <li>A HIL <a class="citation-reference" href="#tep-2" id="id8" name="id8">[TEP_2]</a> interface or component is platform independent but
! needs to wire to particular platform implementations to work. HIL
! components therefore have the same name under different platforms,
! as only one of them will be used.</li>
! </ul>
</li>
</ul>
--- 492,530 ----
in a command should have names that are related to the commands.
Making the command past tense or appending <cite>'Done'</cite> are suggested.</li>
! <li>Constants should be all upper case, words separated by underscores.
! - Use of <cite>#define</cite> for integer constants is discouraged: use <cite>enum</cite>.</li>
<li>Type arguments to generic components and interfaces should use the
same case as C types: all lower-case separated by underscores, ending
in '_t'.</li>
! <li>Module (global) variables should be mixed case, starting lower case.</li>
</ul>
</blockquote>
</div>
! <div class="section" id="id7">
! <h3><a class="toc-backref" href="#id17" name="id7">4.1.2 Packages</a></h3>
! <blockquote>
! <ul>
! <li><p class="first">Each package may use a prefix for its component, interface and
! global C names. These prefixes may sometimes be common to multiple
! packages. Examples:</p>
! <div class="system-message">
! <p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">txt/tep3.txt</tt>, line 153)</p>
! <p>Unexpected indentation.</p>
! </div>
<blockquote>
<ul class="simple">
! <li>All hardware presentation layer names start with Hpl (this is
! an example of a shared prefix).</li>
! <li>Chip-specific hardware abstraction layer components and interfaces
! start with the chip name, e.g., Atm128 for ATmega128.</li>
! <li>The Maté virtual machine uses the Mate to prefix all its names.</li>
! <li>Core TinyOS names (e.g., the timer components, the Init interface)
! do not use a prefix.</li>
</ul>
+ </blockquote>
</li>
! <li><p class="first">Some packages may use multiple prefixes. For instance, the ATmega128
! chip package uses an Hpl prefix for hardware presentation layer
! components and Atm128 for hardware abstraction layer components.</p>
</li>
</ul>
***************
*** 544,556 ****
</div>
<div class="section" id="preprocessor">
! <h3><a class="toc-backref" href="#id19" name="preprocessor">4.1.3 Preprocessor</a></h3>
<blockquote>
<ul class="simple">
<li>Don't use the nesC <cite>includes</cite> statement. It does not handle macro
inclusion properly. Use <cite>#include</cite> instead.</li>
! <li>Macros declared in an <cite>.nc</cite> file must be <cite>#define</cite>'d within
! a <cite>module</cite> definition to actually limit their scope to the module.</li>
<li>Macros which are meant for use in multiple <cite>.nc</cite> files should be
! <cite>#define</cite>'d in an associated C header.</li>
<li>Use of macros should be minimized:
<cite>#define</cite> should only be used where <cite>enum</cite> and <cite>inline</cite> do not suffice.<ul>
--- 532,545 ----
</div>
<div class="section" id="preprocessor">
! <h3><a class="toc-backref" href="#id18" name="preprocessor">4.1.3 Preprocessor</a></h3>
<blockquote>
<ul class="simple">
<li>Don't use the nesC <cite>includes</cite> statement. It does not handle macro
inclusion properly. Use <cite>#include</cite> instead.</li>
! <li>Macros declared in an <cite>.nc</cite> file must be <cite>#define</cite>'d after the
! <cite>module</cite> or <cite>configuration</cite> keyword to actually limit their scope to
! the module.</li>
<li>Macros which are meant for use in multiple <cite>.nc</cite> files should be
! <cite>#define</cite>'d in a <cite>#include</cite>'d C header file.</li>
<li>Use of macros should be minimized:
<cite>#define</cite> should only be used where <cite>enum</cite> and <cite>inline</cite> do not suffice.<ul>
***************
*** 565,583 ****
</div>
<div class="section" id="c-convention">
! <h2><a class="toc-backref" href="#id20" name="c-convention">4.2 C Convention</a></h2>
<blockquote>
<ul class="simple">
! <li>All C files have a .h (header) or (rarely) a .c (source) extension [*].<ul>
<li>Filenames associated with a component should have the same name as
the component.</li>
! <li>Filenames shared by a package should have a name with the package
! prefix.</li>
</ul>
- <!-- Filenames which are not associated with a component should be lowercase. -->
</li>
! <li>Directory names should be lowercase.</li>
! <li>C does not protect names in any way, so all names should be package
! prefixed. This means all types, functions, variables, and constants.
! This leads naturally to:<ul>
<li>Minimize C code outside of nesC files. In particular: most uses of
hardware specific macros in TinyOS 1.x should be replaced with nesC
--- 554,571 ----
</div>
<div class="section" id="c-convention">
! <h2><a class="toc-backref" href="#id19" name="c-convention">4.2 C Convention</a></h2>
<blockquote>
<ul class="simple">
! <li>All C files have a .h (header) or (rarely) a .c (source) extension.<ul>
<li>Filenames associated with a component should have the same name as
the component.</li>
! <li>Filenames of a package should have a name with the package
! prefix (if any).</li>
! <li>Filenames which are not associated with a component should be lowercase.</li>
</ul>
</li>
! <li>C does not protect names in any way. If a package uses a prefix, it
! should also use it for all types, tags, functions, variables,
! constants and macros. This leads naturally to:<ul>
<li>Minimize C code outside of nesC files. In particular: most uses of
hardware specific macros in TinyOS 1.x should be replaced with nesC
***************
*** 586,608 ****
</li>
<li>C type names (define with <cite>typedef</cite>) should be lower case, words
! separated by underscores, prefixed by package, and ending in <cite>'_t'</cite>.</li>
<li>C tag names (for <cite>struct</cite>, <cite>union</cite>, or <cite>enum</cite>) should be lower case,
! words separated by underscores, prefixed by package. Types with tag
! names should provide a typedef with a '_t' extension.</li>
<li>C types which represent opaque pointers (for use in parameters) should
be named similar to other types but should end in <cite>'_ptr_t'</cite>.</li>
! <li>Functions should be lower case, words separated by underscores,
! prefixed by package.</li>
<li>Function macros (<cite>#define</cite> ) should be all upper case, words separated
! by underscores, prefixed by package.<ul>
<li>Using function macros is discouraged: use <cite>inline</cite> functions.</li>
</ul>
</li>
! <li>Constants should be all upper case, words separated by underscores,
! prefixed by package.<ul>
! <li>Use of <cite>#define</cite> for numeric constants is discouraged: use <cite>enum</cite>.</li>
! <li>Do use <cite>#define</cite> for string constants.</li>
! </ul>
! </li>
<li>Global variables should be mixed case, starting lower case.</li>
</ul>
--- 574,591 ----
</li>
<li>C type names (define with <cite>typedef</cite>) should be lower case, words
! separated by underscores and ending in <cite>'_t'</cite>.</li>
<li>C tag names (for <cite>struct</cite>, <cite>union</cite>, or <cite>enum</cite>) should be lower case,
! words separated by underscores. Types with tag names should provide
! a typedef.</li>
<li>C types which represent opaque pointers (for use in parameters) should
be named similar to other types but should end in <cite>'_ptr_t'</cite>.</li>
! <li>Functions should be lower case, words separated by underscores.</li>
<li>Function macros (<cite>#define</cite> ) should be all upper case, words separated
! by underscores.<ul>
<li>Using function macros is discouraged: use <cite>inline</cite> functions.</li>
</ul>
</li>
! <li>Constants should be all upper case, words separated by underscores.
! - Use of <cite>#define</cite> for integer constants is discouraged: use <cite>enum</cite>.</li>
<li>Global variables should be mixed case, starting lower case.</li>
</ul>
***************
*** 610,624 ****
</div>
<div class="section" id="java-convention">
! <h2><a class="toc-backref" href="#id21" name="java-convention">4.3 Java convention</a></h2>
<blockquote>
<ul class="simple">
! <li>The standard Java coding convention <a class="citation-reference" href="#java-coding-convention" id="id9" name="id9">[Java_Coding_Convention]</a>
should be followed.</li>
! <li>All code declared for core TinyOS is in the package <cite>net.tinyos</cite>.</li>
</ul>
</blockquote>
</div>
<div class="section" id="other-languages">
! <h2><a class="toc-backref" href="#id22" name="other-languages">4.4 Other languages</a></h2>
<blockquote>
<ul class="simple">
--- 593,607 ----
</div>
<div class="section" id="java-convention">
! <h2><a class="toc-backref" href="#id20" name="java-convention">4.3 Java convention</a></h2>
<blockquote>
<ul class="simple">
! <li>The standard Java coding convention <a class="citation-reference" href="#java-coding-convention" id="id8" name="id8">[Java_Coding_Convention]</a>
should be followed.</li>
! <li>All core TinyOS code is in the package <cite>net.tinyos</cite>.</li>
</ul>
</blockquote>
</div>
<div class="section" id="other-languages">
! <h2><a class="toc-backref" href="#id21" name="other-languages">4.4 Other languages</a></h2>
<blockquote>
<ul class="simple">
***************
*** 629,633 ****
</div>
<div class="section" id="author-s-address">
! <h1><a class="toc-backref" href="#id23" name="author-s-address">5 Author's Address</a></h1>
<div class="line-block">
<div class="line">Ion Yannopoulos</div>
--- 612,616 ----
</div>
<div class="section" id="author-s-address">
! <h1><a class="toc-backref" href="#id22" name="author-s-address">5 Author's Address</a></h1>
<div class="line-block">
<div class="line">Ion Yannopoulos</div>
***************
*** 638,642 ****
</div>
<div class="section" id="citations">
! <h1><a class="toc-backref" href="#id24" name="citations">6 Citations</a></h1>
<table class="docutils citation" frame="void" id="tep-1" rules="none">
<colgroup><col class="label" /><col /></colgroup>
--- 621,625 ----
</div>
<div class="section" id="citations">
! <h1><a class="toc-backref" href="#id23" name="citations">6 Citations</a></h1>
<table class="docutils citation" frame="void" id="tep-1" rules="none">
<colgroup><col class="label" /><col /></colgroup>
***************
*** 649,653 ****
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
! <tr><td class="label"><a name="tep-2">[TEP_2]</a></td><td><em>(<a class="fn-backref" href="#id6">1</a>, <a class="fn-backref" href="#id7">2</a>, <a class="fn-backref" href="#id8">3</a>)</em> TEP 2
<<a class="reference" href="http://www.tinyos.net/working_groups/tinyos-2.0wg/teps/tep-2.html">http://www.tinyos.net/working_groups/tinyos-2.0wg/teps/tep-2.html</a>></td></tr>
</tbody>
--- 632,636 ----
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
! <tr><td class="label"><a name="tep-2">[TEP_2]</a></td><td>TEP 2
<<a class="reference" href="http://www.tinyos.net/working_groups/tinyos-2.0wg/teps/tep-2.html">http://www.tinyos.net/working_groups/tinyos-2.0wg/teps/tep-2.html</a>></td></tr>
</tbody>
***************
*** 662,666 ****
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
! <tr><td class="label"><a class="fn-backref" href="#id9" name="java-coding-convention">[Java_Coding_Convention]</a></td><td>Java Coding Convention
<<a class="reference" href="http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html">http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html</a>></td></tr>
</tbody>
--- 645,649 ----
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
! <tr><td class="label"><a class="fn-backref" href="#id8" name="java-coding-convention">[Java_Coding_Convention]</a></td><td>Java Coding Convention
<<a class="reference" href="http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html">http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html</a>></td></tr>
</tbody>
- Previous message: [Tinyos-beta-commits] CVS: tinyos-1.x/beta/platform/pxa27x
PXA27XQuickCaptInt.h, NONE, 1.1 PXA27XQuickCaptInt.nc, NONE,
1.1 PXA27XQuickCaptIntC.nc, NONE, 1.1 PXA27XQuickCaptIntM.nc,
NONE, 1.1 PXA27XI2CM.nc, 1.1, 1.2 pxa27x_registers.h, 1.11, 1.12
- Next message: [Tinyos-beta-commits]
CVS: tinyos-1.x/beta/teps/txt tep102.txt, 1.14, 1.15
- Messages sorted by:
[ date ]
[ thread ]
[ subject ]
[ author ]
More information about the Tinyos-beta-commits
mailing list