[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