<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.3.6: http://docutils.sourceforge.net/" />
<title>TinyOS 2.0 Overview</title>
<meta name="author" content="Philip Levis" />
<meta name="date" content="Oct 30 2006" />
</style>
</head>
<body>
-<div class="document" id="tinyos-2-0-overview">
<h1 class="title">TinyOS 2.0 Overview</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<td>Oct 30 2006</td></tr>
</tbody>
</table>
+<div class="document" id="tinyos-2-0-overview">
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">This document gives a brief overview of TinyOS 2.0, highlighting how
and where it departs from 1.1 and 1.0. Further detail on these changes
is detailed in TEP (TinyOS Enhancement Proposal) documents.</p>
</div>
-<div class="section">
-<h1><a id="introduction" name="introduction">1. Introduction</a></h1>
+<div class="section" id="introduction">
+<h1><a name="introduction">1. Introduction</a></h1>
<p>TinyOS 2.0 is a clean slate redesign and re-implementation of TinyOS.
Its development was motivated by our belief that many aspects of 1.x
strain to meet requirements and uses that were not foreseen
these can be found in TEPs (TinyOS Enhancement Proposals), which
document and describe these abstractions.</p>
</div>
-<div class="section">
-<h1><a id="platforms-hardware-abstraction" name="platforms-hardware-abstraction">2. Platforms/Hardware Abstraction</a></h1>
+<div class="section" id="platforms-hardware-abstraction">
+<h1><a name="platforms-hardware-abstraction">2. Platforms/Hardware Abstraction</a></h1>
<p>Platforms exist in the <tt class="docutils literal"><span class="pre">tos/platforms</span></tt> subdirectory. In TinyOS 2.0, a
<em>platform</em> is a collection of <em>chips</em> and some glue code that connects
them together. For example, the mica2 platform is the CC1000 radio
</blockquote>
<p>The btnode3 platform is not included in the RPM.</p>
</div>
-<div class="section">
-<h1><a id="scheduler" name="scheduler">3. Scheduler</a></h1>
+<div class="section" id="scheduler">
+<h1><a name="scheduler">3. Scheduler</a></h1>
<p>As with TinyOS 1.x, TinyOS 2.0 scheduler has a non-preemptive FIFO
policy. However, tasks in 2.0 operate slightly differently than in
1.x.</p>
analysis. Details on the new scheduler and how to extend it can be found
in TEP 106: Schedulers and Tasks[<a class="reference" href="#tep106">TEP106</a>].</p>
</div>
-<div class="section">
-<h1><a id="booting-initialization" name="booting-initialization">4. Booting/Initialization</a></h1>
+<div class="section" id="booting-initialization">
+<h1><a name="booting-initialization">4. Booting/Initialization</a></h1>
<p>TinyOS 2.0 has a different boot sequence than 1.x. The 1.x interface
<tt class="docutils literal"><span class="pre">StdControl</span></tt> has been split into two interfaces: <tt class="docutils literal"><span class="pre">Init</span></tt> and
<tt class="docutils literal"><span class="pre">StdControl</span></tt>. The latter only has two commands: <tt class="docutils literal"><span class="pre">start</span></tt> and <tt class="docutils literal"><span class="pre">stop</span></tt>.
the new boot sequence can be found in TEP 107: TinyOS 2.x Boot
Sequence[<a class="reference" href="#tep107">TEP107</a>].</p>
</div>
-<div class="section">
-<h1><a id="virtualization" name="virtualization">5. Virtualization</a></h1>
+<div class="section" id="virtualization">
+<h1><a name="virtualization">5. Virtualization</a></h1>
<p>TinyOS 2.0 is written with nesC 1.2, which introduces the concept
of a 'generic' or instantiable component. Generic modules allow
TinyOS to have reusable data structures, such as bit vectors and
queues, which simplify development. More importantly, generic
-configurations allow services to encapsulate complex wiring
+configurations allow services to encapsulate complex wiring
relationships for clients that need them.</p>
<p>In practice, this means that many basic TinyOS services are now
<em>virtualized.</em> Rather than wire to a component with a parameterized
case of timers, to a unique) automatically, reducing wiring
mistakes and simplifying use of the abstraction.</p>
</div>
-<div class="section">
-<h1><a id="timers" name="timers">6. Timers</a></h1>
+<div class="section" id="timers">
+<h1><a name="timers">6. Timers</a></h1>
<p>TinyOS 2.0 provides a much richer set of timer interfaces than
1.x. Experience has shown that timers are one of the most critical
abstractions a mote OS can provide, and so 2.0 expands the fidelity
timers that fire asynchronously (they have the async
keyword). Components can query their timers for how much time
remainins before they fire, and can start timers in the future (e.g.,
-'start firing a timer at 1Hz starting 31ms from now'). TEP 102:
+'start firing a timer at 1Hz starting 31ms from now'). TEP 102:
Timers[<a class="reference" href="#tep102">TEP102</a>] defines what HIL components a platform must provide
in order to support standard TinyOS timers. Platforms are
required to provide millisecond granularity timers, and can provide
App.Timer -> TimerMilliC;
</pre>
</div>
-<div class="section">
-<h1><a id="communication" name="communication">7. Communication</a></h1>
+<div class="section" id="communication">
+<h1><a name="communication">7. Communication</a></h1>
<p>In TinyOS 2.0, the message buffer type is <tt class="docutils literal"><span class="pre">message_t</span></tt>, and it is a
buffer that is large enough to hold a packet from any of a node's
communication interfaces. The structure itself is completely opaque:
communication. Instead, a component should wire to
SerialActiveMessageC, which provides active message communication over
the serial port.</p>
-<p>Active message communication is virtualized through four generic
-components, which take the AM type as a parameter: AMSenderC,
+<p>Active message communication is virtualized through four generic
+components, which take the AM type as a parameter: AMSenderC,
AMReceiverC, AMSnooperC, and AMSnoopingReceiverC. AMSenderC is
virtualized in that the call to send() does not fail if some
other component is sending (as it does with GenericComm in 1.x). Instead,
outstanding or if the radio is not in a sending state. Underneath,
the active message system queues and sends these outstanding packets.
This is different than the QueuedSendC approach of 1.x, in which there
-is an N-deep queue that is shared among all senders. With N AMSenderC
+is an N-deep queue that is shared among all senders. With N AMSenderC
components, there is an N-deep queue where each sender has a single
-reserved entry. This means that each AMSenderC receives
+reserved entry. This means that each AMSenderC receives
1/n of the available post-MAC transmission opportunities, where
n is the number of AMSenderC components with outstanding packets.
In the worst case, n is the number of components; even when every
radio (mica2 platform) and an experimental low-power stack for
the CC2420 radio (micaz, telosb, and intelmote2 platforms).</p>
</div>
-<div class="section">
-<h1><a id="sensors" name="sensors">8. Sensors</a></h1>
+<div class="section" id="sensors">
+<h1><a name="sensors">8. Sensors</a></h1>
<p>In TinyOS 2.0, named sensor components comprise the HIL of a
platform's sensors. TEP 114 describes a set of HIL data acquisition
interfaces, such as Read, ReadStream, and Get, which sensors
Sensorboards[<a class="reference" href="#tep109">TEP109</a>], and the details of the HIL sensor interfaces
can be found in TEP 114: Source and Sink Independent Drivers[<a class="reference" href="#tep114">TEP114</a>].</p>
</div>
-<div class="section">
-<h1><a id="error-codes" name="error-codes">9. Error Codes</a></h1>
+<div class="section" id="error-codes">
+<h1><a name="error-codes">9. Error Codes</a></h1>
<p>The standard TinyOS 1.x return code is <tt class="docutils literal"><span class="pre">result_t</span></tt>, whose value is
either SUCCESS (a non-zero value) or FAIL (a zero value). While this
makes conditionals on calls very easy to write (e.g., <tt class="docutils literal"><span class="pre">if</span> <span class="pre">(call</span>
different in 2.0. Calls that were once:</p>
<pre class="literal-block">
if (call X.y()) {
- busy = TRUE;
+ busy = TRUE;
}
</pre>
<p>now have their meanings reversed. In 1.x, the busy statement will execute
}
</pre>
</div>
-<div class="section">
-<h1><a id="arbitration" name="arbitration">10. Arbitration</a></h1>
+<div class="section" id="arbitration">
+<h1><a name="arbitration">10. Arbitration</a></h1>
<p>While basic abstractions, such as packet communication and timers,
-can be virtualized, experiences with 1.x showed that some cannot
+can be virtualized, experiences with 1.x showed that some cannot
without either adding significant complexity or limiting the system.
The most pressing example of this is a shared bus on a microcontroller.
Many different systems -- sensors, storage, the radio -- might need
to use the bus at the same time, so some way of arbitrating access
is needed.</p>
-<p>To support these kinds of abstractions, TinyOS 2.0 introduces
+<p>To support these kinds of abstractions, TinyOS 2.0 introduces
the Resource interface, which components use to request and
-acquire shared resources, and arbiters, which provide a policy for
+acquire shared resources, and arbiters, which provide a policy for
arbitrating access between multiple clients. For some abstractions,
the arbiter also provides a power management policy, as it can tell
when the system is no longer needed and can be safely turned off.</p>
<p>TEP 108: Resource Arbitration[<a class="reference" href="#tep108">TEP108</a>] describes the Resource interface
and how arbiters work.</p>
</div>
-<div class="section">
-<h1><a id="power-management" name="power-management">11. Power Management</a></h1>
+<div class="section" id="power-management">
+<h1><a name="power-management">11. Power Management</a></h1>
<p>Power management in 2.0 is divided into two parts: the power state
of the microcontroller and the power state of devices. The former,
discussed in TEP 112: Microcontroller Power Management[<a class="reference" href="#tep112">TEP112</a>],
-is computed in a chip-specific manner by examining which devices
+is computed in a chip-specific manner by examining which devices
and interrupt souces are active. The latter, discussed in
TEP 115: Power Management of Non-Virtualised Devices{<a class="reference" href="#tep115">TEP115</a>], is handled
through resource abiters. Fully virtualized services have their
<p>TinyOS 2.0 provides low-power stacks for the CC1000 (mica2)
and CC2420 (micaz, telosb, imote2) radios. Both use a low-power
listening apporach, where transmitters send long preambles or
-repeatedly send packets and receivers wake up periodically to
-sense the channel to hear if there is a packet being
+repeatedly send packets and receivers wake up periodically to
+sense the channel to hear if there is a packet being
transmitted. The low-power stack CC1000 is standard, while
the CC2420 stack is experimental. That is, the default CC1000
-stack (chips/cc1000) has low-power-listening, while the default
+stack (chips/cc1000) has low-power-listening, while the default
CC2420 stack (chips/cc2420) does not. To use the low-power CC2420
stack, you must include chips/cc2420_lpl in your application Makefile.</p>
</div>
-<div class="section">
-<h1><a id="network-protocols" name="network-protocols">12. Network Protocols</a></h1>
-<p>TinyOS 2.0 provides simple reference implementations of two of
+<div class="section" id="network-protocols">
+<h1><a name="network-protocols">12. Network Protocols</a></h1>
+<p>TinyOS 2.0 provides simple reference implementations of two of
the most basic protocols used in mote networks: dissemination
-and collection. Dissemination reliably delivers small (fewer
+and collection. Dissemination reliably delivers small (fewer
than 20 byte) data items to every node in a network, while
collection builds a routing tree rooted at a sink node. Together,
these two protocols enable a wide range of data collection
applications. Collection has advanced significantly since the
-most recent beta release; experimental tests in multiple
+most recent beta release; experimental tests in multiple
network conditions have seen very high (>98%) deliver rates
as long as the network is not saturated.</p>
</div>
-<div class="section">
-<h1><a id="conclusion" name="conclusion">13. Conclusion</a></h1>
+<div class="section" id="conclusion">
+<h1><a name="conclusion">13. Conclusion</a></h1>
<p>TinyOS 2.0 represents the next step of TinyOS development. Building on
user experiences over the past few years, it has taken the basic
TinyOS architecture and pushed it forward in several directions,
non-volatile storage, basic multihop protocols (collection routing,
dissemination), and further power management abstractions.</p>
</div>
-<div class="section">
-<h1><a id="acknowledgments" name="acknowledgments">14. Acknowledgments</a></h1>
+<div class="section" id="acknowledgments">
+<h1><a name="acknowledgments">14. Acknowledgments</a></h1>
<p>TinyOS 2.0 is the result of a lot of hard work from a lot of people,
-including (but not limited to) David Gay, Philip Levis, Cory Sharp,
-Vlado Handziski, Jan Hauer, Kevin Klues, Joe Polastre, Jonathan Hui,
-Prabal Dutta,
-Gilman Tolle, Martin Turon, Phil Buonodonna, Ben Greenstein, David Culler,
-Kristin Wright, Ion Yannopoulos, Henri Dubois-Ferriere, Jan Beutel,
+including (but not limited to) David Gay, Philip Levis, Cory Sharp,
+Vlado Handziski, Jan Hauer, Kevin Klues, Joe Polastre, Jonathan Hui,
+Prabal Dutta,
+Gilman Tolle, Martin Turon, Phil Buonodonna, Ben Greenstein, David Culler,
+Kristin Wright, Ion Yannopoulos, Henri Dubois-Ferriere, Jan Beutel,
Robert Szewczyk, Rodrigo Fonseca, Kyle Jamieson, Omprakash Gnawali,
David Moss, and Kristin Wright.</p>
</div>
-<div class="section">
-<h1><a id="author-s-address" name="author-s-address">15. Author's Address</a></h1>
+<div class="section" id="author-s-address">
+<h1><a name="author-s-address">15. Author's Address</a></h1>
<div class="line-block">
<div class="line">Philip Levis</div>
<div class="line">358 Gates</div>
<div class="line">email - <a class="reference" href="mailto:pal@cs.stanford.edu">pal@cs.stanford.edu</a></div>
</div>
</div>
-<div class="section">
-<h1><a id="citations" name="citations">16. Citations</a></h1>
+<div class="section" id="citations">
+<h1><a name="citations">16. Citations</a></h1>
<table class="docutils citation" frame="void" id="tep1" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.3.6: http://docutils.sourceforge.net/" />
<title>Porting TinyOS 1.x Code to TinyOS 2.0</title>
<meta name="author" content="Tahir Azim and Philip Levis" />
<meta name="date" content="October 26 2006" />
</style>
</head>
<body>
-<div class="document" id="porting-tinyos-1-x-code-to-tinyos-2-0">
<h1 class="title">Porting TinyOS 1.x Code to TinyOS 2.0</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<td>October 26 2006</td></tr>
</tbody>
</table>
+<div class="document" id="porting-tinyos-1-x-code-to-tinyos-2-0">
<div class="note">
<p class="first admonition-title">Note</p>
-<p class="last">This document provides a few important points that describe
+<p class="last">This document provides a few important points that describe
major steps required for porting TinyOS 1.x code to TinyOS 2.0.
It is based on Tahir Azim's experience porting Beacon Vector
Routing (BVR[<a class="reference" href="#id1">1</a>]) from TinyOS 1.x to T2. This document is not
a complete porting guide, but the hope is that it will provide
some help or guidance.</p>
</div>
-<div class="section">
-<h1><a id="porting-points" name="porting-points">1. Porting Points</a></h1>
+<div class="section" id="porting-points">
+<h1><a name="porting-points">1. Porting Points</a></h1>
<p>As these observations come from porting a network protocol, they are
rather protocol-centric and do not consider other abstractions such
as storage. We hope to add such points in the future.</p>
</ol>
<p>In TinyOS 2.x, SUCCESS is equal to a zero error code, while other error codes are non-zero. So calls like this should be changed to make sure they test the result for equality with SUCCESS:</p>
<pre class="literal-block">
-if (call Packet... () == SUCCESS ) {
+if (call Packet... () == SUCCESS ) {
//SUCCESS!: do this...
}
</pre>
</ol>
</blockquote>
</div>
-<div class="section">
-<h1><a id="author-s-address" name="author-s-address">2. Author's Address</a></h1>
+<div class="section" id="author-s-address">
+<h1><a name="author-s-address">2. Author's Address</a></h1>
<div class="line-block">
<div class="line">Tahir Azim</div>
<div class="line">358 Gates Hall</div>
<div class="line">email - <a class="reference" href="mailto:pal@cs.stanford.edu">pal@cs.stanford.edu</a></div>
</div>
</div>
-<div class="section">
-<h1><a id="citations" name="citations">3. Citations</a></h1>
+<div class="section" id="citations">
+<h1><a name="citations">3. Citations</a></h1>
<table class="docutils footnote" frame="void" id="id1" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.3.6: http://docutils.sourceforge.net/" />
<title>TEP Structure and Keywords</title>
<meta name="author" content="Philip Levis" />
<style type="text/css">
</style>
</head>
<body>
-<div class="document" id="tep-structure-and-keywords">
<h1 class="title">TEP Structure and Keywords</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<td>Philip Levis</td></tr>
<tr class="field"><th class="docinfo-name">Draft-Created:</th><td class="field-body">18-Oct-2004</td>
</tr>
-<tr class="field"><th class="docinfo-name">Draft-Version:</th><td class="field-body">1.1.2.5</td>
+<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">2006-10-19</td>
+<tr class="field"><th class="docinfo-name">Draft-Modified:</th><td class="field-body">2006-12-12</td>
</tr>
<tr class="field"><th class="docinfo-name">Draft-Discuss:</th><td class="field-body">TinyOS Developer List <tinyos-devel at mail.millennium.berkeley.edu></td>
</tr>
</tbody>
</table>
+<div class="document" id="tep-structure-and-keywords">
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">This document specifies a Best Current Practices for the
TinyOS Community, and requests discussion and suggestions for
improvements. Distribution of this memo is unlimited.</p>
</div>
-<div class="section">
-<h1><a id="abstract" name="abstract">Abstract</a></h1>
+<div class="section" id="abstract">
+<h1><a name="abstract">Abstract</a></h1>
<p>This memo describes the structure all TinyOS Extension Proposal (TEP)
documents follow, and defines the meaning of several key words in
those documents.</p>
</div>
-<div class="section">
-<h1><a id="introduction" name="introduction">1. Introduction</a></h1>
+<div class="section" id="introduction">
+<h1><a name="introduction">1. Introduction</a></h1>
<p>In order to simplify management, reading, and tracking development,
all TinyOS Extension Proposals (TEPs) MUST have a particular
structure. Additionally, to simplify development and improve
several key words that specify levels of compliance. This document
describes and follows both.</p>
</div>
-<div class="section">
-<h1><a id="keywords" name="keywords">2. Keywords</a></h1>
+<div class="section" id="keywords">
+<h1><a name="keywords">2. Keywords</a></h1>
<p>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in TEP 1.</p>
<p>Note that the force of these words is modified by the requirement
level of the document in which they are used.</p>
-<div class="section">
-<h2><a id="must" name="must">2.1 MUST</a></h2>
+<div class="section" id="must">
+<h2><a name="must">2.1 MUST</a></h2>
<p>MUST: This word, or the terms "REQUIRED" or "SHALL", mean that the
definition is an absolute requirement of the specification.</p>
</div>
-<div class="section">
-<h2><a id="must-not" name="must-not">2.2 MUST NOT</a></h2>
+<div class="section" id="must-not">
+<h2><a name="must-not">2.2 MUST NOT</a></h2>
<p>MUST NOT: This phrase, or the phrase "SHALL NOT", mean that the
definition is an absolute prohibition of the specification.</p>
</div>
-<div class="section">
-<h2><a id="should" name="should">2.3 SHOULD</a></h2>
+<div class="section" id="should">
+<h2><a name="should">2.3 SHOULD</a></h2>
<p>SHOULD: This word, or the adjective "RECOMMENDED", mean that there
may exist valid reasons in particular circumstances to ignore a
particular item, but the full implications must be understood and
carefully weighed before choosing a different course.</p>
</div>
-<div class="section">
-<h2><a id="should-not" name="should-not">2.4 SHOULD NOT</a></h2>
+<div class="section" id="should-not">
+<h2><a name="should-not">2.4 SHOULD NOT</a></h2>
<p>SHOULD NOT: This phrase, or the phrase "NOT RECOMMENDED" mean that
there may exist valid reasons in particular circumstances when the
particular behavior is acceptable or even useful, but the full
implications should be understood and the case carefully weighed
before implementing any behavior described with this label.</p>
</div>
-<div class="section">
-<h2><a id="may" name="may">2.5 MAY</a></h2>
+<div class="section" id="may">
+<h2><a name="may">2.5 MAY</a></h2>
<p>MAY: This word, or the adjective "OPTIONAL", mean that an item is
truly optional. One implementer may choose to include the item
because a particular application requires it or because the
another implementation which does not include the option (except, of
course, for the feature the option provides.)</p>
</div>
-<div class="section">
-<h2><a id="guidance-in-the-use-of-these-imperatives" name="guidance-in-the-use-of-these-imperatives">2.6 Guidance in the use of these Imperatives</a></h2>
+<div class="section" id="guidance-in-the-use-of-these-imperatives">
+<h2><a name="guidance-in-the-use-of-these-imperatives">2.6 Guidance in the use of these Imperatives</a></h2>
<p>Imperatives of the type defined in this memo must be used with care
and sparingly. In particular, they MUST only be used where it is
actually required for interoperation or to limit behavior which has
interoperability.</p>
</div>
</div>
-<div class="section">
-<h1><a id="tep-structure" name="tep-structure">3. TEP Structure</a></h1>
+<div class="section" id="tep-structure">
+<h1><a name="tep-structure">3. TEP Structure</a></h1>
<p>TEPs have two major parts, a header and a body. The header states
-document metadata, for management and status. The body contains the
+document metadata, for management and status. The body contains the
content of the proposal.</p>
-<p>All TEPs MUST follow the TEP docutils template, and conform to
-reStructuredText standards <a class="footnote-reference" href="#id2" id="id1" name="id1">[1]</a>, to enable translation from
+<p>All TEPs MUST follow the TEP docutils template, and conform to
+reStructuredText standards <a class="footnote-reference" href="#id2" id="id1" name="id1">[1]</a>, to enable translation from
reStructuredText to HTML and Latex.</p>
-<div class="section">
-<h2><a id="tep-header" name="tep-header">3.1 TEP Header</a></h2>
+<div class="section" id="tep-header">
+<h2><a name="tep-header">3.1 TEP Header</a></h2>
<p>The TEP header has several fields which MUST be included, as well as
others which MAY be included. The first six header fields MUST be
included in all TEPs, in the order stated here.</p>
<p>The first field is "TEP," and specifies the TEP number of the
-document. A TEP's number is unique.. This document is TEP 1. The
+document. A TEP's number is unique.. This document is TEP 1. The
TEP type (discussed below)
determines how a number is assigned to it. Generally, when a document
is ready to be a TEP, it is assigned the smallest available number.
follow all current BCPs.</p>
<p>Documentary TEPs describe a system or protocol that exists; a
documentary TEP MUST reference an implementation that a reader can
-easily obtain. Documentary TEPs simplify interoperability when
+easily obtain. Documentary TEPs simplify interoperability when
needed, and document TinyOS service implementations.</p>
<p>Informational TEPs provide information that is of interest to the
community. Informational TEPs include data gathered on radio behavior,
or experiences which could help the community achieve its goals.</p>
<p>Experimental TEPs describe a completely experimental approach to a
problem, which are outside the TinyOS core and will not necessarily
-become part of it. Unlike Documentary TEPs, Experimental TEPs may
+become part of it. Unlike Documentary TEPs, Experimental TEPs may
describe systems that do not have a reference implementation.</p>
<p>The fourth field is "Status," which specifies the status of the TEP.
A TEP status can either be "Draft," which means it is a work in
-progress, "Final," which means it is complete and will not change.
-Once a TEP has the status "Final," its body MUST NOT change.
+progress, "Final," which means it is complete and will not change.
+Once a TEP has the status "Final," its body MUST NOT change.
The values of its header fields MUST NOT change. The header of a
Final TEP MAY have an "Obsoleted By" field added.</p>
<p>The "Obsoletes" field is a backward pointer to an earlier TEP which
<p>There is an optional field, "Extends." The "Extends" field refers to
another TEP. The purpose of this field is to denote when a TEP represents
an addition to an existing TEP. Meeting the requirements of a TEP with an
-Extends field requires also meeting the requirements of all TEPs listed
+Extends field requires also meeting the requirements of all TEPs listed
in the Extends field.</p>
<p>If a TEP is a Draft, then four additional fields MUST be included:
Draft-Created, Draft-Modified, Draft-Version, and Draft-Discuss.
where the draft is being discussed. Final and Obsolete TEPs MUST NOT
have these fields, which are for Drafts only.</p>
</div>
-<div class="section">
-<h2><a id="tep-body" name="tep-body">3.2 TEP Body</a></h2>
+<div class="section" id="tep-body">
+<h2><a name="tep-body">3.2 TEP Body</a></h2>
<p>The first element of the TEP body MUST be the title of the document. A
TEP SHOULD follow the title with an Abstract, which gives a brief
overview of the content of the TEP. Longer TEPs MAY, after the
detailed author contact information.</p>
</div>
</div>
-<div class="section">
-<h1><a id="reference" name="reference">4. Reference</a></h1>
+<div class="section" id="reference">
+<h1><a name="reference">4. Reference</a></h1>
<p>The reference use of this document is TEP 1 (itself).</p>
</div>
-<div class="section">
-<h1><a id="acknowledgments" name="acknowledgments">5. Acknowledgments</a></h1>
+<div class="section" id="acknowledgments">
+<h1><a name="acknowledgments">5. Acknowledgments</a></h1>
<p>The definitions of the compliance terms are a direct copy of
definitions taken from IETF RFC 2119.</p>
</div>
-<div class="section">
-<h1><a id="author-s-address" name="author-s-address">6. Author's Address</a></h1>
+<div class="section" id="author-s-address">
+<h1><a name="author-s-address">6. Author's Address</a></h1>
<div class="line-block">
<div class="line">Philip Levis</div>
<div class="line">467 Soda Hall</div>
<div class="line">email - <a class="reference" href="mailto:pal@cs.berkeley.edu">pal@cs.berkeley.edu</a></div>
</div>
</div>
-<div class="section">
-<h1><a id="citations" name="citations">7. Citations</a></h1>
+<div class="section" id="citations">
+<h1><a name="citations">7. Citations</a></h1>
<table class="docutils footnote" frame="void" id="id2" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.3.6: http://docutils.sourceforge.net/" />
<title>Analog-to-Digital Converters (ADCs)</title>
<meta name="author" content="Jan-Hinrich Hauer, Philip Levis, Vlado Handziski, David Gay" />
<style type="text/css">
</style>
</head>
<body>
-<div class="document" id="analog-to-digital-converters-adcs">
<h1 class="title">Analog-to-Digital Converters (ADCs)</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<td>Jan-Hinrich Hauer, Philip Levis, Vlado Handziski, David Gay</td></tr>
</tbody>
</table>
+<div class="document" id="analog-to-digital-converters-adcs">
<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
of this memo is unlimited. This memo is in full compliance with
<a class="citation-reference" href="#tep1" id="id1" name="id1">[TEP1]</a>.</p>
</div>
-<div class="section">
-<h1><a id="abstract" name="abstract">Abstract</a></h1>
+<div class="section" id="abstract">
+<h1><a name="abstract">Abstract</a></h1>
<p>This TEP proposes a hardware abstraction for analog-to-digital converters (ADCs)
in TinyOS 2.x, which is aligned to the three-layer Hardware Abstraction
Architecture (HAA) specified in <a class="citation-reference" href="#tep2" id="id2" name="id2">[TEP2]</a>. It describes some design principles and
documents the set of hardware-independent interfaces to an ADC.</p>
</div>
-<div class="section">
-<h1><a id="introduction" name="introduction">1. Introduction</a></h1>
+<div class="section" id="introduction">
+<h1><a name="introduction">1. Introduction</a></h1>
<p>Analog-to-digital converters (ADCs) are devices that convert analog input
signals to discrete digital output signals, typically voltage to a binary
number. The interested reader can refer to Appendix A for a brief overview of
<ul class="simple">
<li>the set of standard TinyOS interfaces for collecting ADC conversion
results and for configuring an ADC (<a class="reference" href="#interfaces">2. Interfaces</a>)</li>
-<li>guidelines on how an ADC's HAL should expose chip-specific
+<li>guidelines on how an ADC's HAL should expose chip-specific
interfaces (<a class="reference" href="#hal-guidelines">3. HAL guidelines</a>)</li>
<li>what components an ADC's HIL MUST implement (<a class="reference" href="#hil-requirements">4. HIL requirements</a>)</li>
-<li>guidelines on how the HIL should be implemented
+<li>guidelines on how the HIL should be implemented
(<a class="reference" href="#hil-guidelines">5. HIL guidelines</a>)</li>
<li>a section pointing to current implementations (<a class="reference" href="#implementation">6. Implementation</a>)</li>
</ul>
<p>This TEP ends with appendices documenting, as an example, the ADC implementation
for the TI MSP430 MCU.</p>
</div>
-<div class="section">
-<h1><a id="interfaces" name="interfaces">2. Interfaces</a></h1>
+<div class="section" id="interfaces">
+<h1><a name="interfaces">2. Interfaces</a></h1>
<p>This TEP proposes the <tt class="docutils literal"><span class="pre">AdcConfigure</span></tt> interface for ADC hardware configuration
and the <tt class="docutils literal"><span class="pre">Read</span></tt>, <tt class="docutils literal"><span class="pre">ReadStream</span></tt> and <tt class="docutils literal"><span class="pre">ReadNow</span></tt> interfaces to acquire
conversion results. The <tt class="docutils literal"><span class="pre">Read</span></tt> and <tt class="docutils literal"><span class="pre">ReadStream</span></tt> interfaces are documented
in <a class="citation-reference" href="#tep114" id="id9" name="id9">[TEP114]</a> and the <tt class="docutils literal"><span class="pre">ReadNow</span></tt> interface is documented in this TEP. A
<tt class="docutils literal"><span class="pre">Read[Now|Stream]</span></tt> interface is always provided in conjunction with a
<tt class="docutils literal"><span class="pre">AdcConfigure</span></tt> interface.</p>
-<div class="section">
-<h2><a id="interface-for-configuring-the-adc-hardware" name="interface-for-configuring-the-adc-hardware">Interface for configuring the ADC hardware</a></h2>
+<div class="section" id="interface-for-configuring-the-adc-hardware">
+<h2><a name="interface-for-configuring-the-adc-hardware">Interface for configuring the ADC hardware</a></h2>
<p>The <tt class="docutils literal"><span class="pre">AdcConfigure</span></tt> interface is defined as follows:</p>
<pre class="literal-block">
-interface AdcConfigure< config_type >
+interface AdcConfigure< config_type >
{
- async command config_type getConfiguration();
+ async command config_type getConfiguration();
}
</pre>
<p>This interface is used by the ADC stack to retrieve the hardware configuration
configuration per client - instead the ADC client can, for example, store its
configuration in program memory.</p>
</div>
-<div class="section">
-<h2><a id="interfaces-for-acquiring-conversion-results" name="interfaces-for-acquiring-conversion-results">Interfaces for acquiring conversion results</a></h2>
+<div class="section" id="interfaces-for-acquiring-conversion-results">
+<h2><a name="interfaces-for-acquiring-conversion-results">Interfaces for acquiring conversion results</a></h2>
<p>This TEP proposes to adopt the following two source-independent data
collection interfaces from <a class="citation-reference" href="#tep114" id="id10" name="id10">[TEP114]</a> for the collection of ADC conversion
results on the level of HIL:</p>
<tt class="docutils literal"><span class="pre">size_type</span></tt> parameter reflects an upper bound for the chip-specific
resolution of the conversion results - the actual resolution may be smaller
(e.g. uint16_t for a 12-bit ADC).</p>
-<div class="section">
-<h3><a id="read" name="read">Read</a></h3>
+<div class="section" id="read">
+<h3><a name="read">Read</a></h3>
<p>The <tt class="docutils literal"><span class="pre">Read</span></tt> interface can be used to sample an ADC channel once and return a
single conversion result as an uninterpreted value. The <tt class="docutils literal"><span class="pre">Read</span></tt> interface is
documented in <a class="citation-reference" href="#tep114" id="id11" name="id11">[TEP114]</a>.</p>
</div>
-<div class="section">
-<h3><a id="readstream" name="readstream">ReadStream</a></h3>
+<div class="section" id="readstream">
+<h3><a name="readstream">ReadStream</a></h3>
<p>The <tt class="docutils literal"><span class="pre">ReadStream</span></tt> interface can be used to sample an ADC channel multiple
times with a specified sampling period. The <tt class="docutils literal"><span class="pre">ReadStream</span></tt> interface is
documented in <a class="citation-reference" href="#tep114" id="id12" name="id12">[TEP114]</a> .</p>
</div>
-<div class="section">
-<h3><a id="readnow" name="readnow">ReadNow</a></h3>
+<div class="section" id="readnow">
+<h3><a name="readnow">ReadNow</a></h3>
<p>The <tt class="docutils literal"><span class="pre">ReadNow</span></tt> interface is intended for split-phase low-latency
reading of small values:</p>
<pre class="literal-block">
-interface ReadNow<val_t>
+interface ReadNow<val_t>
{
async command error_t read();
async event void readDone( error_t result, val_t val );
</div>
</div>
</div>
-<div class="section">
-<h1><a id="hal-guidelines" name="hal-guidelines">3. HAL guidelines</a></h1>
+<div class="section" id="hal-guidelines">
+<h1><a name="hal-guidelines">3. HAL guidelines</a></h1>
<p>As explained in <a class="reference" href="#introduction">1. Introduction</a> the HAL exposes the full capabilities of the
ADC hardware. Therefore only chip- and platform-dependent clients can wire to
the HAL. Although the HAL is chip-specific, both, in terms of implementation
and representation, its design should follow the guidelines described in this
section to facilitate the mapping to the HIL representation. Appendix B shows
the signature of the HAL for the MSP430.</p>
-<div class="section">
-<h2><a id="resource-reservation" name="resource-reservation">Resource reservation</a></h2>
+<div class="section" id="resource-reservation">
+<h2><a name="resource-reservation">Resource reservation</a></h2>
<p>As the ADC hardware is a shared resource that is usually multiplexed between
several clients some form of access arbitration is necessary. The HAL should
therefore provide a parameterized <tt class="docutils literal"><span class="pre">Resource</span></tt> interface, instantiate a
all platforms the standard round robin arbiter is recommended. Resource
arbiters and the <tt class="docutils literal"><span class="pre">Resource</span></tt> interface are the topic of <a class="citation-reference" href="#tep108" id="id15" name="id15">[TEP108]</a>.</p>
</div>
-<div class="section">
-<h2><a id="configuration-and-sampling" name="configuration-and-sampling">Configuration and sampling</a></h2>
+<div class="section" id="configuration-and-sampling">
+<h2><a name="configuration-and-sampling">Configuration and sampling</a></h2>
<p>As the ADC hardware is a shared resource the HAL should support hardware
configuration and sampling per client (although per-port configuration is
possible, it is not recommended, because it forces all clients to use the same
it after the return of the respective command. Appendix B shows the HAL
interfaces for the MSP430.</p>
</div>
-<div class="section">
-<h2><a id="hal-virtualization" name="hal-virtualization">HAL virtualization</a></h2>
+<div class="section" id="hal-virtualization">
+<h2><a name="hal-virtualization">HAL virtualization</a></h2>
<p>In order to hide wiring complexities and/or export only a subset of all ADC
functions generic ADC wrapper components may be provided on the level of HAL.
Such components can also be used to ensure that a sampling interface is always
client ID if this is required by the HAL implementation.</p>
</div>
</div>
-<div class="section">
-<h1><a id="hil-requirements" name="hil-requirements">4. HIL requirements</a></h1>
+<div class="section" id="hil-requirements">
+<h1><a name="hil-requirements">4. HIL requirements</a></h1>
<p>The following generic components MUST be provided on all platforms that have an
ADC:</p>
<pre class="literal-block">
-AdcReadClientC
-AdcReadNowClientC
-AdcReadStreamClientC
+AdcReadClientC
+AdcReadNowClientC
+AdcReadStreamClientC
</pre>
<p>These components provide virtualized access to the HIL of an ADC. They are
instantiated by an ADC client and provide/use the four interfaces described in
platform (the question of how to deal with multiple devices of the same class
is a general one in TinyOS 2.x). Appendix C shows the <tt class="docutils literal"><span class="pre">AdcReadClientC</span></tt> for
the MSP430.</p>
-<div class="section">
-<h2><a id="adcreadclientc" name="adcreadclientc">AdcReadClientC</a></h2>
+<div class="section" id="adcreadclientc">
+<h2><a name="adcreadclientc">AdcReadClientC</a></h2>
<pre class="literal-block">
generic configuration AdcReadClientC() {
provides {
placeholders and will be instantiated by the respective HIL implementation (for
an example, see the AdcReadClientC for the MSP430 in Appendix C).</p>
</div>
-<div class="section">
-<h2><a id="adcreadnowclientc" name="adcreadnowclientc">AdcReadNowClientC</a></h2>
+<div class="section" id="adcreadnowclientc">
+<h2><a name="adcreadnowclientc">AdcReadNowClientC</a></h2>
<pre class="literal-block">
generic configuration AdcReadNowClientC() {
provides {
instantiated by the respective HIL implementation (for an example how this is
done for the AdcReadClientC see Appendix C).</p>
</div>
-<div class="section">
-<h2><a id="adcreadstreamclientc" name="adcreadstreamclientc">AdcReadStreamClientC</a></h2>
+<div class="section" id="adcreadstreamclientc">
+<h2><a name="adcreadstreamclientc">AdcReadStreamClientC</a></h2>
<pre class="literal-block">
generic configuration AdcReadStreamClientC() {
provides {
this is done for the AdcReadClientC see Appendix C).</p>
</div>
</div>
-<div class="section">
-<h1><a id="hil-guidelines" name="hil-guidelines">5. HIL guidelines</a></h1>
+<div class="section" id="hil-guidelines">
+<h1><a name="hil-guidelines">5. HIL guidelines</a></h1>
<p>The HIL implementation of an ADC stack has two main tasks: it translates a
<tt class="docutils literal"><span class="pre">Read</span></tt>, <tt class="docutils literal"><span class="pre">ReadNow</span></tt> or <tt class="docutils literal"><span class="pre">ReadStream</span></tt> request to a chip-specific HAL sampling
command and it abstracts from the <tt class="docutils literal"><span class="pre">Resource</span></tt> interface (the latter only for
check can also be done in the HAL implementation). Once the HIL is signalled
the conversion result(s) it forwards it to the respective <tt class="docutils literal"><span class="pre">ReadNow</span></tt> client.</p>
</div>
-<div class="section">
-<h1><a id="implementation" name="implementation">6. Implementation</a></h1>
-<div class="section">
-<h2><a id="testadc-application" name="testadc-application">TestAdc application</a></h2>
+<div class="section" id="implementation">
+<h1><a name="implementation">6. Implementation</a></h1>
+<div class="section" id="testadc-application">
+<h2><a name="testadc-application">TestAdc application</a></h2>
<p>An ADC HIL test application can be found in <tt class="docutils literal"><span class="pre">tinyos-2.x/apps/tests/TestAdc</span></tt>.
Note that this application instantiates generic DemoSensorC, DemoSensorStreamC
and DemoSensorNowC components (see <a class="citation-reference" href="#tep114" id="id19" name="id19">[TEP114]</a>) and assumes that these components
are actually wired to an ADC HIL. Please refer to
<tt class="docutils literal"><span class="pre">tinyos-2.x/apps/tests/TestAdc/README.txt</span></tt> for more information.</p>
</div>
-<div class="section">
-<h2><a id="haa-on-the-msp430-and-atmega-128" name="haa-on-the-msp430-and-atmega-128">HAA on the MSP430 and Atmega 128</a></h2>
+<div class="section" id="haa-on-the-msp430-and-atmega-128">
+<h2><a name="haa-on-the-msp430-and-atmega-128">HAA on the MSP430 and Atmega 128</a></h2>
<p>The implementation of the ADC12 stack on the MSP430 can be found in
<tt class="docutils literal"><span class="pre">tinyos-2.x/tos/chips/msp430/adc12</span></tt>:</p>
<blockquote>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">HplAtm128AdcC.nc</span></tt> is the HPL implementation</li>
<li><tt class="docutils literal"><span class="pre">Atm128AdcP.nc</span></tt> is the HAL implementation</li>
-<li><tt class="docutils literal"><span class="pre">AdcP.nc</span></tt>, <tt class="docutils literal"><span class="pre">WireAdcP.nc</span></tt> and the library components for arbitrating
+<li><tt class="docutils literal"><span class="pre">AdcP.nc</span></tt>, <tt class="docutils literal"><span class="pre">WireAdcP.nc</span></tt> and the library components for arbitrating
'Read', 'ReadNow' and 'ReadStream', <tt class="docutils literal"><span class="pre">ArbitratedReadC</span></tt> and
<tt class="docutils literal"><span class="pre">ArbitratedReadStreamC</span></tt> (in <tt class="docutils literal"><span class="pre">tinyos-2.x/tos/system</span></tt>), realize
the HIL</li>
</blockquote>
</div>
</div>
-<div class="section">
-<h1><a id="appendix-a-hardware-differences-between-platforms" name="appendix-a-hardware-differences-between-platforms">Appendix A: Hardware differences between platforms</a></h1>
+<div class="section" id="appendix-a-hardware-differences-between-platforms">
+<h1><a name="appendix-a-hardware-differences-between-platforms">Appendix A: Hardware differences between platforms</a></h1>
<p>The following table compares the characteristics of two microcontrollers
commonly used in TinyOS platforms:</p>
<table border="1" class="docutils">
<col width="32%" />
</colgroup>
<thead valign="bottom">
-<tr><th class="head"> </th>
-<th class="head">Atmel Atmega 128</th>
-<th class="head">TI MSP430 ADC12</th>
+<tr><th> </th>
+<th>Atmel Atmega 128</th>
+<th>TI MSP430 ADC12</th>
</tr>
</thead>
<tbody valign="top">
</tbody>
</table>
</div>
-<div class="section">
-<h1><a id="appendix-b-a-hal-representation-msp430-adc12" name="appendix-b-a-hal-representation-msp430-adc12">Appendix B: a HAL representation: MSP430 ADC12</a></h1>
+<div class="section" id="appendix-b-a-hal-representation-msp430-adc12">
+<h1><a name="appendix-b-a-hal-representation-msp430-adc12">Appendix B: a HAL representation: MSP430 ADC12</a></h1>
<p>This section shows the HAL signature for the ADC12 of the TI MSP430 MCU. It
reflects the four MSP430 ADC12 conversion modes as it lets a client sample an
ADC channel once ("Single-channel-single-conversion") or repeatedly
<tt class="docutils literal"><span class="pre">DMAExtension</span></tt> interface is used to reset the state machine when the DMA is
responsible for data transfer (managed in an exterior component):</p>
<pre class="literal-block">
-configuration Msp430Adc12P
-{
+configuration Msp430Adc12P
+{
provides {
- interface Resource[uint8_t id];
- interface Msp430Adc12SingleChannel as SingleChannel[uint8_t id];
+ interface Resource[uint8_t id];
+ interface Msp430Adc12SingleChannel as SingleChannel[uint8_t id];
interface AsyncStdControl as DMAExtension[uint8_t id];
}
}
-interface Msp430Adc12SingleChannel
-{
+interface Msp430Adc12SingleChannel
+{
async command error_t configureSingle(const msp430adc12_channel_config_t *config);
async command error_t configureSingleRepeat(const msp430adc12_channel_config_t *config, uint16_t jiffies);
async command error_t configureMultiple( const msp430adc12_channel_config_t *config, uint16_t buffer[], uint16_t numSamples, uint16_t jiffies);
async command error_t configureMultipleRepeat(const msp430adc12_channel_config_t *config, uint16_t buffer[], uint8_t numSamples, uint16_t jiffies);
async command error_t getData();
async event error_t singleDataReady(uint16_t data);
- async event uint16_t* multipleDataReady(uint16_t buffer[], uint16_t numSamples);
+ async event uint16_t* multipleDataReady(uint16_t buffer[], uint16_t numSamples);
}
-typedef struct
-{
- unsigned int inch: 4; // input channel
- unsigned int sref: 3; // reference voltage
- unsigned int ref2_5v: 1; // reference voltage level
- unsigned int adc12ssel: 2; // clock source sample-hold-time
- unsigned int adc12div: 3; // clock divider sample-hold-time
+typedef struct
+{
+ unsigned int inch: 4; // input channel
+ unsigned int sref: 3; // reference voltage
+ unsigned int ref2_5v: 1; // reference voltage level
+ unsigned int adc12ssel: 2; // clock source sample-hold-time
+ unsigned int adc12div: 3; // clock divider sample-hold-time
unsigned int sht: 4; // sample-hold-time
- unsigned int sampcon_ssel: 2; // clock source sampcon signal
+ unsigned int sampcon_ssel: 2; // clock source sampcon signal
unsigned int sampcon_id: 2; // clock divider sampcon signal
} msp430adc12_channel_config_t;
</pre>
</div>
-<div class="section">
-<h1><a id="appendix-c-a-hil-representation-msp430-adc12" name="appendix-c-a-hil-representation-msp430-adc12">Appendix C: a HIL representation: MSP430 ADC12</a></h1>
+<div class="section" id="appendix-c-a-hil-representation-msp430-adc12">
+<h1><a name="appendix-c-a-hil-representation-msp430-adc12">Appendix C: a HIL representation: MSP430 ADC12</a></h1>
<p>The signature of the AdcReadClientC component for the MSP430 ADC12 is as
follows:</p>
<pre class="literal-block">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.3.6: http://docutils.sourceforge.net/" />
<title>Timers</title>
<meta name="author" content="Cory Sharp, Martin Turon, David Gay" />
<style type="text/css">
</style>
</head>
<body>
-<div class="document" id="timers">
<h1 class="title">Timers</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<td>Cory Sharp, Martin Turon, David Gay</td></tr>
<tr class="field"><th class="docinfo-name">Draft-Created:</th><td class="field-body">22-Sep-2004</td>
</tr>
-<tr class="field"><th class="docinfo-name">Draft-Version:</th><td class="field-body">1.1.2.9</td>
+<tr class="field"><th class="docinfo-name">Draft-Version:</th><td class="field-body">1.7</td>
</tr>
-<tr class="field"><th class="docinfo-name">Draft-Modified:</th><td class="field-body">2006-10-18</td>
+<tr class="field"><th class="docinfo-name">Draft-Modified:</th><td class="field-body">2006-12-12</td>
</tr>
<tr class="field"><th class="docinfo-name">Draft-Discuss:</th><td class="field-body">TinyOS Developer List <tinyos-devel at mail.millennium.berkeley.edu></td>
</tr>
</tbody>
</table>
+<div class="document" id="timers">
<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
of this memo is unlimited. This memo is in full compliance with
TEP 1.</p>
</div>
-<div class="section">
-<h1><a id="abstract" name="abstract">Abstract</a></h1>
+<div class="section" id="abstract">
+<h1><a name="abstract">Abstract</a></h1>
<p>This TEP proposes a Timer design that supports common timing
requirements both in precision and width across common hardware
configurations. This TEP focuses on aligning the Timer abstraction
with the three-layer Hardware Abstraction Architecture (HAA).</p>
</div>
-<div class="section">
-<h1><a id="introduction" name="introduction">1. Introduction</a></h1>
+<div class="section" id="introduction">
+<h1><a name="introduction">1. Introduction</a></h1>
<p>Most microcontrollers offer a rich timer system, with features like:</p>
<ul class="simple">
<li>several counters, possibly of different widths, with multiple clocking options</li>
platform-independent fashion. Instead, following the principles of the
HAA[_tep2], each microcontroller should expose all this functionality
via components and interfaces at the HPL and, where appropriate, HAL levels.
-However, two aspects of timers are sufficiently common and important
+However, two aspects of timers are sufficiently common and important
that they should be made available in a well-defined way: measuring time,
and triggering (possibly repeating) events at specific times. The rest
of this TEP specifies:</p>
events (<a class="reference" href="#interfaces">2. Interfaces</a>)</li>
<li>guidelines on how each microcontroller's HAL SHOULD expose its timer hardware
in terms of the above interfaces (<a class="reference" href="#hal-guidelines">3. HAL guidelines</a>)</li>
-<li>what components a microcontroller's timer HIL MUST implement
+<li>what components a microcontroller's timer HIL MUST implement
(<a class="reference" href="#hil-requirements">4. HIL requirements</a>)</li>
<li>a set of utility components whose use simplifies building the components
specified by the HAL guidelines and HIL requirements (<a class="reference" href="#utility-components">5. Utility components</a>)</li>
<p>This TEP ends with appendices documenting, as an example, the mica2
timer subsystem implementation.</p>
</div>
-<div class="section">
-<h1><a id="interfaces" name="interfaces">2. Interfaces</a></h1>
+<div class="section" id="interfaces">
+<h1><a name="interfaces">2. Interfaces</a></h1>
<p>Before presenting the interfaces (2.2), we start with a general
discussion of the issues of precision, width and accuracy in
timer interfaces (2.1).</p>
-<div class="section">
-<h2><a id="precision-width-and-accuracy" name="precision-width-and-accuracy">2.1 Precision, Width and Accuracy.</a></h2>
+<div class="section" id="precision-width-and-accuracy">
+<h2><a name="precision-width-and-accuracy">2.1 Precision, Width and Accuracy.</a></h2>
<p>Three fundamental properties of timers are <em>precision</em>, <em>width</em> and
<em>accuracy</em>.</p>
<p>Examples of precision are millisecond, a cycle of a 32kHz clock, and
<p>Note that the precision names are expressed as either frequency or
period, whichever is convenient.</p>
</div>
-<div class="section">
-<h2><a id="timer-interfaces" name="timer-interfaces">2.2 Timer interfaces</a></h2>
+<div class="section" id="timer-interfaces">
+<h2><a name="timer-interfaces">2.2 Timer interfaces</a></h2>
<p>This TEP proposes these timer interfaces:</p>
<pre class="literal-block">
interface Counter< precision_tag, size_type >
and Counter interfaces are used by the TinyOS timer system and
advanced user components.</p>
</div>
-<div class="section">
-<h2><a id="counter" name="counter">Counter</a></h2>
-<p>A Counter component will increase the width of a low-level hardware timer
+<div class="section" id="counter">
+<h2><a name="counter">Counter</a></h2>
+<p>A Counter component will increase the width of a low-level hardware timer
by wrapping the overflow event and incrementing its higher order bits.
These higher order bits are considered extra state over the HPL register
layer, and therefore qualify all Counters as HAL components.
}
</pre>
<dl class="docutils">
-<dt>get()</dt>
+<dt>get() </dt>
<dd>return the current time.</dd>
-<dt>isOverflowPending()</dt>
+<dt>isOverflowPending() </dt>
<dd>return TRUE if the overflow flag is set for this counter, i.e., if and
only if an overflow interrupt will occur after the outermost atomic
block exits. Return FALSE otherwise. This command only returns the
state of the overflow flag and causes no side effect. It is expected
that the underlying hardware platform sets the overflow flag when
appropriate.</dd>
-<dt>clearOverflow()</dt>
+<dt>clearOverflow() </dt>
<dd>cancel the pending overflow interrupt clearing the overflow flag.</dd>
-<dt>overflow()</dt>
+<dt>overflow() </dt>
<dd>signals that an overflow in the current time. That is, the current
time has wrapped around from its maximum value to zero.</dd>
</dl>
</div>
-<div class="section">
-<h2><a id="alarm" name="alarm">Alarm</a></h2>
+<div class="section" id="alarm">
+<h2><a name="alarm">Alarm</a></h2>
<p>Alarm components are extensions of Counters that signal an event
when their compare register detects the alarm time has been hit.
All commands and events of the Alarm interface are asynchronous (or
}
</pre>
<dl class="docutils">
-<dt>start(dt)</dt>
+<dt>start(dt) </dt>
<dd>cancel any previously running alarm and set to fire in dt time units
from the time of invocation. The alarm will only fire once then
stop.</dd>
-<dt>stop()</dt>
+<dt>stop() </dt>
<dd>cancel any previously running alarm.</dd>
-<dt>fired()</dt>
+<dt>fired() </dt>
<dd>signals that the alarm has occurred.</dd>
-<dt>isRunning()</dt>
+<dt>isRunning() </dt>
<dd>return TRUE if the alarm has been started and has not been cancelled
or has not yet fired. FALSE is returned otherwise.</dd>
</dl>
internally, to be able to use of the full width of an alarm while also
detecting when a short alarm elapses prematurely.</blockquote>
<dl class="docutils">
-<dt>getNow()</dt>
+<dt>getNow() </dt>
<dd>return the current time in the precision and width of the alarm.</dd>
-<dt>getAlarm()</dt>
+<dt>getAlarm() </dt>
<dd>return the time the currently running alarm will fire or the time
that the previously running alarm was set to fire. getAlarm can
be used with startAt to set an alarm from the previous alarm time,
fired() event to construct periodic alarms.</dd>
</dl>
</div>
-<div class="section">
-<h2><a id="busywait" name="busywait">BusyWait</a></h2>
+<div class="section" id="busywait">
+<h2><a name="busywait">BusyWait</a></h2>
<p>The BusyWait interface allows for very short synchronous delays.
BusyWait should be used sparingly and when an Alarm would not be
reasonably efficient or accurate. The BusyWait interface replaces
<dd>block until at least dt time units have elapsed</dd>
</dl>
</div>
-<div class="section">
-<h2><a id="localtime" name="localtime">LocalTime</a></h2>
+<div class="section" id="localtime">
+<h2><a name="localtime">LocalTime</a></h2>
<p>The LocalTime interface exposes a 32-bit counter without overflow
utilities. This is primarily for application code that does not
care about overflow conditions.</p>
}
</pre>
<dl class="docutils">
-<dt>get()</dt>
+<dt>get() </dt>
<dd>return the current time.</dd>
</dl>
</div>
-<div class="section">
-<h2><a id="timer" name="timer">Timer</a></h2>
+<div class="section" id="timer">
+<h2><a name="timer">Timer</a></h2>
<p>All commands and events of the Timer interface are synchronous (or
in "task context"). The Timer interface provides a set of "basic"
commands for common usage and provides a set of "extended" commands
}
</pre>
<dl class="docutils">
-<dt>startPeriodic(dt)</dt>
+<dt>startPeriodic(dt) </dt>
<dd>cancel any previously running timer and set to fire in dt time units
from the time of invocation. The timer will fire periodically every
dt time units until stopped.</dd>
-<dt>startOneShot(dt)</dt>
+<dt>startOneShot(dt) </dt>
<dd>cancel any previously running timer and set to fire in dt time units
from the time of invocation. The timer will only fire once then
stop.</dd>
-<dt>stop()</dt>
+<dt>stop() </dt>
<dd>cancel any previously running timer.</dd>
<dt>fired()</dt>
<dd>signals that the timer has occurred.</dd>
-<dt>isRunning()</dt>
+<dt>isRunning() </dt>
<dd>return TRUE if the timer has been started and has not been cancelled
and has not fired for the case of one-shot timers. One a periodic
timer is started, isRunning will return TRUE until it is cancelled.</dd>
-<dt>isOneShot()</dt>
+<dt>isOneShot() </dt>
<dd>return TRUE if the timer is a one-shot timer. Return FALSE
otherwise if the timer is a periodic timer.</dd>
-<dt>startPeriodicAt(t0,dt)</dt>
+<dt>startPeriodicAt(t0,dt) </dt>
<dd>cancel any previously running timer and set to fire at time t1 =
t0+dt. The timer will fire periodically every dt time units until
stopped.</dd>
-<dt>startOneShotAt(t0,dt)</dt>
+<dt>startOneShotAt(t0,dt) </dt>
<dd>cancel any previously running timer and set to fire at time t1 =
t0+dt. The timer will fire once then stop.</dd>
-<dt>getNow()</dt>
+<dt>getNow() </dt>
<dd>return the current time in the precision and width of the timer.</dd>
-<dt>gett0()</dt>
+<dt>gett0() </dt>
<dd>return the time anchor for the previously started timer or the time
of the previous event for periodic timers.</dd>
-<dt>getdt()</dt>
+<dt>getdt() </dt>
<dd>return the delay or period for the previously started timer.</dd>
</dl>
</div>
</div>
-<div class="section">
-<h1><a id="hal-guidelines" name="hal-guidelines">3. HAL guidelines</a></h1>
+<div class="section" id="hal-guidelines">
+<h1><a name="hal-guidelines">3. HAL guidelines</a></h1>
<p>Platforms SHOULD expose their relevant timing capabilities using
standard Alarm and Counter interfaces. The design pattern presented
here defines a component naming convention to allow platform
components SHOULD produce compile-time errors when compiled
together.</p>
</div>
-<div class="section">
-<h1><a id="hil-requirements" name="hil-requirements">4. HIL requirements</a></h1>
+<div class="section" id="hil-requirements">
+<h1><a name="hil-requirements">4. HIL requirements</a></h1>
<dl class="docutils">
<dt>The following component MUST be provided on all platforms::</dt>
<dd>HilTimerMilliC
BusyWaitMicroC</dd>
</dl>
-<div class="section">
-<h2><a id="hiltimermillic" name="hiltimermillic">HilTimerMilliC</a></h2>
+<div class="section" id="hiltimermillic">
+<h2><a name="hiltimermillic">HilTimerMilliC</a></h2>
<pre class="literal-block">
configuration HilTimerMilliC
{
Timer.h. HilTimerMilliC is used by the generic component
TimerMilliC found in <tt class="docutils literal"><span class="pre">tos/system/</span></tt>.</p>
</div>
-<div class="section">
-<h2><a id="busywaitmicroc" name="busywaitmicroc">BusyWaitMicroC</a></h2>
+<div class="section" id="busywaitmicroc">
+<h2><a name="busywaitmicroc">BusyWaitMicroC</a></h2>
<pre class="literal-block">
configuration BusyWaitMicroC
{
inefficient or insufficiently precise.</p>
</div>
</div>
-<div class="section">
-<h1><a id="utility-components" name="utility-components">5. Utility components</a></h1>
+<div class="section" id="utility-components">
+<h1><a name="utility-components">5. Utility components</a></h1>
<p>A number of platform independent generic components are provided to
help implementers and advanced users of the TinyOS timer system:</p>
<ul class="simple">
</ul>
<p>Appendices B and C show how these can be used to help implement
the timer HAL and HIL.</p>
-<div class="section">
-<h2><a id="alarmtotimerc" name="alarmtotimerc">AlarmToTimerC</a></h2>
+<div class="section" id="alarmtotimerc">
+<h2><a name="alarmtotimerc">AlarmToTimerC</a></h2>
<p>AlarmToTimerC converts a 32-bit Alarm to a Timer.</p>
<pre class="literal-block">
generic component AlarmToTimerC( typedef precision_tag )
}
</pre>
</div>
-<div class="section">
-<h2><a id="busywaitcounterc" name="busywaitcounterc">BusyWaitCounterC</a></h2>
+<div class="section" id="busywaitcounterc">
+<h2><a name="busywaitcounterc">BusyWaitCounterC</a></h2>
<p>BusyWaitCounterC uses a Counter to block until a specified amount of
time elapses.</p>
<pre class="literal-block">
}
</pre>
</div>
-<div class="section">
-<h2><a id="countertolocaltimec" name="countertolocaltimec">CounterToLocalTimeC</a></h2>
+<div class="section" id="countertolocaltimec">
+<h2><a name="countertolocaltimec">CounterToLocalTimeC</a></h2>
<p>CounterToLocalTimeC converts from a 32-bit Counter to LocalTime.</p>
<pre class="literal-block">
generic component CounterToLocalTimeC( precision_tag )
}
</pre>
</div>
-<div class="section">
-<h2><a id="transformalarmc" name="transformalarmc">TransformAlarmC</a></h2>
+<div class="section" id="transformalarmc">
+<h2><a name="transformalarmc">TransformAlarmC</a></h2>
<p>TransformAlarmC decreases precision and/or widens an Alarm. An
already widened Counter component is used to help.</p>
<pre class="literal-block">
-generic component TransformAlarmC(
+generic component TransformAlarmC(
typedef to_precision_tag,
typedef to_size_type @integer(),
typedef from_precision_tag,
consistent. No compile errors are generated if the parameters
passed to TransformAlarmC are inconsistent.</p>
</div>
-<div class="section">
-<h2><a id="transformcounterc" name="transformcounterc">TransformCounterC</a></h2>
+<div class="section" id="transformcounterc">
+<h2><a name="transformcounterc">TransformCounterC</a></h2>
<p>TransformCounterC decreases precision and/or widens a Counter.</p>
<pre class="literal-block">
generic component TransformCounterC(
new TransformCounterC( TMilli, uint32_t, T32khz, uint16_t, 5, uint32_t )
</pre>
</div>
-<div class="section">
-<h2><a id="virtualizetimerc" name="virtualizetimerc">VirtualizeTimerC</a></h2>
+<div class="section" id="virtualizetimerc">
+<h2><a name="virtualizetimerc">VirtualizeTimerC</a></h2>
<p>VirtualizeTimerC uses a single Timer to create up to 255 virtual
timers.</p>
<pre class="literal-block">
</pre>
</div>
</div>
-<div class="section">
-<h1><a id="implementation" name="implementation">6. Implementation</a></h1>
+<div class="section" id="implementation">
+<h1><a name="implementation">6. Implementation</a></h1>
<p>The definition of the HIL interfaces are found in <tt class="docutils literal"><span class="pre">tinyos-2.x/tos/lib/timer</span></tt>:</p>
<blockquote>
<ul class="simple">
</ul>
</blockquote>
</div>
-<div class="section">
-<h1><a id="author-s-address" name="author-s-address">7. Author's Address</a></h1>
+<div class="section" id="author-s-address">
+<h1><a name="author-s-address">7. Author's Address</a></h1>
<div class="line-block">
<div class="line">Cory Sharp</div>
<div class="line">Moteiv Corporation</div>
<div class="line">email - <a class="reference" href="mailto:david.e.gay@intel.com">david.e.gay@intel.com</a></div>
</div>
</div>
-<div class="section">
-<h1><a id="appendix-a-timer-hardware-on-various-microcontrollers" name="appendix-a-timer-hardware-on-various-microcontrollers">Appendix A: Timer hardware on various microcontrollers</a></h1>
+<div class="section" id="appendix-a-timer-hardware-on-various-microcontrollers">
+<h1><a name="appendix-a-timer-hardware-on-various-microcontrollers">Appendix A: Timer hardware on various microcontrollers</a></h1>
<blockquote>
<ol class="loweralpha simple">
<li>Atmega128</li>
</blockquote>
</blockquote>
</div>
-<div class="section">
-<h1><a id="appendix-b-a-microcontroller-atmega-128-timer-subsystem" name="appendix-b-a-microcontroller-atmega-128-timer-subsystem">Appendix B: a microcontroller: Atmega 128 timer subsystem</a></h1>
+<div class="section" id="appendix-b-a-microcontroller-atmega-128-timer-subsystem">
+<h1><a name="appendix-b-a-microcontroller-atmega-128-timer-subsystem">Appendix B: a microcontroller: Atmega 128 timer subsystem</a></h1>
<p>The Atmega128 exposes its four timers through a common set of interfaces:</p>
<blockquote>
<ul class="simple">
async command bool isOn(); //<! Is overflow interrupt on?
/// Clock initialization interface
- async command void off(); //<! Turn off the clock
+ async command void off(); //<! Turn off the clock
async command void setScale( uint8_t scale); //<! Turn on the clock
async command uint8_t getScale(); //<! Get prescaler setting
}
/// Interrupt signals
async event void captured(size_type t); //<! Signalled on capture int
- /// Interrupt flag utilites: Bit level set/clr
+ /// Interrupt flag utilites: Bit level set/clr
async command void reset(); //<! Clear the capture interrupt flag
async command void start(); //<! Enable the capture interrupt
async command void stop(); //<! Turn off capture interrupts
} ...
</pre>
</div>
-<div class="section">
-<h1><a id="appendix-c-a-mote-mica-family-timer-subsystem" name="appendix-c-a-mote-mica-family-timer-subsystem">Appendix C: a mote: Mica family timer subsystem</a></h1>
+<div class="section" id="appendix-c-a-mote-mica-family-timer-subsystem">
+<h1><a name="appendix-c-a-mote-mica-family-timer-subsystem">Appendix C: a mote: Mica family timer subsystem</a></h1>
<p>Members of the mica family (mica2, mica2dot, micaz) use the Atmega128
microprocessor and have external crystals at 4 or 7.37MHz. Additionally,
they can be run from an internal oscillator at 1, 2, 4, or 8 MHz. The
<li><p class="first">Timer 1: the 16-bit hardware timer 1 is set to run at 1MHz if possible.
However, the set of dividers for timer 1 is limited to 1, 8,
64, 256 and 1024. So, when clocked at 2 or 4MHz, a divider of 1 is
-selected and timer 1 runs at 2 or 4MHz. To reflect this fact, the
+selected and timer 1 runs at 2 or 4MHz. To reflect this fact, the
HAL components exposing timer 1 are named <tt class="docutils literal"><span class="pre">CounterOne16C</span></tt> and
<tt class="docutils literal"><span class="pre">AlarmOne16C</span></tt> (rather than the <tt class="docutils literal"><span class="pre">CounterMicro16C</span></tt> <tt class="docutils literal"><span class="pre">AlarmMicro16C</span></tt>
as suggested in Section 3).</p>
<li><p class="first">Timer 3: the 16-bit hardware timer 3 is set to run at a rate close to
32768Hz, if possible. As with timer 1, the limited set of dividers makes
this impossible at some clock frequencies, so the 16-bit timer 3 HAL
-components are named <tt class="docutils literal"><span class="pre">CounterThree16C</span></tt> and <tt class="docutils literal"><span class="pre">AlarmThree16C</span></tt>. As
+components are named <tt class="docutils literal"><span class="pre">CounterThree16C</span></tt> and <tt class="docutils literal"><span class="pre">AlarmThree16C</span></tt>. As
with timer 1, the rate of timer 3 is adjusted in software when
building the 32-bit counter and 32-bit alarms, giving components
<tt class="docutils literal"><span class="pre">Counter32khz32C</span></tt> and <tt class="docutils literal"><span class="pre">Alarm32khz32C</span></tt>. As with timer 1, three compare
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.3.6: http://docutils.sourceforge.net/" />
<title>Permanent Data Storage (Flash)</title>
<meta name="author" content="David Gay, Jonathan Hui" />
<style type="text/css">
</style>
</head>
<body>
-<div class="document" id="permanent-data-storage-flash">
<h1 class="title">Permanent Data Storage (Flash)</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<td>David Gay, Jonathan Hui</td></tr>
</tbody>
</table>
+<div class="document" id="permanent-data-storage-flash">
<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
of this memo is unlimited. This memo is in full compliance with
TEP 1.</p>
</div>
-<div class="section">
-<h1><a id="abstract" name="abstract">Abstract</a></h1>
+<div class="section" id="abstract">
+<h1><a name="abstract">Abstract</a></h1>
<p>This memo documents a set of hardware-independent interfaces to non-volatile
storage for TinyOS 2.x. It describes some design principles for the HPL and
HAL layers of various flash chips.</p>
</div>
-<div class="section">
-<h1><a id="introduction" name="introduction">1. Introduction</a></h1>
+<div class="section" id="introduction">
+<h1><a name="introduction">1. Introduction</a></h1>
<p>Flash chips are a form of EEPROM (electrically-erasable, programmable
read-only memory), distinguished by a fast erase capability. However,
erases can only be done in large units (from 256B to 128kB depending on the
<col width="28%" />
</colgroup>
<thead valign="bottom">
-<tr><th class="head">X</th>
-<th class="head">NOR
+<tr><th>X</th>
+<th>NOR
(ex: ST M25P40,
Intel PXA27x)</th>
-<th class="head">AT45DB</th>
-<th
class="head"><dl class="first last docutils">
+<th>AT45DB</th>
+<th><dl class="first last docutils">
<dt>NAND</dt>
<dd>(ex: Samsung
K9K1G08R0B)</dd>
support some applications (e.g., network reprogramming) very well.</li>
</ul>
</div>
-<div class="section">
-<h1><a id="storage-in-tinyos-2-x" name="storage-in-tinyos-2-x">2. Storage in TinyOS 2.x</a></h1>
+<div class="section" id="storage-in-tinyos-2-x">
+<h1><a name="storage-in-tinyos-2-x">2. Storage in TinyOS 2.x</a></h1>
<p>One approach to hiding the differences between different flash chips is to
provide a disk-like, block interface (with, e.g., 512B blocks). This is the
approach taken by compact flash cards. However, in the context of TinyOS,
flash chips (Section 3), then describes the flash volumes and
storage abstractions in detail (Section 4).</p>
</div>
-<div class="section">
-<h1><a id="hpl-hal-hil-architecture" name="hpl-hal-hil-architecture">3. HPL/HAL/HIL Architecture</a></h1>
+<div class="section" id="hpl-hal-hil-architecture">
+<h1><a name="hpl-hal-hil-architecture">3. HPL/HAL/HIL Architecture</a></h1>
<p>The flash chip architecture follows the three-layer Hardware
Abstraction Architecture (HAA), with each chip providing a presentation
layer (HPL, Section 3.1), adaptation layer (HAL, Section 3.2) and
by relying, e.g., on platform-provided configuration information.</p>
<p>Appendix A shows example HPL and HAL specifications for the AT45DB
and ST M25P chip families.</p>
-<div class="section">
-<h2><a id="hardware-presentation-layer-hpl" name="hardware-presentation-layer-hpl">3.1 Hardware Presentation Layer (HPL)</a></h2>
+<div class="section" id="hardware-presentation-layer-hpl">
+<h2><a name="hardware-presentation-layer-hpl">3.1 Hardware Presentation Layer (HPL)</a></h2>
<p>The flash HPL has a chip-dependent, platform-independent interface. The
implementation of this HPL is platform-dependent. The flash HPL SHOULD be
stateless.</p>
flash chips, this directory MAY also contain a file describing the
particular flash chip found on the platform.</p>
</div>
-<div class="section">
-<h2><a id="hardware-adaptation-layer-hal" name="hardware-adaptation-layer-hal">3.2 Hardware Adaptation Layer (HAL)</a></h2>
+<div class="section" id="hardware-adaptation-layer-hal">
+<h2><a name="hardware-adaptation-layer-hal">3.2 Hardware Adaptation Layer (HAL)</a></h2>
<p>The flash HAL has a chip-dependent, platform-independent interface and
implementation. Flash families with a common HPL SHOULD have a common
HAL. Flash HAL's SHOULD expose a <tt class="docutils literal"><span class="pre">Resource</span></tt> interface and automatically
programmer (see Section 3). This allows users to build new flash
abstractions that interact cleanly with the rest of the flash system.</p>
</div>
-<div class="section">
-<h2><a id="hardware-interface-layer-hil" name="hardware-interface-layer-hil">3.3 Hardware Interface Layer (HIL)</a></h2>
+<div class="section" id="hardware-interface-layer-hil">
+<h2><a name="hardware-interface-layer-hil">3.3 Hardware Interface Layer (HIL)</a></h2>
<p>Each flash chip MUST support at least one of the storage abstractions
described in Section 4. These abstractions SHOULD be presented in
components named <tt class="docutils literal"><span class="pre">ChipAbstractionC</span></tt>, e.g., <tt class="docutils literal"><span class="pre">At45dbLogStorageC</span></tt>.
chip, based on the requested volume.</p>
</div>
</div>
-<div class="section">
-<h1><a id="non-volatile-storage-abstractions" name="non-volatile-storage-abstractions">4. Non-Volatile Storage Abstractions</a></h1>
+<div class="section" id="non-volatile-storage-abstractions">
+<h1><a name="non-volatile-storage-abstractions">4. Non-Volatile Storage Abstractions</a></h1>
<p>The HIL implementations are platform-independent, but chip (family)
dependent. They implement the three storage abstractions and
volume structure discussed in the introduction.</p>
-<div class="section">
-<h2><a id="volumes" name="volumes">4.1. Volumes</a></h2>
+<div class="section" id="volumes">
+<h2><a name="volumes">4.1. Volumes</a></h2>
<p>The division of the flash chip into fixed-size volumes is specified by
an XML file that is placed in the application's directory (where one
types 'make'). The XML file specifies the allocation as follows:</p>
compile-time error since the symbol will be undefined.</p>
<p>A volume MUST NOT be used with more than one storage abstraction instance.</p>
</div>
-<div class="section">
-<h2><a id="large-objects" name="large-objects">4.2 Large objects</a></h2>
+<div class="section" id="large-objects">
+<h2><a name="large-objects">4.2 Large objects</a></h2>
<p>The motivating example for large objects is the transmission or
long-term storage of large pieces of data. For instance, programs in a
network-reprogramming system, or large data-packets in a reliable
by using the <tt class="docutils literal"><span class="pre">computeCrc</span></tt> command and storing the result in a
well-defined location, and checking this CRC when desired.</p>
</div>
-<div class="section">
-<h2><a id="logging" name="logging">4.3 Logging</a></h2>
+<div class="section" id="logging">
+<h2><a name="logging">4.3 Logging</a></h2>
<p>Event and result logging is a common requirement in sensor
networks. Such logging should be reliable (a mote crash should not
lose data). It should also be easy to extract data from the log,
is sufficient to ensure that applications do not to have worry about
incomplete or inconsistent log entries.</p>
</div>
-<div class="section">
-<h2><a id="small-objects" name="small-objects">4.4 Small objects:</a></h2>
+<div class="section" id="small-objects">
+<h2><a name="small-objects">4.4 Small objects:</a></h2>
<p>Sensor network applications need to store configuration data, e.g.,
mote identity, radio frequency, sample rates, etc. Such data is not large, but
losing it may lead to a mote misbehaving or losing contact with the
definitions.</p>
</div>
</div>
-<div class="section">
-<h1><a id="implementations" name="implementations">5. Implementations</a></h1>
+<div class="section" id="implementations">
+<h1><a name="implementations">5. Implementations</a></h1>
<p>An AT45DB implementation can be found in tinyos-2.x/tos/chips/at45db.</p>
<p>An ST M25P implementation can be found in tinyos-2.x/tos/chips/stm25p.</p>
</div>
-<div class="section">
-<h1><a id="authors-addresses" name="authors-addresses">6. Authors' Addresses</a></h1>
+<div class="section" id="authors-addresses">
+<h1><a name="authors-addresses">6. Authors' Addresses</a></h1>
<div class="line-block">
<div class="line">David Gay</div>
<div class="line">2150 Shattuck Ave, Suite 1300</div>
<div class="line">email - <a class="reference" href="mailto:jhui@archedrock.com">jhui@archedrock.com</a></div>
</div>
</div>
-<div class="section">
-<h1><a id="citations" name="citations">7. Citations</a></h1>
+<div class="section" id="citations">
+<h1><a name="citations">7. Citations</a></h1>
<table class="docutils footnote" frame="void" id="id5" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
</tbody>
</table>
</div>
-<div class="section">
-<h1><a id="appendix-a-haa-for-some-existing-flash-chips" name="appendix-a-haa-for-some-existing-flash-chips">Appendix A. HAA for some existing flash chips</a></h1>
-<div class="section">
-<h2><a id="a-1-at45db" name="a-1-at45db">A.1 AT45DB</a></h2>
+<div class="section" id="appendix-a-haa-for-some-existing-flash-chips">
+<h1><a name="appendix-a-haa-for-some-existing-flash-chips">Appendix A. HAA for some existing flash chips</a></h1>
+<div class="section" id="a-1-at45db">
+<h2><a name="a-1-at45db">A.1 AT45DB</a></h2>
<p>The Atmel AT45DB family HPL is:</p>
<pre class="literal-block">
configuration HplAt45dbC {
<p>The <tt class="docutils literal"><span class="pre">At45dbVolume</span></tt> interface has operations to report volume size and
map volume-relative pages to absolute pages.</p>
</div>
-<div class="section">
-<h2><a id="a-2-st-m25p" name="a-2-st-m25p">A.2 ST M25P</a></h2>
+<div class="section" id="a-2-st-m25p">
+<h2><a name="a-2-st-m25p">A.2 ST M25P</a></h2>
<p>The ST M25P family HPL is:</p>
<pre class="literal-block">
configuration Stm25pSpiC {
obtain the volume id of each of its clients.</p>
</div>
</div>
-<div class="section">
-<h1><a id="appendix-b-storage-interfaces" name="appendix-b-storage-interfaces">Appendix B. Storage interfaces</a></h1>
+<div class="section" id="appendix-b-storage-interfaces">
+<h1><a name="appendix-b-storage-interfaces">Appendix B. Storage interfaces</a></h1>
<p>These interfaces are presented briefly here for reference; please refer
to the TinyOS documentation for a full description of the commands,
events and their parameters.</p>
-<div class="section">
-<h2><a id="b-1-blockstorage-interfaces" name="b-1-blockstorage-interfaces">B.1 BlockStorage interfaces</a></h2>
+<div class="section" id="b-1-blockstorage-interfaces">
+<h2><a name="b-1-blockstorage-interfaces">B.1 BlockStorage interfaces</a></h2>
<p>The BlockStorage interfaces are:</p>
<pre class="literal-block">
interface BlockRead {
}
</pre>
</div>
-<div class="section">
-<h2><a id="b-2-configstorage-interfaces" name="b-2-configstorage-interfaces">B.2 ConfigStorage interfaces</a></h2>
+<div class="section" id="b-2-configstorage-interfaces">
+<h2><a name="b-2-configstorage-interfaces">B.2 ConfigStorage interfaces</a></h2>
<p>The ConfigStorage interfaces are:</p>
<pre class="literal-block">
interface Mount {
}
</pre>
</div>
-<div class="section">
-<h2><a id="b-3-logstorage-interfaces" name="b-3-logstorage-interfaces">B.3 LogStorage interfaces</a></h2>
+<div class="section" id="b-3-logstorage-interfaces">
+<h2><a name="b-3-logstorage-interfaces">B.3 LogStorage interfaces</a></h2>
<p>The LogStorage interfaces are:</p>
<pre class="literal-block">
interface LogRead {
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.3.6: http://docutils.sourceforge.net/" />
<title>Schedulers and Tasks</title>
<meta name="author" content="Philip Levis and Cory Sharp" />
<style type="text/css">
</style>
</head>
<body>
-<div class="document" id="schedulers-and-tasks">
<h1 class="title">Schedulers and Tasks</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<td>Philip Levis and Cory Sharp</td></tr>
</tbody>
</table>
+<div class="document" id="schedulers-and-tasks">
<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
of this memo is unlimited. This memo is in full compliance with
TEP 1.</p>
</div>
-<div class="section">
-<h1><a id="abstract" name="abstract">Abstract</a></h1>
+<div class="section" id="abstract">
+<h1><a name="abstract">Abstract</a></h1>
<p>This memo documents the structure and implementation of tasks
and task schedulers in TinyOS 2.x.</p>
</div>
-<div class="section">
-<h1><a id="introduction" name="introduction">1. Introduction</a></h1>
+<div class="section" id="introduction">
+<h1><a name="introduction">1. Introduction</a></h1>
<p>TinyOS has two basic computational abstractions: asynchronous events
and tasks. Early versions of TinyOS provided a single type of task --
parameter free -- and only a FIFO scheduling policy. While changing
the structure of how it does so as well as a simple mechanism that
greatly increases system dependability.</p>
</div>
-<div class="section">
-<h1><a id="tasks-and-the-scheduler-in-tinyos-1-x" name="tasks-and-the-scheduler-in-tinyos-1-x">2. Tasks and the Scheduler in TinyOS 1.x</a></h1>
+<div class="section" id="tasks-and-the-scheduler-in-tinyos-1-x">
+<h1><a name="tasks-and-the-scheduler-in-tinyos-1-x">2. Tasks and the Scheduler in TinyOS 1.x</a></h1>
<p>Tasks in TinyOS are a form of deferred procedure call (DPC) <a class="footnote-reference" href="#id5" id="id1" name="id1">[1]</a>, which
enable a program to defer a computation or operation until a later
time. TinyOS tasks run to completion and do not pre-empt one
mechanisms, <tt class="docutils literal"><span class="pre">task</span></tt> declarations and <tt class="docutils literal"><span class="pre">post</span></tt> expressions:</p>
<pre class="literal-block">
task void computeTask() {
- // Code here
-}
+ // Code here
+}
</pre>
<p>and:</p>
<pre class="literal-block">
knows the one it is sending completes (so it can re-use the
buffer). As the <tt class="docutils literal"><span class="pre">sendDone()</span></tt> event was lost, this does not occur,
and the application stops sending network traffic.</p>
-<p>The solution to this particular problem in TinyOS 1.x is to signal
-sendDone() in the radio send complete interrupt if the post fails:
-this violates the sync/async boundary, but the justification is that
-a <em>possible</em> rare race condition is better than <em>certain</em> failure.
+<p>The solution to this particular problem in TinyOS 1.x is to signal
+sendDone() in the radio send complete interrupt if the post fails:
+this violates the sync/async boundary, but the justification is that
+a <em>possible</em> rare race condition is better than <em>certain</em> failure.
Another solution would be to use an interrupt source to periodically
retry posting the task; while this does not break the sync/async
-boundary, until the post succeeds the system cannot send packets.
+boundary, until the post succeeds the system cannot send packets.
The TinyOS 1.x model prevents it from doing any better.</p>
</div>
-<div class="section">
-<h1><a id="tasks-in-tinyos-2-x" name="tasks-in-tinyos-2-x">3. Tasks in TinyOS 2.x</a></h1>
+<div class="section" id="tasks-in-tinyos-2-x">
+<h1><a name="tasks-in-tinyos-2-x">3. Tasks in TinyOS 2.x</a></h1>
<p>The semantics of tasks in TinyOS 2.x are different than those in 1.x.
This change is based on experiences with the limitations and run time
errors that the 1.x model introduces. <strong>In TinyOS 2.x, a basic post will
-only fail if and only if the task has already been posted and has not
-started execution.</strong> A task can always run, but can only have one
+only fail if and only if the task has already been posted and has not
+started execution.</strong> A task can always run, but can only have one
outstanding post at any time.</p>
<p>2.x achieves these semantics by allocating one
byte of state per task (the assumption is that there will be fewer than 255
-tasks in the system). While a very large number of tasks could make
+tasks in the system). While a very large number of tasks could make
this overhead noticable, it is not significant in practice.
-If a component needs to post a task several times, then the end of
+If a component needs to post a task several times, then the end of
the task logic can repost itself as need be.</p>
<p>For example, one can do this:</p>
<pre class="literal-block">
// do work
if (moreToProcess) {
post processTask();
- }
+ }
}
</pre>
<p>These semantics prevent several problems, such as the inability to
up to the interface. For example, a task interface that allows a task
to take an integer parameter could look like this:</p>
<pre class="literal-block">
-interface TaskParameter {
- async error_t command postTask(uint16_t param);
- event void runTask(uint16_t param);
-}
+interface TaskParameter {
+ async error_t command postTask(uint16_t param);
+ event void runTask(uint16_t param);
+}
</pre>
<p>Using this task interface, a component could post a task with a
<tt class="docutils literal"><span class="pre">uint16_t</span></tt> parameter. When the scheduler runs the task, it will
signal the <tt class="docutils literal"><span class="pre">runTask</span></tt> event with the passed parameter, which contains
-the task's logic. Note, however, that this does not save any RAM:
+the task's logic. Note, however, that this does not save any RAM:
the scheduler must have RAM allocated for the parameter. Furthermore, as
there can only be one copy of a task outstanding at any time, it
is just as simple to store the variable in the component. E.g.,
post parameterTask();
...
task void parameterTask() {
- // use param
+ // use param
}
</pre>
<p>The principal difference between the simplest code for these
}
</pre>
</div>
-<div class="section">
-<h1><a id="the-scheduler-in-tinyos-2-x" name="the-scheduler-in-tinyos-2-x">4. The Scheduler in TinyOS 2.x</a></h1>
+<div class="section" id="the-scheduler-in-tinyos-2-x">
+<h1><a name="the-scheduler-in-tinyos-2-x">4. The Scheduler in TinyOS 2.x</a></h1>
<p>In TinyOS 2.x, the scheduler is a TinyOS component. Every scheduler
MUST support nesC tasks. It MAY also support any number of
additional task interfaces. The scheduler component is resonsible for
dispatch tasks.</p>
<p>For example, the standard TinyOS scheduler has this signature:</p>
<pre class="literal-block">
-module SchedulerBasicP {
- provides interface Scheduler;
- provides interface TaskBasic[uint8_t taskID];
- uses interface McuSleep;
-}
+module SchedulerBasicP {
+ provides interface Scheduler;
+ provides interface TaskBasic[uint8_t taskID];
+ uses interface McuSleep;
+}
</pre>
<p>A scheduler MUST provide a parameterized TaskBasic interface.
If a call to TaskBasic.postTask() returns SUCCESS, the scheduler MUST run it
-eventually, so that starvation is not a concern. The scheduler MUST
+eventually, so that starvation is not a concern. The scheduler MUST
return SUCCESS to a TaskBasic.postTask()
operation unless it is not the first call to TaskBasic.postTask() since
-that task's TaskBasic.runTask() event has been signaled. The
+that task's TaskBasic.runTask() event has been signaled. The
McuSleep interface is used for microcontroller power management;
its workings are explained in TEP 112 <a class="footnote-reference" href="#id7" id="id3" name="id3">[3]</a>.</p>
-<p>A scheduler MUST provide the Scheduler interface.
+<p>A scheduler MUST provide the Scheduler interface.
The Scheduler interface has commands for initialization and running
tasks, and is used by TinyOS to execute tasks:</p>
<pre class="literal-block">
-interface Scheduler {
- command void init();
- command bool runNextTask(bool sleep);
- command void taskLoop();
-}
+interface Scheduler {
+ command void init();
+ command bool runNextTask(bool sleep);
+ command void taskLoop();
+}
</pre>
<p>The init() command initializes the task queue and scheduler data
structures. runNextTask() MUST run to completion whatever task the
in terms of the assembly generated by the TinyOS toolchain.</p>
<p>This is the TaskBasic interface:</p>
<pre class="literal-block">
-interface TaskBasic {
- async command error_t postTask();
- void event runTask();
-}
+interface TaskBasic {
+ async command error_t postTask();
+ void event runTask();
+}
</pre>
<p>When a component declares a task with the <tt class="docutils literal"><span class="pre">task</span></tt> keyword in nesC, it
is implicitly declaring that it uses an instance of the TaskBasic
interface: the task body is the runTask event. When a component uses the
<tt class="docutils literal"><span class="pre">post</span></tt> keyword, it calls the postTask command. Each TaskBasic MUST be
-wired to the scheduler with a unique identifier as its parameter.
-The parameter MUST be obtained with the <tt class="docutils literal"><span class="pre">unique</span></tt> function in nesC,
+wired to the scheduler with a unique identifier as its parameter.
+The parameter MUST be obtained with the <tt class="docutils literal"><span class="pre">unique</span></tt> function in nesC,
with a key of <tt class="docutils literal"><span class="pre">"TinySchedulerC.TaskBasic"</span></tt>. The nesC compiler
automatically does this wiring when the <tt class="docutils literal"><span class="pre">task</span></tt> and <tt class="docutils literal"><span class="pre">post</span></tt>
keywords are used.</p>
in a particular temporal order, this order should be enforced by
the earlier task posting the later task.</p>
</div>
-<div class="section">
-<h1><a id="replacing-the-scheduler" name="replacing-the-scheduler">5. Replacing the Scheduler</a></h1>
+<div class="section" id="replacing-the-scheduler">
+<h1><a name="replacing-the-scheduler">5. Replacing the Scheduler</a></h1>
<p>The TinyOS scheduler is presented as a component named TinySchedulerC.
The default TinyOS scheduler implementation is a module named
SchedulerBasicP; the default scheduler component is a configuration
interface, as SchedulerBasicP does; this supports nesC post statements
and task declarations and enables TinyOS core systems to operate
properly. Generally, TinyOS core code needs to be able to run unchanged
-with new scheduler implementations. All scheduler
+with new scheduler implementations. All scheduler
implementations MUST provide the Scheduler interface.</p>
<p>For example, imagine a hypothetical scheduler that provides earliest
deadline first tasks, which are provided through the TaskEdf
interface:</p>
<pre class="literal-block">
-interface TaskEdf {
- async command error_t postTask(uint16_t deadlineMs);
- event void runTask();
-}
+interface TaskEdf {
+ async command error_t postTask(uint16_t deadlineMs);
+ event void runTask();
+}
</pre>
<p>The scheduler implementation is named SchedulerEdfP, and provides both
TaskBasic and TaskEdf interfaces:</p>
<pre class="literal-block">
-module SchedulerEdfP {
- provides interface Scheduler;
- provides interface TaskBasic[uint8_t taskID];
- provides interface TaskEdf[uint8_t taskID];
-}
+module SchedulerEdfP {
+ provides interface Scheduler;
+ provides interface TaskBasic[uint8_t taskID];
+ provides interface TaskEdf[uint8_t taskID];
+}
</pre>
<p>An application that wants to use SchedulerEdfP instead of
SchedulerBasicP includes a configuration named TinySchedulerC, which
exports all of SchedulerEdfP's interfaces:</p>
<pre class="literal-block">
-configuration TinySchedulerC {
- provides interface Scheduler;
- provides interface TaskBasic[uint8_t taskID];
- provides interface TaskEdf[uint8_t taskID];
-}
-implementation {
- components SchedulerEdfP;
- Scheduler = SchedulerEdf;
- TaskBasic = SchedulerEdfP;
- TaskEDF = SchedulerEdfP;
-}
+configuration TinySchedulerC {
+ provides interface Scheduler;
+ provides interface TaskBasic[uint8_t taskID];
+ provides interface TaskEdf[uint8_t taskID];
+}
+implementation {
+ components SchedulerEdfP;
+ Scheduler = SchedulerEdf;
+ TaskBasic = SchedulerEdfP;
+ TaskEDF = SchedulerEdfP;
+}
</pre>
<p>For a module to have an earliest deadline first task, it uses the
TaskEdf interface. Its configuration SHOULD wire it to TinySchedulerC.
<p>In this example, the module SomethingP requires two EDF
tasks:</p>
<pre class="literal-block">
-configuration SomethingC {
- ...
-}
-implementation {
- components SomethingP, TinySchedulerC;
- SomethingP.SendTask -> TinySchedulerC.TaskEdf[unique(UQ_TASK_EDF)];
- SomethingP.SenseTask -> TinySchedulerC.TaskEdf[unique(UQ_TASK_EDF)];
-}
+configuration SomethingC {
+ ...
+}
+implementation {
+ components SomethingP, TinySchedulerC;
+ SomethingP.SendTask -> TinySchedulerC.TaskEdf[unique(UQ_TASK_EDF)];
+ SomethingP.SenseTask -> TinySchedulerC.TaskEdf[unique(UQ_TASK_EDF)];
+}
</pre>
<p>The module SomethingP also has a basic task. The nesC compiler
automatically transforms task keywords into BasicTask interfaces and
MUST NOT mix the two syntaxes for a given task. This is an example
implementation of SomethingP that uses keywords for basic tasks:</p>
<pre class="literal-block">
-module SomethingP {
- uses interface TaskEdf as SendTask
- uses interface TaskEdf as SenseTask
-}
-implementation {
- // The TaskBasic, written with keywords
- task void cleanupTask() { ... some logic ... }
- event void SendTask.runTask() { ... some logic ... }
- event void SenseTask.runTask() { ... some logic ... }
-
- void internal_function() {
- call SenseTask.postTask(20);
- call SendTask.postTask(100);
- post cleanupTask();
- }
-}
+module SomethingP {
+ uses interface TaskEdf as SendTask
+ uses interface TaskEdf as SenseTask
+}
+implementation {
+ // The TaskBasic, written with keywords
+ task void cleanupTask() { ... some logic ... }
+ event void SendTask.runTask() { ... some logic ... }
+ event void SenseTask.runTask() { ... some logic ... }
+
+ void internal_function() {
+ call SenseTask.postTask(20);
+ call SendTask.postTask(100);
+ post cleanupTask();
+ }
+}
</pre>
<p>The requirement that basic tasks not be subject to starvation
requires that a scheduler supporting EDF tasks must ensure that
basic tasks run eventually even if there is an unending stream of
short deadline tasks to run. Quantifying "eventually" is difficult,
-but a 1% share of the MCU cycles (or invocations) is a reasonable
+but a 1% share of the MCU cycles (or invocations) is a reasonable
approximation.</p>
<p>If the scheduler provides two instances of the same task interface,
-their unique keys are based on the name of the interface as the
+their unique keys are based on the name of the interface as the
scheduler presents it (the "as" keyword). For example, imagine
a scheduler which provides two instances of TaskBasic: standard
tasks and high-priority tasks. The scheduler usually selects a task
for the high priority queue before the standard queue:</p>
<pre class="literal-block">
-configuration TinySchedulerC {
- provides interface Scheduler;
- provides interface TaskBasic[uint8_t taskID];
- provides interface TaskBasic[uint8_t taskID] as TaskHighPriority;
-}
+configuration TinySchedulerC {
+ provides interface Scheduler;
+ provides interface TaskBasic[uint8_t taskID];
+ provides interface TaskBasic[uint8_t taskID] as TaskHighPriority;
+}
</pre>
<p>It cannot always select a high priority task because that could
-starve basic tasks. A component that uses a high priority task would
+starve basic tasks. A component that uses a high priority task would
wire to TaskHighPriority with the key "TinySchedulerC.TaskHighPriority":</p>
<pre class="literal-block">
-configuration SomethingElseC {}
-implementation {
- components TinySchedulerC as Sched, SomethingElseP;
- SomethingElseP.RetransmitTask -> Sched.TaskHighPriority[unique("TinySchedulerC.TaskHighPriority")];
-}
+configuration SomethingElseC {}
+implementation {
+ components TinySchedulerC as Sched, SomethingElseP;
+ SomethingElseP.RetransmitTask -> Sched.TaskHighPriority[unique("TinySchedulerC.TaskHighPriority")];
+}
</pre>
</div>
-<div class="section">
-<h1><a id="implementation" name="implementation">6. Implementation</a></h1>
+<div class="section" id="implementation">
+<h1><a name="implementation">6. Implementation</a></h1>
<p>The following files in <tt class="docutils literal"><span class="pre">tinyos-2.x/tos/system</span></tt> contain the reference
implementations of the scheduler:</p>
<blockquote>
<p>A prototype of a scheduler that supports EDF tasks can be obtained
at the URL <tt class="docutils literal"><span class="pre">http://csl.stanford.edu/~pal/tinyos/edf-sched.tgz.</span></tt></p>
</div>
-<div class="section">
-<h1><a id="author-s-address" name="author-s-address">7. Author's Address</a></h1>
+<div class="section" id="author-s-address">
+<h1><a name="author-s-address">7. Author's Address</a></h1>
<div class="line-block">
<div class="line">Philip Levis</div>
<div class="line">358 Gates Hall</div>
<div class="line">Stanford University</div>
<div class="line">Stanford, CA 94305</div>
<div class="line"><br /></div>
-<div class="line">phone - +1 650 725 9046</div>
+<div class="line">phone - +1 650 725 9046 </div>
<div class="line">email - <a class="reference" href="mailto:pal@cs.stanford.edu">pal@cs.stanford.edu</a></div>
<div class="line"><br /></div>
<div class="line">Cory Sharp</div>
<div class="line">email - <a class="reference" href="mailto:cssharp@eecs.berkeley.edu">cssharp@eecs.berkeley.edu</a></div>
</div>
</div>
-<div class="section">
-<h1><a id="citations" name="citations">8. Citations</a></h1>
+<div class="section" id="citations">
+<h1><a name="citations">8. Citations</a></h1>
<table class="docutils footnote" frame="void" id="id5" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
-<tr><td class="label"><a class="fn-backref" href="#id1" name="id5">[1]</a></td><td>Erik Cota-Robles and James P. Held. "A Comparison of Windows
+<tr><td class="label"><a class="fn-backref" href="#id1" name="id5">[1]</a></td><td>Erik Cota-Robles and James P. Held. "A Comparison of Windows
Driver Model Latency Performance on Windows NT and Windows 98." In
<em>Proceedings of the Third Symposium on Operating System Design
and Implementation (OSDI).</em></td></tr>
</tbody>
</table>
</div>
-<div class="section">
-<h1><a id="appendix-a-changing-the-scheduler" name="appendix-a-changing-the-scheduler">Appendix A: Changing the Scheduler</a></h1>
+<div class="section" id="appendix-a-changing-the-scheduler">
+<h1><a name="appendix-a-changing-the-scheduler">Appendix A: Changing the Scheduler</a></h1>
<p>The nesC compiler transforms the post and task keywords into
nesC interfaces, wirings, and calls. By default, the statement:</p>
<pre class="literal-block">
task x() {
...
post x();
- }
+ }
}
</pre>
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.3.6: http://docutils.sourceforge.net/" />
<title>TinyOS 2.x Boot Sequence</title>
<meta name="author" content="Philip Levis" />
<style type="text/css">
</style>
</head>
<body>
-<div class="document" id="tinyos-2-x-boot-sequence">
<h1 class="title">TinyOS 2.x Boot Sequence</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<td>Philip Levis</td></tr>
</tbody>
</table>
+<div class="document" id="tinyos-2-x-boot-sequence">
<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
of this memo is unlimited. This memo is in full compliance with
TEP 1.</p>
</div>
-<div class="section">
-<h1><a id="abstract" name="abstract">Abstract</a></h1>
+<div class="section" id="abstract">
+<h1><a name="abstract">Abstract</a></h1>
<p>This memo documents the structure and implementation of the mote
boot sequence in TinyOS 2.x.</p>
</div>
-<div class="section">
-<h1><a id="introduction" name="introduction">1. Introduction</a></h1>
+<div class="section" id="introduction">
+<h1><a name="introduction">1. Introduction</a></h1>
<p>TinyOS has a set of calling conventions and semantics in its boot
sequence. Earlier versions of TinyOS used an interface named
"StdControl" to take care of system initialization and starting
notification that the mote has booted. This memo describes the TinyOS
boot sequence and reasons for its semantics.</p>
</div>
-<div class="section">
-<h1><a id="tinyos-1-x-boot-sequence" name="tinyos-1-x-boot-sequence">2. TinyOS 1.x Boot Sequence</a></h1>
+<div class="section" id="tinyos-1-x-boot-sequence">
+<h1><a name="tinyos-1-x-boot-sequence">2. TinyOS 1.x Boot Sequence</a></h1>
<p>The TinyOS 1.x boot sequence is uniform across most mote platforms
(TOSSIM has a very different boot sequence, as it is a PC
program). The module RealMain implements main(), and has the following
call hardwareInit();
call Pot.init(10);
TOSH_sched_init();
-
+
call StdControl.init();
call StdControl.start();
__nesc_enable_interrupt();
-
+
while(1) {
TOSH_run_task();
}
until the radio starts, but main has no mechanism for waiting for the
radio start completion event.</p>
</div>
-<div class="section">
-<h1><a id="tinyos-2-x-boot-interfaces" name="tinyos-2-x-boot-interfaces">3. TinyOS 2.x Boot Interfaces</a></h1>
+<div class="section" id="tinyos-2-x-boot-interfaces">
+<h1><a name="tinyos-2-x-boot-interfaces">3. TinyOS 2.x Boot Interfaces</a></h1>
<p>The TinyOS 2.x boot sequence uses three interfaces:</p>
<blockquote>
<ul class="simple">
is a sequential, synchronous operation: no component can be started
until initialization is complete. If a particular component's
initialization requires waiting for interrupts or other asynchronous
-events, then it must explicitly wait for them (e.g.,
+events, then it must explicitly wait for them (e.g.,
with a spin loop), MUST NOT return until complete. Otherwise the system
may start before initialization is complete.</p>
<p>The Scheduler interface is for initializing and controlling task
}
</pre>
</div>
-<div class="section">
-<h1><a id="id2" name="id2">4. TinyOS 2.x Boot Sequence</a></h1>
+<div class="section" id="id2">
+<h1><a name="id2">4. TinyOS 2.x Boot Sequence</a></h1>
<p>The module RealMainP implements the standard TinyOS 2.x boot sequence.
The configuration MainC wires some of RealMainP's interfaces to
components that implement standard abstractions and exports the others
default event void Boot.booted() { }
}
</pre>
-<div class="section">
-<h2><a id="initialization" name="initialization">4.1 Initialization</a></h2>
+<div class="section" id="initialization">
+<h2><a name="initialization">4.1 Initialization</a></h2>
<p>The first step in the boot sequence is initializing the system:</p>
<pre class="literal-block">
atomic {
operations besides those which are absolutely necessary for further code,
such as scheduler initialization, to execute.
Examples of platform_bootstrap() operations are configuring the memory
-system and setting the processor mode. Generally, platform_bootstrap()
+system and setting the processor mode. Generally, platform_bootstrap()
is an empty function. TinyOS's top-level include file, <tt class="docutils literal"><span class="pre">tos.h</span></tt>, includes
a default implementation of this function which does nothing. If a platform
needs to replace the default, it SHOULD put it in a platform's
-<tt class="docutils literal"><span class="pre">platform.h</span></tt> file as a #define. The implementation of <tt class="docutils literal"><span class="pre">tos.h</span></tt>
+<tt class="docutils literal"><span class="pre">platform.h</span></tt> file as a #define. The implementation of <tt class="docutils literal"><span class="pre">tos.h</span></tt>
supports this:</p>
<pre class="literal-block">
/* This platform_bootstrap macro exists in accordance with TEP
uses interface Init as SoftwareInit;
}
implementation {
- components PlatformC, RealMainP, TinySchedulerC;
+ components PlatformC, RealMainP, TinySchedulerC;
RealMainP.Scheduler -> TinySchedulerC;
RealMainP.PlatformInit -> PlatformC;
<li>The initialization is a prerequisite for common services in the system.</li>
</ol>
<p>Three example operations that often belong in PlatformInit are I/O pin
-configuration, clock calibration, and LED configuration. I/O pin
+configuration, clock calibration, and LED configuration. I/O pin
configuration meets the first two criteria. It should always be performed
(regardless of what components the OS uses) for low-power reasons:
incorrectly configured pins can draw current and prevent the MCU from
nominally meets all three criteria, the most important one is the third:
as LEDs are often needed during SoftwareInit initialization, they must
be set up before it is invoked.</p>
-<p>Note that not all code which meets some of these criteria is wired through
-PlatformC. In particular, criterion 1 is typically necessary but not
+<p>Note that not all code which meets some of these criteria is wired through
+PlatformC. In particular, criterion 1 is typically necessary but not
sufficient to require PlatformC. For example, a timer system that
configures overflow and capture settings or a UART stack that sets the
baud rate and transmission options can often be wired to SoftwareInit.
They are encapsulated abstractions which will not be invoked or
-started until the boot event, and only need to be configured if the
+started until the boot event, and only need to be configured if the
system includes their functionality.</p>
<p>Components whose initialization does not directly depend on hardware
resources SHOULD wire to MainC.SoftwareInit. If a component requires a
implementation {
components HilTimerMilliC, MainC;
MainC.SoftwareInit -> HilTimerMilliC;
- TimerMilli = HilTimerMilliC;
+ TimerMilli = HilTimerMilliC;
}
</pre>
<p>Rather than require an application to wire HilTimerMilliC to MainC,
TimerMilliC, that names TimerMilliP, which will automatically make
sure that the timer system is initialized when TinyOS boots.</p>
</div>
-<div class="section">
-<h2><a id="interrupts-in-initialization" name="interrupts-in-initialization">4.2 Interrupts in Initialization</a></h2>
+<div class="section" id="interrupts-in-initialization">
+<h2><a name="interrupts-in-initialization">4.2 Interrupts in Initialization</a></h2>
<p>Interrupts are not enabled until all calls to Init.init have returned.
If a component's initialization needs to handle interrupts, it can
do one of three things:</p>
can handle an interrupt in the boot sequence only if doing so will not
cause any other component to handle an interrupt. As they have all
been written assuming that interrupts are not enabled until after Init
-completes, making one of them handle an interrupt could cause it to
+completes, making one of them handle an interrupt could cause it to
fail.</p>
<p>Depending on what capabilities the hardware provides, there are
several ways to meet these requirements. The simplest is to push these
functional interfaces on any components that might be shared or
interact with shared resources. Components MAY call functions
on other components that are completely internal to the subsystem.
-For example, a networking layer can call queue operations to
+For example, a networking layer can call queue operations to
initialize its queue, but a link layer must not send commands
over an SPI bus. An HAA
component MAY make other calls to initialize hardware state. A
component that is not part of an HAA SHOULD NOT call Init.init() on
other components unless it needs to enforce a temporal ordering on
initialization.</p>
-<p>If a component A depends on another component, B,
-which needs to be initialized, then A SHOULD wire B's Init directly
+<p>If a component A depends on another component, B,
+which needs to be initialized, then A SHOULD wire B's Init directly
to the boot sequence, unless there is a temporal ordering requirement to
the initialization. The purpose of this convention is to simplify
component initialization and the initialization sequence.</p>
</div>
</div>
-<div class="section">
-<h1><a id="implementation" name="implementation">5. Implementation</a></h1>
+<div class="section" id="implementation">
+<h1><a name="implementation">5. Implementation</a></h1>
<p>The following files in <tt class="docutils literal"><span class="pre">tinyos-2.x/tos/system</span></tt> contain the reference
implementations of the TinyOS boot sequence:</p>
<blockquote>
</ul>
</blockquote>
</div>
-<div class="section">
-<h1><a id="author-s-address" name="author-s-address">6. Author's Address</a></h1>
+<div class="section" id="author-s-address">
+<h1><a name="author-s-address">6. Author's Address</a></h1>
<div class="line-block">
<div class="line">Philip Levis</div>
<div class="line">467 Soda Hall</div>
<div class="line">email - <a class="reference" href="mailto:pal@cs.berkeley.edu">pal@cs.berkeley.edu</a></div>
</div>
</div>
-<div class="section">
-<h1><a id="citations" name="citations">7. Citations</a></h1>
+<div class="section" id="citations">
+<h1><a name="citations">7. Citations</a></h1>
<table class="docutils footnote" frame="void" id="id7" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.3.6: http://docutils.sourceforge.net/" />
<title>Resource Arbitration</title>
-<meta name="authors" content="Kevin Klues Philip Levis David Gay David Culler Vlado Handziski" />
+<meta name="author" content="Kevin Klues" />
+<meta name="author" content="Philip Levis" />
+<meta name="author" content="David Gay" />
+<meta name="author" content="David Culler" />
+<meta name="author" content="Vlado Handziski" />
<style type="text/css">
/*
</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" />
<td>Final</td></tr>
<tr class="field"><th class="docinfo-name">TinyOS-Version:</th><td class="field-body">2.x</td>
</tr>
-<tr><th class="docinfo-name">Authors:</th>
-<td>Kevin Klues
-<br />Philip Levis
-<br />David Gay
-<br />David Culler
-<br />Vlado Handziski</td></tr>
+<tr><th class="docinfo-name">Author:</th>
+<td>Kevin Klues</td></tr>
+<tr><th class="docinfo-name">Author:</th>
+<td>Philip Levis</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>Vlado Handziski</td></tr>
</tbody>
</table>
+<div class="document" id="resource-arbitration">
<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
of this memo is unlimited. This memo is in full compliance with
TEP 1.</p>
</div>
-<div class="section">
-<h1><a id="abstract" name="abstract">Abstract</a></h1>
+<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 access to shared abstractions.</p>
</div>
-<div class="section">
-<h1><a id="introduction" name="introduction">1. Introduction</a></h1>
+<div class="section" id="introduction">
+<h1><a name="introduction">1. Introduction</a></h1>
<p>TinyOS 1.x has two mechanisms for managing shared resources:
virtualization and completion events. A virtualized resource appears
as an independent instance of an abstraction, such as the Timer
example, components in 1.x share a single communication stack,
GenericComm. GenericComm can only handle one outgoing packet at a
time. If a component tries to send a packet when GenericComm is
-already busy, then the call returns FAIL. The component needs a way to
+already busy, then the call returns FAIL. The component needs a way to
tell when GenericComm is free so it can retry. TinyOS
1.x provides the mechanism of a global completion event which is
signaled whenever a packet send completes. Interested components can
handle this event and retry.</p>
-<p>This approach to physical (rather than virtualized) abstractions
+<p>This approach to physical (rather than virtualized) abstractions
has several drawbacks:</p>
<ul class="simple">
<li>If you need to make several requests, you have to handle the
-possibility of a request returning FAIL at any point. This complicates
+possibility of a request returning FAIL at any point. This complicates
implementations by adding internal states.</li>
<li>You have no control over the timing of a sequence of operations. One
-example of when this can be a problem is timing-sensitive use of an
+example of when this can be a problem is timing-sensitive use of an
A/D converter. You need a way to pre-reserve the use of the ADC so
that its operations can be run at the exact moment they are desired.</li>
<li>If a hardware resource supports reservation, you cannot express this
monitoring an abstraction's availability for the purpose of retries,
nor very clear documentation of which requests could happen simultaneously.</li>
</ul>
-<p>It should be clear that a single approach to resource sharing is not appropriate
+<p>It should be clear that a single approach to resource sharing is not appropriate
for all circumstances. For instance, requiring explicit reservation of a
resource allows programs to have better timing guarantees for access to an A/D
converter. If a program does not need precise timing guarantees, however (e.g.,
resource classes in order to address this issue. The sharing policy used by a
particular resource abstraction is dictated by the resource class it belongs to.</p>
</div>
-<div class="section">
-<h1><a id="resource-classes" name="resource-classes">2. Resource Classes</a></h1>
-<p>TinyOS 2.x distinguishes between three kinds of abstractions:
-<em>dedicated</em>, <em>virtualized</em>, and <em>shared</em>. Components offer resource
+<div class="section" id="resource-classes">
+<h1><a name="resource-classes">2. Resource Classes</a></h1>
+<p>TinyOS 2.x distinguishes between three kinds of abstractions:
+<em>dedicated</em>, <em>virtualized</em>, and <em>shared</em>. Components offer resource
sharing mechanisms appropriate to their goals and level of abstraction.</p>
<div class="note">
<p class="first admonition-title">Note</p>
expected use, HPL abstractions can either be dedicated or
shared. For example, while hardware timers are rarely
multiplexed between multiple components, buses almost always are.
-This can be seen on the MSP430 microcontroller, where the compare and
-counter registers are implemented as dedicated resources, and the USARTs
+This can be seen on the MSP430 microcontroller, where the compare and
+counter registers are implemented as dedicated resources, and the USARTs
are shared ones.</p>
</div>
-<div class="section">
-<h2><a id="dedicated" name="dedicated">2.1 Dedicated</a></h2>
+<div class="section" id="dedicated">
+<h2><a name="dedicated">2.1 Dedicated</a></h2>
<p>An abstraction is <em>dedicated</em> if it is a resource
-which a subsystem needs exclusive access to at all times.
-In this class of resources, no sharing policy is needed since only
+which a subsystem needs exclusive access to at all times.
+In this class of resources, no sharing policy is needed since only
a single component ever requires use of the resource. Examples of
dedicated abstractions include interrupts and counters.</p>
-<p>Dedicated abstractions MAY be annotated with the nesC attribute
+<p>Dedicated abstractions MAY be annotated with the nesC attribute
@atmostonce or @exactlyonce to provide compile-time checks that
their usage assumptions are not violated.</p>
-<p>Please refer to Appendix A for an example of how a dedicated
-resource might be represented, including the use of
+<p>Please refer to Appendix A for an example of how a dedicated
+resource might be represented, including the use of
the nesC @exactlyonce attribute.</p>
</div>
-<div class="section">
-<h2><a id="virtualized" name="virtualized">2.2 Virtualized</a></h2>
+<div class="section" id="virtualized">
+<h2><a name="virtualized">2.2 Virtualized</a></h2>
<p><em>Virtual</em> abstractions hide multiple clients from each other
-through software virtualization. Every client of a virtualized resource
+through software virtualization. Every client of a virtualized resource
interacts with it as if it were a dedicated resource, with all virtualized
instances being multiplexed on top of a single underlying resource. Because
the virtualization is done in software, there is no upper bound on the number
of clients using the abstraction, barring memory or efficiency constraints.
-As virtualization usually requires keeping state that scales with the number
-of virtualized instances, virtualized resources often use the Service Instance
+As virtualization usually requires keeping state that scales with the number
+of virtualized instances, virtualized resources often use the Service Instance
pattern <a class="footnote-reference" href="#id6" id="id2" name="id2">[3]</a>, which is based on a parameterized interface.</p>
-<p>Virtualization generally provides a very simple interface to its clients.
-This simplicity comes at the cost of reduced efficiency and an inability to
+<p>Virtualization generally provides a very simple interface to its clients.
+This simplicity comes at the cost of reduced efficiency and an inability to
precisely control the underlying resource. For example, a virtualized
-timer resource introduces CPU overhead from dispatching and maintaining
-each individual virtual timer, as well as introducing jitter whenever two
-timers happen to fire at the same time. Please refer to Appendix A for an
+timer resource introduces CPU overhead from dispatching and maintaining
+each individual virtual timer, as well as introducing jitter whenever two
+timers happen to fire at the same time. Please refer to Appendix A for an
example of how such a virtualized timer resource might be implemented.</p>
</div>
-<div class="section">
-<h2><a id="shared" name="shared">2.3 Shared</a></h2>
+<div class="section" id="shared">
+<h2><a name="shared">2.3 Shared</a></h2>
<p>Dedicated abstractions are useful when a resource is
always controlled by a single component. Virtualized abstractions are
useful when clients are willing to pay a bit of overhead and sacrifice
resource. Clearly, they can't all have such control at the same time:
some degree of multiplexing is needed.</p>
<p>A motivating example of a shared resource is a bus.
-The bus may have multiple peripherals on it, corresponding to
+The bus may have multiple peripherals on it, corresponding to
different subsystems. For example, on the Telos platform the flash
chip (storage) and the radio (network) share a bus. The storage and
network stacks need exclusive access to the bus when using it,
case, virtualization is problematic, as the radio stack needs to be
able to perform a series of operations in quick succession without
having to reacquire the bus in each case. Having the bus be a
-shared resource allows the radio stack to send a series of operations
-to the radio atomically, without having to buffer them all up
+shared resource allows the radio stack to send a series of operations
+to the radio atomically, without having to buffer them all up
in memory beforehand (introducing memory pressure in the process).</p>
<p>In TinyOS 2.x, a resource <em>arbiter</em> is responsible for multiplexing
-between the different clients of a shared resource. It determines
-which client has access to the resource at which time. While a client
-holds a resource, it has complete and unfettered control. Arbiters assume
-that clients are cooperative, only acquiring the resource when needed
-and holding on to it no longer than necessary. Clients explicitly
+between the different clients of a shared resource. It determines
+which client has access to the resource at which time. While a client
+holds a resource, it has complete and unfettered control. Arbiters assume
+that clients are cooperative, only acquiring the resource when needed
+and holding on to it no longer than necessary. Clients explicitly
release resources: there is no way for an arbiter to forcibly reclaim it.
-The following section is dedicated to describing the arbiter and its
+The following section is dedicated to describing the arbiter and its
interfaces.</p>
</div>
</div>
-<div class="section">
-<h1><a id="resource-arbiters" name="resource-arbiters">3. Resource Arbiters</a></h1>
+<div class="section" id="resource-arbiters">
+<h1><a name="resource-arbiters">3. Resource Arbiters</a></h1>
<p>Every shared resource has an arbiter to manage which client
can use the resource at any given time. Because an arbiter is a
centralized place that knows whether the resource is in use, it can also
provide information useful for a variety of other services, such as
power management. An arbiter MUST provide a parameterized Resource
interface as well as an instance of the ArbiterInfo interface. The Resource
-interface is instantiated by different clients wanting to gain access to a
-resource. The ArbiterInfo interface is used by components that wish to
-retrieve global information about the status of a resource (i.e. if it is in
-use, who is using it, etc.). An arbiter SHOULD also provide a parameterized
-ResourceRequested interface and use a parameterized ResourceConfigure interface.
-It MAY also provide an instance of the ResourceDefaultOwner interface or
-any additional interfaces specific to the particular arbitration policy
+interface is instantiated by different clients wanting to gain access to a
+resource. The ArbiterInfo interface is used by components that wish to
+retrieve global information about the status of a resource (i.e. if it is in
+use, who is using it, etc.). An arbiter SHOULD also provide a parameterized
+ResourceRequested interface and use a parameterized ResourceConfigure interface.
+It MAY also provide an instance of the ResourceDefaultOwner interface or
+any additional interfaces specific to the particular arbitration policy
being implemented. Each of these interfaces is explained in greater detail below:</p>
<pre class="literal-block">
-Resource ArbiterInfo ResourceRequested ResourceDefaultOwner
+Resource ArbiterInfo ResourceRequested ResourceDefaultOwner
| | | |
| | | |
| \|/ \|/ |
|--------------| Arbiter |----------------------|
/---------------\
|
- |
+ |
\|/
ResourceConfigure
</pre>
-<div class="section">
-<h2><a id="resource" name="resource">3.1 Resource</a></h2>
-<p>Clients of an arbiter request access
+<div class="section" id="resource">
+<h2><a name="resource">3.1 Resource</a></h2>
+<p>Clients of an arbiter request access
to a shared resource using the Resource interface:</p>
<pre class="literal-block">
interface Resource {
async command bool isOwner();
}
</pre>
-<p>A client lets an arbiter know it needs access to a resource by
+<p>A client lets an arbiter know it needs access to a resource by
making a call to request(). If the resource is free,
-SUCCESS is returned, and a granted event is signaled
-back to the client. If the resource is busy, SUCCESS will
-still be returned, but the request will be queued
-according to the queuing policy of the arbiter. Whenever a client is
-done with the resource, it calls the release() command, and the next
-client in the request queue is given access to the resource and
-is signaled its granted() event. If a client ever makes multiple
-requests before receiving a granted event, an EBUSY value is returned,
-and the request is not queued. Using this policy, clients are not able to
+SUCCESS is returned, and a granted event is signaled
+back to the client. If the resource is busy, SUCCESS will
+still be returned, but the request will be queued
+according to the queuing policy of the arbiter. Whenever a client is
+done with the resource, it calls the release() command, and the next
+client in the request queue is given access to the resource and
+is signaled its granted() event. If a client ever makes multiple
+requests before receiving a granted event, an EBUSY value is returned,
+and the request is not queued. Using this policy, clients are not able to
monolopize the resource queue by making multiple requests, but they may still be
-able to monopolize the use of the resource if they do not release it in a
+able to monopolize the use of the resource if they do not release it in a
timely manner.</p>
-<p>Clients can also request the use of a resource through the
-immediateRequest() command. A call to immediateRequest() can either
-return SUCCESS or FAIL, with requests made through this command never being
-queued. If a call to immediateRequest() returns SUCCESS, the client is granted
-access to the resource immediately after the call has returned, and no granted
-event is ever signaled. If it returns FAIL, the client is not granted access to
-the resource and the request does not get queued. The client will have to try
+<p>Clients can also request the use of a resource through the
+immediateRequest() command. A call to immediateRequest() can either
+return SUCCESS or FAIL, with requests made through this command never being
+queued. If a call to immediateRequest() returns SUCCESS, the client is granted
+access to the resource immediately after the call has returned, and no granted
+event is ever signaled. If it returns FAIL, the client is not granted access to
+the resource and the request does not get queued. The client will have to try
and gain access to the resource again later.</p>
-<p>A client can use the isOwner command of the Resource interface to
-check if it is the current owner of the resource. This command is mostly
+<p>A client can use the isOwner command of the Resource interface to
+check if it is the current owner of the resource. This command is mostly
used to perform runtime checks to make sure that clients not owning a resource
are not able to use it. If a call to isOwner fails, then no call
should be made to commands provided by that resource.</p>
-<p>The diagram below shows how a simple shared resource can be
-built from a dedicated resource by using just the Resource interface
+<p>The diagram below shows how a simple shared resource can be
+built from a dedicated resource by using just the Resource interface
provided by an arbiter.:</p>
<pre class="literal-block">
/|\ /|\
| |
| Data Interface | Resource
- | |
+ | |
--------------------------------------------
| Shared Resource |
--------------------------------------------
<p>An arbiter MUST provide exactly one parameterized Resource interface,
where the parameter is a client ID, following the Service
Instance pattern[3]_. An arbitrated component SomeNameP MUST
-#define SOME_NAME_RESOURCE to a string which can be passed to unique()
+#define SOME_NAME_RESOURCE to a string which can be passed to unique()
to obtain a client id. This #define must be placed in a separate file
because of the way nesC files are preprocessed: including the
SomeNameP component isn't enough to ensure that macros #define'd in
each Resource client is given a unique client ID, with the added
benefit of properly coupling multiple components that all need to
refer to the same client ID.</p>
-<p>Appendix B also provides a complete example of how an I2C resource might be
-abstracted according to this pattern. For further examples see the various
+<p>Appendix B also provides a complete example of how an I2C resource might be
+abstracted according to this pattern. For further examples see the various
chip implementations in the tinyos-2.x source tree under tinyos-2.x/chips/</p>
</div>
-<div class="section">
-<h2><a id="arbiterinfo" name="arbiterinfo">3.2 ArbiterInfo</a></h2>
+<div class="section" id="arbiterinfo">
+<h2><a name="arbiterinfo">3.2 ArbiterInfo</a></h2>
<p>Arbiters MUST provide an instance of the ArbiterInfo interface.
-The ArbiterInfo interface allows a component to query the current
+The ArbiterInfo interface allows a component to query the current
status of an arbiter:</p>
<pre class="literal-block">
interface ArbiterInfo {
async command uint8_t clientId();
}
</pre>
-<p>In contrast to the parameterized Resource interface provided by an arbiter,
-only a single ArbiterInfo interface is provided. Its purpose is
+<p>In contrast to the parameterized Resource interface provided by an arbiter,
+only a single ArbiterInfo interface is provided. Its purpose is
to allow one to find out:</p>
<ul class="simple">
<li>Whether the resource for which it is arbitrating use is currently in use or not</li>
<li>Which client is using it.</li>
</ul>
-<p>One can view ArbiterInfo as an interface for obtaining global information about
-the use of a resource, while Resource can be viewed as an interface for obtaining
+<p>One can view ArbiterInfo as an interface for obtaining global information about
+the use of a resource, while Resource can be viewed as an interface for obtaining
local access to that resource.</p>
-<p>The primary use of the ArbiterInfo interface is to allow a shared resource to reject
-any calls made through its data interface by clients that do not currently have access to
+<p>The primary use of the ArbiterInfo interface is to allow a shared resource to reject
+any calls made through its data interface by clients that do not currently have access to
it. For an example of how this interface is used in this fashion refer to Appendix B.:</p>
<pre class="literal-block">
/|\ /|\
| |
| Data Interface | Resource
- | |
+ | |
-----------------------------------------------------------
| Shared Resource |
-----------------------------------------------------------
---------------------- -------------------------------
</pre>
</div>
-<div class="section">
-<h2><a id="resourcerequested" name="resourcerequested">3.3 ResourceRequested</a></h2>
-<p>Sometimes it is useful for a client to be able to hold onto a resource until
+<div class="section" id="resourcerequested">
+<h2><a name="resourcerequested">3.3 ResourceRequested</a></h2>
+<p>Sometimes it is useful for a client to be able to hold onto a resource until
someone else needs it and only at that time decide to release it. Using the
ResourceRequested interface, this information is made available to the current
owner of a resource:</p>
client makes a request for the resource through the request() command of
its Resource interface. If a request is made through the immediateRequest()
command, then the immediateRequested() event is signaled.</p>
-<p>An arbiter SHOULD provide a parameterized ResourceRequested interface to its
-clients, but is not required to. The client id of the parameterized
-ResourceRequested interface should be coupled with the client id of the Resource
-interface to ensure that all events are signaled to the proper clients. Please
+<p>An arbiter SHOULD provide a parameterized ResourceRequested interface to its
+clients, but is not required to. The client id of the parameterized
+ResourceRequested interface should be coupled with the client id of the Resource
+interface to ensure that all events are signaled to the proper clients. Please
refer to Appendix B for an example of how this interface might be used.:</p>
<pre class="literal-block">
/|\ /|\ /|\
---------------------- ----------------------------------------------------
</pre>
</div>
-<div class="section">
-<h2><a id="resourceconfigure" name="resourceconfigure">3.4 ResourceConfigure</a></h2>
-<p>The existence of the ResourceConfigure interface allows a resource to be
+<div class="section" id="resourceconfigure">
+<h2><a name="resourceconfigure">3.4 ResourceConfigure</a></h2>
+<p>The existence of the ResourceConfigure interface allows a resource to be
automatically configured just before a client is granted access to it.
Components providing the ResourceConfigure interface use the interfaces
provided by an underlying dedicated resource to configure it into one
-of its desired modes of operation. A cleint then wires its shared resource
-abstraction to the component implementing the desired configuration. The
-configure command is called immediataely before the client is granted access
-to the resource, and the unconfigure command is called just before fully
+of its desired modes of operation. A cleint then wires its shared resource
+abstraction to the component implementing the desired configuration. The
+configure command is called immediataely before the client is granted access
+to the resource, and the unconfigure command is called just before fully
releasing it.:</p>
<pre class="literal-block">
interface ResourceConfigure {
ResourceConfigure ResourceConfigure ResourceConfigure
| | /|\
| | |
- \|/ \|/ |
-------------------- ------------------- -------------------
+ \|/ \|/ |
+------------------- ------------------- -------------------
| Configuration 1 | | Configuration 2 | | Shared Resource |
------------------- ------------------- -------------------
| | /|\
| Control Interface | | ResourceConfigure
\|/ \|/ |
- ------------------------------ -----------
+ ------------------------------ -----------
| Dedicated Resource | | Arbiter |
------------------------------ -----------
</pre>
-<p>The arbiter SHOULD use a parameterized ResourceConfigure interface, with
+<p>The arbiter SHOULD use a parameterized ResourceConfigure interface, with
its client ID parameter coupled with the client id of its parameterized
-Resource interface. If an arbiter uses the ResourceConfigure interface,
-it MUST call ResourceConfigure.configure() on the granted client ID
+Resource interface. If an arbiter uses the ResourceConfigure interface,
+it MUST call ResourceConfigure.configure() on the granted client ID
before it signals the Resource.granted() event. Similarly, after a valid
-call to Resource.release(), it MUST call ResourceConfigure.unconfigure()
+call to Resource.release(), it MUST call ResourceConfigure.unconfigure()
on the releasing client ID. By calling ResourceConfigure.configure() just
-before granting a client access to a resource and calling
+before granting a client access to a resource and calling
ResourceConfigure.unconfigure() just before fully releasing it, it is guaranteed
-that a resource is always unconfigured before an attempt to configure it can be
+that a resource is always unconfigured before an attempt to configure it can be
made again.</p>
<p>The commands included in this interface could have been made part of the standard
-Resource interface (and changed into callback events), but at a higher cost than
-keeping them separate. Introducing these new commands into the Resource interface
-would have lead to a large number of clients all including redundant configuration
-code, while using the call out approach to a separate component ensures that we
+Resource interface (and changed into callback events), but at a higher cost than
+keeping them separate. Introducing these new commands into the Resource interface
+would have lead to a large number of clients all including redundant configuration
+code, while using the call out approach to a separate component ensures that we
only have a single instance of the code.</p>
-<p>For an example of how configurations for the three different modes of the
-Msp430 Usart component can take advantage of the ResourceConfigure
-interface refer to Appendix B as well as section 4 on the use of
+<p>For an example of how configurations for the three different modes of the
+Msp430 Usart component can take advantage of the ResourceConfigure
+interface refer to Appendix B as well as section 4 on the use of
cross-component reservation.</p>
</div>
-<div class="section">
-<h2><a id="resourcedefaultowner" name="resourcedefaultowner">3.5 ResourceDefaultOwner</a></h2>
-<p>The normal Resource interface is for use by clients that all share the resource
-in an equal fashion. The ResourceDefaultOwner interface is for use by a single
-client that needs to be given control of the resource whenever no one else is
-using it. An arbiter MAY provide a single instance of the ResourceDefaultOwner
+<div class="section" id="resourcedefaultowner">
+<h2><a name="resourcedefaultowner">3.5 ResourceDefaultOwner</a></h2>
+<p>The normal Resource interface is for use by clients that all share the resource
+in an equal fashion. The ResourceDefaultOwner interface is for use by a single
+client that needs to be given control of the resource whenever no one else is
+using it. An arbiter MAY provide a single instance of the ResourceDefaultOwner
interface. It MUST NOT provide more than one.:</p>
<pre class="literal-block">
interface ResourceDefaultOwner {
}
</pre>
<p>The Arbiter MUST guarantee that the client of the ResourceDefaulrClient interface is
-made the owner of the resource before the boot initialization sequence is
-completed. When a normal resource client makes a request for the resource, the
-ResourceDefaultOwner will receive either a requested() or an immediateRequested()
-event depending on how the request was made. It must then decide if and when to
-release it. Once released, all clients that have pending requests will be
-granted access to the resource in the order determined by the queuing policy of
-the arbiter in use. Once all pending requests have been granted (including
-those that came in while other clients had access to the resource), the
-ResourceDefaultOwner is automatically given control of the resource, receiving its
-granted() event in the process. The ResourceDefaultOwner interface also contains
-the same isOwner() command as the normal Resource interface, and the semantics
+made the owner of the resource before the boot initialization sequence is
+completed. When a normal resource client makes a request for the resource, the
+ResourceDefaultOwner will receive either a requested() or an immediateRequested()
+event depending on how the request was made. It must then decide if and when to
+release it. Once released, all clients that have pending requests will be
+granted access to the resource in the order determined by the queuing policy of
+the arbiter in use. Once all pending requests have been granted (including
+those that came in while other clients had access to the resource), the
+ResourceDefaultOwner is automatically given control of the resource, receiving its
+granted() event in the process. The ResourceDefaultOwner interface also contains
+the same isOwner() command as the normal Resource interface, and the semantics
of its use are exactly the same.</p>
-<p>Although the ResourceDefaultOwner interface looks similar to a combination of the
-normal Resource interface and the ResourceRequested interface, its intended use
-is quite different. The ResourceDefaultOwner interface should only be used by
-clients that wish to have access to a resource only when no other clients are
-using it. They do not actively seek access to the resource, but rather use
+<p>Although the ResourceDefaultOwner interface looks similar to a combination of the
+normal Resource interface and the ResourceRequested interface, its intended use
+is quite different. The ResourceDefaultOwner interface should only be used by
+clients that wish to have access to a resource only when no other clients are
+using it. They do not actively seek access to the resource, but rather use
it to perform operations when it would otherwise simply be idle.</p>
-<p>The primary motivation behind the definition of the ResourceDefaultOwner
+<p>The primary motivation behind the definition of the ResourceDefaultOwner
interface is to allow for an easy integration of power management
-for a resource with its arbitration policy. Arbiters that want to allow
-a resource to be controlled by a particular power management policy can
-provide the ResourceDefaultOwner interface for use by a component that
-implements that policy. The power management component will receive the
+for a resource with its arbitration policy. Arbiters that want to allow
+a resource to be controlled by a particular power management policy can
+provide the ResourceDefaultOwner interface for use by a component that
+implements that policy. The power management component will receive the
granted() event whenever the resource has gone idle, and will proceed in
-powering it down. When another client requests the resource, the power
-manager will be notified through either the requested() or
-immediateRequested() events as appropriate. It can then power up the resource
-and release it once the power up has completed. Note that if power up is
-a split-phase operation (takes a while), then calls by clients to
-immediateRequest() when in the powered down state will return
+powering it down. When another client requests the resource, the power
+manager will be notified through either the requested() or
+immediateRequested() events as appropriate. It can then power up the resource
+and release it once the power up has completed. Note that if power up is
+a split-phase operation (takes a while), then calls by clients to
+immediateRequest() when in the powered down state will return
FAIL. Please see the TEP on the Power Management of Non-Virtualized devices
(<a class="footnote-reference" href="#id7" id="id3" name="id3">[4]</a>) for more details.</p>
</div>
</div>
-<div class="section">
-<h1><a id="cross-component-reservation" name="cross-component-reservation">4. Cross-Component Reservation</a></h1>
+<div class="section" id="cross-component-reservation">
+<h1><a name="cross-component-reservation">4. Cross-Component Reservation</a></h1>
<p>In some cases, it is desirable to share the reservation of a
single resource across multiple components. For example, on the TI
MSP430, a single USART component can be used as an I2C bus, a UART,
parameter to the parameterized Resource interface provided by the
Msp430Spi0P component. This is where the mapping of the two
different ids begins. As well as <em>providing</em> a parameterized
-Resource interface (Msp430Spi0P.Resource), the Msp430Spi0P component
-also <em>uses</em> a parameterized Resource interface (Msp430Spi0P.UsartResource).
-Whenever a client makes a call through the provided Resource interface
-with id CLIENT_ID, an underlying call to the Msp430Spi0P.Resource interface
-with the same id is implicitly made. By then wiring the Msp430Spi0P.UsartResource
-interface with id CLIENT_ID to an instance of the Resource interface
-provided by the instantiation of the Msp430Usart0C component, the mapping
-is complete. Any calls to the Resource interface provided by a new
-instantiation of the Msp430Spi0C component will now be made through a
+Resource interface (Msp430Spi0P.Resource), the Msp430Spi0P component
+also <em>uses</em> a parameterized Resource interface (Msp430Spi0P.UsartResource).
+Whenever a client makes a call through the provided Resource interface
+with id CLIENT_ID, an underlying call to the Msp430Spi0P.Resource interface
+with the same id is implicitly made. By then wiring the Msp430Spi0P.UsartResource
+interface with id CLIENT_ID to an instance of the Resource interface
+provided by the instantiation of the Msp430Usart0C component, the mapping
+is complete. Any calls to the Resource interface provided by a new
+instantiation of the Msp430Spi0C component will now be made through a
unique Resource interface on the underlying Msp430Usart0C component.</p>
<p>This level of indirection is necessary because it may not always be
desirable to directly wire the service level Resource interface to
the underlying shared Resource interface. Sometimes we may want to
perform some operations between a service level command being
-called, and calling the underlying command on the shared resource.
+called, and calling the underlying command on the shared resource.
With such a mapping, inserting these operations is made possible.</p>
<p>Having such a mapping is also important for services that need to
explicitly keep track of the number of clients they have,
<p>Implementations of components similar to this one can be found in the
tinyos-2.x source tree in the tos/chips/msp430/uart directory</p>
</div>
-<div class="section">
-<h1><a id="implementation" name="implementation">5. Implementation</a></h1>
+<div class="section" id="implementation">
+<h1><a name="implementation">5. Implementation</a></h1>
<p>Because most components use one of a small number of arbitration
policies, tinyos-2.x includes a number of default resource arbiters. These
arbiters can be found in <tt class="docutils literal"><span class="pre">tinyos-2.x/tos/system</span></tt> and are all
provides interface ResourceDefaultOwner;
provides interface ArbiterInfo;
uses interface ResourceConfigure[uint8_t id];
-}
+}
</pre>
-<p>The "Simple" arbiters are intended for use by resources that
+<p>The "Simple" arbiters are intended for use by resources that
do not require the additional overhead incurred by providing the
ResourceDefaultOwner interface.</p>
<p>For many situations, changing an arbitration policy requires nothing
more than changing the queuing policy it uses to decide the order in
-which incoming requests should be granted. In this way, separating
-queuing policy implementations from actual arbitration implementations
-encourages code reuse. The introduction of the SimpleArbiterP and
+which incoming requests should be granted. In this way, separating
+queuing policy implementations from actual arbitration implementations
+encourages code reuse. The introduction of the SimpleArbiterP and
ArbiterP components found under tinyos-2.x/tos/system help in this
separation. They can be wired to components providing
-a particular queuing policy through the use of the ResourceQueue
+a particular queuing policy through the use of the ResourceQueue
interface.:</p>
<pre class="literal-block">
interface ResourceQueue {
async command bool isEnqueued(resource_client_id_t id);
async command resource_client_id_t dequeue();
async command error_t enqueue(resource_client_id_t id);
-}
+}
</pre>
-<p>An example of wiring a First-Come-First-Serve (FCFS) queuing policy to
+<p>An example of wiring a First-Come-First-Serve (FCFS) queuing policy to
the SimpleArbiterP component using the ResourceQueue interface
defined above can be seen below:</p>
<pre class="literal-block">
</pre>
<p>This generic configuration can be instantiated by a resource in order
to grant requests made by its clients in an FCFS fashion.</p>
-<p>All of the default queuing policies provided in tinyos-2.x along with the
-respective arbitration components that have been built using them are
+<p>All of the default queuing policies provided in tinyos-2.x along with the
+respective arbitration components that have been built using them are
given below:</p>
<p>Queuing Policies:</p>
<ul class="simple">
<li>SimpleRoundRobinArbiterC</li>
<li>RoundRobinArbiterC</li>
</ul>
-<p>Keep in mind that neither the implementation of an arbiter nor its
-queuing policy can be used to explicitly restrict access to an
+<p>Keep in mind that neither the implementation of an arbiter nor its
+queuing policy can be used to explicitly restrict access to an
underlying shared resource. The arbiter simply provides a standardized
-way of managing client ids so that shared resources don't have to duplicate
+way of managing client ids so that shared resources don't have to duplicate
this functionality themselves every time they are implemented. In order to
actually restrict clients from using a resource without first requesting it,
a shared resource must use the functionality provided by the ArbiterInfo interface
-to perform runtime checks on the current owner of a resource. Please refer
+to perform runtime checks on the current owner of a resource. Please refer
to the section on the ArbiterInfo interface in Appendix B for more information
on how such runtime checks can be performed.</p>
</div>
-<div class="section">
-<h1><a id="author-s-address" name="author-s-address">6. Author's Address</a></h1>
+<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">Kevin Klues</div>
<div class="line">503 Bryan Hall</div>
<div class="line">email - <a class="reference" href="mailto:handzisk@tkn.tu-berlin.de">handzisk@tkn.tu-berlin.de</a></div>
</div>
</div>
-<div class="section">
-<h1><a id="citations" name="citations">7. Citations</a></h1>
+<div class="section" id="citations">
+<h1><a name="citations">7. Citations</a></h1>
<table class="docutils footnote" frame="void" id="id4" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
</tbody>
</table>
</div>
-<div class="section">
-<h1><a id="appendix-a-resource-class-examples" name="appendix-a-resource-class-examples">Appendix A: Resource Class Examples</a></h1>
-<div class="section">
-<h2><a id="dedicated-resource" name="dedicated-resource">Dedicated Resource</a></h2>
+<div class="section" id="appendix-a-resource-class-examples">
+<h1><a name="appendix-a-resource-class-examples">Appendix A: Resource Class Examples</a></h1>
+<div class="section" id="dedicated-resource">
+<h2><a name="dedicated-resource">Dedicated Resource</a></h2>
<p>Timer 2 on the Atmega128 microprocessor is a dedicated resource
represented by the HplAtm128Timer2C component:</p>
<pre class="literal-block">
</pre>
<p>Only a single client can wire to any of these interfaces as enforced through
the nesC @exactlyonce attribute. Keep in mind that although the interfaces of
-this component are only allowed to be wired to once, nothing prevents the
-component wiring to them from virtualizing the services they provide at some
-higher level. If you are unfamiliar with how @exactlyonce and other nesC
-attributes are used to by the nesC compiler, please refer to section 9.1 of the
+this component are only allowed to be wired to once, nothing prevents the
+component wiring to them from virtualizing the services they provide at some
+higher level. If you are unfamiliar with how @exactlyonce and other nesC
+attributes are used to by the nesC compiler, please refer to section 9.1 of the
TinyOS Programming Manual <a class="footnote-reference" href="#id8" id="id9" name="id9">[5]</a>.</p>
</div>
-<div class="section">
-<h2><a id="virtualized-resource" name="virtualized-resource">Virtualized Resource</a></h2>
-<p>The TimerMilliC component provides a virtual abstraction of millisecond
-precision timers to application components <a class="footnote-reference" href="#id5" id="id10" name="id10">[2]</a>. It encapsulates the required
-parameterized Timer interface through the use of a generic configuration.
-Clients wishing to use a millisecond timer need only instantiate a single
-instance of the TimerMilliC generic, leaving the fact that it is virtualized
+<div class="section" id="virtualized-resource">
+<h2><a name="virtualized-resource">Virtualized Resource</a></h2>
+<p>The TimerMilliC component provides a virtual abstraction of millisecond
+precision timers to application components <a class="footnote-reference" href="#id5" id="id10" name="id10">[2]</a>. It encapsulates the required
+parameterized Timer interface through the use of a generic configuration.
+Clients wishing to use a millisecond timer need only instantiate a single
+instance of the TimerMilliC generic, leaving the fact that it is virtualized
underneath transparent.:</p>
<pre class="literal-block">
generic configuration TimerMilliC {
Timer = TimerMilliP.TimerMilli[unique(UQ_TIMER_MILLI)];
}
</pre>
-<p>The actual parameterized Timer interface is provided by the chip specific
-HilTimerMilliC component. This interface is exposed through
-the TimerMilliP component which wires HilTimerMilliC to the boot
+<p>The actual parameterized Timer interface is provided by the chip specific
+HilTimerMilliC component. This interface is exposed through
+the TimerMilliP component which wires HilTimerMilliC to the boot
initialization sequence:</p>
<pre class="literal-block">
configuration TimerMilliP {
</pre>
</div>
</div>
-<div class="section">
-<h1><a id="appendix-b-arbiter-interface-examples" name="appendix-b-arbiter-interface-examples">Appendix B: Arbiter Interface Examples</a></h1>
+<div class="section" id="appendix-b-arbiter-interface-examples">
+<h1><a name="appendix-b-arbiter-interface-examples">Appendix B: Arbiter Interface Examples</a></h1>
<!-- Note:
-Most of the examples provided in this section use complex nesC syntax that may
-be unfamiliar to the novice nesC programmer. Please refer to the TinyOS
-programming Manual [5]_ for clarification as necessary. -->
-<div class="section">
-<h2><a id="id11" name="id11">Resource</a></h2>
+Most of the examples provided in this section use complex nesC syntax that may
+be unfamiliar to the novice nesC programmer. Please refer to the TinyOS
+programming Manual [5]_ for clarification as necessary. -->
+<div class="section" id="id11">
+<h2><a name="id11">Resource</a></h2>
<p>Examples of how to use the Resource interface for arbitrating
between multiple clients can be found in the tinyos-2.x
source tree under tinyos-2.x/apps/tests/TestArbiter.</p>
-<p>A specific example of where the Resource.isOwner() is used
-can be seen in the HplTda5250DataP component of the Infineon
+<p>A specific example of where the Resource.isOwner() is used
+can be seen in the HplTda5250DataP component of the Infineon
Tda5250 radio implementation:</p>
<pre class="literal-block">
async command error_t HplTda5250Data.tx(uint8_t data) {
...
}
</pre>
-<p>where I2CPacketImplP contains the actual implementation of the
-I2C service, and I2CPacket.h contains the #define for the
+<p>where I2CPacketImplP contains the actual implementation of the
+I2C service, and I2CPacket.h contains the #define for the
name of the resource required by the arbiter:</p>
<pre class="literal-block">
#ifndef I2CPACKETC_H
}
implementation {
enum { CLIENT_ID = unique(I2CPACKET_RESOURCE) };
-
+
components I2CPacketP as I2C;
Resource = I2C.Resource[CLIENT_ID];
- I2CPacket = I2C.I2CPacket[CLIENT_ID];
+ I2CPacket = I2C.I2CPacket[CLIENT_ID];
}
</pre>
<p>In this example, an instance of the I2CPacket interface is coupled with
an instance of the Resource interface on every new instantiation of
the I2CPacketC component. In this way, a single Resource and a
-single I2CPacket interface can be exported by this component together
+single I2CPacket interface can be exported by this component together
for use by a client.</p>
<p>Clients of the I2C service would use it as follows:</p>
<pre class="literal-block">
}
</pre>
</div>
-<div class="section">
-<h2><a id="id12" name="id12">ArbiterInfo</a></h2>
+<div class="section" id="id12">
+<h2><a name="id12">ArbiterInfo</a></h2>
<p>In the implementation of the ADC component on the Msp430 microcontroller,
a simple arbiter is used to provide a round robin sharing policy
between clients of the ADC:</p>
<pre class="literal-block">
-configuration Msp430Adc12C {
- provides interface Resource[uint8_t id];
- provides interface Msp430Adc12SingleChannel[uint8_t id];
- provides interface Msp430Adc12FastSingleChannel[uint8_t id];
-}
-implementation {
- components Msp430Adc12P,MainC,
+configuration Msp430Adc12C {
+ provides interface Resource[uint8_t id];
+ provides interface Msp430Adc12SingleChannel[uint8_t id];
+ provides interface Msp430Adc12FastSingleChannel[uint8_t id];
+}
+implementation {
+ components Msp430Adc12P,MainC,
new SimpleRoundRobinArbiterC(MSP430ADC12_RESOURCE) as Arbiter,
...
...
}
</pre>
-<p>In this configuration we see that the Resource interface provided by
+<p>In this configuration we see that the Resource interface provided by
Msp430Adc12C is wired directly to the instance of the SimpleRoundRobinArbiterC
component that is created. The ArbiterInfo interface provided by
-SimpleRoundRobinArbiterC is then wired to Msp430Adc12P. The Msp430Adc12P
+SimpleRoundRobinArbiterC is then wired to Msp430Adc12P. The Msp430Adc12P
component then uses this interface to perform run time checks to ensure that
-only the client that currently has access to the ADC resource is able to
+only the client that currently has access to the ADC resource is able to
use it:</p>
<pre class="literal-block">
async command error_t Msp430Adc12SingleChannel.getSingleData[uint8_t id]() {
}
else return ERESERVE;
}
-
+
async command error_t Msp430Adc12FastSingleChannel.configure[uint8_t id]() {
if (call ADCArbiterInfo.clientId() == id){
clientID = id
}
else return ERESERVE;
}
-
-async command error_t Msp430Adc12FastSingleChannel.getSingleData[uint8_t id]()
+
+async command error_t Msp430Adc12FastSingleChannel.getSingleData[uint8_t id]()
{
if (clientID = id)
// Start getting data
else return ERESERVE;
}
</pre>
-<p>In order for these runtime checks to succeed, users of the
-Msp430Adc12SingleChannel and Msp430Adc12FastSingleChannel interfaces will have
-to match their client id's with the client id of a corresponding Resource
+<p>In order for these runtime checks to succeed, users of the
+Msp430Adc12SingleChannel and Msp430Adc12FastSingleChannel interfaces will have
+to match their client id's with the client id of a corresponding Resource
interface. This can be done in the following way:</p>
<pre class="literal-block">
generic configuration Msp430Adc12ClientC() {
provides interface Resource;
provides interface Msp430Adc12SingleChannel;
-}
+}
implementation {
components Msp430Adc12C;
enum { ID = unique(MSP430ADC12_RESOURCE) };
-
+
Resource = Msp430Adc12C.Resource[ID];
Msp430Adc12SingleChannel = Msp430Adc12C.SingleChannel[ID];
-}
+}
</pre>
<pre class="literal-block">
generic configuration Msp430Adc12FastClientC() {
provides interface Resource;
provides interface Msp430Adc12FastSingleChannel;
-}
+}
implementation {
components Msp430Adc12C;
enum { ID = unique(MSP430ADC12_RESOURCE) };
-
+
Resource = Msp430Adc12C.Resource[ID];
Msp430Adc12FastSingleChannel = Msp430Adc12C.SingleChannel[ID];
-}
+}
</pre>
<p>Since these are generic components, clients simply need to instantiate them
in order to get access to a single Resource interface that is already
properly coupled with a Msp430Adc12SingleChannel or Msp430Adc12FastSingleChannel
interface.</p>
-<p>Take a look in the tinyos-2.x source tree under tinyos-2.x/tos/chips/adc12
+<p>Take a look in the tinyos-2.x source tree under tinyos-2.x/tos/chips/adc12
to see the full implementation of these components in their original context.</p>
</div>
-<div class="section">
-<h2><a id="id13" name="id13">ResourceRequested</a></h2>
+<div class="section" id="id13">
+<h2><a name="id13">ResourceRequested</a></h2>
<p>On the eyesIFXv2 platform, both the radio and the flash need access to the bus
-provided by the Usart0 component on the Msp430 microcontroller. Using
-a simple cooperative arbitration policy, these two components should able to
-share the Usart resource by only holding on to it as long as they need it and
-then releasing it for use by the other component. In the case of the MAC
-implementation of the Tda5250 radio component, however, the Msp430 Usart
-resource needs be held onto indefinitely. It only ever considers releasing the
-resource if a request from the flash component comes in through its
-ResourceRequested interface. If it cannot release it right away (i.e. it is in
-the middle of receiving a packet), it defers the release until some later point
-in time. Once it is ready to release the resource, it releases it, but then
-immediately requests it again. The flash is then able to do what it wants with
+provided by the Usart0 component on the Msp430 microcontroller. Using
+a simple cooperative arbitration policy, these two components should able to
+share the Usart resource by only holding on to it as long as they need it and
+then releasing it for use by the other component. In the case of the MAC
+implementation of the Tda5250 radio component, however, the Msp430 Usart
+resource needs be held onto indefinitely. It only ever considers releasing the
+resource if a request from the flash component comes in through its
+ResourceRequested interface. If it cannot release it right away (i.e. it is in
+the middle of receiving a packet), it defers the release until some later point
+in time. Once it is ready to release the resource, it releases it, but then
+immediately requests it again. The flash is then able to do what it wants with
the Usart, with the radio regaining control soon thereafter.</p>
-<p>In the CsmaMacP implementation of the Tda5250 radio we see the ResourceRequested
+<p>In the CsmaMacP implementation of the Tda5250 radio we see the ResourceRequested
event being implemented:</p>
<pre class="literal-block">
async event void ResourceRequested.requested() {
...
}
</pre>
-<p>Although the full implementation of these components is not provided, the
-functionality they exhibit should be clear. The CsmaMacP component receives the
-ResourceRequested.requested() event when the flash requests the use of the
-Msp430 Usart0 resource. If it is already in the receive state, it tries to
-reset the receive state through a call to a lower level component. This
-component checks to see if the radio is in the middle of doing anything (i.e.
-the radioBusy() == FALSE check), and if not, releases the resource and then
+<p>Although the full implementation of these components is not provided, the
+functionality they exhibit should be clear. The CsmaMacP component receives the
+ResourceRequested.requested() event when the flash requests the use of the
+Msp430 Usart0 resource. If it is already in the receive state, it tries to
+reset the receive state through a call to a lower level component. This
+component checks to see if the radio is in the middle of doing anything (i.e.
+the radioBusy() == FALSE check), and if not, releases the resource and then
requests it again.</p>
-<p>To see the full implementations of these components and their wirings to one
-another, please refer to the tinyos-2.x source tree under
-tinyos-2.x/tos/chips/tda5250, tinyos-2.x/tos/chips/tda5250/mac,
-tinyos-2.x/tos/platforms/eyesIFX/chips/tda5250, and
+<p>To see the full implementations of these components and their wirings to one
+another, please refer to the tinyos-2.x source tree under
+tinyos-2.x/tos/chips/tda5250, tinyos-2.x/tos/chips/tda5250/mac,
+tinyos-2.x/tos/platforms/eyesIFX/chips/tda5250, and
tinyos-2.x/tos/platforms/eyesIFX/chips/msp430.</p>
</div>
-<div class="section">
-<h2><a id="resource-configure" name="resource-configure">Resource Configure</a></h2>
-<p>The Msp430 Usart0 bus can operate in three modes: SPI, I2C,
-and UART. Using all three concurrently is problematic: only one should
+<div class="section" id="resource-configure">
+<h2><a name="resource-configure">Resource Configure</a></h2>
+<p>The Msp430 Usart0 bus can operate in three modes: SPI, I2C,
+and UART. Using all three concurrently is problematic: only one should
be enabled at any given time. However, different clients of the bus might
require the bus to be configured for different protocols. On Telos, for example
-many of the available sensors use an I2C bus, while the radio and flash chip use
+many of the available sensors use an I2C bus, while the radio and flash chip use
SPI.</p>
<p>A component providing the SPI service on top of the shared Usart component looks
like this:</p>
}
implementation {
enum { CLIENT_ID = unique( MSP430_SPIO_BUS ) };
-
+
components Msp430SpiNoDma0P as SpiP;
components new Msp430Usart0C() as UsartC;
SpiP.ResourceConfigure[ CLIENT_ID ] <- UsartC.ResourceConfigure;
</pre>
<p>And one providing the I2C service looks like this:</p>
<pre class="literal-block">
-generic configuration Msp430I2CC() {
+generic configuration Msp430I2CC() {
provides interface Resource;
provides interface I2CPacket<TI2CBasicAddr> as I2CBasicAddr;
- ...
+ ...
}
implementation {
enum { CLIENT_ID = unique( MSP430_I2CO_BUS ) };
}
</pre>
<p>The implementation of the ResourceConfigure interface is
-provided by both the Msp430SpiNoDma0P and the Msp430I2C0P. In the
+provided by both the Msp430SpiNoDma0P and the Msp430I2C0P. In the
two different components, the same Msp430Usart0C component is used,
but wired to the proper implementation of the ResourceConfigure
-interface. In this way, different instances of the Msp430Usart0C
-can each have different configurations associated with them, but
+interface. In this way, different instances of the Msp430Usart0C
+can each have different configurations associated with them, but
still provide the same functionality.</p>
-<p>Take a look in the tinyos-2.x source tree under
-tinyos-2.x/tos/chips/msp430/usart to see the full implementation of
+<p>Take a look in the tinyos-2.x source tree under
+tinyos-2.x/tos/chips/msp430/usart to see the full implementation of
these components along with the corresponding Uart implementation.</p>
</div>
</div>
<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.10: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.3.6: http://docutils.sourceforge.net/" />
<title>Sensors and Sensor Boards</title>
<meta name="author" content="David Gay, Phil Levis, Wei Hong, Joe Polastre, and Gilman Tolle" />
<style type="text/css">
/*
:Author: David Goodger
:Contact: goodger@users.sourceforge.net
-:Date: $Date$
-:Revision: $Revision$
-:Copyright: This stylesheet has been placed in the public domain.
+:date: $Date$
+:version: $Revision$
+:copyright: This stylesheet has been placed in the public domain.
Default cascading style sheet for the HTML output of Docutils.
-
-See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
-customize this style sheet.
*/
+body {
+ font-family: Times;
+ font-size: 16px;
+}
-/* "! important" is used here to override other ``margin-top`` and
- ``margin-bottom`` styles that are later in the stylesheet or
- more specific. See http://www.w3.org/TR/CSS1#the-cascade */
.first {
margin-top: 0 ! important }
-.last, .with-subtitle {
+.last {
margin-bottom: 0 ! important }
.hidden {
blockquote.epigraph {
margin: 2em 5em ; }
-dl.docutils dd {
+dd {
margin-bottom: 0.5em }
-/* Uncomment (and remove this text!) to get bold-faced definition list terms
-dl.docutils dt {
+/* Uncomment (& remove this text!) to get bold-faced definition list terms
+dt {
font-weight: bold }
*/
font-weight: bold ;
text-align: center }
-div.admonition, div.attention, div.caution, div.danger, div.error,
-div.hint, div.important, div.note, div.tip, div.warning {
+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.admonition p.admonition-title, div.hint p.admonition-title,
-div.important p.admonition-title, div.note p.admonition-title,
-div.tip p.admonition-title {
- font-weight: bold ;
- font-family: sans-serif }
-
div.attention p.admonition-title, div.caution p.admonition-title,
div.danger p.admonition-title, div.error p.admonition-title,
div.warning p.admonition-title {
font-weight: bold ;
font-family: sans-serif }
-/* Uncomment (and remove this text!) to get reduced vertical space in
- compound paragraphs.
-div.compound .compound-first, div.compound .compound-middle {
- margin-bottom: 0.5em }
-
-div.compound .compound-last, div.compound .compound-middle {
- margin-top: 0.5em }
-*/
+div.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 ;
margin-left: 2em }
div.footer, div.header {
- clear: both;
font-size: smaller }
div.line-block {
div.sidebar {
margin-left: 1em ;
border: medium outset ;
- padding: 1em ;
+ padding: 0em 1em ;
background-color: #ffffee ;
width: 40% ;
float: right ;
div.topic {
margin: 2em }
-h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
-h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
- margin-top: 0.4em }
+h1 {
+ font-family: Arial, sans-serif;
+ font-size: 20px;
+}
h1.title {
- text-align: center }
+ text-align: center;
+ font-size: 32px;
+}
+
+h2 {
+ font-size: 16px;
+ font-family: Arial, sans-serif;
+}
h2.subtitle {
text-align: center }
-hr.docutils {
- width: 75% }
-
-img.align-left {
- clear: left }
-
-img.align-right {
- clear: right }
+h3 {
+ font-size: 12px;
+ font-family: Arial, sans-serif;
+}
-img.borderless {
- border: 0 }
+hr {
+ width: 75% }
ol.simple, ul.simple {
margin-bottom: 1em }
pre.literal-block, pre.doctest-block {
margin-left: 2em ;
margin-right: 2em ;
- background-color: #eeeeee }
+ background-color: #eeeeee;
+ border-color: #000000;
+ border-width: thin;
+ font-size: 14px
+}
span.classifier {
font-family: sans-serif ;
span.option {
white-space: nowrap }
+span.option-argument {
+ font-style: italic }
+
span.pre {
white-space: pre }
span.problematic {
color: red }
-span.section-subtitle {
- /* font-size relative to parent (h1..h6 element) */
- font-size: 80% }
+table {
+ margin-top: 0.5em ;
+ margin-bottom: 0.5em }
table.citation {
- border-left: solid thin gray }
+ border-left: solid thin gray ;
+ padding-left: 0.5ex }
table.docinfo {
- margin: 2em 4em }
-
-table.docutils {
- margin-top: 0.5em ;
- margin-bottom: 0.5em }
+ margin: 2em 4em;
+}
table.footnote {
- border-left: solid thin black }
+ border-left: solid thin black ;
+ padding-left: 0.5ex }
-table.docutils td, table.docutils th,
-table.docinfo td, table.docinfo th {
+td, th {
padding-left: 0.5em ;
padding-right: 0.5em ;
vertical-align: top }
-table.docutils th.field-name, table.docinfo th.docinfo-name {
+th.docinfo-name, th.field-name {
font-weight: bold ;
text-align: left ;
- white-space: nowrap ;
- padding-left: 0 }
+ white-space: nowrap;
+ }
-h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
-h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
+h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt {
font-size: 100% }
-tt.docutils {
- background-color: #eeeeee }
+tt {}
ul.auto-toc {
list-style-type: none }
</style>
</head>
<body>
-<div class="document" id="sensors-and-sensor-boards">
<h1 class="title">Sensors and Sensor Boards</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
</tr>
</tbody>
</table>
+<div class="document" id="sensors-and-sensor-boards">
<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
of this memo is unlimited. This memo is in full compliance with
TEP 1.</p>
</div>
-<div class="section">
-<h1><a id="abstract" name="abstract">Abstract</a></h1>
+<div class="section" id="abstract">
+<h1><a name="abstract">Abstract</a></h1>
<p>This memo documents how sensor drivers are organized in TinyOS and how
sets of sensor drivers are combined into sensor boards and sensor
platforms, along with general principles followed by the components
that provide access to sensors.</p>
</div>
-<div class="section">
-<h1><a id="principles" name="principles">1. Principles</a></h1>
+<div class="section" id="principles">
+<h1><a name="principles">1. Principles</a></h1>
<p>This section describes the basic organization principles for sensor
drivers in TinyOS.</p>
<p>For background, a sensor can be attached to the microcontroller on a
higher-level clients to obtain information needed to properly
interpret the value.</p>
</div>
-<div class="section">
-<h1><a id="sensor-hil-components" name="sensor-hil-components">2. Sensor HIL Components</a></h1>
+<div class="section" id="sensor-hil-components">
+<h1><a name="sensor-hil-components">2. Sensor HIL Components</a></h1>
<p>A sensor HIL component MUST provide:</p>
<ul class="simple">
<li>One or more SID interfaces <a class="citation-reference" href="#tep114" id="id2" name="id2">[TEP114]</a>, for reading data.</li>
}
</pre>
</div>
-<div class="section">
-<h1><a id="sensor-hal-components" name="sensor-hal-components">3. Sensor HAL Components</a></h1>
+<div class="section" id="sensor-hal-components">
+<h1><a name="sensor-hal-components">3. Sensor HAL Components</a></h1>
<p>Sensors with a richer interface than would be supported by the SID
interfaces MAY provide a HAL component in addition to a HIL
component.</p>
}
</pre>
</div>
-<div class="section">
-<h1><a id="directory-organization-guidelines" name="directory-organization-guidelines">4. Directory Organization Guidelines</a></h1>
+<div class="section" id="directory-organization-guidelines">
+<h1><a name="directory-organization-guidelines">4. Directory Organization Guidelines</a></h1>
<p>Because the same physical sensor can be attached to TinyOS platforms
in many different ways, the organization of sensor drivers SHOULD
reflect the distinction between sensor and sensor interconnect.</p>
components can be placed anywhere as long as the nesC compiler
receives enough <cite>-I</cite> directives to locate all of the necessary pieces.</p>
</div>
-<div class="section">
-<h1><a id="authors-addresses" name="authors-addresses">5. Authors' Addresses</a></h1>
+<div class="section" id="authors-addresses">
+<h1><a name="authors-addresses">5. Authors' Addresses</a></h1>
<div class="line-block">
<div class="line">David Gay</div>
<div class="line">2150 Shattuck Ave, Suite 1300</div>
<div class="line">email - <a class="reference" href="mailto:gtolle@archrock.com">gtolle@archrock.com</a></div>
</div>
</div>
-<div class="section">
-<h1><a id="citations" name="citations">6. Citations</a></h1>
+<div class="section" id="citations">
+<h1><a name="citations">6. Citations</a></h1>
<table class="docutils citation" frame="void" id="tep2" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
</tbody>
</table>
</div>
-<div class="section">
-<h1><a id="appendix-a-sensor-driver-examples" name="appendix-a-sensor-driver-examples">Appendix A: Sensor Driver Examples</a></h1>
-<div class="section">
-<h2><a id="analog-adc-connected-sensor" name="analog-adc-connected-sensor">1. Analog ADC-Connected Sensor</a></h2>
+<div class="section" id="appendix-a-sensor-driver-examples">
+<h1><a name="appendix-a-sensor-driver-examples">Appendix A: Sensor Driver Examples</a></h1>
+<div class="section" id="analog-adc-connected-sensor">
+<h2><a name="analog-adc-connected-sensor">1. Analog ADC-Connected Sensor</a></h2>
<p>The Analog sensor requires two components</p>
<ul class="simple">
<li>a component to present the sensor itself (HamamatsuS1087ParC)</li>
}
</pre>
</div>
-<div class="section">
-<h2><a id="binary-pin-connected-sensor" name="binary-pin-connected-sensor">2. Binary Pin-Connected Sensor</a></h2>
+<div class="section" id="binary-pin-connected-sensor">
+<h2><a name="binary-pin-connected-sensor">2. Binary Pin-Connected Sensor</a></h2>
<p>The Binary sensor gets a bit more complex, because it has three
components:</p>
<ul class="simple">
}
</pre>
</div>
-<div class="section">
-<h2><a id="digital-bus-connected-sensor" name="digital-bus-connected-sensor">3. Digital Bus-Connected Sensor</a></h2>
+<div class="section" id="digital-bus-connected-sensor">
+<h2><a name="digital-bus-connected-sensor">3. Digital Bus-Connected Sensor</a></h2>
<p>The Digital sensor is the most complex out of the set, and includes
six components:</p>
<ul class="simple">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.3.6: http://docutils.sourceforge.net/" />
<title>Virtualization</title>
<meta name="author" content="Philip Levis" />
<style type="text/css">
</style>
</head>
<body>
-<div class="document" id="virtualization">
<h1 class="title">Virtualization</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<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.1.2.2</td>
+<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">2006-02-08</td>
+<tr class="field"><th class="docinfo-name">Draft-Modified:</th><td class="field-body">2006-12-12</td>
</tr>
<tr class="field"><th class="docinfo-name">Draft-Discuss:</th><td class="field-body">TinyOS Developer List <tinyos-devel at mail.millennium.berkeley.edu></td>
</tr>
</tbody>
</table>
+<div class="document" id="virtualization">
<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
of this memo is unlimited. This memo is in full compliance with
TEP 1.</p>
</div>
-<div class="section">
-<h1><a id="abstract" name="abstract">Abstract</a></h1>
+<div class="section" id="abstract">
+<h1><a name="abstract">Abstract</a></h1>
<p>This memo desribes how TinyOS 2.0 virtualizes common abstractions through
a combination of static allocation and runtime arbitration. It describes
the benefits and tradeoffs of this approach and how it is used in several
major abstractions.</p>
</div>
-<div class="section">
-<h1><a id="introduction" name="introduction">1. Introduction</a></h1>
+<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
how their implementations are structured to simplify application
writing.</p>
</div>
-<div class="section">
-<h1><a id="distributions" name="distributions">2. Distributions</a></h1>
+<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
<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">
-<h2><a id="controlling-a-service" name="controlling-a-service">2.1 Controlling a Service</a></h2>
+<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
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">
-<h2><a id="service-initialization" name="service-initialization">2.2 Service Initialization</a></h2>
+<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
distribution can achieve this.</p>
</div>
</div>
-<div class="section">
-<h1><a id="oski-services" name="oski-services">3. OSKI Services</a></h1>
+<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">
-<h2><a id="timers" name="timers">3.1 Timers</a></h2>
+<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
<div class="line">}</div>
</div>
</div>
-<div class="section">
-<h2><a id="active-messages" name="active-messages">3.2 Active Messages</a></h2>
+<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,
<p>The active messages layer has control abstractions, named <tt class="docutils literal"><span class="pre">AMServiceC</span></tt>
and <tt class="docutils literal"><span class="pre">AMServiceNotifierC</span></tt>. Active messages follow an OR policy.</p>
</div>
-<div class="section">
-<h2><a id="broadcasts" name="broadcasts">3.3 Broadcasts</a></h2>
+<div class="section" id="broadcasts">
+<h2><a name="broadcasts">3.3 Broadcasts</a></h2>
<p>In addition to active messages, OSKI provides a broadcasting service.
Unlike active messages, which are addressed in terms of AM addresses,
broadcasts are address-free. Broadcast communication has two
named <tt class="docutils literal"><span class="pre">BroadcastServiceC</span></tt> and <tt class="docutils literal"><span class="pre">BroadcastServiceNotifierC</span></tt>, which
follow an OR policy.</p>
</div>
-<div class="section">
-<h2><a id="tree-collection-convergecast" name="tree-collection-convergecast">3.4 Tree Collection/Convergecast</a></h2>
-<p><strong>NOTE: These services are not supported as of the 2.x prerelease.
+<div class="section" id="tree-collection-convergecast">
+<h2><a name="tree-collection-convergecast">3.4 Tree Collection/Convergecast</a></h2>
+<p><strong>NOTE: These services are not supported as of the 2.x prerelease.
They will be supported by the first full release.</strong></p>
<p>OSKI's third communication service is tree-based collection routing.
This service has four abstractions:</p>
<tt class="docutils literal"><span class="pre">CollectionServiceNotifierC</span></tt> abstractions, which follow an OR
policy.</p>
</div>
-<div class="section">
-<h2><a id="uart" name="uart">3.5 UART</a></h2>
-<p><strong>NOTE: These services are not supported as of the 2.x prerelease.
-They will be supported by the first full release.
-They will be fully defined pending discussion/codification of
+<div class="section" id="uart">
+<h2><a name="uart">3.5 UART</a></h2>
+<p><strong>NOTE: These services are not supported as of the 2.x prerelease.
+They will be supported by the first full release.
+They will be fully defined pending discussion/codification of
UART interfaces.</strong></p>
</div>
</div>
-<div class="section">
-<h1><a id="oski-service-structure-and-design" name="oski-service-structure-and-design">4. OSKI Service Structure and Design</a></h1>
+<div class="section" id="oski-service-structure-and-design">
+<h1><a name="oski-service-structure-and-design">4. OSKI Service Structure and Design</a></h1>
<p>Presenting services through abstractions hides the underlying wiring
details and gives a distribution a great deal of implementation
freedom. One issue that arises, however, is initialization. If a user
the service is initialized properly. OSKI achieves this by
encapsulating a complete service as a working component; abstractions
export the service's interfaces.</p>
-<div class="section">
-<h2><a id="example-timers" name="example-timers">4.1 Example: Timers</a></h2>
+<div class="section" id="example-timers">
+<h2><a name="example-timers">4.1 Example: Timers</a></h2>
<p>For example, the timer service provides a single abstraction,
OskiTimerMilliC, which is a generic component. OskiTimerMilliC provides a
single instance of the Timer<TMilli> interface. It is implemented as a
underlying Service Instance pattern: the abstractions take care of
that.</p>
</div>
-<div class="section">
-<h2><a id="example-active-messages" name="example-active-messages">4.2 Example: Active Messages</a></h2>
+<div class="section" id="example-active-messages">
+<h2><a name="example-active-messages">4.2 Example: Active Messages</a></h2>
<p>Active messaging reprsent a slightly more complex service, as it has
several abstractions and a control interface. However, it follows the
same basic pattern: abstractions are generics that export wirings to
<div class="line-block">
<div class="line">provides {</div>
<div class="line-block">
-<div class="line">interface SplitControl;</div>
+<div class="line">interface SplitControl; </div>
<div class="line">interface AMSend[am_id_t id];</div>
<div class="line">interface Receive[am_id_t id];</div>
<div class="line">interface Receive as Snoop[am_id_t id];</div>
pattern in generic components relieves the programmer of having to
deal with unique strings, a common source of bugs in TinyOS 1.x code.</p>
</div>
-<div class="section">
-<h2><a id="oski-requirements" name="oski-requirements">4.3 OSKI Requirements</a></h2>
+<div class="section" id="oski-requirements">
+<h2><a name="oski-requirements">4.3 OSKI Requirements</a></h2>
<p>OSKI is a layer on top of system components: it presents a more
usable, less error-prone, and simpler interface to common TinyOS
functionality. For OSKI to work properly, a platform MUST be compliant
inoperable, exhibit strange behavior, or being uncompilable.</p>
</div>
</div>
-<div class="section">
-<h1><a id="distribution-interfaces" name="distribution-interfaces">5. Distribution Interfaces</a></h1>
+<div class="section" id="distribution-interfaces">
+<h1><a name="distribution-interfaces">5. Distribution Interfaces</a></h1>
<p>The basic notion of a distribution is that it provides a self-contained,
-tested, and complete (for an application domain) programming interface
-to TinyOS. Layers can be added on top of a distribution, but as a
+tested, and complete (for an application domain) programming interface
+to TinyOS. Layers can be added on top of a distribution, but as a
distribution is a self-contained set of abstractions, adding new
services can lead to failures. A distribution represents a hard line
above which all other code operates. One SHOULD NOT add new services,
create a new distribution that extends an existing one, but this is
in and of itself a new distribution.</p>
<p>Generally, as distributions are intended to be higher-level abstractions,
-they SHOULD NOT provide any asynchronous (async) events. They can,
+they SHOULD NOT provide any asynchronous (async) events. They can,
of course, provide async commands. The idea is that no code written on
top of a distribution should be asynchronous, due to the complexity
introduced by having to manage concurrency. Distributions are usually
chances are it is operating close to the hardware, and so is not
platform independent.</p>
</div>
-<div class="section">
-<h1><a id="author-s-address" name="author-s-address">6. Author's Address</a></h1>
+<div class="section" id="author-s-address">
+<h1><a name="author-s-address">6. Author's Address</a></h1>
<div class="line-block">
<div class="line">Philip Levis</div>
<div class="line">467 Soda Hall</div>
<div class="line">email - <a class="reference" href="mailto:pal@cs.berkeley.edu">pal@cs.berkeley.edu</a></div>
</div>
</div>
-<div class="section">
-<h1><a id="citations" name="citations">7. Citations</a></h1>
+<div class="section" id="citations">
+<h1><a name="citations">7. Citations</a></h1>
<table class="docutils citation" frame="void" id="rst" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.3.6: http://docutils.sourceforge.net/" />
<title>message_t</title>
<meta name="author" content="Philip Levis" />
<style type="text/css">
</style>
</head>
<body>
-<div class="document" id="message-t">
<h1 class="title">message_t</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<td>Philip Levis</td></tr>
</tbody>
</table>
+<div class="document" id="message-t">
<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
of this memo is unlimited. This memo is in full compliance with
TEP 1.</p>
</div>
-<div class="section">
-<h1><a id="abstract" name="abstract">Abstract</a></h1>
+<div class="section" id="abstract">
+<h1><a name="abstract">Abstract</a></h1>
<p>This memo covers the TinyOS 2.x message buffer abstraction, <tt class="docutils literal"><span class="pre">message_t</span></tt>.
-It describes the message buffer design considerations, how and where
+It describes the message buffer design considerations, how and where
<tt class="docutils literal"><span class="pre">message_t</span></tt> is specified, and how data link layers should access it.
The major goal of <tt class="docutils literal"><span class="pre">message_t</span></tt> is to allow datagrams to be passed between
different link layers as a contiguous region of memory with zero copies.</p>
</div>
-<div class="section">
-<h1><a id="introduction" name="introduction">1. Introduction</a></h1>
+<div class="section" id="introduction">
+<h1><a name="introduction">1. Introduction</a></h1>
<p>In TinyOS 1.x, a message buffer is a <tt class="docutils literal"><span class="pre">TOS_Msg</span></tt>. A buffer contains an
active message (AM) packet as well as packet metadata, such as timestamps,
acknowledgement bits, and signal strength if the packet was received.
AM payload length (the default is 29 bytes). Fixed sized buffers allows
TinyOS 1.x to have zero-copy semantics: when a component receives a
buffer, rather than copy out the contents it can return a pointer
-to a new buffer for the underlying layer to use for the next received
+to a new buffer for the underlying layer to use for the next received
packet.</p>
<p>One issue that arises is what defines the <tt class="docutils literal"><span class="pre">TOS_Msg</span></tt> structure, as different
-link layers may require different layouts. For example, 802.15.4 radio
-hardware (such as the CC2420, used in the Telos and micaZ platforms)
+link layers may require different layouts. For example, 802.15.4 radio
+hardware (such as the CC2420, used in the Telos and micaZ platforms)
may require 802.15.4 headers, while a software stack built on top of
-byte radios (such as the CC1000, used in the mica2 platform) can specify
+byte radios (such as the CC1000, used in the mica2 platform) can specify
its own packet format. This means that <tt class="docutils literal"><span class="pre">TOS_Msg</span></tt> may be different on
different platforms.</p>
<p>The solution to this problem in TinyOS 1.x is for there to be a standard
definition of <tt class="docutils literal"><span class="pre">TOS_Msg</span></tt>, which a platform (e.g., the micaZ) can
-redefine to match its radio. For example, a mica2 mote uses the standard
+redefine to match its radio. For example, a mica2 mote uses the standard
definition, which is:</p>
<pre class="literal-block">
typedef struct TOS_Msg {
uint8_t type;
uint8_t group;
int8_t data[TOSH_DATA_LENGTH];
-
+
// The following fields are not actually transmitted or received
// on the radio! They are used for internal accounting only.
// The reason they are in this structure is that the AM interface
// requires them to be part of the TOS_Msg that is passed to
// send/receive operations.
-
+
uint8_t strength;
uint8_t lqi;
bool crc;
structure. This introduces dependencies between higher level components
and the structure layout. For example, many network services built on
top of data link layers care whether sent packets are acknowledged. They
-therefore check the <tt class="docutils literal"><span class="pre">ack</span></tt> field of <tt class="docutils literal"><span class="pre">TOS_Msg</span></tt>. If a link layer does not
+therefore check the <tt class="docutils literal"><span class="pre">ack</span></tt> field of <tt class="docutils literal"><span class="pre">TOS_Msg</span></tt>. If a link layer does not
provide acknowledgements, it must still include the <tt class="docutils literal"><span class="pre">ack</span></tt> field
and always set it to 0, wasting a byte of RAM per buffer.</p>
<p>Second, this model does not easily support multiple data link layers.
-Radio chip implementations assume that the fields they require are
+Radio chip implementations assume that the fields they require are
defined in the structure and directly access them. If a platform
has two different link layers (e.g., a CC1000 <em>and</em> a CC2420 radio),
then a <tt class="docutils literal"><span class="pre">TOS_Msg</span></tt> needs to allocate the right amount of space for both
<p>The <tt class="docutils literal"><span class="pre">data</span></tt> payload is especially problematic. Many
components refer to this field, so it must be at a fixed offset
from the beginning of the structure.
-Depending on the underlying link layer, the header fields
+Depending on the underlying link layer, the header fields
preceding it might have different lengths, and packet-level radios
-often require packets to be contiguous memory regions. Overall, these
+often require packets to be contiguous memory regions. Overall, these
complexities make specifying the format of <tt class="docutils literal"><span class="pre">TOS_Msg</span></tt> very difficult.</p>
<p>TinyOS has traditionally used statically sized packet buffers,
rather than more dynamic approaches, such as scatter-gather I/O
-in UNIX sockets (see the man page for <tt class="docutils literal"><span class="pre">recv(2)</span></tt> for details).
+in UNIX sockets (see the man page for <tt class="docutils literal"><span class="pre">recv(2)</span></tt> for details).
TinyOS 2.x continues this approach.</p>
</div>
-<div class="section">
-<h1><a id="id1" name="id1">2. message_t</a></h1>
+<div class="section" id="id1">
+<h1><a name="id1">2. message_t</a></h1>
<p>In TinyOS 2.x, the standard message buffer is <tt class="docutils literal"><span class="pre">message_t</span></tt>. The
message_t structure is defined in <tt class="docutils literal"><span class="pre">tos/types/message.h</span></tt>:</p>
<pre class="literal-block">
nx_uint8_t metadata[sizeof(message_metadata_t)];
} message_t;
</pre>
-<p>This format keeps data at a fixed offset on a platform, which
+<p>This format keeps data at a fixed offset on a platform, which
is important when
passing a message buffer between two different link layers. If the
data payload were at different offsets for different link layers, then
passing a packet between two link layers would require a <tt class="docutils literal"><span class="pre">memmove(3)</span></tt>
operation (essentially, a copy). Unlike in TinyOS 1.x, where TOS_Msg
as explicitly an active messaging packet, message_t is a more general
-data-link buffer. In practice, most data-link layers in TinyOS 2.x
-provide active messaging, but it is possible for a non-AM stack to
+data-link buffer. In practice, most data-link layers in TinyOS 2.x
+provide active messaging, but it is possible for a non-AM stack to
share message_t with AM stacks.</p>
<p>The header, footer, and metadata formats are all opaque. Source code
cannot access fields directly. Instead, data-link layers provide access
-to fields through nesC interfaces. Section 3 discusses this in
+to fields through nesC interfaces. Section 3 discusses this in
greater depth.</p>
<p>Every link layer defines its header, footer, and metadata
-structures. These structures MUST be external structs (<tt class="docutils literal"><span class="pre">nx_struct</span></tt>),
-and all of their fields MUST be external types (<tt class="docutils literal"><span class="pre">nx_*</span></tt>), for two
+structures. These structures MUST be external structs (<tt class="docutils literal"><span class="pre">nx_struct</span></tt>),
+and all of their fields MUST be external types (<tt class="docutils literal"><span class="pre">nx_*</span></tt>), for two
reasons. First, external types ensure cross-platform compatibility <a class="footnote-reference" href="#id5" id="id2" name="id2">[1]</a>.
-Second, it forces structures to be aligned on byte boundaries,
-circumventing issues with the
+Second, it forces structures to be aligned on byte boundaries,
+circumventing issues with the
alignment of packet buffers and field offsets within them. Metadata fields
must be nx_structs for when complete packets are forwarded to the serial
port in order to log traffic.
looks like this:</p>
<pre class="literal-block">
typedef union message_header {
- cc1000_header_t cc1k;
+ cc1000_header_t cc1k;
serial_header_t serial;
} message_header_t;
message_t fields to be a union of the underlying link layer structures.
This ensures that enough space is allocated for all underlying link layers.</p>
</div>
-<div class="section">
-<h1><a id="the-message-t-fields" name="the-message-t-fields">3. The message_t fields</a></h1>
+<div class="section" id="the-message-t-fields">
+<h1><a name="the-message-t-fields">3. The message_t fields</a></h1>
<p>TinyOS 2.x components treat packets as abstract data types (ADTs),
rather than C structures, obtaining all of the traditional benefits
of this approach. First and foremost, clients of a packet layer
do not depend on particular field names or locations, allowing the
implementations to choose packet formats and make a variety of
optimizations.</p>
-<p>Components above the basic data-link layer MUST always access
-packet fields through interfaces. A component that introduces
-new packet fields SHOULD provide an interface to those that
+<p>Components above the basic data-link layer MUST always access
+packet fields through interfaces. A component that introduces
+new packet fields SHOULD provide an interface to those that
are of interest to other components. These interfaces SHOULD take
the form of get/set operations that take and return values, rather
than offsts into the structure.</p>
-<p>For example, active messages have an interface named <tt class="docutils literal"><span class="pre">AMPacket</span></tt>
-which provides access commands to AM fields. In TinyOS 1.x, a
-component would directly access <tt class="docutils literal"><span class="pre">TOS_Msg.addr</span></tt>; in TinyOS 2.x,
+<p>For example, active messages have an interface named <tt class="docutils literal"><span class="pre">AMPacket</span></tt>
+which provides access commands to AM fields. In TinyOS 1.x, a
+component would directly access <tt class="docutils literal"><span class="pre">TOS_Msg.addr</span></tt>; in TinyOS 2.x,
a component calls <tt class="docutils literal"><span class="pre">AMPacket.getAddress(msg)</span></tt>.
The most basic of these interfaces is Packet, which provides
-access to a packet payload. TEP 116 describes common TinyOS
+access to a packet payload. TEP 116 describes common TinyOS
packet ADT interfaces <a class="footnote-reference" href="#id7" id="id4" name="id4">[3]</a>.</p>
-<p>Link layer components MAY access packet fields differently than other
+<p>Link layer components MAY access packet fields differently than other
components, as they are aware of the actual packet format. They can
therefore implement the interfaces that provide access to the fields
for other components.</p>
-<div class="section">
-<h2><a id="headers" name="headers">3.1 Headers</a></h2>
-<p>The message_t header field is an array of bytes whose size is
+<div class="section" id="headers">
+<h2><a name="headers">3.1 Headers</a></h2>
+<p>The message_t header field is an array of bytes whose size is
the size of a platform's union of data-link headers.
-Because radio stacks often prefer packets to be stored contiguously,
-the layout of a packet in memory does not necessarily reflect the
+Because radio stacks often prefer packets to be stored contiguously,
+the layout of a packet in memory does not necessarily reflect the
layout of its nesC structure.</p>
<p>A packet header MAY start somewhere besides the beginning of
the message_t. For example, consider the Telos platform:</p>
+-----------+-----------------------------+-------+
message_t | header | data | meta |
+-----------+-----------------------------+-------+
-
+
+-----------+------------+ +-------+
CC2420 | header | data | | meta |
+-----------+------------+ +-------+
- +-----+------------+
-Serial | hdr | data |
- +-----+------------+
+ +-----+------------+
+Serial | hdr | data |
+ +-----+------------+
</pre>
<p>Neither the CC2420 nor the serial stack has packet footers, and
the serial stack does not have any metadata.</p>
<p>The packet for a link layer does not necessarily start at the beginning
of the message_t. Instead, it starts at a negative offset from the
-data field. When a link layer component needs to read or write protocol
-header fields, it MUST compute the location of the header as a negative
+data field. When a link layer component needs to read or write protocol
+header fields, it MUST compute the location of the header as a negative
offset from the data field. For example, the serial stack header has
active message fields, such as the AM type. The command that returns
the AM type, <tt class="docutils literal"><span class="pre">AMPacket.type()</span></tt>, looks like this:</p>
<pre class="literal-block">
serial_header_t* getHeader(message_t* msg) {
return (serial_header_t*)(msg->data - sizeof(serial_header_t));
-}
+}
command am_id_t AMPacket.type(message_t* msg) {
- serial_header_t* hdr = getheader(msg);
+ serial_header_t* hdr = getheader(msg);
return hdr->type;
}
</pre>
<pre class="literal-block">
serial_header_t* getHeader(message_t* msg) {
return (serial_header_t*)(msg->header);
-}
+}
</pre>
-<p>In the case of Telos, for example, this would result in a packet
+<p>In the case of Telos, for example, this would result in a packet
layout that looks like this:</p>
<pre class="literal-block">
11 bytes TOSH_DATA_LENGTH 7 bytes
message_t | header | data | meta |
+-----------+-----------------------------+-------+
- +-----+ +------------+
-Serial | hdr | | data |
- +-----+ +------------+
+ +-----+ +------------+
+Serial | hdr | | data |
+ +-----+ +------------+
</pre>
</div>
-<div class="section">
-<h2><a id="data" name="data">3.2 Data</a></h2>
+<div class="section" id="data">
+<h2><a name="data">3.2 Data</a></h2>
<p>The data field of message_t stores the single-hop packet payload.
It is TOSH_DATA_LENGTH bytes long. The default size is 28 bytes.
A TinyOS application can redefine TOSH_DATA_LENGTH at compile time
with a command-line option to ncc: <tt class="docutils literal"><span class="pre">-DTOSH_DATA_LENGTH=x</span></tt>.
Because this value can be reconfigured, it is possible that two
different versions of an application can have different MTU sizes.
-If a packet layer receives a packet whose payload size is
+If a packet layer receives a packet whose payload size is
longer than TOSH_DATA_LENGTH, it MUST discard the packet. As
headers are right justified to the beginning of the data payload,
the data payloads of all link layers on a platform start
at the same fixed offset from the beginning of the message buffer.</p>
</div>
-<div class="section">
-<h2><a id="footer" name="footer">3.3 Footer</a></h2>
+<div class="section" id="footer">
+<h2><a name="footer">3.3 Footer</a></h2>
<p>The message_footer_t field ensures that message_t has enough space to
store the footers for all underlying link layers when there are
MTU-sized packets. Like headers, footers are not necessarily stored
contiguously with the data region. For short packets, this can mean
that the footer will actually be stored in the data field.</p>
</div>
-<div class="section">
-<h2><a id="metadata" name="metadata">3.4 Metadata</a></h2>
-<p>The metadata field of message_t stores data that
-a single-hop stack uses or collects does not transmit.
-This mechanism allows packet layers to store per-packet
+<div class="section" id="metadata">
+<h2><a name="metadata">3.4 Metadata</a></h2>
+<p>The metadata field of message_t stores data that
+a single-hop stack uses or collects does not transmit.
+This mechanism allows packet layers to store per-packet
information such as RSSI or timestamps. For example, this is
the CC2420 metadata structure:</p>
<pre class="literal-block">
} cc2420_metadata_t;
</pre>
</div>
-<div class="section">
-<h2><a id="variable-sized-structures" name="variable-sized-structures">3.5 Variable Sized Structures</a></h2>
+<div class="section" id="variable-sized-structures">
+<h2><a name="variable-sized-structures">3.5 Variable Sized Structures</a></h2>
<p>The message_t structure is optimized for packets with fixed-size
headers and footers. Variable-sized footers are generally easy
to implement. Variable-sized headers are a bit more difficult.
the data region, but assuming a byte-based send path this merely
requires adjusting the index.</p>
<p>If the underlying link hardware is packet-based, then the
-protocol stack can either include metadata (e.g., in the
+protocol stack can either include metadata (e.g., in the
metadata structure) stating where the header begins or it
can place the header at a fixed position and use <tt class="docutils literal"><span class="pre">memmove(3)</span></tt>
on reception and transmit. In this latter case, on
reception the packet is continguously read into the message_t
beginning at the offset of the header structure. Once the
packet is completely received, the header can be decoded,
-its length calculated, and the data region of the packet
+its length calculated, and the data region of the packet
can be moved to the <tt class="docutils literal"><span class="pre">data</span></tt> field. On transmission,
the opposite occurs: the data region (and footer if need
be) are moved to be contiguous with the header. Note that
copy at the botttom layer.</p>
</div>
</div>
-<div class="section">
-<h1><a id="implementation" name="implementation">4. Implementation</a></h1>
-<p>The definition of message_t can be found in
+<div class="section" id="implementation">
+<h1><a name="implementation">4. Implementation</a></h1>
+<p>The definition of message_t can be found in
<tt class="docutils literal"><span class="pre">tinyos-2.x/tos/types/message.h</span></tt>.</p>
<p>The definition of the CC2420
message format can be found in <tt class="docutils literal"><span class="pre">tinyos-2.x/tos/chips/cc2420/CC2420.h</span></tt>.</p>
-<p>The defintion of the CC1000 message format can be found in
+<p>The defintion of the CC1000 message format can be found in
<tt class="docutils literal"><span class="pre">tinyos-2.x/tos/chips/cc1000/CC1000Msg.h</span></tt>.</p>
<p>The definition
of the standard serial stack packet format can be found in
<tt class="docutils literal"><span class="pre">tinyos-2.x/tos/lib/serial/Serial.h</span></tt></p>
<p>The definition of
-the telos family packet format can be found in
+the telos family packet format can be found in
<tt class="docutils literal"><span class="pre">tinyos-2.x/tos/platform/telosa/platform_message.h</span></tt> and the micaz format can be found in
<tt class="docutils literal"><span class="pre">tinyos-2.x/tos/platforms/micaz/platform_message.h</span></tt>.</p>
</div>
-<div class="section">
-<h1><a id="author-s-address" name="author-s-address">5. Author's Address</a></h1>
+<div class="section" id="author-s-address">
+<h1><a name="author-s-address">5. Author's Address</a></h1>
<div class="line-block">
<div class="line">Philip Levis</div>
<div class="line">358 Gates Hall</div>
<div class="line">email - <a class="reference" href="mailto:pal@cs.stanford.edu">pal@cs.stanford.edu</a></div>
</div>
</div>
-<div class="section">
-<h1><a id="citations" name="citations">6. Citations</a></h1>
+<div class="section" id="citations">
+<h1><a name="citations">6. Citations</a></h1>
<table class="docutils footnote" frame="void" id="id5" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.3.6: http://docutils.sourceforge.net/" />
<title>Microcontroller Power Management</title>
<meta name="author" content="Robert Szewczyk, Philip Levis, Martin Turon, Lama Nachman, Philip Buonadonna, Vlado Handziski" />
<style type="text/css">
</style>
</head>
<body>
-<div class="document" id="microcontroller-power-management">
<h1 class="title">Microcontroller Power Management</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<td>Robert Szewczyk, Philip Levis, Martin Turon, Lama Nachman, Philip Buonadonna, Vlado Handziski</td></tr>
<tr class="field"><th class="docinfo-name">Draft-Created:</th><td class="field-body">19-Sep-2005</td>
</tr>
-<tr class="field"><th class="docinfo-name">Draft-Version:</th><td class="field-body">1.6</td>
+<tr class="field"><th class="docinfo-name">Draft-Version:</th><td class="field-body">1.7</td>
</tr>
-<tr class="field"><th class="docinfo-name">Draft-Modified:</th><td class="field-body">2006-12-20</td>
+<tr class="field"><th class="docinfo-name">Draft-Modified:</th><td class="field-body">2007-01-10</td>
</tr>
<tr class="field"><th class="docinfo-name">Draft-Discuss:</th><td class="field-body">TinyOS Developer List <tinyos-devel at mail.millennium.berkeley.edu></td>
</tr>
</tbody>
</table>
+<div class="document" id="microcontroller-power-management">
<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
of this memo is unlimited. This memo is in full compliance with
TEP 1.</p>
</div>
-<div class="section">
-<h1><a id="abstract" name="abstract">Abstract</a></h1>
+<div class="section" id="abstract">
+<h1><a name="abstract">Abstract</a></h1>
<p>This memo documents how TinyOS manages the lower power state of a
microcontroller.</p>
</div>
-<div class="section">
-<h1><a id="introduction" name="introduction">1. Introduction</a></h1>
+<div class="section" id="introduction">
+<h1><a name="introduction">1. Introduction</a></h1>
<p>Microcontrollers often have several power states, with varying power
draws, wakeup latencies, and peripheral support. The microcontroller
should always be in the lowest possible power state that can satisfy
and how they work, as well as the basics of subsystem power
management.</p>
</div>
-<div class="section">
-<h1><a id="background" name="background">2. Background</a></h1>
+<div class="section" id="background">
+<h1><a name="background">2. Background</a></h1>
<p>The TinyOS scheduler[<a class="reference" href="#id3">2</a>] puts a processor into a sleep state when
the task queue is empty. However, processors can have a spectrum of
power states. For example, the MSP430 has one active mode (issuing
requirements, which it considers when calculating the right low power
state.</p>
</div>
-<div class="section">
-<h1><a id="id1" name="id1">3. Microcontroller Power Management</a></h1>
+<div class="section" id="id1">
+<h1><a name="id1">3. Microcontroller Power Management</a></h1>
<p>TinyOS 2.x uses three basic mechanisms to manage and control
microcontroller power states: a dirty bit, a chip-specific low power
state calculation function, and a power state override function. The
</div>
<p>McuSleepC MAY have additional interfaces.</p>
</div>
-<div class="section">
-<h1><a id="the-dirty-bit" name="the-dirty-bit">3.1 The Dirty Bit</a></h1>
+<div class="section" id="the-dirty-bit">
+<h1><a name="the-dirty-bit">3.1 The Dirty Bit</a></h1>
<p>Whenever a Hardware Presentation Layer (HPL, see TEP 2: Hardware
Abstraction Architecture[<a class="reference" href="#id2">1</a>]) component changes an aspect of
hardware configuration that might change the possible low power state
low power state before the next time it goes to sleep as a result of
McuSleep.sleep() being called.</p>
</div>
-<div class="section">
-<h1><a id="low-power-state-calculation" name="low-power-state-calculation">3.2 Low Power State Calculation</a></h1>
+<div class="section" id="low-power-state-calculation">
+<h1><a name="low-power-state-calculation">3.2 Low Power State Calculation</a></h1>
<p>McuSleepC is responsible for calculating the lowest power state that
it can safely put the microcontroller into without disrupting the
operation of TinyOS subsystems. McuSleepC SHOULD minimize how often it
</tbody>
</table>
</div>
-<div class="section">
-<h1><a id="power-state-override" name="power-state-override">3.3 Power State Override</a></h1>
+<div class="section" id="power-state-override">
+<h1><a name="power-state-override">3.3 Power State Override</a></h1>
<p>When McuSleepC computes the best low power state, it MUST call
<tt class="docutils literal"><span class="pre">PowerOverride.lowestState().</span></tt> McuSleepC SHOULD have a default
implementation of this command, which returns the lowest power state
<p>Section 5 describes one example use of McuPowerOverride, in the
timer stack for the Atmega128 microcontroller family.</p>
</div>
-<div class="section">
-<h1><a id="peripherals-and-subsystems" name="peripherals-and-subsystems">4. Peripherals and Subsystems</a></h1>
+<div class="section" id="peripherals-and-subsystems">
+<h1><a name="peripherals-and-subsystems">4. Peripherals and Subsystems</a></h1>
<p>At the HIL level, TinyOS subsystems generally have a simple,
imperative power management interface. Depending on the latencies
involved, this interface is either <tt class="docutils literal"><span class="pre">StdControl</span></tt>, <tt class="docutils literal"><span class="pre">SplitControl</span></tt>,
disabled). Following the requirements in 3.1, the MCU power management
subsystem will be notified of a significant change and act
appropriately when the system next goes to sleep. TEP 115[<a class="reference" href="#id6">5</a>]
-describes the power management of non-virtualized devices in
+describes the power management of non-virtualized devices in
greater detail, and TEP 108[<a class="reference" href="#id5">4</a>] describes how TinyOS can automatically
include power management into shared non-virtualized devices.</p>
</div>
-<div class="section">
-<h1><a id="implementation" name="implementation">5. Implementation</a></h1>
-<p>An implementation of McuSleepC can be found in <tt class="docutils literal"><span class="pre">tinyos-2.x/tos/chips/atm128</span></tt>,
+<div class="section" id="implementation">
+<h1><a name="implementation">5. Implementation</a></h1>
+<p>An implementation of McuSleepC can be found in <tt class="docutils literal"><span class="pre">tinyos-2.x/tos/chips/atm128</span></tt>,
<tt class="docutils literal"><span class="pre">tinyos-2.x/tos/chips/msp430</span></tt>, and <tt class="docutils literal"><span class="pre">tinyos-2.x/tos/chips/px27ax</span></tt>.</p>
<p>An example of a use of McuPowerOverride can be found in the atmega128 timer
system. Because some low-power states have much longer wakeup latencies than
others, the timer system does not allow long latencies if it has a timer
-that is going to fire soon. The implementation can be found in
+that is going to fire soon. The implementation can be found in
<tt class="docutils literal"><span class="pre">tinyos-2.x/tos/chips/atm128/timer/HplAtm128Timer0AsyncP.nc</span></tt>, and
<tt class="docutils literal"><span class="pre">tinyos-2.x/tos/chips/atm128/timer/HplAtm128Timer0AsyncC.nc</span></tt> automatically
wires it to McuSleepC if it is included.</p>
</div>
-<div class="section">
-<h1><a id="author-s-address" name="author-s-address">6. Author's Address</a></h1>
+<div class="section" id="author-s-address">
+<h1><a name="author-s-address">6. Author's Address</a></h1>
<div class="line-block">
<div class="line">Robert Szewczyk</div>
<div class="line">Moteiv Corporation</div>
<div class="line"><br /></div>
</div>
</div>
-<div class="section">
-<h1><a id="citations" name="citations">6. Citations</a></h1>
+<div class="section" id="citations">
+<h1><a name="citations">6. Citations</a></h1>
<table class="docutils footnote" frame="void" id="id2" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.3.6: http://docutils.sourceforge.net/" />
<title>Serial Communication</title>
<meta name="author" content="Ben Greenstein and Philip Levis" />
<style type="text/css">
</style>
</head>
<body>
-<div class="document" id="serial-communication">
<h1 class="title">Serial Communication</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
</tr>
</tbody>
</table>
+<div class="document" id="serial-communication">
<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
of this memo is unlimited. This memo is in full compliance with
TEP 1.</p>
</div>
-<div class="section">
-<h1><a id="abstract" name="abstract">Abstract</a></h1>
+<div class="section" id="abstract">
+<h1><a name="abstract">Abstract</a></h1>
<p>This memo describes the structure and standard implementation of the
TinyOS 2.x serial communication system for mote-to-PC data
exchange. The system is broken into three levels (encoding, framing,
the supported packet formats is platform independent, so PC-side
applications can communicate with arbitrary motes.</p>
</div>
-<div class="section">
-<h1><a id="introduction" name="introduction">1. Introduction</a></h1>
+<div class="section" id="introduction">
+<h1><a name="introduction">1. Introduction</a></h1>
<p>Users need to read data out of a TinyOS network. The most common
approach is to attach a mote to a PC or laptop with a wired
connection. While the interface on the PC side can vary from a serial
PC toolchain. This memo documents the protocols and structure of the
TinyOS 2.x serial communication stack.</p>
</div>
-<div class="section">
-<h1><a id="serial-stack-structure" name="serial-stack-structure">2. Serial Stack Structure</a></h1>
+<div class="section" id="serial-stack-structure">
+<h1><a name="serial-stack-structure">2. Serial Stack Structure</a></h1>
<p>The TinyOS 2.x serial communication stack is broken up into four
functional components. From bottom to top, they are</p>
<blockquote>
</blockquote>
<p>Structurally, they look like this:</p>
<pre class="literal-block">
- _____________________
-| |
+ _____________________
+| |
| Dispatcher | Packet formatting.
-|_____________________|
- _____________________
-| |
+|_____________________|
+ _____________________
+| |
| Protocol | Acknowledgements, CRC computation,
|_____________________| windowing.
- _____________________
-| |
+ _____________________
+| |
| Encoder/Framer | Translating raw bytes into frame
|_____________________| delimiters, escape bytes.
- _____________________
-| |
+ _____________________
+| |
| Raw UART | Platform code for reading/writing
|_____________________| bytes over the serial connection.
</pre>
3.4 describes how the default TinyOS 2.x implementation,
<tt class="docutils literal"><span class="pre">SerialDispatcherC</span></tt> does this.</p>
</div>
-<div class="section">
-<h1><a id="the-2-x-serial-stack-implementation" name="the-2-x-serial-stack-implementation">3. The 2.x Serial Stack Implementation</a></h1>
+<div class="section" id="the-2-x-serial-stack-implementation">
+<h1><a name="the-2-x-serial-stack-implementation">3. The 2.x Serial Stack Implementation</a></h1>
<p>Section 2 describes the basic structure of the TinyOS 2.x serial
stack. This section describes its actual implementation,
including SerialActiveMessageC, which sits on top of the Dispatcher.
All of the components except for UartC are part of the serial
library that lives in <tt class="docutils literal"><span class="pre">tos/lib/serial</span></tt>.</p>
-<div class="section">
-<h2><a id="raw-uart-uartc" name="raw-uart-uartc">3.1 Raw UART: UartC</a></h2>
+<div class="section" id="raw-uart-uartc">
+<h2><a name="raw-uart-uartc">3.1 Raw UART: UartC</a></h2>
<p>The UART HIL[<a class="reference" href="#tep2">TEP2</a>] is <tt class="docutils literal"><span class="pre">UartC</span></tt>, which provides a byte-level
interface to the underlying serial communication. It provides the
<tt class="docutils literal"><span class="pre">SerialByteComm</span></tt> interface:</p>
<p>It may provide additional interfaces for configuring the serial
port. This TEP does not consider this topic.</p>
</div>
-<div class="section">
-<h2><a id="encoder-framer-hdlctranslatec" name="encoder-framer-hdlctranslatec">3.2 Encoder/Framer: HdlcTranslateC</a></h2>
+<div class="section" id="encoder-framer-hdlctranslatec">
+<h2><a name="encoder-framer-hdlctranslatec">3.2 Encoder/Framer: HdlcTranslateC</a></h2>
<p>HdlcTranslateC is the serial encoder/framer. It uses the
<tt class="docutils literal"><span class="pre">SerialByteComm</span></tt> interface and provides the <tt class="docutils literal"><span class="pre">SerialFrameComm</span></tt>
interface:</p>
and sends an escape byte. When the escape byte is sent, it sends the
stored data byte.</p>
</div>
-<div class="section">
-<h2><a id="protocol-serialp" name="protocol-serialp">3.3 Protocol: SerialP</a></h2>
+<div class="section" id="protocol-serialp">
+<h2><a name="protocol-serialp">3.3 Protocol: SerialP</a></h2>
<p>The SerialP component implements the serial protocol using PPP/HDLC-
like framing (See RFC 1662[<a class="reference" href="#rfc1662">RFC1662</a>]). Type dispatch and buffer
management are left to higher layers in the serial stack. The protocol
be transmitted may begin spooling into SerialP while SerialP is
actively sending an acknowledgement.</p>
</div>
-<div class="section">
-<h2><a id="dispatcher-serialdispatcherc" name="dispatcher-serialdispatcherc">3.4 Dispatcher: SerialDispatcherC</a></h2>
+<div class="section" id="dispatcher-serialdispatcherc">
+<h2><a name="dispatcher-serialdispatcherc">3.4 Dispatcher: SerialDispatcherC</a></h2>
<p>SerialDispatcherC handles the data packets that the Protocol component
receives. It uses the SendBytePacket and ReceiveBytePacket interfaces,
and provides parameterized Send and Receive interfaces. The parameter
<tt class="docutils literal"><span class="pre">TOS_SERIAL_UNKNOWN_ID</span></tt> are reserved. New packet formats MUST NOT
reuse any reserved identifiers.</p>
</div>
-<div class="section">
-<h2><a id="serialactivemessagec" name="serialactivemessagec">3.5 SerialActiveMessageC</a></h2>
+<div class="section" id="serialactivemessagec">
+<h2><a name="serialactivemessagec">3.5 SerialActiveMessageC</a></h2>
<p>SerialActiveMessageC is a platform-independent active message layer
that operates on top of the serial communication
stack. SerialActiveMessageC is a configuration that wires
implementation {
components new SerialActiveMessageP() as AM, SerialDispatcherC;
components SerialPacketInfoActiveMessageP as Info;
-
+
Init = SerialDispatcherC;
Leds = SerialDispatcherC;
-
+
AMSend = AM;
Receive = AM;
Packet = AM;
AMPacket = AM;
-
+
AM.SubSend -> SerialDispatcherC.Send[TOS_SERIAL_ACTIVE_MESSAGE_ID];
AM.SubReceive -> SerialDispatcherC.Receive[TOS_SERIAL_ACTIVE_MESSAGE_ID];
-
+
SerialDispatcherC.SerialPacketInfo[TOS_SERIAL_ACTIVE_MESSAGE_ID] -> Info;
}
</pre>
} SerialAMHeader;
</pre>
</div>
-<div class="section">
-<h2><a id="packet-format" name="packet-format">3.6 Packet Format</a></h2>
+<div class="section" id="packet-format">
+<h2><a name="packet-format">3.6 Packet Format</a></h2>
<p>A data packet in the TinyOS 2.x serial stack has the following format
over the wire. Each protocol field is associated with a specific component:</p>
<pre class="literal-block">
____________________________________________
| | | | | | | |
- | | | | | | | |
+ | | | | | | | |
|_|_|_|_|_______________________________|__|_|
F P S D Payload CR F
-
+
F = Framing byte, denoting start of packet: HdlcTranslateC
P = Protocol byte: SerialP
S = Sequence number byte: SerialP
(P) is 0x40 (64), corresponding to <tt class="docutils literal"><span class="pre">SERIAL_PROTO_ACK</span></tt> (in Serial.h).</p>
</div>
</div>
-<div class="section">
-<h1><a id="access-abstractions" name="access-abstractions">4. Access Abstractions</a></h1>
+<div class="section" id="access-abstractions">
+<h1><a name="access-abstractions">4. Access Abstractions</a></h1>
<p>Two generic components: SerialAMSenderC and SerialAMReceiverC connect
to SerialActiveMessageC to provide virtualized access to the serial
stack. Each instantiation of SerialAMSenderC has its own queue of
services in the TEP 116, the serial component virtualizations provide
no snooping capabilities.</p>
</div>
-<div class="section">
-<h1><a id="author-s-address" name="author-s-address">5. Author's Address</a></h1>
+<div class="section" id="author-s-address">
+<h1><a name="author-s-address">5. Author's Address</a></h1>
<div class="line-block">
<div class="line">Philip Levis</div>
<div class="line">358 Gates</div>
<div class="line">email - <a class="reference" href="mailto:benjamin.m.greenstein@intel.com">benjamin.m.greenstein@intel.com</a></div>
</div>
</div>
-<div class="section">
-<h1><a id="citations" name="citations">6. Citations</a></h1>
+<div class="section" id="citations">
+<h1><a name="citations">6. Citations</a></h1>
<table class="docutils citation" frame="void" id="tep2" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.3.6: http://docutils.sourceforge.net/" />
<title>SIDs: Source and Sink Independent Drivers</title>
<meta name="author" content="Gilman Tolle, Philip Levis, and David Gay" />
<style type="text/css">
</style>
</head>
<body>
-<div class="document" id="sids-source-and-sink-independent-drivers">
<h1 class="title">SIDs: Source and Sink Independent Drivers</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<td>Gilman Tolle, Philip Levis, and David Gay</td></tr>
<tr class="field"><th class="docinfo-name">Draft-Created:</th><td class="field-body">30-Oct-2005</td>
</tr>
-<tr class="field"><th class="docinfo-name">Draft-Version:</th><td class="field-body">1.6</td>
+<tr class="field"><th class="docinfo-name">Draft-Version:</th><td class="field-body">1.7</td>
</tr>
-<tr class="field"><th class="docinfo-name">Draft-Modified:</th><td class="field-body">2006-12-12</td>
+<tr class="field"><th class="docinfo-name">Draft-Modified:</th><td class="field-body">2007-01-10</td>
</tr>
<tr class="field"><th class="docinfo-name">Draft-Discuss:</th><td class="field-body">TinyOS Developer List <tinyos-devel at mail.millennium.berkeley.edu></td>
</tr>
</tbody>
</table>
+<div class="document" id="sids-source-and-sink-independent-drivers">
<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
of this memo is unlimited. This memo is in full compliance with
TEP 1.</p>
</div>
-<div class="section">
-<h1><a id="abstract" name="abstract">Abstract</a></h1>
-<p>This memo documents a set of hardware- and sensor-independent interfaces
+<div class="section" id="abstract">
+<h1><a name="abstract">Abstract</a></h1>
+<p>This memo documents a set of hardware- and sensor-independent interfaces
for data sources and sinks in TinyOS 2.x.</p>
</div>
-<div class="section">
-<h1><a id="introduction" name="introduction">1. Introduction</a></h1>
+<div class="section" id="introduction">
+<h1><a name="introduction">1. Introduction</a></h1>
<p>Sensing is an integral part of any sensor network application. Having
a wide variety of sensor interfaces usually does not impose a large
burden on an application developer, as any given application uses a
therefore has telescoping sensor abstractions, providing both simple
and sensor-independent as well as sensor-specific interfaces.</p>
</div>
-<div class="section">
-<h1><a id="sensors-in-tinyos-1-x" name="sensors-in-tinyos-1-x">2. Sensors in TinyOS 1.x</a></h1>
+<div class="section" id="sensors-in-tinyos-1-x">
+<h1><a name="sensors-in-tinyos-1-x">2. Sensors in TinyOS 1.x</a></h1>
<p>Early TinyOS sensors were generally analog. To sample one of these
sensors, an application makes an analog-to-digital conversion using
the MCU ADC. Because all early sensors required ADC conversions, the
and common interfaces for basic and portable use. Providing a
telescoping sensor abstraction allows both classes of use.</p>
</div>
-<div class="section">
-<h1><a id="sensors-in-tinyos-2-x" name="sensors-in-tinyos-2-x">3. Sensors in TinyOS 2.x</a></h1>
+<div class="section" id="sensors-in-tinyos-2-x">
+<h1><a name="sensors-in-tinyos-2-x">3. Sensors in TinyOS 2.x</a></h1>
<p>TinyOS 2.x has several sensor-independent interfaces, which cover a
range of common use cases. These interfaces can be used to write a
Source- or Sink-Independent Driver (SID). A SID is source/sink
information on the sort of sensor or device they sit on top of. A SID
SHOULD provide one or more of the interfaces described in this
section, depending on its expected uses and underlying data model.</p>
-<div class="section">
-<h2><a id="split-phase-small-scalar-i-o" name="split-phase-small-scalar-i-o">3.1 Split-Phase Small Scalar I/O</a></h2>
+<div class="section" id="split-phase-small-scalar-i-o">
+<h2><a name="split-phase-small-scalar-i-o">3.1 Split-Phase Small Scalar I/O</a></h2>
<p>The first set of interfaces can be used for low-rate scalar I/O:</p>
<pre class="literal-block">
interface Read<val_t> {
include many basic sensors, such as photo, temp, voltage, and ADC
readings.</p>
</div>
-<div class="section">
-<h2><a id="split-phase-large-scalar-i-o" name="split-phase-large-scalar-i-o">3.2 Split-Phase Large Scalar I/O</a></h2>
+<div class="section" id="split-phase-large-scalar-i-o">
+<h2><a name="split-phase-large-scalar-i-o">3.2 Split-Phase Large Scalar I/O</a></h2>
<p>If the SID's data object is too big to be passed efficienctly on the
stack, it can provide read/write interfaces that pass parameters by
pointer rather than value:</p>
<tt class="docutils literal"><span class="pre">val</span></tt> parameter points to MUST be filled with zeroes.</p>
<p>Examples of sensors that are suited to this set of interfaces include
those that generate multiple simultaneous readings for which
-passing by value is inefficient, such as a two-axis digital
+passing by value is inefficient, such as a two-axis digital
accelerometer.</p>
</div>
-<div class="section">
-<h2><a id="single-phase-scalar-i-o" name="single-phase-scalar-i-o">3.4 Single-Phase Scalar I/O</a></h2>
+<div class="section" id="single-phase-scalar-i-o">
+<h2><a name="single-phase-scalar-i-o">3.4 Single-Phase Scalar I/O</a></h2>
<p>Some devices may have their state cached or readily available. In
these cases, the device can provide a single-phase instead of
split-phase operation. Examples include a node's MAC address (which
}
</pre>
</div>
-<div class="section">
-<h2><a id="notification-based-scalar-i-o" name="notification-based-scalar-i-o">3.5 Notification-Based Scalar I/O</a></h2>
+<div class="section" id="notification-based-scalar-i-o">
+<h2><a name="notification-based-scalar-i-o">3.5 Notification-Based Scalar I/O</a></h2>
<p>Some sensor devices represent triggers, rather than request-driven
data acquisition. Examples of such sensors include switches,
passive-IR (PIR) motion sensors, tone detectors, and smoke
remain enabled.</p>
<p>The val parameter is used as defined in the Read interface.</p>
</div>
-<div class="section">
-<h2><a id="split-phase-streaming-i-o" name="split-phase-streaming-i-o">3.7 Split-Phase Streaming I/O</a></h2>
+<div class="section" id="split-phase-streaming-i-o">
+<h2><a name="split-phase-streaming-i-o">3.7 Split-Phase Streaming I/O</a></h2>
<p>Some sensors can provide a continuous stream of readings, and some
actuators can accept a continuous stream of new data. Depending on the
rate needed and jitter bounds that higher level components can
command error_t read( uint32_t usPeriod );
- event void bufferDone( error_t result,
+ event void bufferDone( error_t result,
val_t* buf, uint16_t count );
event void readDone( error_t result );
-}
+}
</pre>
<p>The postBuffer command takes an array parameterized by the sample
type, and the number of entries in that buffer. A driver can then
command error_t write( uint32_t period );
- event void bufferDone( error_t result,
+ event void bufferDone( error_t result,
val_t* buf, uint16_t count );
event void writeDone( error_t result );
for the ReadStream interface, as are write() and writeDone().</p>
</div>
</div>
-<div class="section">
-<h1><a id="summary" name="summary">4. Summary</a></h1>
+<div class="section" id="summary">
+<h1><a name="summary">4. Summary</a></h1>
<p>According to the design principles described in the HAA[_haa], authors
should write device drivers that provide rich, device-specific
interfaces that expose the full capabilities of each device. In
who only need simple interfaces, and can reduce the effort needed to
connect a sensor into a more general system.</p>
</div>
-<div class="section">
-<h1><a id="author-s-address" name="author-s-address">5. Author's Address</a></h1>
+<div class="section" id="author-s-address">
+<h1><a name="author-s-address">5. Author's Address</a></h1>
<div class="line-block">
<div class="line">Gilman Tolle</div>
<div class="line">2168 Shattuck Ave.</div>
<div class="line"><br /></div>
</div>
</div>
-<div class="section">
-<h1><a id="citations" name="citations">6. Citations</a></h1>
+<div class="section" id="citations">
+<h1><a name="citations">6. Citations</a></h1>
<table class="docutils footnote" frame="void" id="id2" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.3.6: http://docutils.sourceforge.net/" />
<title>Power Management of Non-Virtualised Devices</title>
<meta name="author" content="Kevin Klues, Vlado Handziski, Jan-Hinrich Hauer, Phil Levis" />
<style type="text/css">
</style>
</head>
<body>
-<div class="document" id="power-management-of-non-virtualised-devices">
<h1 class="title">Power Management of Non-Virtualised Devices</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
</tr>
<tr class="field"><th class="docinfo-name">Draft-Modified:</th><td class="field-body">2007-02-21</td>
</tr>
-<tr class="field"><th class="docinfo-name">Draft-Discuss:</th><td class="field-body">TinyOS Developer List
+<tr class="field"><th class="docinfo-name">Draft-Discuss:</th><td class="field-body">TinyOS Developer List
<tinyos-devel at mail.millennium.berkeley.edu></td>
</tr>
</tbody>
</table>
+<div class="document" id="power-management-of-non-virtualised-devices">
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">This memo documents a part of TinyOS for the TinyOS Community, and
of this memo is unlimited. This memo is in full compliance with TEP
1.</p>
</div>
-<div class="section">
-<h1><a id="abstract" name="abstract">Abstract</a></h1>
+<div class="section" id="abstract">
+<h1><a name="abstract">Abstract</a></h1>
<p>This memo documents how TinyOS 2.x manages the power state of physical
(not virtualised) abstractions.</p>
</div>
-<div class="section">
-<h1><a id="introduction" name="introduction">1. Introduction</a></h1>
+<div class="section" id="introduction">
+<h1><a name="introduction">1. Introduction</a></h1>
<p>TinyOS platforms have limited energy. A unified power management
strategy for all devices and peripherpals is not feasible, as
they vary significantly in warm-up times, power profiles, and
devices are not virtualised in the sense that access to
them must be explicitly requested and released by their users.</p>
</div>
-<div class="section">
-<h1><a id="power-management-models" name="power-management-models">2. Power Management Models</a></h1>
+<div class="section" id="power-management-models">
+<h1><a name="power-management-models">2. Power Management Models</a></h1>
<p>There are two different models to managing the power state of a
peripheral in TinyOS: <em>explicit power management</em> and <em>implicit
power management</em>.</p>
clients. For example, when a client requests the ADC, this implies
the ADC should be on; if there are no requests of the ADC, this implies
it should be off. Therefore shared devices do not need to provide a
-power control interface. They can use an implicit power management policy.
+power control interface. They can use an implicit power management policy.
Section 4.2 discusses this in more detail.:</p>
<pre class="literal-block">
/|\ /|\
| |
Data Interface Resource
- | |
+ | |
-----------------------------------------------------------------------
| Shared Device (implicitly power managed) |
-----------------------------------------------------------------------
--------------------------------- --------------------------------
</pre>
</div>
-<div class="section">
-<h1><a id="explicit-power-management" name="explicit-power-management">3. Explicit Power Management</a></h1>
+<div class="section" id="explicit-power-management">
+<h1><a name="explicit-power-management">3. Explicit Power Management</a></h1>
<p>Just as in TinyOS 1.x, TinyOS 2.x has <tt class="docutils literal"><span class="pre">StdControl</span></tt> and <tt class="docutils literal"><span class="pre">SplitControl</span></tt>
interfaces in order to control the on and off
power states of explicitly managed peripherals. TinyOS 2.x also
latencies involved in changing between these two states as well as the
nature of the code (sync or async) executing any of the interfaces
commands.</p>
-<div class="section">
-<h2><a id="power-management-with-stdcontrol" name="power-management-with-stdcontrol">3.1 Power Management with <tt class="docutils literal"><span class="pre">StdControl</span></tt></a></h2>
+<div class="section" id="power-management-with-stdcontrol">
+<h2><a name="power-management-with-stdcontrol">3.1 Power Management with <tt class="docutils literal"><span class="pre">StdControl</span></tt></a></h2>
<p>Whenever the powerup and powerdown times of a non-virtualised device
-are negligible, they SHOULD provide the <tt class="docutils literal"><span class="pre">StdControl</span></tt> interface as
+are negligible, they SHOULD provide the <tt class="docutils literal"><span class="pre">StdControl</span></tt> interface as
defined below:</p>
<pre class="literal-block">
interface StdControl {
device MUST be completely powered on, allowing calls to commands of other
interfaces implemented by the device to succeed.</p>
<p>Upon the successful return of a call to <tt class="docutils literal"><span class="pre">StdControl.stop()</span></tt>, a
-device MUST be completely powered down, and any calls to commands
+device MUST be completely powered down, and any calls to commands
of other interfaces implemented by that device MUST return FAIL or EOFF.</p>
<p>If a device is not able to complete the <tt class="docutils literal"><span class="pre">StdControl.start()</span></tt> or
<tt class="docutils literal"><span class="pre">StdControl.stop()</span></tt> request for any reason, it MUST return FAIL.</p>
<col width="31%" />
</colgroup>
<thead valign="bottom">
-<tr><th class="head">Call</th>
-<th class="head">Device On</th>
-<th class="head">Device Off</th>
+<tr><th>Call</th>
+<th>Device On</th>
+<th>Device Off</th>
</tr>
</thead>
<tbody valign="top">
}
</pre>
</div>
-<div class="section">
-<h2><a id="power-management-with-splitcontrol" name="power-management-with-splitcontrol">3.2 Power Management with <tt class="docutils literal"><span class="pre">SplitControl</span></tt></a></h2>
+<div class="section" id="power-management-with-splitcontrol">
+<h2><a name="power-management-with-splitcontrol">3.2 Power Management with <tt class="docutils literal"><span class="pre">SplitControl</span></tt></a></h2>
<p>When a device's powerup and powerdown times are non-negligible, the
<em>``SplitControl``</em> interface MUST be used in place of the <em>``StdControl``</em>
interface. The definition of this interface can be seen below:</p>
<p>Successful calls to <tt class="docutils literal"><span class="pre">SplitControl.stop()</span></tt> MUST signal one of
<tt class="docutils literal"><span class="pre">SplitControl.stopDone(SUCCESS)</span></tt> or <tt class="docutils literal"><span class="pre">SplitControl.stopDone(FAIL)</span></tt>.</p>
<p>Upon signaling a <tt class="docutils literal"><span class="pre">SplitControl.startDone(SUCCESS)</span></tt>, a device MUST
-be completely powered on, and operation requests through calls to commands
+be completely powered on, and operation requests through calls to commands
of other interfaces implemented by the device MAY succeed.</p>
-<p>Upon signalling a <tt class="docutils literal"><span class="pre">SplitControl.stopDone(SUCCESS)</span></tt>, a device MUST be
-completely powered down, and any subsequent calls to commands of other
+<p>Upon signalling a <tt class="docutils literal"><span class="pre">SplitControl.stopDone(SUCCESS)</span></tt>, a device MUST be
+completely powered down, and any subsequent calls to commands of other
interfaces implemented by the device MUST return EOFF or FAIL.</p>
<p>If a device is powered on and a successful call to <tt class="docutils literal"><span class="pre">SplitControl.stop()</span></tt>
-signals a <tt class="docutils literal"><span class="pre">SplitControl.stopDone(FAIL)</span></tt>, the device MUST still be fully
-powered on, and operation requests through calls to commands of other
+signals a <tt class="docutils literal"><span class="pre">SplitControl.stopDone(FAIL)</span></tt>, the device MUST still be fully
+powered on, and operation requests through calls to commands of other
interfaces implemented by the device MAY succeed.</p>
-<p>If a device is powered down and a successful call to <tt class="docutils literal"><span class="pre">SplitControl.start()</span></tt>
-signals a <tt class="docutils literal"><span class="pre">SplitControl.startDone(FAIL)</span></tt>, the device MUST still be fully
-powered down, and operation requests through calls to commands of other
+<p>If a device is powered down and a successful call to <tt class="docutils literal"><span class="pre">SplitControl.start()</span></tt>
+signals a <tt class="docutils literal"><span class="pre">SplitControl.startDone(FAIL)</span></tt>, the device MUST still be fully
+powered down, and operation requests through calls to commands of other
interfaces implemented by the device MUST return EOFF or FAIL.</p>
<p>If a device is not able to complete the <tt class="docutils literal"><span class="pre">SplitControl.start()</span></tt> or
<tt class="docutils literal"><span class="pre">SplitControl.stop()</span></tt> requests they MUST return FAIL.</p>
<col width="15%" />
</colgroup>
<thead valign="bottom">
-<tr><th class="head">Call</th>
-<th class="head">Device On</th>
-<th class="head">Device Off</th>
-<th class="head">Starting</th>
-<th class="head">Stopping</th>
+<tr><th>Call</th>
+<th>Device On</th>
+<th>Device Off</th>
+<th>Starting</th>
+<th>Stopping</th>
</tr>
</thead>
<tbody valign="top">
}
</pre>
</div>
-<div class="section">
-<h2><a id="power-management-with-asyncstdcontrol" name="power-management-with-asyncstdcontrol">3.3 Power Management with <tt class="docutils literal"><span class="pre">AsyncStdControl</span></tt></a></h2>
+<div class="section" id="power-management-with-asyncstdcontrol">
+<h2><a name="power-management-with-asyncstdcontrol">3.3 Power Management with <tt class="docutils literal"><span class="pre">AsyncStdControl</span></tt></a></h2>
<p>The commands and the events of the <em>``StdControl``</em> and the <em>``SplitControl``</em>
interfaces are synchronous and can not be called from within
asynchronous code (such as interrupt service routines, etc.). For the
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">The <tt class="docutils literal"><span class="pre">AsyncStdControl</span></tt> interface should be provided whenever it might be
-necessary to allow a device to be powered on or off while running in
-async context. If it is anticipated that a device <em>will</em> not (or more
+necessary to allow a device to be powered on or off while running in
+async context. If it is anticipated that a device <em>will</em> not (or more
likely <em>should</em> not) be powered on or off while in asynchronous context,
-then the <tt class="docutils literal"><span class="pre">StdControl</span></tt> interface SHOULD be provided instead. Components
+then the <tt class="docutils literal"><span class="pre">StdControl</span></tt> interface SHOULD be provided instead. Components
that wish to power the device on or off from within async context would
-then be required to post a task before doing so. In practice,
-<tt class="docutils literal"><span class="pre">AsyncStdControl</span></tt> is provided by low-level hardware resources, while
-<tt class="docutils literal"><span class="pre">StdControl</span></tt> is provided by higher level services built on top of these
+then be required to post a task before doing so. In practice,
+<tt class="docutils literal"><span class="pre">AsyncStdControl</span></tt> is provided by low-level hardware resources, while
+<tt class="docutils literal"><span class="pre">StdControl</span></tt> is provided by higher level services built on top of these
resources.</p>
</div>
</div>
</div>
-<div class="section">
-<h1><a id="implicit-power-management" name="implicit-power-management">4. Implicit Power Management</a></h1>
+<div class="section" id="implicit-power-management">
+<h1><a name="implicit-power-management">4. Implicit Power Management</a></h1>
<p>While explicit power management provides the mechanism for changing
power states, it does not specify a policy.
This does not represent a large problem for the simple case
-of <em>dedicated</em> devices, but can become crucial for non-trivial cases
-involving complex interdependencies between devices controlled by multiple
+of <em>dedicated</em> devices, but can become crucial for non-trivial cases
+involving complex interdependencies between devices controlled by multiple
clients.</p>
-<p>For example, if component <em>A</em> is a client of both component <em>B</em>
+<p>For example, if component <em>A</em> is a client of both component <em>B</em>
and component <em>C</em>, what happens with <em>B</em> and <em>C</em> if
<tt class="docutils literal"><span class="pre">StdControl.stop()</span></tt> is called on component <em>A</em> ? Should components
-<em>B</em> and <em>C</em> also be stopped? What about the reverse case where both
-<em>B</em> and <em>C</em> are clients of the single shared component, <em>A</em>? If
-devices <em>B</em> and <em>C</em> are shut off, should <em>A</em> be shut off as well?
+<em>B</em> and <em>C</em> also be stopped? What about the reverse case where both
+<em>B</em> and <em>C</em> are clients of the single shared component, <em>A</em>? If
+devices <em>B</em> and <em>C</em> are shut off, should <em>A</em> be shut off as well?
How can one decide when it is appropriate to cascade such powerup
and powerdown requests?</p>
<p>The complex nature of the problem is evident from the number of
unexpected behaviors in TinyOS 1.x involving <tt class="docutils literal"><span class="pre">StdControl</span></tt>. On several
platforms, one of the SPI buses is shared between the radio and the
flash device. On some of them, issuing <tt class="docutils literal"><span class="pre">StdControl.stop()</span></tt> on the
-radio results in a series of cascaded calls that result in SPI bus
-becoming disabled, rendering the communication with the flash impossible.
-Of course, the right policy would involve tracking the clients of the
-SPI bus and powering it off only once both the radio and the flash
+radio results in a series of cascaded calls that result in SPI bus
+becoming disabled, rendering the communication with the flash impossible.
+Of course, the right policy would involve tracking the clients of the
+SPI bus and powering it off only once both the radio and the flash
devices were no longer using it. Conversely, the SPI bus should be
powered on whenever there is at least one active client.</p>
-<p>The selection of the right power management policy to use is a complex
-task that depends on the nature of the devices in use, their
-interdependency, as well as on any specific application requirements.
-For cases when some of these features are known a-priori or are
-restricted in some sense, it is preferable that the system provide
-architectural support for enforcing a meaningful <em>default</em> power-management
-policy instead of passing that task on to the application programmer to be
+<p>The selection of the right power management policy to use is a complex
+task that depends on the nature of the devices in use, their
+interdependency, as well as on any specific application requirements.
+For cases when some of these features are known a-priori or are
+restricted in some sense, it is preferable that the system provide
+architectural support for enforcing a meaningful <em>default</em> power-management
+policy instead of passing that task on to the application programmer to be
solved on a case-by-case basis.</p>
-<div class="section">
-<h2><a id="power-management-policies" name="power-management-policies">4.1. Power Management Policies</a></h2>
+<div class="section" id="power-management-policies">
+<h2><a name="power-management-policies">4.1. Power Management Policies</a></h2>
<p>Just as generic arbiters are offered in TinyOS 2.x to provide the
arbitration functionality required by shared resources, generic power
management policies are also offered to allow the power management of
<tt class="docutils literal"><span class="pre">ResourceDefaultOwner.granted()</span></tt> event to be signaled in order to
gain ownership over the resource device.</p>
<p>Once it owns the device, the <em>Power Manager</em> is free to execute its
-power-management policy using the StdControl-like interface provided by the
-underlying resource. Different power managers can implement different
+power-management policy using the StdControl-like interface provided by the
+underlying resource. Different power managers can implement different
policies. In the simplest case, this would involve an immediate power-down
-via one of the <tt class="docutils literal"><span class="pre">stop()</span></tt> commands. When the power-state transition
-involves non-negligible costs in terms of wake-up latency or power
-consumption, the <em>PowerManager</em> might revert to a more intelligent
-strategy that tries to reduce these effects. As pointed out in the
-introduction, one such strategy might involve the use of a timer to defer
-the power-down of the resource to some later point in time, giving any
-resource clients a window of opportunity to put in requests before the
+via one of the <tt class="docutils literal"><span class="pre">stop()</span></tt> commands. When the power-state transition
+involves non-negligible costs in terms of wake-up latency or power
+consumption, the <em>PowerManager</em> might revert to a more intelligent
+strategy that tries to reduce these effects. As pointed out in the
+introduction, one such strategy might involve the use of a timer to defer
+the power-down of the resource to some later point in time, giving any
+resource clients a window of opportunity to put in requests before the
device is fully shut down.</p>
-<p>Regardless of the power management policy in use, the <em>Power Manager</em>
-remains owner of the resource as long as the resource is not requested
+<p>Regardless of the power management policy in use, the <em>Power Manager</em>
+remains owner of the resource as long as the resource is not requested
by one of its clients. Whenever a client puts in a request, the
-<em>Power Manager</em> will receive a <tt class="docutils literal"><span class="pre">ResourceDefaultOwner.requested()</span></tt> event
-(or <tt class="docutils literal"><span class="pre">immediateRequested()</span></tt> event) from the arbiter it is associated with.
-Upon receiving this event, the <em>Power Manager</em> MUST power up the
+<em>Power Manager</em> will receive a <tt class="docutils literal"><span class="pre">ResourceDefaultOwner.requested()</span></tt> event
+(or <tt class="docutils literal"><span class="pre">immediateRequested()</span></tt> event) from the arbiter it is associated with.
+Upon receiving this event, the <em>Power Manager</em> MUST power up the
resource through the StdControl-like interface provided by the lower level
abstraction of the physical device. The <em>Power Manager</em> SHOULD release the
ownership of the resource (using the <tt class="docutils literal"><span class="pre">ResourceDefaultOwner.release()</span></tt>
-command) but MUST wait until after the resource has been fully powered on
+command) but MUST wait until after the resource has been fully powered on
before doing so.</p>
<p>Modeling devices as shared resources and allowing them to be
controlled in the way described here, solves the problems outlined in
events answers the question of when. As long as the resource at
the bottom of a large set of nested resource clients has been fully released,
the power mananger will be able to power down the resource appropriately.</p>
-<p>Using the model described above, a resource that uses one of these policies
+<p>Using the model described above, a resource that uses one of these policies
according to the <em>implicitly power management</em> model could be built as shown below:</p>
<pre class="literal-block">
module MyFlashP {
}
implementation {
...
-}
+}
generic module PowerManagerC(uint8_t POWERDOWN_DELAY) {
provides {
, MyFlashP;
Init = MyFlashP;
- Resource = FcfsArbiter;
+ Resource = FcfsArbiter;
FlashCommands = MyFlashP;
PowerManagerC.ResourceDefaultUser -> FcfsArbiter;
PowerManagerC.SplitControl -> MyFlashP;
-
+
}
</pre>
<p>This example implementation is built out of three components. The
components, as well as an arbiter component for managing shared clients
of the device. Notice how the <em>Power Manager</em> is wired to both the
<tt class="docutils literal"><span class="pre">ResourceDefaultUser</span></tt> interface provided by the arbiter, and the
-<tt class="docutils literal"><span class="pre">SplitControl</span></tt> interface provided by the flash. All clients of this flash
+<tt class="docutils literal"><span class="pre">SplitControl</span></tt> interface provided by the flash. All clients of this flash
device are directly connected to the resource interface provided by
the arbiter. As outlined above, the <tt class="docutils literal"><span class="pre">PowerManagerC</span></tt> component will use
-the events signaled through the <tt class="docutils literal"><span class="pre">ResourceDefaultUser</span></tt> interface to determine
+the events signaled through the <tt class="docutils literal"><span class="pre">ResourceDefaultUser</span></tt> interface to determine
when to make calls to power the device up and power it down through
the <tt class="docutils literal"><span class="pre">SplitControl</span></tt> interface.</p>
</div>
-<div class="section">
-<h2><a id="example-power-managers-powermanagerc-and-deferredpowermanagerc" name="example-power-managers-powermanagerc-and-deferredpowermanagerc">4.2. Example Power Managers: PowerManagerC and DeferredPowerManagerC</a></h2>
+<div class="section" id="example-power-managers-powermanagerc-and-deferredpowermanagerc">
+<h2><a name="example-power-managers-powermanagerc-and-deferredpowermanagerc">4.2. Example Power Managers: PowerManagerC and DeferredPowerManagerC</a></h2>
<p>TinyOS 2.x currently has two default power management policies
-that it provides. These policies are implemented by the various
-components located under tinyos-2.x/lib/power. The first policy
+that it provides. These policies are implemented by the various
+components located under tinyos-2.x/lib/power. The first policy
is implemented using an <em>immediate</em> power control scheme, whereby
devices are powered on and off immediately after they have been
requested and released. The second policy is implemented using
-a <em>deferred</em> power control scheme, whereby devices are powered
+a <em>deferred</em> power control scheme, whereby devices are powered
on immediately after being requested, but powered off after
some small delay from being released.</p>
-<p>Each policy has three different implementations for use by each of
+<p>Each policy has three different implementations for use by each of
the <tt class="docutils literal"><span class="pre">StdControl</span></tt>, <tt class="docutils literal"><span class="pre">SplitControl</span></tt>, and <tt class="docutils literal"><span class="pre">AsyncStdControl</span></tt>
interfaces.</p>
<p>For reference, each of the available components are listed below</p>
</dl>
</div>
</div>
-<div class="section">
-<h1><a id="author-s-address" name="author-s-address">5. Author's Address</a></h1>
+<div class="section" id="author-s-address">
+<h1><a name="author-s-address">5. Author's Address</a></h1>
<div class="line-block">
<div class="line">Kevin Klues</div>
<div class="line">503 Bryan Hall</div>
<div class="line">Stanford, CA 94305-9030</div>
<div class="line"><br /></div>
<div class="line">phone - +1 650 725 9046</div>
-<div class="line">email - <a class="reference" href="mailto:pal@cs.stanford.edu">pal@cs.stanford.edu</a></div>
+<div class="line">email - <a class="reference" href="mailto:pal@cs.stanford.edu">pal@cs.stanford.edu</a> </div>
</div>
</div>
-<div class="section">
-<h1><a id="citations" name="citations">6. Citations</a></h1>
+<div class="section" id="citations">
+<h1><a name="citations">6. Citations</a></h1>
<table class="docutils citation" frame="void" id="tep102" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.3.6: http://docutils.sourceforge.net/" />
<title>Packet Protocols</title>
<meta name="author" content="Philip Levis" />
<style type="text/css">
</style>
</head>
<body>
-<div class="document" id="packet-protocols">
<h1 class="title">Packet Protocols</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<td>Philip Levis</td></tr>
<tr class="field"><th class="docinfo-name">Draft-Created:</th><td class="field-body">10-Dec-2004</td>
</tr>
-<tr class="field"><th class="docinfo-name">Draft-Version:</th><td class="field-body">1.9</td>
+<tr class="field"><th class="docinfo-name">Draft-Version:</th><td class="field-body">1.10</td>
</tr>
-<tr class="field"><th class="docinfo-name">Draft-Modified:</th><td class="field-body">2007-03-21</td>
+<tr class="field"><th class="docinfo-name">Draft-Modified:</th><td class="field-body">2007-03-28</td>
</tr>
<tr class="field"><th class="docinfo-name">Draft-Discuss:</th><td class="field-body">TinyOS Developer List <tinyos-devel at mail.millennium.berkeley.edu></td>
</tr>
</tbody>
</table>
+<div class="document" id="packet-protocols">
<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
of this memo is unlimited. This memo is in full compliance with
TEP 1.</p>
</div>
-<div class="section">
-<h1><a id="abstract" name="abstract">Abstract</a></h1>
-<p>The memo documents the interfaces used by packet protocol components in
-TinyOS 2.x as well as the structure and implementation of ActiveMessageC,
+<div class="section" id="abstract">
+<h1><a name="abstract">Abstract</a></h1>
+<p>The memo documents the interfaces used by packet protocol components in
+TinyOS 2.x as well as the structure and implementation of ActiveMessageC,
the basic data-link HIL component. It also documents the virtualized
active message interfaces AMSenderC and AMReceiverC.</p>
</div>
-<div class="section">
-<h1><a id="introduction" name="introduction">1. Introduction</a></h1>
+<div class="section" id="introduction">
+<h1><a name="introduction">1. Introduction</a></h1>
<p>Sensor nodes are network-centric devices. Much of their software
complexity comes from network protocols and their interactions.
In TinyOS, the basic network abstraction is an <em>active message</em>,
a single-hop, unreliable packet. Active messages have a destination
address, provide synchronous acknowledgements, and can be of
-variable length up to a fixed maximum size. They also have a
+variable length up to a fixed maximum size. They also have a
type field, which is essentially a protocol identifier for
components built on top of this abstraction.</p>
<p>In TinyOS 1.x, the component GenericComm provides interfaces for
</pre>
<p>This component, while simple, has several issues. First, it has the
activity() commmand, which does not have a single caller in the entire
-TinyOS tree. This command requires GenericComm to allocate a
+TinyOS tree. This command requires GenericComm to allocate a
timer, wasting CPU cycles and RAM.</p>
<p>Second, it does not allow a node to receive packets besides
those destined to it. Several network
-protocols (e.g., MintRoute <a class="footnote-reference" href="#id6" id="id1" name="id1">[1]</a>, TAG <a class="footnote-reference" href="#id7" id="id2" name="id2">[2]</a>) take advantage
+protocols (e.g., MintRoute <a class="footnote-reference" href="#id6" id="id1" name="id1">[1]</a>, TAG <a class="footnote-reference" href="#id7" id="id2" name="id2">[2]</a>) take advantage
of snooping on these packets for a variety of improvements in efficiency or
performance. This has led to the creation of GenericCommPromiscuous,
whose Receive interface does not distinguish
packets received that were addressed to other nodes. Choosing
one of the two implementations is a global decision across
an application. There is a way to enable both reception
-semantics at the same time for a different protocols,
+semantics at the same time for a different protocols,
but they require a creative use of default event handlers.</p>
<p>Third, it assumes that components will directly access the packet
structure, the accepted approach in TinyOS 1.x. However, directly
as well as ActiveMessageC, the basic data-link packet communication
HIL.</p>
</div>
-<div class="section">
-<h1><a id="communication-interfaces" name="communication-interfaces">2. Communication interfaces</a></h1>
+<div class="section" id="communication-interfaces">
+<h1><a name="communication-interfaces">2. Communication interfaces</a></h1>
<p>Packet-level communication has three basic classes of interfaces.
-<em>Packet</em> interfaces are for accessing message fields and payloads.
+<em>Packet</em> interfaces are for accessing message fields and payloads.
<em>Send</em> interfaces are for transmitting packets, and are
-distinguished by their addressing scheme.
+distinguished by their addressing scheme.
The <em>Receive</em> interface is for handling packet reception events.
Finally, depending on whether the protocol has a dispatch identifier
field, the Receive and Send interfaces may be parameterized in order
to support multiple higher-level clients.</p>
-<div class="section">
-<h2><a id="packet-interfaces" name="packet-interfaces">2.1 Packet interfaces</a></h2>
-<p>The basic TinyOS 2.x message buffer type is message_t, which is
+<div class="section" id="packet-interfaces">
+<h2><a name="packet-interfaces">2.1 Packet interfaces</a></h2>
+<p>The basic TinyOS 2.x message buffer type is message_t, which is
described in TEP 111. message_t right-justifies data-link
-headers to the data payload so that higher-level components can
+headers to the data payload so that higher-level components can
pass buffers between different data link layers without having
-to move data payloads. This means that the data payload of a
+to move data payloads. This means that the data payload of a
data link frame is always at a fixed offset of a message_t.</p>
<p>Once protocols layer on top of each other, the data
payload for components on top of the data link layer are
-no longer at a fixed offset. Where a component can put its
+no longer at a fixed offset. Where a component can put its
header or data depends on what headers underlying components
introduce. Therefore, in order to be able to find out where
it can put its data, it must query the components below it.
<p>A component can set the payload length with
<tt class="docutils literal"><span class="pre">setPayLoadLength.</span></tt> As Send interfaces always include a length
parameter in their send call, this command is not required for
-sending, and so is never called in common use cases. Instead,
+sending, and so is never called in common use cases. Instead,
it is a way for queues and other packet buffering components
to store the full state of a packet without requiring additional
memory allocation.</p>
case, determining the size of the existing data payload is needed;
in the send case, a component needs to know how much data it can put
in the packet.</p>
-<p>The Packet interface assumes that headers have a fixed size.
-It is difficult to return a pointer into the data region when its
+<p>The Packet interface assumes that headers have a fixed size.
+It is difficult to return a pointer into the data region when its
position will only be known once the header values are bound.</p>
<p>Generally, an incoming call to the Packet interface of a protocol
-has an accompanying outgoing call to the Packet interface of the
+has an accompanying outgoing call to the Packet interface of the
component below it. The one exception to this is the data link
layer. For example, if there is a network that introduces
16-bit sequence numbers to packets, it might look like this:</p>
if (len != NULL) {
*len -= SEQNO_OFFSET;
}
- return payload + SEQNO_OFFSET;
- }
+ return payload + SEQNO_OFFSET;
+ }
}
</pre>
<p>The above example is incomplete: it does not include the code for
the send path that increments sequence numbers.</p>
-<p>In practice, calls to Packet are very efficient even if they
+<p>In practice, calls to Packet are very efficient even if they
pass through many components before reaching the data link
layer. nesC's inlining means that in almost all cases
there will not actually be any function calls, and since payload
position and length calculations all use constant offsets,
-the compiler generally uses constant folding to generate a
+the compiler generally uses constant folding to generate a
fixed offset.</p>
<p>The Packet interface provides access to the one field all packet
layers have, the data payload. Communication layers can add additional
header and footer fields, and may need to provide access to these
fields. If a packet communication component provides access to header
-and/or footer fields, it MUST do so through an interface. The interface
+and/or footer fields, it MUST do so through an interface. The interface
SHOULD have a name of the form <em>XPacket</em>, where <em>X</em> is a name that
describes the communication layer. For example, active message components
provide both the Packet interface and the AMPacket interface. The latter
but when necessary it may use the metadata region of message_t or other
locations.</p>
</div>
-<div class="section">
-<h2><a id="sending-interfaces" name="sending-interfaces">2.2 Sending interfaces</a></h2>
+<div class="section" id="sending-interfaces">
+<h2><a name="sending-interfaces">2.2 Sending interfaces</a></h2>
<p>There are multiple sending interfaces, corresponding to different
addressing modes. For example, address-free protocols, such as
collection routing, provide the basic <tt class="docutils literal"><span class="pre">Send</span></tt> interface. Active
message communication has a destination of an AM address, so
-it provides the <tt class="docutils literal"><span class="pre">AMSend</span></tt> interface. This, for example, is the
+it provides the <tt class="docutils literal"><span class="pre">AMSend</span></tt> interface. This, for example, is the
basic, address-free Send interface:</p>
<pre class="literal-block">
interface Send {
command error_t send(message_t* msg, uint8_t len);
command error_t cancel(message_t* msg);
- event void sendDone(message_t* msg, error_t error);
+ event void sendDone(message_t* msg, error_t error);
command uint8_t maxPayloadLength();
command void* getPayload(message_t* msg);
event void sendDone(message_t* msg, error_t error);
command uint8_t maxPayloadLength();
- command void* getPayload(message_t* msg);
+ command void* getPayload(message_t* msg);
}
</pre>
<p>Sending interfaces MUST include these four commands and one event.
<p>When called with a length that is too long for the underlying
maximum transfer unit (MTU), the send command MUST return ESIZE.</p>
<p>The <tt class="docutils literal"><span class="pre">Send</span></tt> and <tt class="docutils literal"><span class="pre">AMSend</span></tt> interfaces have an explicit queue of
-depth one. A call to <tt class="docutils literal"><span class="pre">send</span></tt> on either of these interfaces MUST
+depth one. A call to <tt class="docutils literal"><span class="pre">send</span></tt> on either of these interfaces MUST
return EBUSY if a prior call to <tt class="docutils literal"><span class="pre">send</span></tt> returned SUCCESS but no
<tt class="docutils literal"><span class="pre">sendDone</span></tt> event has been signaled yet. More explicitly:</p>
<pre class="literal-block">
and cancel returns FAIL, then sendDone SHOULD occur as if the cancel
was not called.</p>
</div>
-<div class="section">
-<h2><a id="receive-interface" name="receive-interface">2.3 Receive interface</a></h2>
+<div class="section" id="receive-interface">
+<h2><a name="receive-interface">2.3 Receive interface</a></h2>
<p>Receive is the interface for receiving packets. It has this signature:</p>
<pre class="literal-block">
interface Receive {
and the same semantics as its twin in <tt class="docutils literal"><span class="pre">Packet</span></tt>.</p>
<p>Receive has a <em>buffer-swap</em> policy. The handler of the event MUST return
a pointer to a valid message buffer for the signaler to use. This
-approach enforces an equilibrium between upper and lower packet
+approach enforces an equilibrium between upper and lower packet
layers. If an upper layer cannot handle packets as quickly as they
are arriving, it still has to return a valid buffer to the lower
layer. This buffer could be the <tt class="docutils literal"><span class="pre">msg</span></tt> parameter passed to it: it
just returns the buffer it was given without looking at it. Following
-this policy means that a data-rate mismatch in an upper-level component
+this policy means that a data-rate mismatch in an upper-level component
will be isolated to that component. It will drop packets, but it will
not prevent other components from receiving packets. If an upper
layer did not have to return a buffer immediately, then when an
<pre class="literal-block">
// Case 1
message_t* Receive.receive(message_t* msg, void* payload, uint8_t len) {
- return msg;
-}
+ return msg;
+}
// Case 2
uint16_t value;
a parameter to <tt class="docutils literal"><span class="pre">receive</span></tt> MUST NOT be touched, used, or stored after
the signaling of <tt class="docutils literal"><span class="pre">receive.</span></tt></p>
</div>
-<div class="section">
-<h2><a id="dispatch" name="dispatch">2.4 Dispatch</a></h2>
+<div class="section" id="dispatch">
+<h2><a name="dispatch">2.4 Dispatch</a></h2>
<p>A packet protocol MAY have a dispatch identifier. This generally manifests
as the protocol component providing parameterized interfaces (rather than
-a single interface instance). A dispatch identifier allows multiple
+a single interface instance). A dispatch identifier allows multiple
services to use a protocol independently. If a protocol provides a
dispatch mechanism, then each dispatch identifier SHOULD correspond to
a single packet format: if an identifier corresponds to multiple packet
-formats, then there is no way to disambiguate them. Packets whose internal
+formats, then there is no way to disambiguate them. Packets whose internal
structure depends on their fields (for example,
a packet that has a control field which indicates which optional fields
are present) do not pose such problems.</p>
</div>
</div>
-<div class="section">
-<h1><a id="hil-activemessagec" name="hil-activemessagec">3. HIL: ActiveMessageC</a></h1>
-<p>A platform MUST provide ActiveMessageC as a basic HIL to
-packet-level communication. ActiveMessageC provides a best-effort,
-single-hop communication abstraction. Every active message has a
-16-bit destination address and an 8-bit type. There is one reserved
-destination address, <tt class="docutils literal"><span class="pre">AM_BROADCAST_ADDR</span></tt>, which has the value
+<div class="section" id="hil-activemessagec">
+<h1><a name="hil-activemessagec">3. HIL: ActiveMessageC</a></h1>
+<p>A platform MUST provide ActiveMessageC as a basic HIL to
+packet-level communication. ActiveMessageC provides a best-effort,
+single-hop communication abstraction. Every active message has a
+16-bit destination address and an 8-bit type. There is one reserved
+destination address, <tt class="docutils literal"><span class="pre">AM_BROADCAST_ADDR</span></tt>, which has the value
of <tt class="docutils literal"><span class="pre">0xffff</span></tt>. ActiveMessageC has the following signature:</p>
<pre class="literal-block">
configuration ActiveMessageC {
provides {
interface Init;
- interface SplitControl;
+ interface SplitControl;
interface AMSend[uint8_t id];
interface Receive[uint8_t id];
}
}
</pre>
-<p>The Receive interface is for packets destined to the node, while
-the Snoop interface is for packets destined to other nodes. A
-packet is destined for a node if its destination AM address is
-either the AM broadcast address or an address associated with
-the AM stack. Different link layers have different snooping
-capabilities. The Snoop interface does not assume always-on
-listening, for example, in the case of a TDMA or RTS/CTS data
+<p>The Receive interface is for packets destined to the node, while
+the Snoop interface is for packets destined to other nodes. A
+packet is destined for a node if its destination AM address is
+either the AM broadcast address or an address associated with
+the AM stack. Different link layers have different snooping
+capabilities. The Snoop interface does not assume always-on
+listening, for example, in the case of a TDMA or RTS/CTS data
link layer. By separating out these two interfaces, ActiveMessageC
avoids the complications encountered in 1.x with regards to
GenericComm vs. GenericCommPromiscuous.</p>
implementation. The definition of ActiveMessageC is left
to the platform for when a node has more than one
radio. In this case, the platform decides how to map the
-basic packet abstraction to the hardware underneath. Approaches
+basic packet abstraction to the hardware underneath. Approaches
include choosing one radio or having some form of address-based
dispatch.</p>
</div>
-<div class="section">
-<h1><a id="am-services-amsenderc-amreceiverc-amsnooperc-amsnoopingreceiverc" name="am-services-amsenderc-amreceiverc-amsnooperc-amsnoopingreceiverc">4. AM Services: AMSenderC, AMReceiverC, AMSnooperC, AMSnoopingReceiverC</a></h1>
+<div class="section" id="am-services-amsenderc-amreceiverc-amsnooperc-amsnoopingreceiverc">
+<h1><a name="am-services-amsenderc-amreceiverc-amsnooperc-amsnoopingreceiverc">4. AM Services: AMSenderC, AMReceiverC, AMSnooperC, AMSnoopingReceiverC</a></h1>
<p>TinyOS 2.x provides four component single-hop communication
virtualizations to applications:
AMReceiverC, AMSnooperC, AMSnoopingReceiverC, and AMSenderC. Each is a
generic component that takes an active message ID as a
parameter. These components assume the existence of ActiveMessageC.</p>
-<div class="section">
-<h2><a id="dispatch-am-id-t" name="dispatch-am-id-t">4.1 Dispatch: <tt class="docutils literal"><span class="pre">am_id_t</span></tt></a></h2>
+<div class="section" id="dispatch-am-id-t">
+<h2><a name="dispatch-am-id-t">4.1 Dispatch: <tt class="docutils literal"><span class="pre">am_id_t</span></tt></a></h2>
<p>Active messages have an 8-bit type field, which allows multiple
protocols to all use AM communication without conflicting. Following
the guidelines for protocol dispatch identifiers, each
that the am_id_t, combined with the packet contents, are sufficient
to determine the exact packet format.</p>
</div>
-<div class="section">
-<h2><a id="amreceiverc" name="amreceiverc">4.2 AMReceiverC</a></h2>
+<div class="section" id="amreceiverc">
+<h2><a name="amreceiverc">4.2 AMReceiverC</a></h2>
<p>AMReceiverC has the following signature:</p>
<pre class="literal-block">
generic configuration AMReceiverC(am_id_t t) {
instantiate an AMReceiver and an AMSnoopingReceiver with the same
am_id_t.</p>
</div>
-<div class="section">
-<h2><a id="amsnooperc" name="amsnooperc">4.3 AMSnooperC</a></h2>
+<div class="section" id="amsnooperc">
+<h2><a name="amsnooperc">4.3 AMSnooperC</a></h2>
<p>AMSnooper has an identical signature to AMReceiver:</p>
<pre class="literal-block">
generic configuration AMSnooperC(am_id_t t) {
instantiate an AMSnooper and an AMSnoopingReceiver with the same
am_id_t.</p>
</div>
-<div class="section">
-<h2><a id="amsnoopingreceiverc" name="amsnoopingreceiverc">4.4 AMSnoopingReceiverC</a></h2>
+<div class="section" id="amsnoopingreceiverc">
+<h2><a name="amsnoopingreceiverc">4.4 AMSnoopingReceiverC</a></h2>
<p>AMSnoopingReceiverC has an identical signature to AMReceiverC:</p>
<pre class="literal-block">
generic configuration AMSnoopingReceiverC(am_id_t t) {
a certain am_id_t MUST NOT instantiate another AMSnoopingReceiverC,
AMSnooperC, or AMReceiverC with the same am_id_t.</p>
</div>
-<div class="section">
-<h2><a id="amsenderc" name="amsenderc">4.5 AMSenderC</a></h2>
+<div class="section" id="amsenderc">
+<h2><a name="amsenderc">4.5 AMSenderC</a></h2>
<p>AMSenderC has the following signature:</p>
<pre class="literal-block">
generic configuration AMSenderC(am_id_t AMId) {
AMSenderC. That is, each AMSenderC has a queue of depth one. The exact
order in which pending AMSenderC requests are serviced is undefined,
but it MUST be fair, where fair means that each client with outstanding
-packets receives a reasonable approximation of an equal share of the
+packets receives a reasonable approximation of an equal share of the
available transmission bandwidth.</p>
</div>
</div>
-<div class="section">
-<h1><a id="power-management-and-local-address" name="power-management-and-local-address">5. Power Management and Local Address</a></h1>
+<div class="section" id="power-management-and-local-address">
+<h1><a name="power-management-and-local-address">5. Power Management and Local Address</a></h1>
<p>In addition to standard datapath interfaces for sending and
receiving packets, an active message layer also has control interfaces.</p>
-<div class="section">
-<h2><a id="power-management" name="power-management">5.1 Power Management</a></h2>
+<div class="section" id="power-management">
+<h2><a name="power-management">5.1 Power Management</a></h2>
<p>The communication virtualizations do not support power management.
ActiveMessageC provides SplitControl for explicit power control.
-For packet communication to operate properly, a component in an
+For packet communication to operate properly, a component in an
application has to call ActiveMessageC.SplitControl.start().
-The HAL underneath ActiveMessageC MAY employ power management
+The HAL underneath ActiveMessageC MAY employ power management
techniques, such as TDMA scheduling or low power listening, when
"on."</p>
</div>
-<div class="section">
-<h2><a id="local-active-message-address" name="local-active-message-address">5.2 Local Active Message Address</a></h2>
-<p>An application can change ActiveMessageC's local AM address
+<div class="section" id="local-active-message-address">
+<h2><a name="local-active-message-address">5.2 Local Active Message Address</a></h2>
+<p>An application can change ActiveMessageC's local AM address
at runtime. This will change which packets a node receives and
the source address it embeds in packets. To change the local AM
address at runtime, a component can wire to the component
for changing their addresses in a stack-specific fashion.</p>
</div>
</div>
-<div class="section">
-<h1><a id="hal-requirements" name="hal-requirements">5. HAL Requirements</a></h1>
+<div class="section" id="hal-requirements">
+<h1><a name="hal-requirements">5. HAL Requirements</a></h1>
<p>A radio chip <em>X</em> MUST have a packet abstraction with the following
signature:</p>
<pre class="literal-block">
provides interface AMPacket;
provides interface PacketAcknowledgments;
</pre>
-<p>The component SHOULD be named <em>XActiveMessageC</em>, where <em>X</em> is
-the name of the radio chip. The component MAY have additional interfaces.
+<p>The component SHOULD be named <em>XActiveMessageC</em>, where <em>X</em> is
+the name of the radio chip. The component MAY have additional interfaces.
These interfaces can either be chip-specific or chip-independent.</p>
</div>
-<div class="section">
-<h1><a id="message-t" name="message-t">6. message_t</a></h1>
+<div class="section" id="message-t">
+<h1><a name="message-t">6. message_t</a></h1>
<p>Active messages are a basic single-hop packet abstraction. Therefore,
following TEP 111 <a class="footnote-reference" href="#id8" id="id4" name="id4">[3]</a>, all data link and active message headers
MUST be in the <tt class="docutils literal"><span class="pre">message_header_t</span></tt> structure of message_t. This ensures
can be passed to another data link layer (e.g., the UART) without
shifting the data payload. This means that the <tt class="docutils literal"><span class="pre">message_header_t</span></tt> must
include all data needed for AM fields, which might introduce headers
-in addition to those of the data link. For example, this is an example
+in addition to those of the data link. For example, this is an example
structure for a CC2420 (802.15.4) header:</p>
<pre class="literal-block">
typedef nx_struct cc2420_header_t {
type field, however, has been added to the header structure in order
to support AM dispatch.</p>
</div>
-<div class="section">
-<h1><a id="implementation" name="implementation">7. Implementation</a></h1>
-<p>The following files in <tt class="docutils literal"><span class="pre">tinyos-2.x/tos/system</span></tt> provide reference
+<div class="section" id="implementation">
+<h1><a name="implementation">7. Implementation</a></h1>
+<p>The following files in <tt class="docutils literal"><span class="pre">tinyos-2.x/tos/system</span></tt> provide reference
implementations of the abstractions described in this TEP.</p>
<blockquote>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">AMSenderC.nc</span></tt>, <tt class="docutils literal"><span class="pre">AMReceiverC.nc</span></tt>, <tt class="docutils literal"><span class="pre">AMSnooperC.nc</span></tt>,
-and <tt class="docutils literal"><span class="pre">AMSnoopingReceiverC.nc</span></tt> are implementations of
+and <tt class="docutils literal"><span class="pre">AMSnoopingReceiverC.nc</span></tt> are implementations of
virtualized AM services.</li>
<li><tt class="docutils literal"><span class="pre">AMQueueP</span></tt> provides a send queue of <em>n</em> entries for <em>n</em>
AMSenderC clients, such that each client has a dedicated entry.</li>
packet protocols provide.</p>
</li>
<li><dl class="first docutils">
-<dt><tt class="docutils literal"><span class="pre">Send.nc</span></tt> is the transmission interface for address-free</dt>
+<dt><tt class="docutils literal"><span class="pre">Send.nc</span></tt> is the transmission interface for address-free </dt>
<dd><p class="first last">protocols.</p>
</dd>
</dl>
The micaz platform and telos family have an <tt class="docutils literal"><span class="pre">ActiveMessageC.nc</span></tt>
which exports the interfaces of <tt class="docutils literal"><span class="pre">CC2420ActiveMessageC</span></tt>.</p>
</div>
-<div class="section">
-<h1><a id="author-s-address" name="author-s-address">8. Author's Address</a></h1>
+<div class="section" id="author-s-address">
+<h1><a name="author-s-address">8. Author's Address</a></h1>
<div class="line-block">
<div class="line">Philip Levis</div>
<div class="line">358 Gates Hall</div>
<div class="line">phone - +1 650 725 9046</div>
</div>
</div>
-<div class="section">
-<h1><a id="citations" name="citations">9. Citations</a></h1>
+<div class="section" id="citations">
+<h1><a name="citations">9. Citations</a></h1>
<table class="docutils footnote" frame="void" id="id6" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.3.6: http://docutils.sourceforge.net/" />
<title>Low-Level I/O</title>
<meta name="author" content="Phil Buonadonna, Jonathan Hui" />
<style type="text/css">
</style>
</head>
<body>
-<div class="document" id="low-level-i-o">
<h1 class="title">Low-Level I/O</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<td>Phil Buonadonna, Jonathan Hui</td></tr>
<tr class="field"><th class="docinfo-name">Draft-Created:</th><td class="field-body">23-Jan-2006</td>
</tr>
-<tr class="field"><th class="docinfo-name">Draft-Version:</th><td class="field-body">1.1.2.9</td>
+<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">2006-09-30</td>
+<tr class="field"><th class="docinfo-name">Draft-Modified:</th><td class="field-body">2006-12-12</td>
</tr>
<tr class="field"><th class="docinfo-name">Draft-Discuss:</th><td class="field-body">TinyOS Developer List <tinyos-devel at mail.millennium.berkeley.edu></td>
</tr>
</tbody>
</table>
+<div class="document" id="low-level-i-o">
<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
of this memo is unlimited. This memo is in full compliance with
TEP 1.</p>
</div>
-<div class="section">
-<h1><a id="abstract" name="abstract">Abstract</a></h1>
+<div class="section" id="abstract">
+<h1><a name="abstract">Abstract</a></h1>
<p>The memo documents the TinyOS 2.x interfaces used for controlling
digital IO functionality and digital interfaces.</p>
</div>
-<div class="section">
-<h1><a id="introduction" name="introduction">1. Introduction</a></h1>
+<div class="section" id="introduction">
+<h1><a name="introduction">1. Introduction</a></h1>
<p>The canonical TinyOS device is likely to have a variety of digital
interfaces. These interfaces may be divided into two broad
categories. The first are general purpose digital I/O lines (pins) for
coverage.</p>
<p>This memo documents the interfaces used for pins and the three buses.</p>
</div>
-<div class="section">
-<h1><a id="pins" name="pins">2. Pins</a></h1>
+<div class="section" id="pins">
+<h1><a name="pins">2. Pins</a></h1>
<p>General Purpose I/O (GPIO) pins are single, versatile digital I/O
signals individually controllable on a particular chip or
platform. Each GPIO can be placed into either an input mode or an
<li>GpioCapture</li>
</ul>
</blockquote>
-<div class="section">
-<h2><a id="generalio" name="generalio">2.1 GeneralIO</a></h2>
+<div class="section" id="generalio">
+<h2><a name="generalio">2.1 GeneralIO</a></h2>
<p>The GeneralIO HIL interface is the fundamental mechanism for controlling a
GPIO pin. The interface provides a mechanism for setting the pin mode
and reading/setting the pin value. The toggle function switches the
}
</pre>
</div>
-<div class="section">
-<h2><a id="gpiointerrupt" name="gpiointerrupt">2.2 GpioInterrupt</a></h2>
+<div class="section" id="gpiointerrupt">
+<h2><a name="gpiointerrupt">2.2 GpioInterrupt</a></h2>
<p>The GPIO Interrupt HIL interface provides baseline event control for a
GPIO pin. It provides a mechanism to detect a rising edge OR a falling
edge. Note that calls to enableRisingEdge and enableFallingEdge are
}
</pre>
</div>
-<div class="section">
-<h2><a id="gpiocapture" name="gpiocapture">2.3 GpioCapture</a></h2>
+<div class="section" id="gpiocapture">
+<h2><a name="gpiocapture">2.3 GpioCapture</a></h2>
<p>The GpioCapture interface provides a means of associating a timestamp
with a GPIO event. Platforms MAY provide this interface.</p>
<p>Some platforms may have hardware support for such a feature. Other
</pre>
</div>
</div>
-<div class="section">
-<h1><a id="buses" name="buses">3. Buses</a></h1>
+<div class="section" id="buses">
+<h1><a name="buses">3. Buses</a></h1>
<p>Bus operations may be divided into two categories: data and
control. The control operations of a particular bus controller are
platform specific and not covered here. Instead, we focus on the data
interfaces at the HIL level that are expected to be provided.</p>
-<div class="section">
-<h2><a id="serial-peripheral-interface" name="serial-peripheral-interface">3.1 Serial Peripheral Interface</a></h2>
+<div class="section" id="serial-peripheral-interface">
+<h2><a name="serial-peripheral-interface">3.1 Serial Peripheral Interface</a></h2>
<p>The Serial Peripheral Interface (SPI) is part of a larger class of
Synchronous Serial Protocols. The term SPI typically refers to the
Motorola SPI protocols. Other protocols include the National
}
</pre>
</div>
-<div class="section">
-<h2><a id="i2c" name="i2c">3.2 I2C</a></h2>
+<div class="section" id="i2c">
+<h2><a name="i2c">3.2 I2C</a></h2>
<p>The Inter-Integrated Circuit (I2C) interface is another type of
digital bus that is often used for chip-to-chip communication. It is
also known as a two-wire interface.</p>
<p>The interface is typed according to the addressing space the
underlying implementation supports. Valid type values are below.</p>
<pre class="literal-block">
-TI2CExtdAddr - Interfaces uses the extended (10-bit) addressing mode.
+TI2CExtdAddr - Interfaces uses the extended (10-bit) addressing mode.
TI2CBasicAddr - Interfaces uses the basic (7-bit) addressing mode.
</pre>
<p>The i2c_flags_t values are defined below. The flags define the
I2C_START - Transmit an I2C STOP at the beginning of the operation.
I2C_STOP - Transmit an I2C STOP at the end of the operation. Cannot be used
with the I2C_ACK_END flag.
-I2C_ACK_END - ACK the last byte sent from the buffer. This flags is only valid
+I2C_ACK_END - ACK the last byte sent from the buffer. This flags is only valid
a write operation. Cannot be used with the I2C_STOP flag.
</pre>
</div>
-<div class="section">
-<h2><a id="uart" name="uart">3.3 UART</a></h2>
+<div class="section" id="uart">
+<h2><a name="uart">3.3 UART</a></h2>
<p>The Universal Asynchronous Receiver/Transmitter (UART) interface is a
type of serial interconnect. The interface is "asynchronous" since it
recovers timing from the data stream itself, rather than a separate
interface UartStream {
async command error_t send( uint8_t* buf, uint16_t len );
async event void sendDone( uint8_t* buf, uint16_t len, error_t error );
-
+
async command error_t enableReceiveInterrupt();
async command error_t disableReceiveInterrupt();
async event void receivedByte( uint8_t byte );
-
+
async command error_t receive( uint8_t* buf, uint8_t len );
async event void receiveDone( uint8_t* buf, uint16_t len, error_t error );
}
</pre>
</div>
</div>
-<div class="section">
-<h1><a id="implementation" name="implementation">4. Implementation</a></h1>
+<div class="section" id="implementation">
+<h1><a name="implementation">4. Implementation</a></h1>
<p>Example implementations of the pin interfaces can be found in tos/chips/msp430/pins,
tos/chips/atm128/pins, and tos/chips/pxa27x/gpio.</p>
<p>Example implementations of the SPI interfaces can be found in tos/chips/msp430/usart,
<p>Example implementations of the UART interfaces can be found in tos/chips/msp430/usart,
tos/chips/atm128/uart/ and tos/chips/pxa27x/uart.</p>
</div>
-<div class="section">
-<h1><a id="author-s-address" name="author-s-address">5. Author's Address</a></h1>
+<div class="section" id="author-s-address">
+<h1><a name="author-s-address">5. Author's Address</a></h1>
<div class="line-block">
<div class="line">Phil Buonadonna</div>
<div class="line">Arch Rock Corporation</div>
<div class="line">phone - +1 415 692-0828 x2835</div>
</div>
</div>
-<div class="section">
-<h1><a id="citations" name="citations">6. Citations</a></h1>
+<div class="section" id="citations">
+<h1><a name="citations">6. Citations</a></h1>
<table class="docutils citation" frame="void" id="tep113" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.3.6: http://docutils.sourceforge.net/" />
<title>Dissemination</title>
<meta name="author" content="Philip Levis and Gilman Tolle" />
<style type="text/css">
</style>
</head>
<body>
-<div class="document" id="dissemination">
<h1 class="title">Dissemination</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<td>Philip Levis and Gilman Tolle</td></tr>
<tr class="field"><th class="docinfo-name">Draft-Created:</th><td class="field-body">10-Dec-2004</td>
</tr>
-<tr class="field"><th class="docinfo-name">Draft-Version:</th><td class="field-body">1.1.2.3</td>
+<tr class="field"><th class="docinfo-name">Draft-Version:</th><td class="field-body">1.6</td>
</tr>
-<tr class="field"><th class="docinfo-name">Draft-Modified:</th><td class="field-body">2006-06-20</td>
+<tr class="field"><th class="docinfo-name">Draft-Modified:</th><td class="field-body">2006-12-12</td>
</tr>
<tr class="field"><th class="docinfo-name">Draft-Discuss:</th><td class="field-body">TinyOS Developer List <tinyos-devel at mail.millennium.berkeley.edu></td>
</tr>
</tbody>
</table>
+<div class="document" id="dissemination">
<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
of this memo is unlimited. This memo is in full compliance with
TEP 1.</p>
</div>
-<div class="section">
-<h1><a id="abstract" name="abstract">Abstract</a></h1>
+<div class="section" id="abstract">
+<h1><a name="abstract">Abstract</a></h1>
<p>The memo documents the interfaces, components, and semantics for
disseminating small (smaller than a single packet payload) pieces of
data in TinyOS 2.x. Dissemination is reliably delivering a piece of
data to every node in a network.</p>
</div>
-<div class="section">
-<h1><a id="introduction" name="introduction">1. Introduction</a></h1>
+<div class="section" id="introduction">
+<h1><a name="introduction">1. Introduction</a></h1>
<p>Dissemination is a basic sensor network protocol. The ability to
reliably deliver a piece of data to every node allows administrators
to reconfigure, query, and reprogram a network. Reliability is
document describes a set of components and interfaces for a
dissemination service of this kind.</p>
</div>
-<div class="section">
-<h1><a id="dissemination-interfaces" name="dissemination-interfaces">2. Dissemination interfaces</a></h1>
+<div class="section" id="dissemination-interfaces">
+<h1><a name="dissemination-interfaces">2. Dissemination interfaces</a></h1>
<p>Small-value dissemination has two interfaces: DisseminationValue and
DisseminationUpdate. The former is for consumers of a disseminated
value, the latter is for producers. They are as follows:</p>
<pre class="literal-block">
interface DisseminationValue<t> {
command const t* get();
- event void changed();
+ event void changed();
}
interface DisseminationUpdate<t> {
dissemination protocol therefore MUST have a tie-breaking mechanism,
so that eventually every node has the same data value.</p>
</div>
-<div class="section">
-<h1><a id="dissemination-service" name="dissemination-service">3 Dissemination Service</a></h1>
+<div class="section" id="dissemination-service">
+<h1><a name="dissemination-service">3 Dissemination Service</a></h1>
<p>A dissemination service MUST provide one component, DisseminatorC,
which has the following signature:</p>
<pre class="literal-block">
<p>Two different instances of DisseminatorC MUST NOT share the same value
for the <tt class="docutils literal"><span class="pre">key</span></tt> argument.</p>
</div>
-<div class="section">
-<h1><a id="dissemination-keys" name="dissemination-keys">4 Dissemination Keys</a></h1>
+<div class="section" id="dissemination-keys">
+<h1><a name="dissemination-keys">4 Dissemination Keys</a></h1>
<p>One issue that comes up when using this interfaces is the selection of
a key for each value. On one hand, using unique() is easy, but this
means that the keyspaces for two different compilations of the same
author might write something like this:</p>
<pre class="literal-block">
#include <disseminate_keys.h>
-configuration SomeComponentC {
+configuration SomeComponentC {
...
}
implementation {
#endif
components SomeComponentP;
components new DisseminatorC(uint8_t, DIS_SOME_COMPONENT_KEY);
- SomeComponentP.ConfigVal -> DisseminatorC;
+ SomeComponentP.ConfigVal -> DisseminatorC;
}
</pre>
<p>To override, you can then make a disseminate_keys.h in your app
binaries and not store them. This GUID won't be part of the external
interface, but will be used internally.</p>
</div>
-<div class="section">
-<h1><a id="more-complex-dissemination" name="more-complex-dissemination">5. More Complex Dissemination</a></h1>
+<div class="section" id="more-complex-dissemination">
+<h1><a name="more-complex-dissemination">5. More Complex Dissemination</a></h1>
<p>An application can use this low-level networking primitive to build
more complex dissemination systems. For example, if you want have a
dissemination that only nodes which satisfy a predicate receive, you
data value in it, and layering the predicate evaluation on top of the
above interfaces.</p>
</div>
-<div class="section">
-<h1><a id="implementation" name="implementation">6. Implementation</a></h1>
+<div class="section" id="implementation">
+<h1><a name="implementation">6. Implementation</a></h1>
<p>An implementation of this TEP can be found in
<tt class="docutils literal"><span class="pre">tinyos-2.x/tos/lib/net</span></tt>. This dissemination implementation uses
network trickles <a class="footnote-reference" href="#id3" id="id1" name="id1">[2]</a>. Each dissemination value has a separate
trickle.</p>
</div>
-<div class="section">
-<h1><a id="author-s-address" name="author-s-address">6. Author's Address</a></h1>
+<div class="section" id="author-s-address">
+<h1><a name="author-s-address">6. Author's Address</a></h1>
<div class="line-block">
<div class="line">Philip Levis</div>
<div class="line">358 Gates Hall</div>
<div class="line">email - <a class="reference" href="mailto:gtolle@archedrock.com">gtolle@archedrock.com</a></div>
</div>
</div>
-<div class="section">
-<h1><a id="citations" name="citations">7. Citations</a></h1>
+<div class="section" id="citations">
+<h1><a name="citations">7. Citations</a></h1>
<table class="docutils footnote" frame="void" id="id2" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
</table>
</div>
<div class="system-messages section">
-<h1>Docutils System Messages</h1>
+<h1><a>Docutils System Messages</a></h1>
<div class="system-message" id="id4">
<p class="system-message-title">System Message: <a name="id4">ERROR/3</a> (<tt class="docutils">txt/tep118.txt</tt>, line 116); <em><a href="#id5">backlink</a></em></p>
Unknown target name: "tep111".</div>
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.3.6: http://docutils.sourceforge.net/" />
<title>Collection</title>
<meta name="author" content="Rodrigo Fonseca, Omprakash Gnawali, Kyle Jamieson, and Philip Levis" />
<style type="text/css">
</style>
</head>
<body>
-<div class="document" id="collection">
<h1 class="title">Collection</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
</tr>
</tbody>
</table>
+<div class="document" id="collection">
<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
of this memo is unlimited. This memo is in full compliance with
TEP 1.</p>
</div>
-<div class="section">
-<h1><a id="abstract" name="abstract">Abstract</a></h1>
+<div class="section" id="abstract">
+<h1><a name="abstract">Abstract</a></h1>
<p>The memo documents the interfaces, components, and semantics used by
collection protocol in TinyOS 2.x. Collection provides a best-effort,
multihop delivery of packets to the root of <em>a</em> tree. There may be
are of <em>anycast</em> delivery to at least one of the roots. A node sending
a packet does not specify which root the packet is destined to.</p>
</div>
-<div class="section">
-<h1><a id="introduction" name="introduction">1. Introduction</a></h1>
+<div class="section" id="introduction">
+<h1><a name="introduction">1. Introduction</a></h1>
<p>Collecting data at a base station is a common requirement of sensor
network applications. The general approach used is to build one
or more collection <em>trees</em>, each of which is rooted at a base
-station. When a node has data which needs to be collected, it
+station. When a node has data which needs to be collected, it
sends the data up the tree, and it forwards collection data that
other nodes send to it. Sometimes, depending on the form of data
collection, systems need to be able to inspect packets as they go
by, either to gather statistics, compute aggregates, or suppress
redundant transmissions.</p>
<p>When a network has multiple base stations that act as <em>root</em> nodes,
-rather than one tree, it has a <em>forest</em> of trees. By picking a
+rather than one tree, it has a <em>forest</em> of trees. By picking a
parent node, a collection protocol implicitly joins one of these
trees. Collection provides a best-effort,
multihop delivery of packets to one of a network's tree roots:
it is an <em>anycast</em> protocol. The semantics is that the protocol
will make a reasonable effort to deliver the message to at least
-one of the roots in the network. There are however no guarantees of
+one of the roots in the network. There are however no guarantees of
delivery, and there can be duplicates delivered to one or more
roots. There is also no ordering guarantees.</p>
<p>Given the limited state that nodes can store and a general need
<ul class="simple">
<li>Loop detection, detecting when a node selects one of its
descendants as a new parent.</li>
-<li>Duplicate suppression, detecting and dealing with when lost
-acknowledgments are causing packets to replicate in the
+<li>Duplicate suppression, detecting and dealing with when lost
+acknowledgments are causing packets to replicate in the
network, wasting bandwidth.</li>
<li>Link estimation, evaluating the link quality to single-hop
neighbors.</li>
<p>The rest of this document describes a set of components and interfaces
for a collection service outlined above.</p>
</div>
-<div class="section">
-<h1><a id="collection-interfaces" name="collection-interfaces">2. Collection interfaces</a></h1>
+<div class="section" id="collection-interfaces">
+<h1><a name="collection-interfaces">2. Collection interfaces</a></h1>
<p>A node can perform four different roles in collection: producer,
consumer, snooper, and in-network processor. Depending on their role,
the nodes use different interfaces to interact with the collection
component.</p>
<p>A consumer is a root of a tree. The set of all roots and the paths that
lead to them form the collection routing infrastructure in the network.
-For any connected set of nodes implementing the collection protocol
-there is only one collection infrastructure, <em>i.e.</em>, all roots in this
+For any connected set of nodes implementing the collection protocol
+there is only one collection infrastructure, <em>i.e.</em>, all roots in this
set active at the same time are part of the same infrastructure.</p>
<p>A node is configured to become a root by using the RootControl
interface. RootControl.setRoot() MUST make the current node a root of
a packet. The collection identifier is specified as a parameter
to Intercept during instantiation.</p>
</div>
-<div class="section">
-<h1><a id="collection-services" name="collection-services">3 Collection Services</a></h1>
+<div class="section" id="collection-services">
+<h1><a name="collection-services">3 Collection Services</a></h1>
<p>A collection service MUST provide one component, CollectionC,
which has the following signature:</p>
<pre class="literal-block">
CollectionC SHOULD NOT configure a node as a root by default.</p>
<p>Packet and CollectionPacket allow components to access collection
data packet fields [<a class="reference" href="#id1">1</a>].</p>
-<div class="section">
-<h2><a id="collectionsenderc" name="collectionsenderc">3.1 CollectionSenderC</a></h2>
+<div class="section" id="collectionsenderc">
+<h2><a name="collectionsenderc">3.1 CollectionSenderC</a></h2>
<p>Collection has a virtualized sending abstraction, the generic
component CollectionSenderC:</p>
<pre class="literal-block">
based on its collection ID and contents.</p>
</div>
</div>
-<div class="section">
-<h1><a id="implementation" name="implementation">4 Implementation</a></h1>
+<div class="section" id="implementation">
+<h1><a name="implementation">4 Implementation</a></h1>
<p>An implementation of this TEP can be found in
<tt class="docutils literal"><span class="pre">tinyos-2.x/tos/lib/net/ctp</span></tt> and <tt class="docutils literal"><span class="pre">tinyos-2.x/tos/lib/net/le</span></tt>, in
the CTP protocol. It is beyond the scope of this document to fully
estimation are decoupled from the routing protocol. Furthermore, the
routing protocol and route selection are decoupled from the
forwarding policies, such as queueing and timing.</p>
-<div class="section">
-<h2><a id="linkestimatorp" name="linkestimatorp">4.1 LinkEstimatorP</a></h2>
+<div class="section" id="linkestimatorp">
+<h2><a name="linkestimatorp">4.1 LinkEstimatorP</a></h2>
<p>LinkEstimatorP estimates the quality of link to or from each
neighbor. Link estimation can be done in a variety of ways, and we
do not impose one here. It is decoupled from the establishment of
}
</pre>
</div>
-<div class="section">
-<h2><a id="ctproutingenginep" name="ctproutingenginep">4.2 CtpRoutingEngineP</a></h2>
+<div class="section" id="ctproutingenginep">
+<h2><a name="ctproutingenginep">4.2 CtpRoutingEngineP</a></h2>
<p>CtpRoutingEngineP is responsible for computing routes to the roots of a
tree. In traditional networking terminology, this is part of the
control plane of the network, and is does not directly forward any
-data packets, which is the responsibility of CtpForwardingEngine.
+data packets, which is the responsibility of CtpForwardingEngine.
The main interface between the two is UnicastNameFreeRouting.</p>
<p>CtpRoutingEngineP uses the LinkEstimator interface to learn
about the nodes in the neighbor table maintained by LinkEstimatorP and
the quality of links to and from the neighbors. The routing protocol
on which collection is implemented MUST be a tree-based routing
-protocol with a single or multiple roots. CtpRoutingEngineP
+protocol with a single or multiple roots. CtpRoutingEngineP
allows a node to be configured as a root or a non-root node
dynamically. CtpRoutingEngineP maintains multiple candidate next hops:</p>
<pre class="literal-block">
-generic module CtpRoutingEngineP(uint8_t routingTableSize,
- uint16_t minInterval,
+generic module CtpRoutingEngineP(uint8_t routingTableSize,
+ uint16_t minInterval,
uint16_t maxInterval) {
provides {
interface UnicastNameFreeRouting as Routing;
interface StdControl;
interface CtpRoutingPacket;
interface Init;
- }
+ }
uses {
interface AMSend as BeaconSend;
interface Receive as BeaconReceive;
}
</pre>
</div>
-<div class="section">
-<h2><a id="ctpforwardingenginep" name="ctpforwardingenginep">4.3 CtpForwardingEngineP</a></h2>
+<div class="section" id="ctpforwardingenginep">
+<h2><a name="ctpforwardingenginep">4.3 CtpForwardingEngineP</a></h2>
<p>The CtpForwardingEngineP component provides all the top level interfaces
-(except RootControl) which CollectionC provides and an application
+(except RootControl) which CollectionC provides and an application
uses. It deals with retransmissions, duplicate suppression, packet
timing, loop detection, and also informs the LinkEstimator of the
outcome of attempted transmissions.:</p>
</blockquote>
</div>
</div>
-<div class="section">
-<h1><a id="author-s-address" name="author-s-address">5. Author's Address</a></h1>
+<div class="section" id="author-addresses">
+<h1><a name="author-addresses">5. Author Addresses</a></h1>
<div class="line-block">
-<div class="line">Rodrigo Fonseca</div>
+<div class="line">Rodrigo Fonseca </div>
<div class="line">473 Soda Hall</div>
<div class="line">Berkeley, CA 94720-1776</div>
<div class="line"><br /></div>
<div class="line"><br /></div>
<div class="line"><br /></div>
<div class="line">Omprakash Gnawali</div>
-<div class="line">Ronald Tutor Hall (RTH) 418</div>
+<div class="line">Ronald Tutor Hall (RTH) 418 </div>
<div class="line">3710 S. McClintock Avenue</div>
-<div class="line">Los Angeles, CA 90089</div>
+<div class="line">Los Angeles, CA 90089 </div>
<div class="line"><br /></div>
<div class="line">phone - +1 213 821-5627</div>
<div class="line">email - <a class="reference" href="mailto:gnawali@usc.edu">gnawali@usc.edu</a></div>
<div class="line">Kyle Jamieson</div>
<div class="line">The Stata Center</div>
<div class="line">32 Vassar St.</div>
-<div class="line">Cambridge, MA 02139</div>
+<div class="line">Cambridge, MA 02139 </div>
<div class="line"><br /></div>
<div class="line">email - <a class="reference" href="mailto:jamieson@csail.mit.edu">jamieson@csail.mit.edu</a></div>
<div class="line"><br /></div>
<div class="line">email - <a class="reference" href="mailto:pal@cs.stanford.edu">pal@cs.stanford.edu</a></div>
</div>
</div>
-<div class="section">
-<h1><a id="citations" name="citations">6. Citations</a></h1>
+<div class="section" id="citations">
+<h1><a name="citations">6. Citations</a></h1>
<table class="docutils footnote" frame="void" id="id1" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<table class="docutils footnote" frame="void" id="id2" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
-<tr><td class="label"><a name="id2">[2]</a></td><td>TEP 124: The Collection Tree Protocol (CTP) - (upcoming)</td></tr>
+<tr><td class="label"><a name="id2">[2]</a></td><td>TEP 123: The Collection Tree Protocol (CTP)</td></tr>
</tbody>
</table>
</div>
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.3.6: http://docutils.sourceforge.net/" />
<title>TinyOS Alliance Structure</title>
-<meta name="authors" content="Philippe Bonnet David Culler Deborah Estrin Ramesh Govindan Mike Horton Jeonghoon Kang Philip Levis Lama Nachman Jack Stankovic Rob Szewczyk Matt Welsh Adam Wolisz" />
+<meta name="author" content="Philippe Bonnet" />
+<meta name="author" content="David Culler" />
+<meta name="author" content="Deborah Estrin" />
+<meta name="author" content="Ramesh Govindan" />
+<meta name="author" content="Mike Horton" />
+<meta name="author" content="Jeonghoon Kang" />
+<meta name="author" content="Philip Levis" />
+<meta name="author" content="Lama Nachman" />
+<meta name="author" content="Jack Stankovic" />
+<meta name="author" content="Rob Szewczyk" />
+<meta name="author" content="Matt Welsh" />
+<meta name="author" content="Adam Wolisz" />
<style type="text/css">
/*
</style>
</head>
<body>
-<div class="document" id="tinyos-alliance-structure">
<h1 class="title">TinyOS Alliance Structure</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<td>Draft</td></tr>
<tr class="field"><th class="docinfo-name">TinyOS-Version:</th><td class="field-body">All</td>
</tr>
-<tr><th class="docinfo-name">Authors:</th>
-<td>Philippe Bonnet
-<br />David Culler
-<br />Deborah Estrin
-<br />Ramesh Govindan
-<br />Mike Horton
-<br />Jeonghoon Kang
-<br />Philip Levis
-<br />Lama Nachman
-<br />Jack Stankovic
-<br />Rob Szewczyk
-<br />Matt Welsh
-<br />Adam Wolisz</td></tr>
+<tr><th class="docinfo-name">Author:</th>
+<td>Philippe Bonnet</td></tr>
+<tr><th class="docinfo-name">Author:</th>
+<td>David Culler</td></tr>
+<tr><th class="docinfo-name">Author:</th>
+<td>Deborah Estrin</td></tr>
+<tr><th class="docinfo-name">Author:</th>
+<td>Ramesh Govindan</td></tr>
+<tr><th class="docinfo-name">Author:</th>
+<td>Mike Horton</td></tr>
+<tr><th class="docinfo-name">Author:</th>
+<td>Jeonghoon Kang</td></tr>
+<tr><th class="docinfo-name">Author:</th>
+<td>Philip Levis</td></tr>
+<tr><th class="docinfo-name">Author:</th>
+<td>Lama Nachman</td></tr>
+<tr><th class="docinfo-name">Author:</th>
+<td>Jack Stankovic</td></tr>
+<tr><th class="docinfo-name">Author:</th>
+<td>Rob Szewczyk</td></tr>
+<tr><th class="docinfo-name">Author:</th>
+<td>Matt Welsh</td></tr>
+<tr><th class="docinfo-name">Author:</th>
+<td>Adam Wolisz</td></tr>
<tr class="field"><th class="docinfo-name">Draft-Created:</th><td class="field-body">17-April-2006</td>
</tr>
-<tr class="field"><th class="docinfo-name">Draft-Version:</th><td class="field-body">1.1.2.5</td>
+<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">2006-10-25</td>
+<tr class="field"><th class="docinfo-name">Draft-Modified:</th><td class="field-body">2006-12-12</td>
</tr>
<tr class="field"><th class="docinfo-name">Draft-Discuss:</th><td class="field-body">TinyOS Alliance <tinyos-alliance at mail.millennium.berkeley.edu></td>
</tr>
</tbody>
</table>
+<div class="document" id="tinyos-alliance-structure">
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">This memo documents a blueprint for an open alliance aroung
of this memo is unlimited. This memo is in full compliance with
TEP 1.</p>
</div>
-<div class="section">
-<h1><a id="abstract" name="abstract">Abstract</a></h1>
+<div class="section" id="abstract">
+<h1><a name="abstract">Abstract</a></h1>
<p>This memo describes the goals and organization structure of the TinyOS Alliance.
It covers membership, the working group forums for contribution, intellectual
property, source licensing, and the TinyOS Steering Committee (TSC).</p>
</div>
-<div class="section">
-<h1><a id="charter" name="charter">1. Charter</a></h1>
+<div class="section" id="charter">
+<h1><a name="charter">1. Charter</a></h1>
<!-- TinyOS Alliance Charter:: -->
<p>Formulate a legal and organizational framework for an alliance that
can facilitate the continued advancement of the open embedded network
ecosystem around TinyOS and support the activities, interactions, and
development of the worldwide academic and industrial TinyOS community.</p>
</div>
-<div class="section">
-<h1><a id="overview" name="overview">2. Overview</a></h1>
-<p>This memo defines a blueprint and conceptual foundation for an open
-alliance that fulfills the above charter.
+<div class="section" id="overview">
+<h1><a name="overview">2. Overview</a></h1>
+<p>This memo defines a blueprint and conceptual foundation for an open
+alliance that fulfills the above charter.
It defines the following ten aspects of the alliance:</p>
<blockquote>
<ul class="simple">
<li>Work products</li>
</ul>
</blockquote>
-<p>We (the Alliance) recognize that each of these aspects contributes to the
-whole, is inter-related and needs to be consistent overall. This document
-attempts to address them sequentially, recognizing that each depends on the
+<p>We (the Alliance) recognize that each of these aspects contributes to the
+whole, is inter-related and needs to be consistent overall. This document
+attempts to address them sequentially, recognizing that each depends on the
others. It draws on lessons from several related
organizations, although each of these also has significantly
different goals from those set out in the charter.</p>
<li>OSGI - Service layer</li>
<li>FSF - Foundational software</li>
</ol>
-<p>We (the Alliance) draw most strongly upon the IETF, even though that
+<p>We (the Alliance) draw most strongly upon the IETF, even though that
organization was
focused around creating and standardizing protocols, rather than
developing a code base. Its emphasis on rough consensus AND
might pull IP into the pool. We prefer a process of declaration and
multiple implementation.</p>
</div>
-<div class="section">
-<h1><a id="mission" name="mission">3. Mission</a></h1>
+<div class="section" id="mission">
+<h1><a name="mission">3. Mission</a></h1>
<p>The mission of the TinyOS Alliance is to provide a forum to facilitate:</p>
<blockquote>
<ul class="simple">
standard interfaces and protocols, vetted extensions, open reference
implementations, technical documents, testing and verification suites,
and educational materials,</li>
-<li>the contribution of innovative technology from a world-wide research
+<li>the contribution of innovative technology from a world-wide research
community and the maturation and dissemination of these
contributions, and</li>
-<li>the promotion of the technology, the community, and the impact of networked
+<li>the promotion of the technology, the community, and the impact of networked
embedded systems.</li>
</ul>
</blockquote>
</div>
-<div class="section">
-<h1><a id="organizational-structure" name="organizational-structure">4. Organizational Structure</a></h1>
+<div class="section" id="organizational-structure">
+<h1><a name="organizational-structure">4. Organizational Structure</a></h1>
<p>The Alliance has a technical advisory function: guide the evolution of
the TinyOS architecture, formulate and track progress of working
groups, and provide an open and impartial process for technical
-documentation. It also has an organizational advisory function: manage
+documentation. It also has an organizational advisory function: manage
industry
interaction, legal and IP issues, evolution of the organization
itself, membership issues and so on.</p>
Directors, a small support staff (primarily volunteer or outsourced)
and a Steering Committee. The Steering Committee oversees a collection
of Working Groups, each with a Chair and Members.</p>
-<div class="section">
-<h2><a id="steering-committee" name="steering-committee">4.1 Steering Committee</a></h2>
+<div class="section" id="steering-committee">
+<h2><a name="steering-committee">4.1 Steering Committee</a></h2>
<p>In the steady state the Steering Committee will consist of the chairs
of working groups plus a handful of elected members at large. Tenure
of a position on the Steering Committee will consist of two years with
access to code repositories and Alliance web sites, and regular
Alliance meetings.</p>
</div>
-<div class="section">
-<h2><a id="working-groups" name="working-groups">4.2 Working Groups</a></h2>
+<div class="section" id="working-groups">
+<h2><a name="working-groups">4.2 Working Groups</a></h2>
<p>The working groups form the core of the alliance. Each working
group will have a chair who will be responsible for WG processes,
reporting, meetings, and membership. Working groups and their
functions are discussed in more detail in a later section.</p>
</div>
-<div class="section">
-<h2><a id="board-of-directors" name="board-of-directors">4.3 Board of Directors</a></h2>
+<div class="section" id="board-of-directors">
+<h2><a name="board-of-directors">4.3 Board of Directors</a></h2>
<p>The non-profit will require a Board of Directors responsible for
corporate matters.</p>
</div>
</div>
-<div class="section">
-<h1><a id="membership-and-participation" name="membership-and-participation">5. Membership and Participation</a></h1>
+<div class="section" id="membership-and-participation">
+<h1><a name="membership-and-participation">5. Membership and Participation</a></h1>
<p>We desire to continue the TinyOS tradition of promoting broad
membership. This means that we want to keep barriers to entry low in
all respects: legal, financial, and organizational. As with IETF and
Apache, we want to shape the organization as a meritocracy that
-encourages, promotes, and credits the contributions of its members.
+encourages, promotes, and credits the contributions of its members.
Companies have essential role, but merit, not finances should
dictate direction. Membership and influence should recognize the
importance of adopters, not just developers.</p>
</blockquote>
<p>There is no individual membership fee, but members will be responsible for
nominal registration fees at Alliance meetings.</p>
-<p>Corporations and organizational have institutional membership, which reflects
+<p>Corporations and organizational have institutional membership, which reflects
their degree of effort.</p>
<blockquote>
<ul class="simple">
institutions, or unaffiliated. We will provide a fee structure that encourages
the participation of small companies and start-ups.</p>
</div>
-<div class="section">
-<h1><a id="id1" name="id1">6. Working Groups</a></h1>
+<div class="section" id="id1">
+<h1><a name="id1">6. Working Groups</a></h1>
<p>There will be two forms of working groups. LONG-STANDING
groups are chartered to develop important areas or subsystems. For
-example, we expect longstanding groups on
+example, we expect longstanding groups on
routing, management, platforms, testing, programming tools, and
education. SHORT-TERM groups have a fixed mandate to tackle a
particular topic. For example, there may be groups to develop a
allow for multiple, interoperable implementations.
The Steering committee will be engaged in ratification of standards.</p>
</div>
-<div class="section">
-<h1><a id="intellectual-property" name="intellectual-property">7. Intellectual Property</a></h1>
+<div class="section" id="intellectual-property">
+<h1><a name="intellectual-property">7. Intellectual Property</a></h1>
<p>In general we want to promote the development, adoption and use of
open technology. We want to avoid having the advancement of embedded
networks getting trapped into proprietary IP. Accordingly, our IP
development tools, such as the compilers and peripheral Linux-based
devices.</p>
</div>
-<div class="section">
-<h1><a id="source-licensing" name="source-licensing">8. Source Licensing</a></h1>
+<div class="section" id="source-licensing">
+<h1><a name="source-licensing">8. Source Licensing</a></h1>
<p>In general, we want to provide a mechanism where individuals and
companies can easily contribute source, can utilize what is available,
and can gain recognition for their efforts. Following the TinyOS
of standardized interfaces and protocols. Alliance is not the only
vehicle for producing a hardened, tested, certified code base.
To do so would require the Alliance host a large technical staff, as
-OSDL does.
+OSDL does.
Comapanies may do so, or produce implementations with enhanced
performance, reliability, or efficiency using their own proprietary
technology. The Alliance encourages such innovation while promoting
standardized interfaces that allows such technology to interoperate.</p>
</div>
-<div class="section">
-<h1><a id="funding" name="funding">9. Funding</a></h1>
+<div class="section" id="funding">
+<h1><a name="funding">9. Funding</a></h1>
<p>Initially, we expect that there are no full time employees in the
Alliance and that funding needs are limited to such items as lawyer's
fees, web site costs, and insurance. If the Alliance eventually
to avoid the heavy-handed quid-pro-quo seen in many industrial
consortiums where funding determines influence. The best use of funds
and the best form of influence is direct contribution to the work
-products of the Alliance.
+products of the Alliance.
To keep the structure of the Alliance and its operations minimalist
and lean, membership focuses on desired impact and recognition, rather
than control. We want the best way to influence the direction of the Alliance
-to be to contribute technical work and demonstrate leadership, rather than
+to be to contribute technical work and demonstrate leadership, rather than
try to control what individuals can or cannot contribute.</p>
<p>Companies and institutions are encouraged to contribute financial and
in-kind support. It will be essential that companies provide initial
funding to create the legal structure and to establish basic IT
capabilities to host the web site and working groups.
Institutional members
-will pay an annual membership fee. In some cases, a
+will pay an annual membership fee. In some cases, a
contributing corporate member may provide in-kind services
such as lawyers' time used to
-draw up or comment on by-laws.
+draw up or comment on by-laws.
Targeted contributions will be
-solicited and encouraged. In this case the donator need not
+solicited and encouraged. In this case the donator need not
become a contributing corporate member, e.g., in those cases
where such a membership may be prohibited or unwanted.
The costs of meetings, such as the TinyOS
technology exchange, will be covered through registration fees and
not by institutional membership fees.</p>
</div>
-<div class="section">
-<h1><a id="work-products" name="work-products">10. Work Products</a></h1>
-<p>The broad mission of the Alliance calls for a broad range of
+<div class="section" id="work-products">
+<h1><a name="work-products">10. Work Products</a></h1>
+<p>The broad mission of the Alliance calls for a broad range of
work products.</p>
<p>Foremost among these are a set of TEPs documenting
systems and protocols as well as TEPs that provide guidance
use, refine, improve, and discuss. These reference implementations
will not preclude alternative, compatibile implementations which may
have additional features or optimizations. The Alliance Working Groups
-will periodically produce periodic releases of these reference
+will periodically produce periodic releases of these reference
implementations for the community to use and improve.</p>
<p>The Alliance will support community contributions
-of innovative extensions and systems by providing a CVS repository
+of innovative extensions and systems by providing a CVS repository
to store them.
In order to keep these contributions organized for users, the
Steering Committee may nominate one or more people to caretake
is to teach new developers about the internals and workings of
the technology, the Alliance will develop and make available
several end-user applications and tools. The goal is to improve
-the accessibility of the technology to end-users while
+the accessibility of the technology to end-users while
demonstrating its effectiveness. Historical examples of such applications
include Surge and TinyDB. An important part of this effort is
good documentation for users who are not expert programmers, as well
as tools and graphical environments.</p>
</div>
-<div class="section">
-<h1><a id="conclusions" name="conclusions">11. Conclusions</a></h1>
-<p>By focusing on consensus building and technical excellence, the
+<div class="section" id="conclusions">
+<h1><a name="conclusions">11. Conclusions</a></h1>
+<p>By focusing on consensus building and technical excellence, the
Alliance seeks to avoid being a forum for political and economic
positioning. It will achieve this by focusing on working groups
-and the contributions of individuals, while not taking strong
+and the contributions of individuals, while not taking strong
positions on the benefits or drawbacks of different approaches.
The variety of application domains sensornets are used in and
-the huge differences in requirements mean that having a suite
+the huge differences in requirements mean that having a suite
of solutions, rather than a single one, is often not only
desirable but essential.</p>
<p>Over the past five years, low-power embedded sensor networks have
industry, making advances quickly accessible and usable. A great
catalyst to this growth has been the presence of a large community
around a shared, free code base.</p>
-<p>The time has come to create an organizational structure to
+<p>The time has come to create an organizational structure to
allow the effort to grow further. As sensornets become more widespread,
contributions and advancements will be from an increasingly broad
demographic of users, and bringing them all together will speed
set of expectations that will encourage the exchange of ideas and
technology.</p>
</div>
-<div class="section">
-<h1><a id="author-s-address" name="author-s-address">12. Author's Address</a></h1>
+<div class="section" id="author-s-address">
+<h1><a name="author-s-address">12. Author's Address</a></h1>
<div class="line-block">
-<div class="line">Philippe Bonnet <<a class="reference" href="mailto:bonnet.p@gmail.com">bonnet.p@gmail.com</a>></div>
-<div class="line">David Culler <<a class="reference" href="mailto:culler@cs.berkeley.edu">culler@cs.berkeley.edu</a>></div>
+<div class="line">Philippe Bonnet <<a class="reference" href="mailto:bonnet.p@gmail.com">bonnet.p@gmail.com</a>> </div>
+<div class="line">David Culler <<a class="reference" href="mailto:culler@cs.berkeley.edu">culler@cs.berkeley.edu</a>> </div>
<div class="line">David Culler <dculler at archrock.com>,</div>
-<div class="line">Deborah Estrin <<a class="reference" href="mailto:destrin@cs.ucla.edu">destrin@cs.ucla.edu</a>></div>
-<div class="line">Ramesh Govindan <<a class="reference" href="mailto:ramesh@usc.edu">ramesh@usc.edu</a>></div>
-<div class="line">Mike Horton <<a class="reference" href="mailto:mhorton@xbow.com">mhorton@xbow.com</a>></div>
-<div class="line">Jeonghoon Kang <<a class="reference" href="mailto:budge@keti.re.kr">budge@keti.re.kr</a>></div>
+<div class="line">Deborah Estrin <<a class="reference" href="mailto:destrin@cs.ucla.edu">destrin@cs.ucla.edu</a>> </div>
+<div class="line">Ramesh Govindan <<a class="reference" href="mailto:ramesh@usc.edu">ramesh@usc.edu</a>> </div>
+<div class="line">Mike Horton <<a class="reference" href="mailto:mhorton@xbow.com">mhorton@xbow.com</a>> </div>
+<div class="line">Jeonghoon Kang <<a class="reference" href="mailto:budge@keti.re.kr">budge@keti.re.kr</a>> </div>
<div class="line">Philip Levis <<a class="reference" href="mailto:pal@cs.stanford.edu">pal@cs.stanford.edu</a>></div>
<div class="line">Lama Nachman <<a class="reference" href="mailto:lama.nachman@intel.com">lama.nachman@intel.com</a>></div>
<div class="line">Jack Stankovic <<a class="reference" href="mailto:stankovic@cs.virginia.edu">stankovic@cs.virginia.edu</a>></div>
-<div class="line">Rob Szewczyk <<a class="reference" href="mailto:rob@moteiv.com">rob@moteiv.com</a>></div>
-<div class="line">Matt Welsh <<a class="reference" href="mailto:mdw@cs.harvard.edu">mdw@cs.harvard.edu</a>></div>
-<div class="line">Adam Wolisz <<a class="reference" href="mailto:awo@ieee.org">awo@ieee.org</a>></div>
+<div class="line">Rob Szewczyk <<a class="reference" href="mailto:rob@moteiv.com">rob@moteiv.com</a>> </div>
+<div class="line">Matt Welsh <<a class="reference" href="mailto:mdw@cs.harvard.edu">mdw@cs.harvard.edu</a>> </div>
+<div class="line">Adam Wolisz <<a class="reference" href="mailto:awo@ieee.org">awo@ieee.org</a>> </div>
</div>
</div>
</div>
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.3.6: http://docutils.sourceforge.net/" />
<title>Towards TinyOS for 8051</title>
<meta name="author" content="Anders Egeskov Petersen, Sidsel Jensen, Martin Leopold" />
<style type="text/css">
</style>
</head>
<body>
-<div class="document" id="towards-tinyos-for-8051">
<h1 class="title">Towards TinyOS for 8051</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
</tr>
</tbody>
</table>
+<div class="document" id="towards-tinyos-for-8051">
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">This memo is informational. It will hopefully be a basis for
discussions and suggestions for improvements. Distribution of this
memo is unlimited. This memo is in full compliance with TEP 1.</p>
</div>
-<div class="section">
-<h1><a id="abstract" name="abstract">Abstract</a></h1>
+<div class="section" id="abstract">
+<h1><a name="abstract">Abstract</a></h1>
<p>This TEP covers our effort of porting <a class="reference" href="http://www.tinyos.net">TinyOS</a> to the nRF24E1
platform. We ported the basic modules of TinyOS: Timer, UART, ADC and
LEDS.</p>
</div>
-<div class="section">
-<h1><a id="project-outline" name="project-outline">1. Project Outline</a></h1>
+<div class="section" id="project-outline">
+<h1><a name="project-outline">1. Project Outline</a></h1>
<p>The original 8 bit 8051 chip is a member of the <a class="reference" href="http://www.intel.com/design/mcs51">mcs51 family</a> and
was developed in 1980 by Intel. It is still to this date one of the most
widely used microcontrollers. Porting TinyOS to the 8051 System on chip
<p>This work was done under the supervision of Martin Leopold at University
of Copenhagen.</p>
</div>
-<div class="section">
-<h1><a id="project-approach" name="project-approach">2. Project Approach</a></h1>
+<div class="section" id="project-approach">
+<h1><a name="project-approach">2. Project Approach</a></h1>
<p>The approach to the porting project has been pragmatic. The focus has
been on producing working code, so testing and debugging have been key
elements of our work. The process has been to implement new
</dd>
</dl>
</div>
-<div class="section">
-<h1><a id="development-environment-and-tool-chain" name="development-environment-and-tool-chain">3. Development Environment and Tool Chain</a></h1>
+<div class="section" id="development-environment-and-tool-chain">
+<h1><a name="development-environment-and-tool-chain">3. Development Environment and Tool Chain</a></h1>
<p>The following subsections describe the different development tools,
their selection and interconnection.</p>
-<div class="section">
-<h2><a id="selection-of-development-tools-compilers" name="selection-of-development-tools-compilers">3.1 Selection of Development Tools/Compilers</a></h2>
+<div class="section" id="selection-of-development-tools-compilers">
+<h2><a name="selection-of-development-tools-compilers">3.1 Selection of Development Tools/Compilers</a></h2>
<p>A large number of 8051 compilers exist primarily for the DOS and Windows
platforms. We have focused on two popular and regularly updated
compilers: <a class="reference" href="http://www.keil.com">KEIL</a> and the Small Device C Compiler (SDCC).</p>
kit. This gave us a working debug environment - with minimal change to
the already produced code.</p>
</div>
-<div class="section">
-<h2><a id="our-recommendation" name="our-recommendation">3.1.1 Our Recommendation</a></h2>
+<div class="section" id="our-recommendation">
+<h2><a name="our-recommendation">3.1.1 Our Recommendation</a></h2>
<p>In our experience the SDCC compiler and associated tools are not yet
mature enough to support our development. We recommend pursuing other
alternatives such as KEIL or other compiler suites.</p>
the use of open source software and cross-platform development. We hope
SDCC will prove an reliable alternative in the future.</p>
</div>
-<div class="section">
-<h2><a id="tool-chain-overview" name="tool-chain-overview">3.2 Tool Chain Overview</a></h2>
+<div class="section" id="tool-chain-overview">
+<h2><a name="tool-chain-overview">3.2 Tool Chain Overview</a></h2>
<p>The following figure and sections are an overview of the current tool
chain. The tool chain is based on TinyOS 1.x, NesC 1.1.3, avr-gcc 3.4.3,
PERL v. 5.8.6 and SDCC 2.5.4 or KEIL C51 version 7.20.</p>
<pre class="literal-block">
Mangle-
TinyOS script
------> app.c -----> app_mangled.c --------> app.hex ------> nRF24E1
+-----> app.c -----> app_mangled.c --------> app.hex ------> nRF24E1
NesC PERL SDCC/KEIL nRFPROG
</pre>
</div>
-<div class="section">
-<h2><a id="description-of-the-tool-chain" name="description-of-the-tool-chain">3.3 Description of the Tool Chain</a></h2>
+<div class="section" id="description-of-the-tool-chain">
+<h2><a name="description-of-the-tool-chain">3.3 Description of the Tool Chain</a></h2>
<p>The compilation of the TinyOS test program outputs two files, a
'main.exe' file and an 'app.c' file. The 'app.c' file contains all the
needed code to run the TinyOS application. However the C code produced
produces a hex file that is transferred to the chip by the nRFPROG
software.</p>
</div>
-<div class="section">
-<h2><a id="description-of-the-mangling-script" name="description-of-the-mangling-script">3.4 Description of the Mangling Script</a></h2>
+<div class="section" id="description-of-the-mangling-script">
+<h2><a name="description-of-the-mangling-script">3.4 Description of the Mangling Script</a></h2>
<p>The mangling script is written in PERL, a commonly used general purpose
scripting language with powerful pattern matching capabilities and
extensive handling of regular expressions. The mangle script handles all
</dl>
<p>or</p>
<dl class="docutils">
-<dt>"./sdccMangleAppC.pl -SDCC -file build/mcs51/app.c ></dt>
+<dt>"./sdccMangleAppC.pl -SDCC -file build/mcs51/app.c > </dt>
<dd>build/mcs51/app_mangled.c"</dd>
</dl>
<p>The 'sdccMangleAppC.pl' script handles a number of needed alterations:</p>
</blockquote>
<p>Each of these alterations will be explained in the sections below.</p>
</div>
-<div class="section">
-<h2><a id="sfr-and-sbit-declarations" name="sfr-and-sbit-declarations">3.4.1 SFR and SBIT Declarations</a></h2>
+<div class="section" id="sfr-and-sbit-declarations">
+<h2><a name="sfr-and-sbit-declarations">3.4.1 SFR and SBIT Declarations</a></h2>
<p>In order to make TinyOS accept the 8051 special function registers (SFR)
and special bit variables (SBIT), we have included them into the TinyOS
8051 platform folder as a 8051.h file.</p>
<p>In order to make TinyOS accept the SFRs we have type defined them in the
NesC code as:</p>
<blockquote>
-typedef int sfr;
+typedef int sfr;
sfr P0 __attribute((x80));</blockquote>
<p>which is altered to</p>
<blockquote>
to SDCC, but it produces code with illegal syntax, so either do not use
it, or alter it to produce code with the right syntax.</p>
</div>
-<div class="section">
-<h2><a id="sdcc-keil-data-types" name="sdcc-keil-data-types">3.4.2 SDCC/KEIL Data Types</a></h2>
+<div class="section" id="sdcc-keil-data-types">
+<h2><a name="sdcc-keil-data-types">3.4.2 SDCC/KEIL Data Types</a></h2>
<p>TinyOS and SDCC/KEIL do not support the same data types, so some
alterations were needed to compile the code with SDCC and KEIL.</p>
<dl class="docutils">
very small hardware memory model, we decided to change the NesC 64 bit
data types to 32 bit. This is done in the mangling script.</p>
</div>
-<div class="section">
-<h2><a id="reserved-keywords-in-sdcc" name="reserved-keywords-in-sdcc">3.4.3 Reserved Keywords in SDCC</a></h2>
+<div class="section" id="reserved-keywords-in-sdcc">
+<h2><a name="reserved-keywords-in-sdcc">3.4.3 Reserved Keywords in SDCC</a></h2>
<p>A number of keywords are reserved in SDCC. Half of them represent a
directive to the compiler, defining which memory segment on the nRF24E1
the specific lines of code refer to. To ensure that the developer does
KEIL it can be changed through selecting it in the options pane for the
target.</p>
</div>
-<div class="section">
-<h2><a id="removal-of-inlining" name="removal-of-inlining">3.4.4 Removal of inlining</a></h2>
+<div class="section" id="removal-of-inlining">
+<h2><a name="removal-of-inlining">3.4.4 Removal of inlining</a></h2>
<p>NesC assumes that GCC is being used for the final compilation. GCC
supports inline functions and can be made to optimize code quite
aggressively, so the code generated by NesC does not need to be very
efficient. Unfortunately SDCC does not support code inlining, so the
inline statements have to be removed, when compiling for SDCC.</p>
<p>Lines with the following format are affected:</p>
-<p>static inline void TOSH_sleep(void );
+<p>static inline void TOSH_sleep(void );
static __inline void TOSH_SET_RED_LED_PIN(void);
__inline void__nesc_enable_interrupt(void);</p>
-<p>Lines with the noinline attribute is substituted with the
+<p>Lines with the noinline attribute is substituted with the
#pragma NO_INLINE.</p>
</div>
-<div class="section">
-<h2><a id="removal-of-preprocessor-line-numbering" name="removal-of-preprocessor-line-numbering">3.4.5 Removal of Preprocessor Line Numbering</a></h2>
+<div class="section" id="removal-of-preprocessor-line-numbering">
+<h2><a name="removal-of-preprocessor-line-numbering">3.4.5 Removal of Preprocessor Line Numbering</a></h2>
<p>Also NesC produce preprocessor line number meta data, to allow the
compiler to report error messages referring to the original code. We do
not really need them for anything, so we filter them out to minimize the
debug purposes the regular expression in the mangle script which remove
them can be commented out.</p>
</div>
-<div class="section">
-<h2><a id="change-in-identifiers" name="change-in-identifiers">3.4.6 Change $ in Identifiers</a></h2>
+<div class="section" id="change-in-identifiers">
+<h2><a name="change-in-identifiers">3.4.6 Change $ in Identifiers</a></h2>
<p>The SDCC compiler is very strict when it comes to valid symbols in
identifiers. NesC produce GCC-code which inserts $ as a separator
character in identifiers. We mangle the $ to two underscores in order to
enable SDCC/KEIL to compile.</p>
</div>
-<div class="section">
-<h2><a id="interrupt-vectors" name="interrupt-vectors">3.4.7 Interrupt Vectors</a></h2>
+<div class="section" id="interrupt-vectors">
+<h2><a name="interrupt-vectors">3.4.7 Interrupt Vectors</a></h2>
<p>The syntax for declaration of interrupt vectors are different in GCC and
SDCC/KEIL. So we mangle the interrupt declaration:</p>
-<p>From: void __attribute((interrupt)) __vector_5(void)
+<p>From: void __attribute((interrupt)) __vector_5(void)
To: void __vector_5(void) interrupt 5</p>
<p>Additionally KEIL does not understand that the interrupt vector is
defined previous to its use. So we remove the forward declaration of the
vectors in the mangle script, when compiling for KEIL.</p>
</div>
</div>
-<div class="section">
-<h1><a id="tinyos-modifications" name="tinyos-modifications">4. TinyOS Modifications</a></h1>
+<div class="section" id="tinyos-modifications">
+<h1><a name="tinyos-modifications">4. TinyOS Modifications</a></h1>
<p>TinyOS is based on modules with different levels of hardware
abstraction. When porting TinyOS to a new platform, you change the
underlying hardware dependencies in TinyOS, and you have to rebuild the
interrupt handling.</p>
<p>Modified TinyOS modules overview:</p>
<pre class="literal-block">
-+------------------------------------------------------------+
++------------------------------------------------------------+
| TinyOS Application | App
-+------------------------------------------------------------+
++------------------------------------------------------------+
\/ /\ \/ /\ \/ /\ \/ /\ -----
-+----------+ +----------+ +---------+ +--------+
++----------+ +----------+ +---------+ +--------+
| Timer | | UART | | ADC | | LEDs | HAL
+----------+ +----------+ +---------+ +--------+
\/ /\ \/ /\ \/ /\ -----
++----------+ +---------------------+ +---------+
+| HPLClock | | HPLUART | | HPLADC | \/ HPL
+----------+ +---------------------+ +---------+
-| HPLClock | | HPLUART | | HPLADC | \/ HPL
-+----------+ +---------------------+ +---------+
- \/ /\ \/ \/ /\ \/ /\ -----
-+----------+ +--------+ +--------+ +---------+ +--------+
-| Timer2 | | Timer1 | > | Serial | | Sensors | | Port | HW
-+----------+ +--------+ | Port | +---------+ +--------+
+ \/ /\ \/ \/ /\ \/ /\ -----
++----------+ +--------+ +--------+ +---------+ +--------+
+| Timer2 | | Timer1 | > | Serial | | Sensors | | Port | HW
++----------+ +--------+ | Port | +---------+ +--------+
+--------+
</pre>
<p>The following sections describe the changes to the four groups of modules.</p>
-<div class="section">
-<h2><a id="hplclock-and-related-modules" name="hplclock-and-related-modules">4.1 HPLClock and related modules</a></h2>
+<div class="section" id="hplclock-and-related-modules">
+<h2><a name="hplclock-and-related-modules">4.1 HPLClock and related modules</a></h2>
<p>The 8051 chip has three independent timer/counter circuits: Timer0,
Timer1 and Timer2, which can run in various modes. Each timer/counter
consists of a 16-bit register that is accessible to software as three
which would result in a great deal of interrupts and consume processing
power for administrational overhead.</p>
</div>
-<div class="section">
-<h2><a id="timer" name="timer">4.1.1 Timer</a></h2>
+<div class="section" id="timer">
+<h2><a name="timer">4.1.1 Timer</a></h2>
<p>The Timer module (HAL) uses the HPLClock module to handle the hardware
timing. These two modules communicate through the clock interface.
However, the standard TinyOS clock interface is designed for an MCU with
for the reduced prescaler options, we decided to widen the clock
interface from 8 to 16 bit. We are using the factor 1/4 for the
prescaler.</p>
-<p>The interface change has affected the following methods:
-result_t setRate(uint16_t interval, char scale)
-void setInterval(uint16_t value)
-void setNextInterval(uint16_t value)
+<p>The interface change has affected the following methods:
+result_t setRate(uint16_t interval, char scale)
+void setInterval(uint16_t value)
+void setNextInterval(uint16_t value)
uint16_t getInterval()
result_t setIntervalAndScale(uint16_t interval, uint8_t scale)
-uint16_t readCounter()
+uint16_t readCounter()
void setCounter(uint16_t n)</p>
<dl class="docutils">
-<dt>See:</dt>
-<dd>Clock.h
-Clock.nc
-HPLClock.nc
-TimerM.nc
-TimerC.nc
+<dt>See: </dt>
+<dd>Clock.h
+Clock.nc
+HPLClock.nc
+TimerM.nc
+TimerC.nc
8051.h</dd>
</dl>
</div>
-<div class="section">
-<h2><a id="hpluart" name="hpluart">4.2 HPLUART</a></h2>
+<div class="section" id="hpluart">
+<h2><a name="hpluart">4.2 HPLUART</a></h2>
<p>The UART is depending on a timer to generate a baud rate for the serial
port. The architecture only allows two of the three timers (Timer1 or
Timer2), to act as such. Since Timer2 is already used by the clock
sent. The HPLUART interrupt handler was also modified to take the
multiple byte data into account.</p>
<dl class="docutils">
-<dt>See:</dt>
-<dd>8051.h
-HPLUART.nc
-HPLUARTC.nc
+<dt>See: </dt>
+<dd>8051.h
+HPLUART.nc
+HPLUARTC.nc
HPLUARTM.nc</dd>
</dl>
</div>
-<div class="section">
-<h2><a id="hpladc" name="hpladc">4.3 HPLADC</a></h2>
+<div class="section" id="hpladc">
+<h2><a name="hpladc">4.3 HPLADC</a></h2>
<p>The TinyOS standard ADC interface was developed for the AVR which
includes hardware functionality for repetitive sampling at a given
interval. Implementing this functionality on the 8051, which does not
not to implement repetitive sampling, therefore the setSampleRate method
currently has no use.</p>
<dl class="docutils">
-<dt>See:</dt>
-<dd>8051.h
-ADCM.nc
-HPLADCC.nc
+<dt>See: </dt>
+<dd>8051.h
+ADCM.nc
+HPLADCC.nc
HPLADCM.nc</dd>
</dl>
</div>
-<div class="section">
-<h2><a id="leds" name="leds">4.4 LEDS</a></h2>
+<div class="section" id="leds">
+<h2><a name="leds">4.4 LEDS</a></h2>
<p>TinyOS features three standard LEDs (Red, Green and Yellow), but the
nRF24E1 evaluation board is not equipped with programmable LEDs so we
used the general purpose ports (GPIO).</p>
<p>To visualize the status of the GPIO, including the three standard LEDs,
we built a LED expansion board.</p>
<dl class="docutils">
-<dt>The three LEDs are currently wired to:</dt>
-<dd>Red -> P1.0
+<dt>The three LEDs are currently wired to: </dt>
+<dd>Red -> P1.0
Green -> P1.1
Yellow -> P0.7.</dd>
-<dt>See:</dt>
-<dd>8051.h
-hardware.h
-mcs51hardware.h
+<dt>See: </dt>
+<dd>8051.h
+hardware.h
+mcs51hardware.h
LedsC.nc</dd>
</dl>
</div>
-<div class="section">
-<h2><a id="interrupts" name="interrupts">4.5 Interrupts</a></h2>
+<div class="section" id="interrupts">
+<h2><a name="interrupts">4.5 Interrupts</a></h2>
<p>In TinyOS interrupts are not implemented as a single module, they are
mainly facilitated in atomic blocks and in the init, start and stop
methods of the various HPL modules. The init, start and stop methods
This is used to avoid preempting code execution in critical blocks.</p>
</div>
</div>
-<div class="section">
-<h1><a id="conclusion" name="conclusion">5. Conclusion</a></h1>
+<div class="section" id="conclusion">
+<h1><a name="conclusion">5. Conclusion</a></h1>
<p>The project have reached a plateau of development in porting TinyOS to
the 8051 platform, on which future development can be based. The basic
modules (Timer, UART, ADC and LEDS) have been implemented making 8051
<p>The result of our work will be uploaded to the TinyOS 8051 Working Group
website.</p>
</div>
-<div class="section">
-<h1><a id="future-work" name="future-work">6. Future Work</a></h1>
+<div class="section" id="future-work">
+<h1><a name="future-work">6. Future Work</a></h1>
<p>The work presented in this TEP is short of being a complete porting of
TinyOS to the 8051 platform. Two obvious future tasks are implementing a
Radio module involving the SPI interface and Power Management for duty
should target TinyOS 2.0. This might be a challenge with the timer
interface being so different from TinyOS 1.x.</p>
</div>
-<div class="section">
-<h1><a id="authors" name="authors">7. Authors</a></h1>
+<div class="section" id="authors">
+<h1><a name="authors">7. Authors</a></h1>
<div class="line-block">
-<div class="line">Anders Egeskov Petersen</div>
-<div class="line">University of Copenhagen, Dept. of Computer Science</div>
-<div class="line">Universitetsparken 1</div>
-<div class="line">DK-2100 K¯benhavn ÿ</div>
-<div class="line">Denmark</div>
+<div class="line">Anders Egeskov Petersen </div>
+<div class="line">University of Copenhagen, Dept. of Computer Science </div>
+<div class="line">Universitetsparken 1 </div>
+<div class="line">DK-2100 København Ø </div>
+<div class="line">Denmark </div>
<div class="line"><br /></div>
-<div class="line">Sidsel Jensen</div>
-<div class="line">University of Copenhagen, Dept. of Computer Science</div>
-<div class="line">Universitetsparken 1</div>
-<div class="line">DK-2100 K¯benhavn ÿ</div>
-<div class="line">Denmark</div>
+<div class="line">Sidsel Jensen </div>
+<div class="line">University of Copenhagen, Dept. of Computer Science </div>
+<div class="line">Universitetsparken 1 </div>
+<div class="line">DK-2100 København Ø </div>
+<div class="line">Denmark </div>
<div class="line"><br /></div>
<div class="line">email - <a class="reference" href="mailto:purps@diku.dk">purps@diku.dk</a></div>
<div class="line"><br /></div>
<div class="line">Martin Leoold</div>
-<div class="line">University of Copenhagen, Dept. of Computer Science</div>
-<div class="line">Universitetsparken 1</div>
-<div class="line">DK-2100 K¯benhavn ÿ</div>
-<div class="line">Denmark</div>
+<div class="line">University of Copenhagen, Dept. of Computer Science </div>
+<div class="line">Universitetsparken 1 </div>
+<div class="line">DK-2100 København Ø</div>
+<div class="line">Denmark </div>
<div class="line"><br /></div>
<div class="line">Phone +45 3532 1464</div>
<div class="line"><br /></div>
<div class="line">email - <a class="reference" href="mailto:leopold@diku.dk">leopold@diku.dk</a></div>
</div>
</div>
-<div class="section">
-<h1><a id="citations" name="citations">8. Citations</a></h1>
+<div class="section" id="citations">
+<h1><a name="citations">8. Citations</a></h1>
<table class="docutils citation" frame="void" id="nsc" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<table class="docutils citation" frame="void" id="peh" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
-<tr><td class="label"><a name="peh">[PEH]</a></td><td>Martin Leopold. "Power Estimation using the Hogthrob Prototype Platform" <em>M.Sc.
+<tr><td class="label"><a name="peh">[PEH]</a></td><td>Martin Leopold. "Power Estimation using the Hogthrob Prototype Platform" <em>M.Sc.
Thesis, DIKU, Copenhagen University, Denmark, December 2004</em> .</td></tr>
</tbody>
</table>
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.3.6: http://docutils.sourceforge.net/" />
<title>The Collection Tree Protocol (CTP)</title>
<meta name="author" content="Rodrigo Fonseca, Omprakash Gnawali, Kyle Jamieson, Sukun Kim, Philip Levis, and Alec Woo" />
<style type="text/css">
</style>
</head>
<body>
-<div class="document" id="the-collection-tree-protocol-ctp">
<h1 class="title">The Collection Tree Protocol (CTP)</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
</tr>
</tbody>
</table>
+<div class="document" id="the-collection-tree-protocol-ctp">
<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
of this memo is unlimited. This memo is in full compliance with
TEP 1.</p>
</div>
-<div class="section">
-<h1><a id="abstract" name="abstract">Abstract</a></h1>
-<p>This memo documents the Collection Tree Protocol (CTP), which
-provides best-effort anycast datagram communication to one of the
+<div class="section" id="abstract">
+<h1><a name="abstract">Abstract</a></h1>
+<p>This memo documents the Collection Tree Protocol (CTP), which
+provides best-effort anycast datagram communication to one of the
collection roots in a network.</p>
</div>
-<div class="section">
-<h1><a id="introduction" name="introduction">1. Introduction</a></h1>
+<div class="section" id="introduction">
+<h1><a name="introduction">1. Introduction</a></h1>
</div>
-<div class="section">
-<h1><a id="assumptions-and-limitations" name="assumptions-and-limitations">2. Assumptions and Limitations</a></h1>
+<div class="section" id="assumptions-and-limitations">
+<h1><a name="assumptions-and-limitations">2. Assumptions and Limitations</a></h1>
<p>CTP is a tree-based collection protocol. Some number of nodes in a
network advertise themselves as tree roots. Nodes form a set of routing
trees to these roots. CTP is <strong>address-free</strong> in that a node does not
<li>Has single-hop source and destination fields.</li>
</ol>
</blockquote>
-<p>CTP assumes that it has link quality estimates of some number of nearby
-neighbors. These provide an estimate of the number of transmissions it
+<p>CTP assumes that it has link quality estimates of some number of nearby
+neighbors. These provide an estimate of the number of transmissions it
takes for the node to send a unicast packet whose acknowledgment is
successfully received.</p>
<p>CTP has several mechanisms in order to improve delivery reliability,
might benefit from a different protocol, which can, for example, pack
multiple small frames into a single data-link packet.</p>
</div>
-<div class="section">
-<h1><a id="collection-and-ctp" name="collection-and-ctp">3. Collection and CTP</a></h1>
+<div class="section" id="collection-and-ctp">
+<h1><a name="collection-and-ctp">3. Collection and CTP</a></h1>
<p>CTP uses expected transmissions (ETX) as its routing gradient. A root
has an ETX of 0. The ETX of a node is the ETX of its parent plus the
ETX of its link to its parent. This additive measure assumes that
the same THL value, while a looped version of the packet is unlikely
to do so.</p>
</div>
-<div class="section">
-<h1><a id="ctp-data-frame" name="ctp-data-frame">4. CTP Data Frame</a></h1>
+<div class="section" id="ctp-data-frame">
+<h1><a name="ctp-data-frame">4. CTP Data Frame</a></h1>
<p>The CTP data frame format is as follows:</p>
<pre class="literal-block">
- 1
- 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6
+ 1
+ 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|P|C| reserved | THL |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| ETX |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-| origin |
+| origin |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-| seqno | collect_id |
+| seqno | collect_id |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-| data ...
+| data ...
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
</pre>
<p>Field definitions are as follows:</p>
<li>data: the data payload, of zero or more bytes. A node forwarding a data frame MUST NOT modify the data payload.</li>
</ul>
</blockquote>
-<p>Together, the origin, seqno and collect_id fields denote a unique
+<p>Together, the origin, seqno and collect_id fields denote a unique
<strong>*origin packet.*</strong> Together, the origin, seqno, collect_id, and
THL denote a unique <strong>*packet instance*</strong> within the network. The
distinction is important for duplicate suppression in the presence
drop the packet. However, if it suppresses packet instances, then it
will route succesfully in the presence of transient loops unless the
THL happens to wrap around to a forwarded packet instance.</p>
-<p>A node MUST send CTP data frames as unicast messages with link-layer
+<p>A node MUST send CTP data frames as unicast messages with link-layer
acknowledgments enabled.</p>
</div>
-<div class="section">
-<h1><a id="ctp-routing-frame" name="ctp-routing-frame">5. CTP Routing Frame</a></h1>
+<div class="section" id="ctp-routing-frame">
+<h1><a name="ctp-routing-frame">5. CTP Routing Frame</a></h1>
<p>The CTP routing frame format is as follows:</p>
<pre class="literal-block">
- 1
- 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6
+ 1
+ 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|P|C| reserved | parent |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-| parent | ETX |
+| parent | ETX |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-| ETX |
+| ETX |
+-+-+-+-+-+-+-+-+
</pre>
<p>The fields are as follows:</p>
own, it MUST schedule a routing frame for transmission in the near
future.</p>
</div>
-<div class="section">
-<h1><a id="implementation" name="implementation">6. Implementation</a></h1>
+<div class="section" id="implementation">
+<h1><a name="implementation">6. Implementation</a></h1>
<p>An implementation of CTP can be found in the tos/lib/net/ctp directory
of TinyOS 2.0. This section describes the structure of that implementation
and is not in any way part of the specification of CTP.</p>
to send. It decides when and if to send them. The name is a little
misleading: the forwarding engine is responsible for forwarded traffic
as well as traffic generated on the node.</p>
-<div class="section">
-<h2><a id="link-estimation" name="link-estimation">6.1 Link Estimation</a></h2>
+<div class="section" id="link-estimation">
+<h2><a name="link-estimation">6.1 Link Estimation</a></h2>
<p>The implementation uses two mechanisms to estimate the quality of a link:
periodic LEEP <a class="footnote-reference" href="#id4" id="id1" name="id1">[1]</a> packets and data packets. The implementation sends
routing beacons as LEEP packets. These packets seed the neighbor table
<p>The estimator combines the beacon and data estimates by incorporating
them into an exponentially weighted moving average. Beacon-based
estimates seed the neighbor table. The expectation is that the low
-beacon rate in a stable network means that for a selected route,
+beacon rate in a stable network means that for a selected route,
data estimates will outweigh beacon estimates. Additionally, as
the rate at which CTP collects data estimates is proportional to
the transmission rate, then it can quickly detect a broken link and
<p>The component <tt class="docutils literal"><span class="pre">tos/lib/net/le/LinkEstimatorP</span></tt> implements the
link estimator. It couples LEEP-based and data-based estimates.</p>
</div>
-<div class="section">
-<h2><a id="routing-engine" name="routing-engine">6.2 Routing Engine</a></h2>
+<div class="section" id="routing-engine">
+<h2><a name="routing-engine">6.2 Routing Engine</a></h2>
<p>The implementation's routing engine is responsible for picking the next
hop for a data transmission. It keeps track of the path ETX values of
a subset of the nodes maintained by the link estimation table. The minimum
along the entire route. The component <tt class="docutils literal"><span class="pre">tos/lib/net/ctp/CtpRoutingEngineP</span></tt>
implements the routing engine.</p>
</div>
-<div class="section">
-<h2><a id="forwarding-engine" name="forwarding-engine">6.3 Forwarding Engine</a></h2>
+<div class="section" id="forwarding-engine">
+<h2><a name="forwarding-engine">6.3 Forwarding Engine</a></h2>
<p>The component <tt class="docutils literal"><span class="pre">tos/lib/net/ctp/CtpForwardingEngineP</span></tt> implements the
forwarding engine. It has five repsonsibilities:</p>
<blockquote>
along the path.</p>
</div>
</div>
-<div class="section">
-<h1><a id="citations" name="citations">7. Citations</a></h1>
+<div class="section" id="citations">
+<h1><a name="citations">7. Citations</a></h1>
<div class="line-block">
-<div class="line">Rodrigo Fonseca</div>
+<div class="line">Rodrigo Fonseca </div>
<div class="line">473 Soda Hall</div>
<div class="line">Berkeley, CA 94720-1776</div>
<div class="line"><br /></div>
<div class="line"><br /></div>
<div class="line"><br /></div>
<div class="line">Omprakash Gnawali</div>
-<div class="line">Ronald Tutor Hall (RTH) 418</div>
+<div class="line">Ronald Tutor Hall (RTH) 418 </div>
<div class="line">3710 S. McClintock Avenue</div>
-<div class="line">Los Angeles, CA 90089</div>
+<div class="line">Los Angeles, CA 90089 </div>
<div class="line"><br /></div>
<div class="line">phone - +1 213 821-5627</div>
<div class="line">email - <a class="reference" href="mailto:gnawali@usc.edu">gnawali@usc.edu</a></div>
<div class="line">Kyle Jamieson</div>
<div class="line">The Stata Center</div>
<div class="line">32 Vassar St.</div>
-<div class="line">Cambridge, MA 02139</div>
+<div class="line">Cambridge, MA 02139 </div>
<div class="line"><br /></div>
<div class="line">email - <a class="reference" href="mailto:jamieson@csail.mit.edu">jamieson@csail.mit.edu</a></div>
<div class="line"><br /></div>
<div class="line">email - <a class="reference" href="mailto:pal@cs.stanford.edu">pal@cs.stanford.edu</a></div>
</div>
</div>
-<div class="section">
-<h1><a id="id3" name="id3">8. Citations</a></h1>
+<div class="section" id="id3">
+<h1><a name="id3">8. Citations</a></h1>
<table class="docutils footnote" frame="void" id="id4" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.3.6: http://docutils.sourceforge.net/" />
<title>The Link Estimation Exchange Protocol (LEEP)</title>
<meta name="author" content="Omprakash Gnawali" />
<style type="text/css">
</style>
</head>
<body>
-<div class="document" id="the-link-estimation-exchange-protocol-leep">
<h1 class="title">The Link Estimation Exchange Protocol (LEEP)</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
</tr>
</tbody>
</table>
+<div class="document" id="the-link-estimation-exchange-protocol-leep">
<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
of this memo is unlimited. This memo is in full compliance with
TEP 1.</p>
</div>
-<div class="section">
-<h1><a id="abstract" name="abstract">Abstract</a></h1>
+<div class="section" id="abstract">
+<h1><a name="abstract">Abstract</a></h1>
<p>The memo documents the Link Estimation Exchange Protocol (LEEP). Nodes
use LEEP to estimate and exchange information about the quality of
links to the neighbors.</p>
</div>
-<div class="section">
-<h1><a id="introduction" name="introduction">1. Introduction</a></h1>
+<div class="section" id="introduction">
+<h1><a name="introduction">1. Introduction</a></h1>
<p>Routing protocols often require bi-directional link qualities to
compute the routes. Nodes can estimate the quality of the in-bound
link from a neighbor by estimating the ratio of successfully received
messages and the total transmitted messages. LEEP appends in-bound
-packet reception rate (PRR) estimates to packets. Other nodes hearing
+packet reception rate (PRR) estimates to packets. Other nodes hearing
these packets can combine the in-bound PRR values with their own
in-bound values to compute bi-directional link quality.</p>
</div>
-<div class="section">
-<h1><a id="definitions" name="definitions">2. Definitions</a></h1>
-<div class="section">
-<h2><a id="link-quality" name="link-quality">2.1 Link Quality</a></h2>
+<div class="section" id="definitions">
+<h1><a name="definitions">2. Definitions</a></h1>
+<div class="section" id="link-quality">
+<h2><a name="link-quality">2.1 Link Quality</a></h2>
<p>The link quality between a directed node pair (A,B) is the probability
that a packet transmitted by A will be successfully received by B. The
-bidirectional link quality of an undirected node pair (A,B) is the
+bidirectional link quality of an undirected node pair (A,B) is the
product of the link quality of (A,B) and (B,A). This definition
assumes independent link losses. It also includes the case when
the link quality of (A,B) and (B,A) are different; this can occur
due to local interference or noise.</p>
</div>
-<div class="section">
-<h2><a id="in-bound-link-quality" name="in-bound-link-quality">2.2 In-bound Link Quality</a></h2>
+<div class="section" id="in-bound-link-quality">
+<h2><a name="in-bound-link-quality">2.2 In-bound Link Quality</a></h2>
<p>In a node pair (A,B), with B as the node of reference, in-bound link
quality is a value in the range of 0 to 255 that describes the quality
of the link from A to B estimated by B by counting the successfully
link quality indicators such as LQI and RSSI provided by the radio on
the node B, or some other methods.</p>
</div>
-<div class="section">
-<h2><a id="out-bound-link-quality" name="out-bound-link-quality">2.3 Out-bound Link Quality</a></h2>
+<div class="section" id="out-bound-link-quality">
+<h2><a name="out-bound-link-quality">2.3 Out-bound Link Quality</a></h2>
<p>In a node pair (A,B), with B as the node of reference, out-bound link
quality is defined as the quality of the link from B to A. B can
determine the out-bound link quality if A advertises its in-bound link
qualities. LEEP is the protocol that is used to exchange the in-bound
link qualities.</p>
</div>
-<div class="section">
-<h2><a id="link-information-entry" name="link-information-entry">2.4 Link Information Entry</a></h2>
+<div class="section" id="link-information-entry">
+<h2><a name="link-information-entry">2.4 Link Information Entry</a></h2>
<p>Link Information Entry created by node k is a tuple (n,q) where q is
the in-bound link quality from node n to k.</p>
</div>
</div>
-<div class="section">
-<h1><a id="id1" name="id1">3. The Link Estimation Exchange Protocol (LEEP)</a></h1>
-<div class="section">
-<h2><a id="assumptions" name="assumptions">3.1 Assumptions</a></h2>
+<div class="section" id="id1">
+<h1><a name="id1">3. The Link Estimation Exchange Protocol (LEEP)</a></h1>
+<div class="section" id="assumptions">
+<h2><a name="assumptions">3.1 Assumptions</a></h2>
<p>Following are the assumptions made by LEEP:</p>
<p>3.1.1. The data link frame has a single-hop source field.
3.1.2. The data link layer provides a broadcast address.
3.1.3. The data link layer provides the length of the LEEP frame.</p>
</div>
-<div class="section">
-<h2><a id="the-protocol" name="the-protocol">3.2 The Protocol</a></h2>
+<div class="section" id="the-protocol">
+<h2><a name="the-protocol">3.2 The Protocol</a></h2>
<p>To compute the bi-directional link quality, in-bound link quality must
be exchanged among the neighbors. LEEP maintains a sequence number
that is incremented by one for each outgoing LEEP frame. The sequence
receiver node to find the out-bound link quality to the transmitter
node identified by the data link source address.</p>
</div>
-<div class="section">
-<h2><a id="leep-frame" name="leep-frame">3.3 LEEP Frame</a></h2>
+<div class="section" id="leep-frame">
+<h2><a name="leep-frame">3.3 LEEP Frame</a></h2>
<p>A LEEP frame has a header, the payload, and a footer with the Link
Information (LI) entries as shown in this diagram:</p>
<pre class="literal-block">
allowed by the data link layer. A LEEP frame can have 0 Link
Information entry.</p>
</div>
-<div class="section">
-<h2><a id="leep-header" name="leep-header">3.3.1 LEEP header</a></h2>
+<div class="section" id="leep-header">
+<h2><a name="leep-header">3.3.1 LEEP header</a></h2>
<p>The following diagram shows the LEEP header format:</p>
<pre class="literal-block">
1
</ul>
</blockquote>
</div>
-<div class="section">
-<h2><a id="id2" name="id2">3.3.2 Link Information Entry</a></h2>
+<div class="section" id="id2">
+<h2><a name="id2">3.3.2 Link Information Entry</a></h2>
<p>The following diagram shows the Link Information Entry format:</p>
<pre class="literal-block">
1
</blockquote>
</div>
</div>
-<div class="section">
-<h1><a id="implementation" name="implementation">4. Implementation</a></h1>
+<div class="section" id="implementation">
+<h1><a name="implementation">4. Implementation</a></h1>
<p>The following files in <tt class="docutils literal"><span class="pre">tinyos-2.x/tos/lib/net/le</span></tt> provide a
reference implementation of LEEP described in this TEP.</p>
<blockquote>
frame. The LEEP frames are transmitted whenever the CTP <a class="footnote-reference" href="#id4" id="id3" name="id3">[1]</a> beacons,
sent as a LEEP payload, are sent.</p>
</div>
-<div class="section">
-<h1><a id="author-s-address" name="author-s-address">5. Author's Address</a></h1>
+<div class="section" id="author-s-address">
+<h1><a name="author-s-address">5. Author's Address</a></h1>
<div class="line-block">
<div class="line">Omprakash Gnawali</div>
-<div class="line">Ronald Tutor Hall (RTH) 418</div>
+<div class="line">Ronald Tutor Hall (RTH) 418 </div>
<div class="line">3710 S. McClintock Avenue</div>
-<div class="line">Los Angeles, CA 90089</div>
+<div class="line">Los Angeles, CA 90089 </div>
<div class="line"><br /></div>
<div class="line">phone - +1 213 821-5627</div>
<div class="line">email - <a class="reference" href="mailto:gnawali@usc.edu">gnawali@usc.edu</a></div>
<div class="line"><br /></div>
</div>
</div>
-<div class="section">
-<h1><a id="citations" name="citations">6. Citations</a></h1>
+<div class="section" id="citations">
+<h1><a name="citations">6. Citations</a></h1>
<table class="docutils footnote" frame="void" id="id4" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.3.6: http://docutils.sourceforge.net/" />
<title>TinyOS 802.15.4 Frames</title>
<meta name="author" content="Jonathan Hui, Philip Levis, and David Moss" />
<style type="text/css">
</style>
</head>
<body>
-<div class="document" id="tinyos-802-15-4-frames">
<h1 class="title">TinyOS 802.15.4 Frames</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<td>Jonathan Hui, Philip Levis, and David Moss</td></tr>
<tr class="field"><th class="docinfo-name">Draft-Created:</th><td class="field-body">2-Feb-2007</td>
</tr>
-<tr class="field"><th class="docinfo-name">Draft-Version:</th><td class="field-body">1.1</td>
+<tr class="field"><th class="docinfo-name">Draft-Version:</th><td class="field-body">1.2</td>
</tr>
-<tr class="field"><th class="docinfo-name">Draft-Modified:</th><td class="field-body">2007-04-03</td>
+<tr class="field"><th class="docinfo-name">Draft-Modified:</th><td class="field-body">2007-04-09</td>
</tr>
<tr class="field"><th class="docinfo-name">Draft-Discuss:</th><td class="field-body">TinyOS Developer List <tinyos-devel at mail.millennium.berkeley.edu></td>
</tr>
</tbody>
</table>
+<div class="document" id="tinyos-802-15-4-frames">
<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
of this memo is unlimited. This memo is in full compliance with
TEP 1.</p>
</div>
-<div class="section">
-<h1><a id="abstract" name="abstract">Abstract</a></h1>
+<div class="section" id="abstract">
+<h1><a name="abstract">Abstract</a></h1>
<p>This memo documents the frame format for 802.15.4 packets in TinyOS
2.0.</p>
</div>
-<div class="section">
-<h1><a id="introduction" name="introduction">1. Introduction</a></h1>
+<div class="section" id="introduction">
+<h1><a name="introduction">1. Introduction</a></h1>
<p>802.15.4 is a data-link and physical packet format for
low-power wireless networks that is used in many TinyOS platforms.
The TinyOS 2.0 active message layer adds a packet field for higher-level
the second format is for networks that share the spectrum with 6lowpan
networks[1]_.</p>
</div>
-<div class="section">
-<h1><a id="id1" name="id1">2. 802.15.4</a></h1>
+<div class="section" id="id1">
+<h1><a name="id1">2. 802.15.4</a></h1>
<p>802.15.4 supports several different source and destination addressing
modes, and so has a variable sized packet header.[2]_ A TinyOS device MUST
support packet frames with 16-bit short source and destination addresses.
A TinyOS device MAY support additional 802.15.4 frame formats.</p>
</div>
-<div class="section">
-<h1><a id="frame-format" name="frame-format">3. Frame Format</a></h1>
+<div class="section" id="frame-format">
+<h1><a name="frame-format">3. Frame Format</a></h1>
<p>TinyOS has two 802.15.4 frame formats. The first format, the T-Frame, is
for TinyOS networks which do not share their channel with other wireless
networking archtiectures. This frame format assumes that TinyOS can use
a 6lowpan packet, the code used MUST be in the range of 192-55.</p>
<p>The AM type 6lowpan is reserved. A TinyOS program MUST NOT use it.</p>
</div>
-<div class="section">
-<h1><a id="implementation" name="implementation">4. Implementation</a></h1>
+<div class="section" id="implementation">
+<h1><a name="implementation">4. Implementation</a></h1>
<p>An implementation of the T-Frame can be found in tinyos-2.x/tos/chips/cc2420.</p>
-<p>An implementation of the I-Frame will soon be found in
+<p>An implementation of the I-Frame will soon be found in
tinyos-2.x/tos/chips/cc2420.</p>
</div>
-<div class="section">
-<h1><a id="author-addresses" name="author-addresses">5. Author Addresses</a></h1>
+<div class="section" id="author-addresses">
+<h1><a name="author-addresses">5. Author Addresses</a></h1>
<div class="line-block">
<div class="line"><br /></div>
<div class="line">Jonathan Hui</div>
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.3.6: http://docutils.sourceforge.net/" />
<title>CC2420 Radio Stack</title>
<meta name="author" content="David Moss, Jonathan Hui, Philip Levis, and Jung Il Choi" />
<style type="text/css">
</style>
</head>
<body>
-<div class="document" id="cc2420-radio-stack">
<h1 class="title">CC2420 Radio Stack</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<td>David Moss, Jonathan Hui, Philip Levis, and Jung Il Choi</td></tr>
<tr class="field"><th class="docinfo-name">Draft-Created:</th><td class="field-body">5-Mar-2007</td>
</tr>
-<tr class="field"><th class="docinfo-name">Draft-Version:</th><td class="field-body">1.1</td>
+<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">2007-03-23</td>
+<tr class="field"><th class="docinfo-name">Draft-Modified:</th><td class="field-body">2007-04-20</td>
</tr>
<tr class="field"><th class="docinfo-name">Draft-Discuss:</th><td class="field-body">TinyOS Developer List <tinyos-devel at mail.millennium.berkeley.edu></td>
</tr>
</tbody>
</table>
+<div class="document" id="cc2420-radio-stack">
<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
of this memo is unlimited. This memo is in full compliance with
TEP 1.</p>
</div>
-<div class="section">
-<h1><a id="abstract" name="abstract">Abstract</a></h1>
+<div class="section" id="abstract">
+<h1><a name="abstract">Abstract</a></h1>
<p>This TEP documents the architecture of the CC2420 low power listening
-radio stack found in TinyOS 2.x. Radio stack layers and implementation
+radio stack found in TinyOS 2.x. Radio stack layers and implementation
details of the CC2420 stack will be discussed. Readers will be better
informed about existing features, possible improvements, and limitations
of the CC2420 radio stack. Furthermore, lessons learned from
-the construction of the CC2420 radio stack can help guide development
+the construction of the stack can help guide development
of future TinyOS radio stacks.</p>
</div>
-<div class="section">
-<h1><a id="introduction" name="introduction">1. Introduction</a></h1>
-<p>The TI/Chipcon CC2420 radio is a complex device, requiring a rather
-complex software radio stack implementation. Although much of the
-functionality is available within the radio chip itself, there are
-still many factors to consider when implementing a flexible,
+<div class="section" id="introduction">
+<h1><a name="introduction">1. Introduction</a></h1>
+<p>The TI/Chipcon CC2420 radio is a complex device, taking care of
+many of the low-level details of transmitting and receiving packets
+through hardware. Specifying the proper behavior of that hardware
+requires a well defined radio stack implementation. Although much
+of the functionality is available within the radio chip itself, there
+are still many factors to consider when implementing a flexible,
general radio stack.</p>
<p>The software radio stack that drives the CC2420 radio consists of
many layers that sit between the application and hardware. The highest
levels of the radio stack modify data and headers in each packet, while
-the lowest levels determine the actual send and receive behavior.
-By understanding the functionality at each layer of the stack, as well
-as the architecture of a layer itself, it is possible to easily extend
+the lowest levels determine the actual send and receive behavior.
+By understanding the functionality at each layer of the stack, as well
+as the architecture of a layer itself, it is possible to easily extend
or condense the CC2420 radio stack to meet project requirements.</p>
<p>Some details about the CC2420 are out of the scope of this document.
-These details can be found in the CC2420 datasheet <a class="footnote-reference" href="#id11" id="id1" name="id1">[1]</a>.</p>
+These details can be found in the CC2420 datasheet <a class="footnote-reference" href="#id13" id="id1" name="id1">[1]</a>.</p>
</div>
-<div class="section">
-<h1><a id="cc2420-radio-stack-layers" name="cc2420-radio-stack-layers">2. CC2420 Radio Stack Layers</a></h1>
-<div class="section">
-<h2><a id="layer-architecture" name="layer-architecture">2.1 Layer Architecture</a></h2>
-<p>The CC2420 radio stack consists of layers of functionality stacked
+<div class="section" id="cc2420-radio-stack-layers">
+<h1><a name="cc2420-radio-stack-layers">2. CC2420 Radio Stack Layers</a></h1>
+<div class="section" id="layer-architecture">
+<h2><a name="layer-architecture">2.1 Layer Architecture</a></h2>
+<p>The CC2420 radio stack consists of layers of functionality stacked
on top of each other to provide a complete mechanism that
-modifies, filters, transmits, and controls inbound and outbound messages.
-Each layer is a distinct module that can provide and use three sets of
-interfaces in relation to the actual radio stack: Send, Receive, and
-SplitControl. If a general layer provides one of those interfaces, it
-also uses that interface from the layer below it in the stack. This
+modifies, filters, transmits, and controls inbound and outbound messages.
+Each layer is a distinct module that can provide and use three sets of
+interfaces in relation to the actual radio stack: Send, Receive, and
+SplitControl. If a general layer provides one of those interfaces, it
+also uses that interface from the layer below it in the stack. This
allows any given layer to be inserted anywhere in the stack through
independant wiring. For example::</p>
<pre class="literal-block">
uses interface SplitControl as subControl;
</pre>
<p>The actual wiring of the CC2420 radio stack is done at the highest level
-of the stack, inside CC2420ActiveMessageC. This configuration defines
+of the stack, inside CC2420ActiveMessageC. This configuration defines
three branches: Send, Receive, and SplitControl. Note that not all
layers need to provide and use all three Send, Receive, and SplitControl
interfaces::</p>
// Send Layers
AM.SubSend -> UniqueSendC;
-UniqueSendC.SubSend -> TransportC;
-TransportC.SubSend -> LplC.Send;
-LplC.SubSend -> CC2420DispatchC.Send;
-CC2420DispatchC.SubSend -> CsmaC;
+UniqueSendC.SubSend -> LinkC;
+LinkC.SubSend -> LplC.Send;
+LplC.SubSend -> TinyosNetworkC.Send;
+TinyosNetworkC.SubSend -> CsmaC;
// Receive Layers
AM.SubReceive -> LplC;
-LplC.SubReceive -> UniqueReceiveC;
-UniqueReceiveC.SubReceive -> CC2420DispatchC.Receive;
-CC2420DispatchC.SubReceive -> CsmaC;
+LplC.SubReceive -> UniqueReceiveC.Receive;
+UniqueReceiveC.SubReceive -> TinyosNetworkC.Receive;
+TinyosNetworkC.SubReceive -> CsmaC;
</pre>
<p>If another layer were to be added, CC2420ActiveMessageC would need
to be modified to wire it into the correct location.</p>
</div>
-<div class="section">
-<h2><a id="layer-descriptions" name="layer-descriptions">2.1 Layer Descriptions</a></h2>
-<p>The main layers we see in this version of the stack are:</p>
-<ul class="simple">
-<li>ActiveMessageP: This is the highest layer in the stack, responsible
+<div class="section" id="layer-descriptions">
+<h2><a name="layer-descriptions">2.1 Layer Descriptions</a></h2>
+<p>The layers found within this radio stack are in the following order:</p>
+<ul>
+<li><p class="first">ActiveMessageP: This is the highest layer in the stack, responsible
for filling in details in the packet header and providing information
-about the packet to the application level <a class="footnote-reference" href="#id12" id="id2" name="id2">[2]</a>. Because the CC2420 radio
-chip itself uses 802.15.4 headers in hardware <a class="footnote-reference" href="#id11" id="id3" name="id3">[1]</a>, it is not possible
-for the layer to rearrange header bytes.</li>
-<li>UniqueSend: This layer generates a unique data sequence
-number (DSN) byte for the packet header. This byte is generated once
-per outgoing packet. A receiver can detect duplicate packets by comparing
-the source and DSN byte of a received packet with previous packets.
-DSN is defined in the 802.15.4 specification <a class="footnote-reference" href="#id13" id="id4" name="id4">[3]</a>.</li>
-<li>MessageTransportP: This layer provides the MessageTransport
-interface, and is responsible for retrying a packet transmission if no
-acknowledgement was heard from the receiver. MessageTransport is
+about the packet to the application level <a class="footnote-reference" href="#id14" id="id2" name="id2">[2]</a>. Because the CC2420 radio
+chip itself uses 802.15.4 headers in hardware <a class="footnote-reference" href="#id13" id="id3" name="id3">[1]</a>, it is not possible
+for the layer to rearrange header bytes.</p>
+</li>
+<li><p class="first">UniqueSend: This layer generates a unique Data Sequence
+Number (DSN) byte for the packet header. This byte is incremented once
+per outgoing packet, starting with a pseudo-randomly generated number.
+A receiver can detect duplicate packets by comparing
+the source and DSN byte of a received packet with previous packets.
+DSN is defined in the 802.15.4 specification <a class="footnote-reference" href="#id15" id="id4" name="id4">[3]</a>.</p>
+</li>
+<li><p class="first">PacketLink: This layer provides automatic retransmission functionality
+and is responsible for retrying a packet transmission if no
+acknowledgement was heard from the receiver. PacketLink is
activated on a per-message basis, meaning the outgoing packet will
-not use MessageTransport unless it is configured ahead of time to do so.
-MessageTransport is most reliable when software acknowledgements are enabled,
-as opposed to hardware auto acknowledgements.</li>
-<li>LowPowerListeningP <a class="footnote-reference" href="#id14" id="id5" name="id5">[4]</a>: This layer provides the asynchronous low
-power listening functionality of the radio. It is broken up into
-two parts: CC2420LowPowerListeningP and CC2420DutyCycleP. The
-DutyCycleP component is responsible for turning the radio on
-and off and performing detections. After a detection occurs,
-DutyCycleP is hands off responsibility to LowPowerListeningP to turn
-the radio off and continue duty cycling when convenient. Low power listening
-transmissions are activated on a per-message basis, and the layer
-will retransmit the full outbound packet over and over until either a
-response from the receiver is heard or the transmit time expires.</li>
-<li>UniqueReceive: This layer maintains a history of the source address
+not use PacketLink unless it is configured ahead of time to do so.
+PacketLink is most reliable when software acknowledgements are enabled
+as opposed to hardware auto acknowledgements.</p>
+</li>
+<li><p class="first">CC2420AckLplP / CC2420NoAckLplP <a class="footnote-reference" href="#id16" id="id5" name="id5">[4]</a>: These layers provide
+asynchronous low power listening implementations. Supporting both of them
+is CC2420DutyCycleP. The DutyCycleP component is responsible for
+turning the radio on and off and performing receive checks.
+After a detection occurs, DutyCycleP is hands off responsibility to
+LowPowerListeningP to perform some transaction and turn the radio off
+when convenient. Low power listening transmissions are activated on
+a per-message basis, and the layer will continuously retransmit the full outbound
+packet until either a response from the receiver is heard or the
+transmit time expires.</p>
+<p>The AckLplP implementation supports acknowledgement gaps during the
+low power listening packetized preamble, which allows
+transmitters to stop early but penalizes receive check lengths.
+AckLplP low power listening is optimal for high transmission, long
+receive check interval networks.</p>
+<p>The NoAckLplP implementation does not support acknowledgements during
+the packetized preamble. It continuously modulates the channel,
+allowing the receiver to perform the smallest possible receive check.
+NoAckLpl low power listening is effective for low transmission, short
+receive check interval networks.</p>
+</li>
+<li><p class="first">UniqueReceive: This layer maintains a history of the source address
and DSN byte of the past few packets it has received, and helps
-filter out duplicate received packets.</li>
-<li>DispatchC: This layer allows the TinyOS 2.x radio stack to interoperate
-with other non-TinyOS networks. The 6LowPAN specifications include
-a network identifier byte after the standard 802.15.4 header <a class="footnote-reference" href="#id15" id="id6" name="id6">[5]</a>.
-If interoperability frames are used, the dispatch layer provides
-functionality for setting the network byte on outgoing packets
-and filtering non-TinyOS incoming packets.</li>
-<li>CsmaC: This layer is responsible for defining 802.15.4 FCF
+filter out duplicate received packets.</p>
+</li>
+<li><p class="first">TinyosNetworkC: This layer allows the TinyOS 2.x radio stack to
+interoperate with other non-TinyOS networks. Proposed 6LowPAN
+specifications include a network identifier byte after the
+standard 802.15.4 header <a class="footnote-reference" href="#id17" id="id6" name="id6">[5]</a>. If interoperability frames are
+used, the dispatch layer provides functionality for setting
+the network byte on outgoing packets and filtering non-TinyOS
+incoming packets.</p>
+</li>
+<li><p class="first">CsmaC: This layer is responsible for defining 802.15.4 FCF
byte information in the outbound packet, providing default
backoff times when the radio detects a channel in use, and
-defining the power-up/power-down procedure for the radio.</li>
-<li>TransmitP/ReceiveP: These layers are responsible for interacting
-directly with the radio through the SPI bus, interrupts, and GPIO lines.</li>
+defining the power-up/power-down procedure for the radio.</p>
+</li>
+<li><p class="first">TransmitP/ReceiveP: These layers are responsible for interacting
+directly with the radio through the SPI bus, interrupts, and GPIO lines.</p>
+</li>
</ul>
+<blockquote>
+<table border="1" class="docutils">
+<colgroup>
+<col width="47%" />
+<col width="53%" />
+</colgroup>
+<tbody valign="top">
+<tr><td colspan="2">Application Layer</td>
+</tr>
+</tbody>
+</table>
+<div class="system-message">
+<p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">txt/tep126.txt</tt>, line 184)</p>
+Unexpected indentation.</div>
+<div class="system-message">
+<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep126.txt</tt>, line 184)</p>
+Blank line required after table.</div>
+<blockquote>
+<blockquote>
+<div class="line-block">
+<div class="line"><br /></div>
+<div class="line"><br /></div>
+</div>
+</blockquote>
+<div class="system-message">
+<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep126.txt</tt>, line 186)</p>
+Block quote ends without a blank line; unexpected unindent.</div>
+<table border="1" class="docutils">
+<colgroup>
+<col width="47%" />
+<col width="53%" />
+</colgroup>
+<tbody valign="top">
+<tr><td colspan="2">Active Message Layer</td>
+</tr>
+</tbody>
+</table>
+<div class="system-message">
+<p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">txt/tep126.txt</tt>, line 189)</p>
+Unexpected indentation.</div>
+<div class="system-message">
+<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep126.txt</tt>, line 189)</p>
+Blank line required after table.</div>
+<blockquote>
+<div class="line-block">
+<div class="line"><br /></div>
+</div>
+</blockquote>
+<div class="system-message">
+<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep126.txt</tt>, line 190)</p>
+Block quote ends without a blank line; unexpected unindent.</div>
+<table border="1" class="docutils">
+<colgroup>
+<col width="47%" />
+<col width="53%" />
+</colgroup>
+<tbody valign="top">
+<tr><td colspan="2">Unique Send Layer</td>
+</tr>
+</tbody>
+</table>
+<div class="system-message">
+<p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">txt/tep126.txt</tt>, line 193)</p>
+Unexpected indentation.</div>
+<div class="system-message">
+<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep126.txt</tt>, line 193)</p>
+Blank line required after table.</div>
+<blockquote>
+<div class="line-block">
+<div class="line"><br /></div>
</div>
+</blockquote>
+<div class="system-message">
+<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep126.txt</tt>, line 194)</p>
+Block quote ends without a blank line; unexpected unindent.</div>
+<table border="1" class="docutils">
+<colgroup>
+<col width="47%" />
+<col width="53%" />
+</colgroup>
+<tbody valign="top">
+<tr><td colspan="2">Optional Packet Link Layer</td>
+</tr>
+</tbody>
+</table>
+<div class="system-message">
+<p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">txt/tep126.txt</tt>, line 197)</p>
+Unexpected indentation.</div>
+<div class="system-message">
+<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep126.txt</tt>, line 197)</p>
+Blank line required after table.</div>
+<blockquote>
+<div class="line-block">
+<div class="line"><br /></div>
+</div>
+</blockquote>
+<div class="system-message">
+<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep126.txt</tt>, line 198)</p>
+Block quote ends without a blank line; unexpected unindent.</div>
+<table border="1" class="docutils">
+<colgroup>
+<col width="47%" />
+<col width="53%" />
+</colgroup>
+<tbody valign="top">
+<tr><td colspan="2">Optional Low Power Listening Implementations</td>
+</tr>
+</tbody>
+</table>
+<div class="system-message">
+<p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">txt/tep126.txt</tt>, line 201)</p>
+Unexpected indentation.</div>
+<div class="system-message">
+<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep126.txt</tt>, line 201)</p>
+Blank line required after table.</div>
+<blockquote>
+<div class="line-block">
+<div class="line"><br /></div>
+</div>
+</blockquote>
+<div class="system-message">
+<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep126.txt</tt>, line 202)</p>
+Block quote ends without a blank line; unexpected unindent.</div>
+<table border="1" class="docutils">
+<colgroup>
+<col width="47%" />
+<col width="53%" />
+</colgroup>
+<tbody valign="top">
+<tr><td colspan="2">Unique Receive Filtering Layer</td>
+</tr>
+</tbody>
+</table>
+<div class="system-message">
+<p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">txt/tep126.txt</tt>, line 205)</p>
+Unexpected indentation.</div>
+<div class="system-message">
+<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep126.txt</tt>, line 205)</p>
+Blank line required after table.</div>
+<blockquote>
+<div class="line-block">
+<div class="line"><br /></div>
</div>
-<div class="section">
-<h1><a id="cc2420-packet-format-and-specifications" name="cc2420-packet-format-and-specifications">3. CC2420 Packet Format and Specifications</a></h1>
+</blockquote>
+<div class="system-message">
+<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep126.txt</tt>, line 206)</p>
+Block quote ends without a blank line; unexpected unindent.</div>
+<table border="1" class="docutils">
+<colgroup>
+<col width="47%" />
+<col width="53%" />
+</colgroup>
+<tbody valign="top">
+<tr><td colspan="2">Optional 6LowPAN TinyOS Network Layer</td>
+</tr>
+</tbody>
+</table>
+<div class="system-message">
+<p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">txt/tep126.txt</tt>, line 209)</p>
+Unexpected indentation.</div>
+<div class="system-message">
+<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep126.txt</tt>, line 209)</p>
+Blank line required after table.</div>
+<blockquote>
+<div class="line-block">
+<div class="line"><br /></div>
+</div>
+</blockquote>
+<div class="system-message">
+<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep126.txt</tt>, line 210)</p>
+Block quote ends without a blank line; unexpected unindent.</div>
+<table border="1" class="docutils">
+<colgroup>
+<col width="47%" />
+<col width="53%" />
+</colgroup>
+<tbody valign="top">
+<tr><td colspan="2">Carrier Sense Multiple Access (CSMA)</td>
+</tr>
+</tbody>
+</table>
+<div class="system-message">
+<p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">txt/tep126.txt</tt>, line 213)</p>
+Unexpected indentation.</div>
+<div class="system-message">
+<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep126.txt</tt>, line 213)</p>
+Blank line required after table.</div>
+<blockquote>
+<blockquote>
+<div class="line-block">
+<div class="line"><br /></div>
+</div>
+</blockquote>
+<div class="system-message">
+<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep126.txt</tt>, line 214)</p>
+Block quote ends without a blank line; unexpected unindent.</div>
+<div class="system-message">
+<p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">txt/tep126.txt</tt>, line 214)</p>
+<p>Malformed table.</p>
+<pre class="literal-block">
++------------+------------+
+| |
+</pre>
+</div>
+<div class="system-message">
+<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep126.txt</tt>, line 216)</p>
+Blank line required after table.</div>
+</blockquote>
+</blockquote>
+<div class="system-message">
+<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep126.txt</tt>, line 216)</p>
+Block quote ends without a blank line; unexpected unindent.</div>
+<p>+----------+----------+ +----------+----------+
+| ReceiveP | | TransmitP |
++----------+----------+ +----------+----------+</p>
+<div class="system-message">
+<p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">txt/tep126.txt</tt>, line 219)</p>
+Unexpected indentation.</div>
+<blockquote>
+<div class="line-block">
+<div class="line"><a href="#id7" name="id8"><span class="problematic" id="id8">|</span></a></div>
+</div>
+<div class="system-message" id="id7">
+<p class="system-message-title">System Message: <a name="id7">WARNING/2</a> (<tt class="docutils">txt/tep126.txt</tt>, line 219); <em><a href="#id8">backlink</a></em></p>
+Inline substitution_reference start-string without end-string.</div>
+<div class="system-message">
+<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep126.txt</tt>, line 220)</p>
+Line block ends without a blank line.</div>
+<table border="1" class="docutils">
+<colgroup>
+</colgroup>
+<tbody valign="top">
+</tbody>
+</table>
+<div class="system-message">
+<p class="system-message-title">System Message: ERROR/3 (<tt class="docutils">txt/tep126.txt</tt>, line 221)</p>
+Unexpected indentation.</div>
+<div class="system-message">
+<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep126.txt</tt>, line 221)</p>
+Blank line required after table.</div>
+<blockquote>
+<div class="line-block">
+<div class="line"><br /></div>
+</div>
+</blockquote>
+</blockquote>
+<div class="system-message">
+<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep126.txt</tt>, line 222)</p>
+Block quote ends without a blank line; unexpected unindent.</div>
+<table border="1" class="docutils">
+<colgroup>
+<col width="48%" />
+<col width="52%" />
+</colgroup>
+<tbody valign="top">
+<tr><td colspan="2">SPI bus, GPIO, Interrupts, Timer Capture</td>
+</tr>
+</tbody>
+</table>
+</blockquote>
+</div>
+</div>
+<div class="section" id="cc2420-packet-format-and-specifications">
+<h1><a name="cc2420-packet-format-and-specifications">3. CC2420 Packet Format and Specifications</a></h1>
<p>The CC2420 Packet structure is defined in CC2420.h. The default
I-Frame CC2420 header takes on the following format::</p>
<pre class="literal-block">
nxle_uint16_t destpan;
nxle_uint16_t dest;
nxle_uint16_t src;
- nxle_uint8_t network;
+ nxle_uint8_t network; // optionally included with 6LowPAN layer
nxle_uint8_t type;
} cc2420_header_t;
</pre>
-<p>All fields up to 'network' are 802.15.4 specified fields, and are
-used in the CC2420 hardware itself. The 'network' field is a 6LowPAN
-interoperability specification <a class="footnote-reference" href="#id15" id="id7" name="id7">[5]</a>. The 'type' field is a
+<p>All fields up to 'network' are 802.15.4 specified fields, and are
+used in the CC2420 hardware itself. The 'network' field is a 6LowPAN
+interoperability specification <a class="footnote-reference" href="#id17" id="id9" name="id9">[5]</a> only to be included when the
+6LowPAN TinyosNetwork layer is included. The 'type' field is a
TinyOS specific field.</p>
<p>The TinyOS T-Frame packet does not include the 'network' field, nor
the functionality found in the Dispatch layer to set and check
<p>No software footer is defined for the CC2420 radio. A 2-byte
CRC byte is auto-appended to each outbound packet by the CC2420 radio
hardware itself.</p>
-<p>The CC2420 hardware has three RAM buffers: TXFIFO, RXFIFO, and a
-security RAM buffer. The TXFIFO and RXFIFO are both 128 bytes,
-while the security RAM buffer is 112 bytes. Therefore, the maximum size
-of a packet is 128 bytes including its headers and CRC. Increasing
-the packet size will increase data throughput and RAM consumption
-in the TinyOS application, but will also increase the probability
-that interference will cause the packet to be destroyed and need
-to be retransmitted, which wastes energy. The TOSH_DATA_LENGTH
-preprocessor variable can be altered to increase the size
-of the message_t payload at compile time <a class="footnote-reference" href="#id12" id="id8" name="id8">[2]</a>.</p>
-</div>
-<div class="section">
-<h1><a id="csma-ca" name="csma-ca">4. CSMA/CA</a></h1>
-<div class="section">
-<h2><a id="clear-channel-assessment" name="clear-channel-assessment">4.1 Clear Channel Assessment</a></h2>
-<p>By default, the CC2420 radio stack performs a clear channel assessment
+<p>The maximum size of a packet is 128 bytes including its headers and
+CRC, which matches the 802.15.4 specifications. Increasing the
+packet size will increase data throughput and RAM consumption
+in the TinyOS application, but will also increase the probability
+that interference will cause the packet to be destroyed and need
+to be retransmitted. The TOSH_DATA_LENGTH preprocessor variable can
+be altered to increase the size of the message_t payload at
+compile time <a class="footnote-reference" href="#id14" id="id10" name="id10">[2]</a>.</p>
+</div>
+<div class="section" id="csma-ca">
+<h1><a name="csma-ca">4. CSMA/CA</a></h1>
+<div class="section" id="clear-channel-assessment">
+<h2><a name="clear-channel-assessment">4.1 Clear Channel Assessment</a></h2>
+<p>By default, the CC2420 radio stack performs a clear channel assessment
(CCA) before transmitting. If the channel is not clear, the radio backs
-off for some short, random period of time before attempting to transmit
+off for some short, random period of time before attempting to transmit
again. The CC2420 chip itself provides a strobe command to transmit
the packet if the channel is currently clear.</p>
<p>To specify whether or not to transmit with clear channel assessment,
-the CC2420TransmitP component provides two commands:</p>
-<pre class="literal-block">
-async command error_t Send.sendCCA( message_t* p_msg )
-async command error_t Send.send( message_t* p_msg )
-</pre>
-<p>It is up to the CC2420CsmaP component to select the correct method of
-transmission. Sending a packet without CCA will transmit it as quickly
-as possible, but interference from other transmitters will prevent
-it from being delivered in many cases. Transmitting without CCA will
-also effectively jam other DSSS transmitters on the same channel.</p>
-<p>Future implementations should allow the application layer to specify
-the use of CCA on a per-packet basis, similar to how the application
-layer has the option to specify the backoff period for an outgoing
-message.</p>
-</div>
-<div class="section">
-<h2><a id="radio-backoff" name="radio-backoff">4.2 Radio Backoff</a></h2>
+the CC2420TransmitP requests CCA backoff input through the RadioBackoff
+interface on a per-message basis. By default, each packet will be
+transmitted with CCA enabled.</p>
+<p>If layers above the CSMA layer wish to disable the clear channel
+assessments before transmission, they must intercept the
+RadioBackoff.requestCca(...) event for that message and call back
+using RadioBackoff.setCca(FALSE).</p>
+</div>
+<div class="section" id="radio-backoff">
+<h2><a name="radio-backoff">4.2 Radio Backoff</a></h2>
<p>A backoff is a period of time where the radio pauses before attempting
-to transmit. When the radio needs to backoff, it can choose one of three
+to transmit. When the radio needs to backoff, it can choose one of three
backoff periods: initialBackoff, congestionBackoff, and lplBackoff.
These are implemented through the RadioBackoff interface, which signals
out a request to specify the backoff period. Unlike the CsmaBackoff
interface, components that are interested in adjusting the backoff can
-call back using commands in the RadioBackoff interface. This allows
-multiple components to adjust the backoff period for packets they are
+call back using commands in the RadioBackoff interface. This allows
+multiple components to adjust the backoff period for packets they are
specifically listening to adjust. The lower the backoff period, the
faster the transmission, but the more likely the transmitter is to hog
the channel. Also, backoff periods should be as random as possible
-to prevent two transmitters from sampling the channel at the same
+to prevent two transmitters from sampling the channel at the same
moment.</p>
<p>InitialBackoff is the shortest backoff period, requested on the first
attempt to transmit a packet.</p>
<p>CongestionBackoff is a longer backoff period used when the channel is
-found to be in use. By using a longer backoff period in this case,
+found to be in use. By using a longer backoff period in this case,
the transmitter is less likely to unfairly tie up the channel.</p>
<p>LplBackoff is the backoff period used for a packet being delivered
-with low power listening. Because low power listening requires
+with low power listening. Because low power listening requires
the channel to be modulated as continuously as possible while avoiding
-interference with other transmitters, the low power listening
+interference with other transmitters, the low power listening
backoff period is intentionally short.</p>
</div>
</div>
-<div class="section">
-<h1><a id="acknowledgements" name="acknowledgements">5. Acknowledgements</a></h1>
-<div class="section">
-<h2><a id="hardware-vs-software-acknowledgements" name="hardware-vs-software-acknowledgements">5.1 Hardware vs. Software Acknowledgements</a></h2>
+<div class="section" id="acknowledgements">
+<h1><a name="acknowledgements">5. Acknowledgements</a></h1>
+<div class="section" id="hardware-vs-software-acknowledgements">
+<h2><a name="hardware-vs-software-acknowledgements">5.1 Hardware vs. Software Acknowledgements</a></h2>
<p>Originally, the CC2420 radio stack only used hardware generated
auto-acknowledgements provided by the CC2420 chip itself. This led
to some issues, such as false acknowledgements where the radio chip
-would receive a packet and acknowledge its reception and the
+would receive a packet and acknowledge its reception and the
microcontroller would never actually receive the packet.</p>
-<p>The current CC2420 stack uses software acknowledgements, which
+<p>The current CC2420 stack uses software acknowledgements, which
have a higher drop percentage. When used with the UniqueSend
-and UniqueReceive interfaces, dropped acknowledgements are more desirable
-than false acknowledgements. Received packets are always acknowledged
+and UniqueReceive interfaces, dropped acknowledgements are more desirable
+than false acknowledgements. Received packets are always acknowledged
before being filtered as a duplicate.</p>
-<p>Use the PacketAcknowledgements or MessageTransport interfaces
+<p>Use the PacketAcknowledgements or PacketLink interfaces
to determine if a packet was successfully acknowledged.</p>
</div>
-<div class="section">
-<h2><a id="data-sequence-numbers-uniquesend-and-uniquereceive" name="data-sequence-numbers-uniquesend-and-uniquereceive">5.2 Data Sequence Numbers - UniqueSend and UniqueReceive</a></h2>
+<div class="section" id="data-sequence-numbers-uniquesend-and-uniquereceive">
+<h2><a name="data-sequence-numbers-uniquesend-and-uniquereceive">5.2 Data Sequence Numbers - UniqueSend and UniqueReceive</a></h2>
<p>The 802.15.4 specification identifies a Data Sequence Number (DSN)
-byte in the message header to filter out duplicate packets <a class="footnote-reference" href="#id13" id="id9" name="id9">[3]</a>.</p>
-<p>The UniqueSend interface at the top of the CC2420 radio stack is
-responsible for setting the DSN byte. It is set exactly one time
-per outgoing message. Even if lower levels such as MessageTransport
-or LowPowerListening retransmit the packet, the DSN byte stays the
-same.</p>
+byte in the message header to filter out duplicate packets <a class="footnote-reference" href="#id15" id="id11" name="id11">[3]</a>.</p>
+<p>The UniqueSend interface at the top of the CC2420 radio stack is
+responsible for setting the DSN byte. Upon boot, an initial DSN
+byte is generated using a pseudo-random number generator with a
+maximum of 8-bits (256) values. This number is incremented on
+each outgoing packet transmission. Even if lower levels such as
+PacketLink or LowPowerListening retransmit the packet, the DSN byte
+stays the same for that packet.</p>
<p>The UniqueReceive interface at the bottom of the CC2420 radio stack
-is responsible for filtering out duplicate messages based on
+is responsible for filtering out duplicate messages based on
source address and DSN. The UniqueReceive interface is not meant
-to stop sophisticated replay attacks.</p>
+to stop sophisticated replay attacks. '</p>
+<p>As packets are received, DSN and source address information is placed
+into elements of an array. Each subsequent message from previously
+logged addresses overwrite information in the element allocated to
+that source address. This prevents UniqueReceive's history from
+losing DSN byte information from sources that are not able to access
+the channel as often. If the number of elements in the history array
+runs out, UniqueReceive uses a best effort method to avoid replacing
+recently updated DSN/Source information entries.</p>
</div>
</div>
-<div class="section">
-<h1><a id="message-transport-implementation" name="message-transport-implementation">6. Message Transport Implementation</a></h1>
-<p>Message transport is a layer added to the CC2420 radio stack to help unicast
-packets get delivered successfully. In previous version of TinyOS radio
-stacks, it was left up to the application layer to retry a message
+<div class="section" id="packetlink-implementation">
+<h1><a name="packetlink-implementation">6. PacketLink Implementation</a></h1>
+<p>PacketLink is a layer added to the CC2420 radio stack to help unicast
+packets get delivered successfully. In previous version of TinyOS radio
+stacks, it was left up to the application layer to retry a message
transmission if the application determined the message was not properly
-received. The Message Transport layer helps to remove the reliable delivery
+received. The PacketLink layer helps to remove the reliable delivery
responsibility and functional baggage from application layers.</p>
-<div class="section">
-<h2><a id="compiling-in-the-message-transport-layer" name="compiling-in-the-message-transport-layer">6.1 Compiling in the Message Transport layer</a></h2>
-<p>Because the Message Transport layer uses up extra memory footprint,
+<div class="section" id="compiling-in-the-packetlink-layer">
+<h2><a name="compiling-in-the-packetlink-layer">6.1 Compiling in the PacketLink layer</a></h2>
+<p>Because the PacketLink layer uses up extra memory footprint,
it is not compiled in by default. Developers can simply define
-the preprocessor variable MESSAGE_TRANSPORT to compile the functionality
-of the Message Transport layer in with the CC2420 stack.</p>
+the preprocessor variable PACKET_LINK to compile the functionality
+of the PacketLink layer in with the CC2420 stack.</p>
</div>
-<div class="section">
-<h2><a id="implementation-and-usage" name="implementation-and-usage">6.2 Implementation and Usage</a></h2>
-<p>To send a message using Message Transport, the MessageTransport
+<div class="section" id="implementation-and-usage">
+<h2><a name="implementation-and-usage">6.2 Implementation and Usage</a></h2>
+<p>To send a message using PacketLink, the PacketLink
interface must be called ahead of time to specify two fields in the outbound
message's metadata::</p>
<pre class="literal-block">
the amount of delay in milliseconds between each retry. The combination
of these two commands can set a packet to retry as many times as needed
for as long as necessary.</p>
-<p>Because Message Transport relies on acknowledgements, false
-acknowledgements from the receiver will cause Message Transport to fail.</p>
+<p>Because PacketLink relies on acknowledgements, false acknowledgements
+from the receiver will cause PacketLink to fail. If using software
+acknowledgements, false acknowledgements can still occur as a result
+of the limited DSN space, other 802.15.4 radios in the area with
+the same destination address, etc.</p>
</div>
</div>
-<div class="section">
-<h1><a id="asynchronous-low-power-listening-implementation" name="asynchronous-low-power-listening-implementation">7. Asynchronous Low Power Listening Implementation</a></h1>
+<div class="section" id="asynchronous-low-power-listening-implementation">
+<h1><a name="asynchronous-low-power-listening-implementation">7. Asynchronous Low Power Listening Implementation</a></h1>
<p>Because the Low Power Listening layer uses up extra memory footprint,
it is not compiled in by default. Developers can simply define
the preprocessor variable LOW_POWER_LISTENING to compile the functionality
of the Low Power Listening layer in with the CC2420 stack.</p>
-<div class="section">
-<h2><a id="design-considerations" name="design-considerations">7.1 Design Considerations</a></h2>
+<div class="section" id="design-considerations">
+<h2><a name="design-considerations">7.1 Design Considerations</a></h2>
<p>The CC2420 radio stack low power listening implementation relies
on clear channel assessments to determine if there is a transmitter
nearby. This allows the receiver to turn on and determine there are no
transmitters in a shorter amount of time than leaving the radio on
long enough to pick up a full packet.</p>
<p>The transmitters perform a message delivery by transmitting
-the full packet over and over again for twice the duration of the receiver's
-duty cycle period. Transmitting for twice as long increases the
-probability that the message will be detected by the receiver, and
-allows the receiver to shave off a small amount of time it needs to
+the full packet over and over again for twice the duration of the receiver's
+duty cycle period. Transmitting for twice as long increases the
+probability that the message will be detected by the receiver, and
+allows the receiver to shave off a small amount of time it needs to
keep its radio on.</p>
-<p>Typically, the transmission of a single packet takes on the following
+<p>Typically, the transmission of a single packet takes on the following
form over time:</p>
+<blockquote>
<table border="1" class="docutils">
<colgroup>
-<col width="22%" />
-<col width="62%" />
-<col width="16%" />
+<col width="42%" />
+<col width="21%" />
+<col width="38%" />
</colgroup>
<tbody valign="top">
<tr><td>LPL Backoff</td>
-<td>Packet Transmission</td>
+<td>Packet Tx</td>
<td>Ack Wait</td>
</tr>
</tbody>
</table>
-<p>To decrease the amount of time required for a receive check, the channel
-must be modulated by the transmitter as continuously as possible.
-The only period where the channel is modulated is during the
-Packet Transmission phase. The receiver must continuosly sample the CCA pin
+</blockquote>
+<p>To decrease the amount of time required for a receive check, the channel
+must be modulated by the transmitter as continuously as possible.
+The only period where the channel is modulated is during the
+Packet Transmission phase. The receiver must continuosly sample the CCA pin
a moment longer than the LPL Backoff period and Ack Wait period combined
to overlap the Packet Transmission period. By making the LPL backoff
period as short as possible, we can decrease the amount of time a receiver's
<p>If two transmitters attempt to transmit using low power listening,
one transmitter may hog the channel if its LPL backoff period
is set too short. Both nodes transmitting at the same time
-will cause interference and prevent each other from
+will cause interference and prevent each other from
successfully delivering their messages to the intended recipient.</p>
-<p>To allow multiple transmitters to transmit low power listening packets
-at the same time, the LPL backoff period needed to be increased
+<p>To allow multiple transmitters to transmit low power listening packets
+at the same time, the LPL backoff period needed to be increased
greater than the desired minimum. This increases the amount of time
receiver radios need to be on to perform a receive check because
the channel is no longer being modulated as continuously as possible.
-In other words, the channel is allowed to be shared amongst multiple
+In other words, the channel is allowed to be shared amongst multiple
transmitters at the expense of power consumption.</p>
</div>
-<div class="section">
-<h2><a id="minimizing-power-consumption" name="minimizing-power-consumption">7.2 Minimizing Power Consumption</a></h2>
+<div class="section" id="minimizing-power-consumption">
+<h2><a name="minimizing-power-consumption">7.2 Minimizing Power Consumption</a></h2>
<p>There are several methods the CC2420 radio stack uses to minimize
power consumption:</p>
+<ol class="arabic simple">
+<li>Invalid Packet Shutdown</li>
+</ol>
+<div class="system-message">
+<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep126.txt</tt>, line 471)</p>
+Enumerated list ends without a blank line; unexpected unindent.</div>
<blockquote>
-<p>1. <em>Invalid Packet Shutdown:</em>
Typically, packets are filtered out by address at the radio hardware
level. When a receiver wakes up and does not receive any
-packets into the low power listening layer of the radio stack, it
-will automatically go back to sleep after some period of time. As a
-secondary backup, if address decoding on the radio chip is disabled,
-the low power listening implementation will shut down the radio if
-three packets are receive that do not belong to the node. This helps
-prevent against denial of sleep attacks or the typical transmission
-behavior found in an ad-hoc network with many nodes.</p>
-<p>2. <em>Early Transmission Completion:</em>
+packets into the low power listening layer of the radio stack, it
+will automatically go back to sleep after some period of time. As a
+secondary backup, if address decoding on the radio chip is disabled,
+the low power listening implementation will shut down the radio if
+three packets are receive that do not belong to the node. This helps
+prevent against denial of sleep attacks or the typical transmission
+behavior found in an ad-hoc network with many nodes.</blockquote>
+<ol class="arabic simple" start="2">
+<li>Early Transmission Completion</li>
+</ol>
+<div class="system-message">
+<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep126.txt</tt>, line 482)</p>
+Enumerated list ends without a blank line; unexpected unindent.</div>
+<blockquote>
A transmitter typically sends a packet for twice the amount of time
as the receiver's receive check period. This increases the probability
that the receiver will detect the packet. However, if the transmitter receives
an acknowledgement before the end of its transmission period, it
will stop transmitting to save energy. This is an improvement
over previous low power listening implementations, which transmitted
-for the full period of time regardless of whether the receiver has
-already woken up and received the packet.</p>
-<p>3. <em>Auto Shutdown:</em>
+for the full period of time regardless of whether the receiver has
+already woken up and received the packet.</blockquote>
+<ol class="arabic simple" start="3">
+<li>Auto Shutdown</li>
+</ol>
+<div class="system-message">
+<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep126.txt</tt>, line 492)</p>
+Enumerated list ends without a blank line; unexpected unindent.</div>
+<blockquote>
If the radio does not send or receive messages for some period of
-time while low power listening is enabled, the radio will automatically
-turn off and begin duty cycling at its specified duty cycle period.</p>
-<p>4. <em>CCA Sampling Strategy:</em>
-The actual receive check is performed in a loop inside a function,
+time while low power listening is enabled, the radio will automatically
+turn off and begin duty cycling at its specified duty cycle period.</blockquote>
+<ol class="arabic simple" start="4">
+<li>CCA Sampling Strategy</li>
+</ol>
+<div class="system-message">
+<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">txt/tep126.txt</tt>, line 497)</p>
+Enumerated list ends without a blank line; unexpected unindent.</div>
+<blockquote>
+The actual receive check is performed in a loop inside a function,
not a spinning task. This allows the sampling to be performed
-continuously, with the goal of turning the radio off as quickly as
-possible without interruption.</p>
-</blockquote>
+continuously, with the goal of turning the radio off as quickly as
+possible without interruption.</blockquote>
</div>
</div>
-<div class="section">
-<h1><a id="cc2420-settings-and-registers" name="cc2420-settings-and-registers">8. CC2420 Settings and Registers</a></h1>
+<div class="section" id="cc2420-settings-and-registers">
+<h1><a name="cc2420-settings-and-registers">8. CC2420 Settings and Registers</a></h1>
<p>To interact with registers on the CC2420 chip, the SPI bus must be
-acquired, the chip selecct (CSn) pin must be cleared, and then the
+acquired, the chip selecct (CSn) pin must be cleared, and then the
interaction may occur. After the interaction completes, the
CSn pin must be set high.</p>
-<p>All registers and strobes are defined in the CC2420.h file, and most
+<p>All registers and strobes are defined in the CC2420.h file, and most
are accessible through the CC2420SpiC component. If your application
requires access to a specific register or strobe, the CC2420SpiC component
is the place to add access to it.</p>
<p>Configuring the CC2420 requires the developer to access the CC2420Config
-interface provided by CC2420ControlC. First call the CC2420Config commands to
-change the desired settings of the radio. Next, call CC2420Config.sync()
-to commit these changes to the radio chip. If the radio is currently
-off, the changes will be committed at the time it is turned on.</p>
+interface provided by CC2420ControlC. First call the CC2420Config commands to
+change the desired settings of the radio. If the radio happens to
+be off, the changes will be committed at the time it is turned on.
+Alternatively, calling sync() will commit the changes to the CC2420.</p>
<p>RSSI can be sampled directly by calling the ReadRssi interface provided
by CC2420ControlC. See page 50 of the CC2420 datasheet for information
-on how to convert RSSI to LQI and why it may not be such a good idea <a class="footnote-reference" href="#id11" id="id10" name="id10">[1]</a>.</p>
+on how to convert RSSI to LQI and why it may not be such a good idea <a class="footnote-reference" href="#id13" id="id12" name="id12">[1]</a>.</p>
</div>
-<div class="section">
-<h1><a id="cross-platform-portability" name="cross-platform-portability">9. Cross-platform Portability</a></h1>
+<div class="section" id="cross-platform-portability">
+<h1><a name="cross-platform-portability">9. Cross-platform Portability</a></h1>
<p>To port the CC2420 radio to another platform, the following interfaces
need to be implemented::</p>
<pre class="literal-block">
interface GeneralIO as RSTN;
interface GeneralIO as SFD;
interface GeneralIO as VREN;
-
+
// SPI Bus
interface Resource;
interface SpiByte;
<p>The GpioCapture interface is tied through the Timer to provide a relative time
at which the interrupt occurred. This is useful for timestamping received
packets for node synchronization.</p>
-<p>If the CC2420 is not connected to the proper interrupt lines,
+<p>If the CC2420 is not connected to the proper interrupt lines,
interrupts can be emulated through the use of a spinning task
that polls the GPIO pin. The MICAz implementation, for example, does this
for the CCA interrupt.</p>
</div>
-<div class="section">
-<h1><a id="future-improvement-recommendations" name="future-improvement-recommendations">10. Future Improvement Recommendations</a></h1>
+<div class="section" id="future-improvement-recommendations">
+<h1><a name="future-improvement-recommendations">10. Future Improvement Recommendations</a></h1>
<p>Many improvements can be made to the CC2420 stack. Below are some
recommendations:</p>
-<div class="section">
-<h2><a id="aes-encryption" name="aes-encryption">10.1 AES Encryption</a></h2>
+<div class="section" id="aes-encryption">
+<h2><a name="aes-encryption">10.1 AES Encryption</a></h2>
<p>The CC2420 chip itself provides AES-128 encryption. The implementation
involves loading the security RAM buffers on the CC2420 with the information
to be encrypted - this would be the payload of a packet, without
the header. After the payload is encrypted, the microcontroller reads
-out of the security RAM buffer and concatenates the data with the
+out of the security RAM buffer and concatenates the data with the
unencrypted packet header. This full packet would be uploaded again to the CC2420
TXFIFO buffer and transmitted.</p>
<p>Because the CC2420 cannot begin encryption at a particular offset
-and needs to be written, read, and re-written, use of the AES-128 may be
+and needs to be written, read, and re-written, use of the AES-128 may be
inefficient and will certainly decrease throughput.</p>
</div>
-<div class="section">
-<h2><a id="authentication" name="authentication">10.2 Authentication</a></h2>
-<p>In many cases, authentication is more desirable than encryption.
+<div class="section" id="authentication">
+<h2><a name="authentication">10.2 Authentication</a></h2>
+<p>In many cases, authentication is more desirable than encryption.
Encryption significantly increases energy and decreases packet throughput,
-which does not meet some application requirements. A layer could be
+which does not meet some application requirements. A layer could be
developed and added toward the bottom of the radio stack that validates
neighbors, preventing packets from invalid neighbors from reaching the
application layer. Several proprietary authentication layers have
-been developed for the CC2420 stack, but so far none are available to
+been developed for the CC2420 stack, but so far none are available to
the general public.</p>
-<p>A solid authentication layer would most likely involve the use of a
+<p>A solid authentication layer would most likely involve the use of a
neighbor table and 32-bit frame counts to prevent against replay attacks.
Once a neighbor is verified and established, the node needs to ensure that
future packets are still coming from the same trusted source. Again,
-some high speed low energy proprietary methods to accomplish this exist, but
+some high speed low energy proprietary methods to accomplish this exist, but
encryption is typically the standard method used.</p>
</div>
-<div class="section">
-<h2><a id="synchronous-low-power-listening" name="synchronous-low-power-listening">10.3 Synchronous Low Power Listening</a></h2>
-<p>A synchronous low power listening layer can be transparently built on
+<div class="section" id="synchronous-low-power-listening">
+<h2><a name="synchronous-low-power-listening">10.3 Synchronous Low Power Listening</a></h2>
+<p>A synchronous low power listening layer can be transparently built on
top of the asynchronous low power listening layer. One implementation
of this has already been done on a version of the CC1000 radio stack.
-Moteiv's Boomerang radio stack also has a synchronous low power listening
+Moteiv's Boomerang radio stack also has a synchronous low power listening
layer built as a standalone solution.</p>
<p>In the case of building a synchronous layer on top of the asynchronous
-low power listening layer, a transmitter's radio stack can detect when
-a particular receiver is performing its receive checks by verifying the
-packet was acknowledged after a sendDone event. The transmitter can then
+low power listening layer, a transmitter's radio stack can detect when
+a particular receiver is performing its receive checks by verifying the
+packet was acknowledged after a sendDone event. The transmitter can then
build a table to know when to begin transmission for that particular receiver.
-Each successful transmission would need to adjust the table with updated
+Each successful transmission would need to adjust the table with updated
information to avoid clock skew problems.</p>
<p>The asynchronous low power listening stack needs to be altered a bit
to make this strategy successful. Currently, duty cycling is started
and stopped as packets are detected, received, and transmitted. The
stack would need to be altered to keep a constant clock running in the
background that determines when to perform receive checks. The
-clock should not be affected by normal radio stack Rx/Tx behavior. This
+clock should not be affected by normal radio stack Rx/Tx behavior. This
would allow the receiver to maintain a predictable receive check cycle
for the transmitter to follow.</p>
<p>If the synchronous low power listening layer loses synchronization,
the radio stack can always fall back on the asynchronous low power listening
layer for successful message delivery.</p>
</div>
-<div class="section">
-<h2><a id="neighbor-tables" name="neighbor-tables">10.4 Neighbor Tables</a></h2>
-<p>Moteiv's Boomerange Sensornet Protocol (SP) implementation is a very
+<div class="section" id="neighbor-tables">
+<h2><a name="neighbor-tables">10.4 Neighbor Tables</a></h2>
+<p>Moteiv's Boomerange Sensornet Protocol (SP) implementation is a
good model to follow for radio stack architecture. One of the nice features
of SP is the design and implementation of the neighbor table. By
providing and sharing neighbor table information across the entire
CC2420 radio stack, RAM can be conserved throughout the radio stack
and TinyOS applications.</p>
</div>
-<div class="section">
-<h2><a id="radio-independant-layers" name="radio-independant-layers">10.5 Radio Independant Layers</a></h2>
+<div class="section" id="radio-independant-layers">
+<h2><a name="radio-independant-layers">10.5 Radio Independant Layers</a></h2>
<p>The best radio stack architecture is one that is completely radio independant.
Many of the layers in the CC2420 stack can be implemented independant
of the hardware underneath if the radio stack architecture was redesigned
-and reimplemented. The low power listening receive check strategy may need a
-hardware-dependant implementation, but other layers like MessageTransport,
+and reimplemented. The low power listening receive check strategy may need a
+hardware-dependant implementation, but other layers like PacketLink,
UniqueSend, UniqueReceive, ActiveMessage, Dispatch, etc. do not require
a CC2420 underneath to operate properly. The ultimate TinyOS radio
stack would be one that forms an abstraction between radio-dependant
layers and radio-independant layers, and operates with the same
behavior across any radio chip.</p>
</div>
-<div class="section">
-<h2><a id="extendable-metadata" name="extendable-metadata">10.6 Extendable Metadata</a></h2>
+<div class="section" id="extendable-metadata">
+<h2><a name="extendable-metadata">10.6 Extendable Metadata</a></h2>
<p>Layers added into the radio stack may require extra bytes of metadata.
-The MessageTransport layer, for example, requires two extra fields
+The PacketLink layer, for example, requires two extra fields
in each message's metadata to hold the message's max retries and
delay between retries. The low power listening layer requires
an extra field to specify the destination's duty cycle period for
compiled in and what size fields they required. A combination of
compiler support in the form of unique(..) and uniqueCount(..) functions
made it possible for the array to adjust its size.</p>
-<p>Explicit compiler support would be the most desirable solution to add
+<p>Explicit compiler support would be the most desirable solution to add
fields to a struct as they are needed.</p>
</div>
-<div class="section">
-<h2><a id="error-correcting-codes-ecc" name="error-correcting-codes-ecc">10.7 Error Correcting Codes (ECC)</a></h2>
+<div class="section" id="error-correcting-codes-ecc">
+<h2><a name="error-correcting-codes-ecc">10.7 Error Correcting Codes (ECC)</a></h2>
<p>When two nodes are communicating near the edge of their RF range,
it has been observed that interference may cause the packet to be
corrupted enough that the CRC byte and payload actually passes
packet. Although this is slim, in many cases it is unacceptable.
Some work arounds have implemented an extra byte of software generated
CRC to add to the reliability, and tests have proven its effectiveness.
-Taking this a step further, an ECC layer in the radio stack would help
-correct corrupted payloads and increase the distance at which nodes
+Taking this a step further, an ECC layer in the radio stack would help
+correct corrupted payloads and increase the distance at which nodes
can reliably communicate.</p>
</div>
</div>
-<div class="section">
-<h1><a id="author-s-address" name="author-s-address">11. Author's Address</a></h1>
+<div class="section" id="author-s-address">
+<h1><a name="author-s-address">11. Author's Address</a></h1>
<div class="line-block">
<div class="line">David Moss</div>
<div class="line">Rincon Research Corporation</div>
<div class="line">email -</div>
</div>
</div>
-<div class="section">
-<h1><a id="citations" name="citations">12. Citations</a></h1>
-<table class="docutils footnote" frame="void" id="id11" rules="none">
+<div class="section" id="citations">
+<h1><a name="citations">12. Citations</a></h1>
+<table class="docutils footnote" frame="void" id="id13" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
-<tr><td class="label"><a name="id1
1">[1]</a></td><td><em>(<a class="fn-backref" href="#id1">1</a>, <a class="fn-backref" href="#id3">2</a>, <a class="fn-backref" href="#id10">3</a>)</em> TI/Chipcon CC2420 Datasheet. <a class="reference" href="http://www.chipcon.com/files/CC2420_Data_Sheet_1_3.pdf">http://www.chipcon.com/files/CC2420_Data_Sheet_1_3.pdf</a></td></tr>
+<tr><td class="label"><a name="id1
3">[1]</a></td><td><em>(<a class="fn-backref" href="#id1">1</a>, <a class="fn-backref" href="#id3">2</a>, <a class="fn-backref" href="#id12">3</a>)</em> TI/Chipcon CC2420 Datasheet. <a class="reference" href="http://www.chipcon.com/files/CC2420_Data_Sheet_1_3.pdf">http://www.chipcon.com/files/CC2420_Data_Sheet_1_3.pdf</a></td></tr>
</tbody>
</table>
-<table class="docutils footnote" frame="void" id="id12" rules="none">
+<table class="docutils footnote" frame="void" id="id14" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
-<tr><td class="label"><a name="id12">[2]</a></td><td><em>(<a class="fn-backref" href="#id2">1</a>, <a class="fn-backref" href="#id8">2</a>)</em> TEP111: message_t</td></tr>
+<tr><td class="label"><a name="id14">[2]</a></td><td><em>(<a class="fn-backref" href="#id2">1</a>, <a class="fn-backref" href="#id10">2</a>)</em> TEP111: message_t</td></tr>
</tbody>
</table>
-<table class="docutils footnote" frame="void" id="id13" rules="none">
+<table class="docutils footnote" frame="void" id="id15" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
-<tr><td class="label"><a name="id1
3">[3]</a></td><td><em>(<a class="fn-backref" href="#id4">1</a>, <a class="fn-backref" href="#id9">2</a>)</em> IEEE 802.15.4 Specification: <a class="reference" href="http://standards.ieee.org/getieee802/802.15.html">http://standards.ieee.org/getieee802/802.15.html</a></td></tr>
+<tr><td class="label"><a name="id1
5">[3]</a></td><td><em>(<a class="fn-backref" href="#id4">1</a>, <a class="fn-backref" href="#id11">2</a>)</em> IEEE 802.15.4 Specification: <a class="reference" href="http://standards.ieee.org/getieee802/802.15.html">http://standards.ieee.org/getieee802/802.15.html</a></td></tr>
</tbody>
</table>
-<table class="docutils footnote" frame="void" id="id14" rules="none">
+<table class="docutils footnote" frame="void" id="id16" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
-<tr><td class="label"><a class="fn-backref" href="#id5" name="id14">[4]</a></td><td>TEP105: Low Power Listening</td></tr>
+<tr><td class="label"><a class="fn-backref" href="#id5" name="id16">[4]</a></td><td>TEP105: Low Power Listening</td></tr>
</tbody>
</table>
-<table class="docutils footnote" frame="void" id="id15" rules="none">
+<table class="docutils footnote" frame="void" id="id17" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
-<tr><td class="label"><a name="id15">[5]</a></td><td><em>(<a class="fn-backref" href="#id6">1</a>, <a class="fn-backref" href="#id7">2</a>)</em> TEP125: TinyOS 802.15.4 Frames</td></tr>
+<tr><td class="label"><a name="id17">[5]</a></td><td><em>(<a class="fn-backref" href="#id6">1</a>, <a class="fn-backref" href="#id9">2</a>)</em> TEP125: TinyOS 802.15.4 Frames</td></tr>
</tbody>
</table>
</div>
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.3.6: http://docutils.sourceforge.net/" />
<title>Hardware Abstraction Architecture</title>
-<meta name="author" content="Vlado Handziski, Joseph Polastre, Jan-Hinrich Hauer, Cory Sharp, Adam Wolisz, David Culler, David Gay" />
+<meta name="author" content="Vlado Handziski, Joseph Polastre, Jan-Hinrich Hauer, Cory Sharp, Adam Wolisz, David Culler, David Gay" />
<style type="text/css">
/*
</style>
</head>
<body>
-<div class="document" id="hardware-abstraction-architecture">
<h1 class="title">Hardware Abstraction Architecture</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<tr class="field"><th class="docinfo-name">TinyOS-Version:</th><td class="field-body">2.0</td>
</tr>
<tr><th class="docinfo-name">Author:</th>
-<td>Vlado Handziski, Joseph Polastre, Jan-Hinrich Hauer,
+<td>Vlado Handziski, Joseph Polastre, Jan-Hinrich Hauer,
Cory Sharp, Adam Wolisz, David Culler, David Gay</td></tr>
<tr class="field"><th class="docinfo-name">Draft-Created:</th><td class="field-body">14-Sep-2004</td>
</tr>
</tr>
</tbody>
</table>
+<div class="document" id="hardware-abstraction-architecture">
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">This document specifies a Best Current Practices for the TinyOS
under IEEE copyright and from the <a class="citation-reference" href="#t2-tr" id="id2" name="id2">[T2_TR]</a> technical report. This
memo is in full compliance with <a class="citation-reference" href="#tep1" id="id3" name="id3">[TEP1]</a>.</p>
</div>
-<div class="section">
-<h1><a id="abstract" name="abstract">Abstract</a></h1>
+<div class="section" id="abstract">
+<h1><a name="abstract">Abstract</a></h1>
<p>This TEP documents a <em>Hardware Abstraction Architecture (HAA)</em> for
TinyOS 2.0 that balances the conflicting requirements of code
reusability and portability on the one hand and efficiency and
exported at the second layer, when the performance requirements
outweigh the need for cross-platform compatibility.</p>
</div>
-<div class="section">
-<h1><a id="introduction" name="introduction">1. Introduction</a></h1>
+<div class="section" id="introduction">
+<h1><a name="introduction">1. Introduction</a></h1>
<p>The introduction of hardware abstraction in operating systems has
proved valuable for increasing portability and simplifying application
development by hiding the hardware intricacies from the rest of the
lowest layer structures access to hardware registers and interrupts.</p>
<p>The rest of this TEP specifies:</p>
<ul class="simple">
-<li>the details of the <em>HAA</em> and its three distinct layers
+<li>the details of the <em>HAA</em> and its three distinct layers
(<a class="reference" href="#architecture">2. Architecture</a>)</li>
-<li>guidelines on selecting the "right" level of abstraction
+<li>guidelines on selecting the "right" level of abstraction
(<a class="reference" href="#combining-different-levels-of-abstraction">3. Combining different levels of abstraction</a>)</li>
<li>how hardware abstractions can be shared among different TinyOS
platforms (<a class="reference" href="#horizontal-decomposition">4. Horizontal decomposition</a>)</li>
-<li>the level of hardware abstraction for the processing units
+<li>the level of hardware abstraction for the processing units
(<a class="reference" href="#cpu-abstraction">5. CPU abstraction</a>)</li>
<li>how some hardware abstractions may realize different degrees of
-alignment with the <em>HAA</em> top layer
+alignment with the <em>HAA</em> top layer
(<a class="reference" href="#hil-alignment">6. HIL alignment</a>)</li>
</ul>
<p>The <em>HAA</em> is the architectural basis for many TinyOS 2.0 documentary
focus on the hardware abstraction for a particular hardware module,
and <a class="citation-reference" href="#tep112" id="id7" name="id7">[TEP112]</a> and <a class="citation-reference" href="#tep115" id="id8" name="id8">[TEP115]</a> explain how power management is realized.</p>
</div>
-<div class="section">
-<h1><a id="architecture" name="architecture">2. Architecture</a></h1>
+<div class="section" id="architecture">
+<h1><a name="architecture">2. Architecture</a></h1>
<p>In the proposed architecture (<a class="reference" href="#fig-1">Fig.1</a>), the hardware abstraction
functionality is organized in three distinct layers of components.
Each layer has clearly defined responsibilities and is dependent on
the components become less and less hardware dependent, giving the
developer more freedom in the design and the implementation of
reusable applications.</p>
-<pre class="literal-block" id="fig-1">
+<a class="target" id="fig-1" name="fig-1"></a><pre class="literal-block">
+-----------------------------+
| |
| Cross-platform applications |
|HW Platform 1| |HW Platform 2| |HW Platform 3| |HW Platform 4|
+-------------+ +-------------+ +-------------+ +-------------+
-
+
Fig.1: The proposed Hardware Abstraction Architecture
</pre>
<p>In contrast to the more traditional two step approach used in other
capabilities of the hardware module.</p>
<p>The rest of the section discusses the specific roles of each component
layer in more detail.</p>
-<div class="section">
-<h2><a id="hardware-presentation-layer-hpl" name="hardware-presentation-layer-hpl">Hardware Presentation Layer (HPL)</a></h2>
+<div class="section" id="hardware-presentation-layer-hpl">
+<h2><a name="hardware-presentation-layer-hpl">Hardware Presentation Layer (HPL)</a></h2>
<p>The components belonging to the <em>HPL</em> are positioned directly over the
HW/SW interface. As the name suggests, their major task is to
"present" the capabilities of the hardware using the native concepts
(<em>not</em> rewriting) the <em>HPL</em> components, without any changes to the
implementation code.</p>
</div>
-<div class="section">
-<h2><a id="hardware-adaptation-layer-hal" name="hardware-adaptation-layer-hal">Hardware Adaptation Layer (HAL)</a></h2>
+<div class="section" id="hardware-adaptation-layer-hal">
+<h2><a name="hardware-adaptation-layer-hal">Hardware Adaptation Layer (HAL)</a></h2>
<p>The adaptation layer components represent the core of the
architecture. They use the raw interfaces provided by the <em>HPL</em>
components to build useful abstractions hiding the complexity
behind few overloaded commands. This also enables more efficient
compile-time detection of abstraction interface usage errors.</p>
</div>
-<div class="section">
-<h2><a id="hardware-interface-layer-hil" name="hardware-interface-layer-hil">Hardware Interface Layer (HIL)</a></h2>
+<div class="section" id="hardware-interface-layer-hil">
+<h2><a name="hardware-interface-layer-hil">Hardware Interface Layer (HIL)</a></h2>
<p>The final tier in the architecture is formed by the <em>HIL</em> components
that take the platform-specific abstractions provided by the <em>HAL</em> and
convert them to hardware-independent interfaces used by cross-platform
increasing levels of functionality.</p>
</div>
</div>
-<div class="section">
-<h1><a id="combining-different-levels-of-abstraction" name="combining-different-levels-of-abstraction">3. Combining different levels of abstraction</a></h1>
+<div class="section" id="combining-different-levels-of-abstraction">
+<h1><a name="combining-different-levels-of-abstraction">3. Combining different levels of abstraction</a></h1>
<p>Providing two levels of abstraction to the application --the <em>HIL</em> and
<em>HAL</em>-- means that a hardware asset may be accessed at two levels in
parallel, e.g. from different parts of the application and the OS
interface of the <em>HAL</em> component as it provides much finer control
over the conversion process. (<a class="reference" href="#fig-2">Fig.2</a>) depicts how the ADC hardware
stack on the MSP430 MCU on the level of <em>HIL</em> and <em>HAL</em> in parallel.</p>
-<pre class="literal-block" id="fig-2">
+<a class="target" id="fig-2" name="fig-2"></a><pre class="literal-block">
+--------------------------------+
| APP |
+-+----------------------------+-+
so that a safe shared access to the <em>HPL</em> exported resources can be
guaranteed.</p>
</div>
-<div class="section">
-<h1><a id="horizontal-decomposition" name="horizontal-decomposition">4. Horizontal decomposition</a></h1>
+<div class="section" id="horizontal-decomposition">
+<h1><a name="horizontal-decomposition">4. Horizontal decomposition</a></h1>
<p>In addition to the <em>vertical</em> decomposition of the <em>HAA</em>, a
<em>horizontal</em> decomposition can promote reuse of the hardware resource
abstractions that are common on different platforms. To this aim,
providing <em>HIL</em> implementation(s) as the topmost component(s).
Platforms are then built as compositions of different chip components
with the help of "glue" components that perform the mapping (<a class="reference" href="#fig-3">Fig.3</a>)</p>
-<pre class="literal-block" id="fig-3">
+<a class="target" id="fig-3" name="fig-3"></a><pre class="literal-block">
+----------------------------------------------------+
| AppC |
| /Application Component/ |
both in dedicated scenarios, as well as in situations where multiple
chips are connected to the same physical bus interconnect.</p>
</div>
-<div class="section">
-<h1><a id="cpu-abstraction" name="cpu-abstraction">5. CPU abstraction</a></h1>
+<div class="section" id="cpu-abstraction">
+<h1><a name="cpu-abstraction">5. CPU abstraction</a></h1>
<p>In TinyOS most of the variability between the processing units is
hidden from the OS simply by using a nesC/C based programming language
with a common compiler suite (GCC). For example, the standard library
of the hardware abstraction functionality will have to be explicitly
addressed.</p>
</div>
-<div class="section">
-<h1><a id="hil-alignment" name="hil-alignment">6. HIL alignment</a></h1>
+<div class="section" id="hil-alignment">
+<h1><a name="hil-alignment">6. HIL alignment</a></h1>
<p>While the <em>HAA</em> requires that the <em>HIL</em> provides full hardware
independence (<a class="reference" href="#strong-real-hils">Strong/Real HILs</a>), some abstractions might only
partially meet this goal (<a class="reference" href="#weak-hils">Weak HILs</a>). This section introduces
definition may be different</li>
<li><em>platform-specific X:</em> X is defined on just one platform</li>
</ul>
-<div class="section">
-<h2><a id="strong-real-hils" name="strong-real-hils">Strong/Real HILs</a></h2>
+<div class="section" id="strong-real-hils">
+<h2><a name="strong-real-hils">Strong/Real HILs</a></h2>
<p><em>Strong/Real HILs</em> mean that "code using these abstractions can
reasonably be expected to behave the same on all implementations".
This matches the original definition of the <em>HIL</em> level according to
example, the TinyOS 2.x message buffer abstraction, <tt class="docutils literal"><span class="pre">message_t</span></tt>
(<a class="citation-reference" href="#tep111" id="id17" name="id17">[TEP111]</a>).</p>
</div>
-<div class="section">
-<h2><a id="weak-hils" name="weak-hils">Weak HILs</a></h2>
+<div class="section" id="weak-hils">
+<h2><a name="weak-hils">Weak HILs</a></h2>
<p><em>Weak HILs</em> mean that one "can write portable code over these
abstractions, but any use of them involves platform-specific
behavior". Although such platform-specific behavior can --at least at
which should help programmers and provide guidance to platform
developers.</p>
</div>
-<div class="section">
-<h2><a id="hardware-independent-interfaces-hii" name="hardware-independent-interfaces-hii">Hardware Independent Interfaces (HII)</a></h2>
+<div class="section" id="hardware-independent-interfaces-hii">
+<h2><a name="hardware-independent-interfaces-hii">Hardware Independent Interfaces (HII)</a></h2>
<p><em>Hardware Independent Interfaces (HII)</em>, is just an interface
definition intended for use across multiple platforms.</p>
<p>Examples include the SID interfaces, the pin interfaces from <a class="citation-reference" href="#tep117" id="id18" name="id18">[TEP117]</a>,
the Alarm/Counter/etc interfaces from <a class="citation-reference" href="#tep102" id="id19" name="id19">[TEP102]</a>.</p>
</div>
-<div class="section">
-<h2><a id="utility-components" name="utility-components">Utility components</a></h2>
+<div class="section" id="utility-components">
+<h2><a name="utility-components">Utility components</a></h2>
<p><em>Utility components</em> are pieces of clearly portable code (typically
generic components), which aren't exposing a self-contained service.
Examples include the components in tos/lib/timer and the
ArbitratedRead* components. These provide and use HIIs.</p>
</div>
</div>
-<div class="section">
-<h1><a id="conclusion" name="conclusion">6. Conclusion</a></h1>
+<div class="section" id="conclusion">
+<h1><a name="conclusion">6. Conclusion</a></h1>
<p>The proposed hardware abstraction architecture provides a set of core
services that eliminate duplicated code and provide a coherent view of
the system across different platforms. It supports the concurrent use
while using standard cross-platform hardware interfaces for the
remainder of the application.</p>
</div>
-<div class="section">
-<h1><a id="author-s-address" name="author-s-address">Author's Address</a></h1>
+<div class="section" id="author-s-address">
+<h1><a name="author-s-address">Author's Address</a></h1>
<div class="line-block">
-<div class="line">Vlado Handziski (handzisk at tkn.tu-berlin.de) <a class="footnote-reference" href="#id27" id="id20" name="id20">[1]</a></div>
-<div class="line">Joseph Polastre (polastre at cs.berkeley.edu) <a class="footnote-reference" href="#id28" id="id21" name="id21">[2]</a></div>
+<div class="line">Vlado Handziski (handzisk at tkn.tu-berlin.de) <a class="footnote-reference" href="#id27" id="id20" name="id20">[1]</a> </div>
+<div class="line">Joseph Polastre (polastre at cs.berkeley.edu) <a class="footnote-reference" href="#id28" id="id21" name="id21">[2]</a> </div>
<div class="line">Jan-Hinrich Hauer (hauer at tkn.tu-berlin.de) <a class="footnote-reference" href="#id27" id="id22" name="id22">[1]</a></div>
<div class="line">Cory Sharp (cssharp at eecs.berkeley.edu) <a class="footnote-reference" href="#id28" id="id23" name="id23">[2]</a></div>
<div class="line">Adam Wolisz (awo at ieee.org) <a class="footnote-reference" href="#id27" id="id24" name="id24">[1]</a></div>
<table class="docutils footnote" frame="void" id="id27" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
-<tr><td class="label"><a name="id27">[1]</a></td><td><em>(<a class="fn-backref" href="#id20">1</a>, <a class="fn-backref" href="#id22">2</a>, <a class="fn-backref" href="#id24">3</a>)</em> Technische Universitaet Berlin
-Telecommunication Networks Group
-Sekr. FT 5, Einsteinufer 25
+<tr><td class="label"><a name="id27">[1]</a></td><td><em>(<a class="fn-backref" href="#id20">1</a>, <a class="fn-backref" href="#id22">2</a>, <a class="fn-backref" href="#id24">3</a>)</em> Technische Universitaet Berlin
+Telecommunication Networks Group
+Sekr. FT 5, Einsteinufer 25
10587 Berlin, Germany</td></tr>
</tbody>
</table>
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a name="id28">[2]</a></td><td><em>(<a class="fn-backref" href="#id21">1</a>, <a class="fn-backref" href="#id23">2</a>, <a class="fn-backref" href="#id25">3</a>)</em> University of California, Berkeley
-Computer Science Department
+Computer Science Department
Berkeley, CA 94720 USA</td></tr>
</tbody>
</table>
</tbody>
</table>
</div>
-<div class="section">
-<h1><a id="citations" name="citations">Citations</a></h1>
+<div class="section" id="citations">
+<h1><a name="citations">Citations</a></h1>
<table class="docutils citation" frame="void" id="haa2005" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<table class="docutils citation" frame="void" id="t2-tr" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
-<tr><td class="label"><a class="fn-backref" href="#id2" name="t2-tr">[T2_TR]</a></td><td>P. Levis, D. Gay, V. Handziski, J.-H.Hauer, B.Greenstein,
-M.Turon, J.Hui, K.Klues, C.Sharp, R.Szewczyk, J.Polastre,
-P.Buonadonna, L.Nachman, G.Tolle, D.Culler, and A.Wolisz,
-"T2: A Second Generation OS For Embedded Sensor Networks",
-<em>Technical Report TKN-05-007</em>, Telecommunication Networks Group,
+<tr><td class="label"><a class="fn-backref" href="#id2" name="t2-tr">[T2_TR]</a></td><td>P. Levis, D. Gay, V. Handziski, J.-H.Hauer, B.Greenstein,
+M.Turon, J.Hui, K.Klues, C.Sharp, R.Szewczyk, J.Polastre,
+P.Buonadonna, L.Nachman, G.Tolle, D.Culler, and A.Wolisz,
+"T2: A Second Generation OS For Embedded Sensor Networks",
+<em>Technical Report TKN-05-007</em>, Telecommunication Networks Group,
Technische Universität Berlin, November 2005.</td></tr>
</tbody>
</table>
<table class="docutils citation" frame="void" id="netbsd" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
-<tr><td class="label"><a class="fn-backref" href="#id11" name="netbsd">[NetBSD]</a></td><td>"The NetBSD project home page", <em>Online</em>,
+<tr><td class="label"><a class="fn-backref" href="#id11" name="netbsd">[NetBSD]</a></td><td>"The NetBSD project home page", <em>Online</em>,
<a class="reference" href="http://www.netbsd.org">http://www.netbsd.org</a></td></tr>
</tbody>
</table>
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.3.6: http://docutils.sourceforge.net/" />
<title>Coding Standard</title>
<meta name="author" content="Ion Yannopoulos, David Gay" />
<style type="text/css">
</style>
</head>
<body>
-<div class="document" id="coding-standard">
<h1 class="title">Coding Standard</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<td>Ion Yannopoulos, David Gay</td></tr>
<tr class="field"><th class="docinfo-name">Draft-Created:</th><td class="field-body">31-Dec-2004</td>
</tr>
-<tr class="field"><th class="docinfo-name">Draft-Version:</th><td class="field-body">1.1.2.3</td>
+<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">2006-01-16</td>
+<tr class="field"><th class="docinfo-name">Draft-Modified:</th><td class="field-body">2006-12-12</td>
</tr>
<tr class="field"><th class="docinfo-name">Draft-Discuss:</th><td class="field-body">TinyOS Developer List <tinyos-devel at mail.millennium.berkeley.edu></td>
</tr>
</tbody>
</table>
+<div class="document" id="coding-standard">
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">This document specifies a Best Current Practices for the
improvements. Distribution of this memo is unlimited. This memo
is in full compliance with <a class="citation-reference" href="#tep-1" id="id1" name="id1">[TEP_1]</a>.</p>
</div>
-<div class="contents topic">
-<p class="topic-title first"><a id="contents" name="contents">Contents</a></p>
+<div class="contents topic" id="contents">
+<p class="topic-title first"><a name="contents">Contents</a></p>
<ul class="auto-toc simple">
<li><a class="reference" href="#introduction" id="id7" name="id7">1 Introduction</a></li>
<li><a class="reference" href="#general-conventions" id="id8" name="id8">2 General Conventions</a><ul class="auto-toc">
<li><a class="reference" href="#citations" id="id24" name="id24">6 Citations</a></li>
</ul>
</div>
-<div class="section">
-<h1><a class="toc-backref" href="#id7" id="introduction" name="introduction">1 Introduction</a></h1>
+<div class="section" id="introduction">
+<h1><a class="toc-backref" href="#id7" name="introduction">1 Introduction</a></h1>
<dl class="docutils">
<dt>The purpose of a naming convention is twofold:</dt>
<dd><ul class="first last simple">
below, be consistent in how you do so. If you add any new conventions to
your code, note it in a README.</p>
</div>
-<div class="section">
-<h1><a class="toc-backref" href="#id8" id="general-conventions" name="general-conventions">2 General Conventions</a></h1>
-<div class="section">
-<h2><a class="toc-backref" href="#id9" id="general" name="general">2.1 General</a></h2>
+<div class="section" id="general-conventions">
+<h1><a class="toc-backref" href="#id8" name="general-conventions">2 General Conventions</a></h1>
+<div class="section" id="general">
+<h2><a class="toc-backref" href="#id9" name="general">2.1 General</a></h2>
<blockquote>
<ul class="simple">
<li>Avoid the use of acronyms and abbreviations that are not well known.
Try not to abbreviate "just because".</li>
<li>Acronyms should be capitalized (as in Java), i.e., Adc, not ADC.
-Exception: 2-letter acronyms should be all caps (e.g., AM for active
+Exception: 2-letter acronyms should be all caps (e.g., AM for active
messages, not Am)</li>
<li>If you need to abbreviate a word, do so consistently. Try to be
consistent with code outside your own.</li>
</blockquote>
</div>
</div>
-<div class="section">
-<h1><a class="toc-backref" href="#id10" id="packages" name="packages">3 Packages</a></h1>
+<div class="section" id="packages">
+<h1><a class="toc-backref" href="#id10" name="packages">3 Packages</a></h1>
<p>For the purposes of this document a package is a collection of related
source and other files, in whatever languages are needed. A package is
a logical grouping. It may or may not correspond to a physical grouping
such as a single directory. In TinyOS a package is most often a
directory with zero or more subdirectories.</p>
<p>nesC and C do not currently provide any package support, thus names
-of types and components in different packages might accidentally
+of types and components in different packages might accidentally
clash. To make this less likely, judiciously use prefixes on groups
-of related files (often, but not always, part of a single package).
+of related files (often, but not always, part of a single package).
See the examples below.</p>
<p>In a package, we distinguish between public components (intended to
be used and wired outside the package) and private components (only
used and wired within the package). This distinction is not enforced
by nesC.</p>
-<div class="section">
-<h2><a class="toc-backref" href="#id11" id="directory-structure" name="directory-structure">3.1 Directory structure</a></h2>
+<div class="section" id="directory-structure">
+<h2><a class="toc-backref" href="#id11" name="directory-structure">3.1 Directory structure</a></h2>
<blockquote>
<ul>
<li><p class="first">Each package should have it's own directory. It may have as many
</blockquote>
</div>
</div>
-<div class="section">
-<h1><a class="toc-backref" href="#id12" id="language-conventions" name="language-conventions">4 Language Conventions</a></h1>
-<div class="section">
-<h2><a class="toc-backref" href="#id13" id="nesc-convention" name="nesc-convention">4.1 nesC convention</a></h2>
-<div class="section">
-<h3><a class="toc-backref" href="#id14" id="names" name="names">4.1.1 Names</a></h3>
+<div class="section" id="language-conventions">
+<h1><a class="toc-backref" href="#id12" name="language-conventions">4 Language Conventions</a></h1>
+<div class="section" id="nesc-convention">
+<h2><a class="toc-backref" href="#id13" name="nesc-convention">4.1 nesC convention</a></h2>
+<div class="section" id="names">
+<h3><a class="toc-backref" href="#id14" name="names">4.1.1 Names</a></h3>
<blockquote>
<ul class="simple">
<li>All nesC files must have a <cite>.nc</cite> extension. The nesC compiler requires
</ul>
</blockquote>
</div>
-<div class="section">
-<h3><a class="toc-backref" href="#id15" id="id5" name="id5">4.1.2 Packages</a></h3>
+<div class="section" id="id5">
+<h3><a class="toc-backref" href="#id15" name="id5">4.1.2 Packages</a></h3>
<blockquote>
<ul>
<li><p class="first">Each package may use a prefix for its component, interface and
<li>Chip-specific hardware abstraction layer components and interfaces
start with the chip name, e.g., Atm128 for ATmega128.</li>
<li>The Maté virtual machine uses the Mate to prefix all its names.</li>
-<li>Core TinyOS names (e.g., the timer components, the Init interface)
+<li>Core TinyOS names (e.g., the timer components, the Init interface)
do not use a prefix.</li>
</ul>
</blockquote>
</ul>
</blockquote>
</div>
-<div class="section">
-<h3><a class="toc-backref" href="#id16" id="preprocessor" name="preprocessor">4.1.3 Preprocessor</a></h3>
+<div class="section" id="preprocessor">
+<h3><a class="toc-backref" href="#id16" name="preprocessor">4.1.3 Preprocessor</a></h3>
<blockquote>
<ul class="simple">
<li>Don't use the nesC <cite>includes</cite> statement. It does not handle macro
inclusion properly. Use <cite>#include</cite> instead.</li>
<li>Macros declared in an <cite>.nc</cite> file must be <cite>#define</cite>'d after the
-<cite>module</cite> or <cite>configuration</cite> keyword to actually limit their scope to
+<cite>module</cite> or <cite>configuration</cite> keyword to actually limit their scope to
the module.</li>
<li>Macros which are meant for use in multiple <cite>.nc</cite> files should be
<cite>#define</cite>'d in a <cite>#include</cite>'d C header file.</li>
</blockquote>
</div>
</div>
-<div class="section">
-<h2><a class="toc-backref" href="#id17" id="c-convention" name="c-convention">4.2 C Convention</a></h2>
+<div class="section" id="c-convention">
+<h2><a class="toc-backref" href="#id17" name="c-convention">4.2 C Convention</a></h2>
<blockquote>
<ul class="simple">
<li>All C files have a .h (header) or (rarely) a .c (source) extension.<ul>
-<li>Filenames associated with a component should have the same name as
+<li>Filenames associated with a component should have the same name as
the component.</li>
<li>Filenames of a package should have a name with the package
prefix (if any).</li>
</ul>
</li>
<li>C does not protect names in any way. If a package uses a prefix, it
-should also use it for all types, tags, functions, variables,
+should also use it for all types, tags, functions, variables,
constants and macros. This leads naturally to:<ul>
<li>Minimize C code outside of nesC files. In particular: most uses of
hardware specific macros in TinyOS 1.x should be replaced with nesC
</ul>
</blockquote>
</div>
-<div class="section">
-<h2><a class="toc-backref" href="#id18" id="java-convention" name="java-convention">4.3 Java convention</a></h2>
+<div class="section" id="java-convention">
+<h2><a class="toc-backref" href="#id18" name="java-convention">4.3 Java convention</a></h2>
<blockquote>
<ul class="simple">
<li>The standard Java coding convention <a class="citation-reference" href="#java-coding-convention" id="id6" name="id6">[Java_Coding_Convention]</a>
</ul>
</blockquote>
</div>
-<div class="section">
-<h2><a class="toc-backref" href="#id19" id="other-languages" name="other-languages">4.4 Other languages</a></h2>
+<div class="section" id="other-languages">
+<h2><a class="toc-backref" href="#id19" name="other-languages">4.4 Other languages</a></h2>
<blockquote>
<ul class="simple">
<li>No established conventions.</li>
</blockquote>
</div>
</div>
-<div class="section">
-<h1><a class="toc-backref" href="#id20" id="tinyos-conventions" name="tinyos-conventions">5 TinyOS Conventions</a></h1>
+<div class="section" id="tinyos-conventions">
+<h1><a class="toc-backref" href="#id20" name="tinyos-conventions">5 TinyOS Conventions</a></h1>
<p>TinyOS also follows a number of higher-level programming conventions,
mostly designed to provide a consistent "look" to TinyOS interfaces and
components, and to increase software reliability.</p>
-<div class="section">
-<h2><a class="toc-backref" href="#id21" id="error-returns" name="error-returns">5.1 Error returns</a></h2>
+<div class="section" id="error-returns">
+<h2><a class="toc-backref" href="#id21" name="error-returns">5.1 Error returns</a></h2>
<p>TinyOS defines a standard error return type, <tt class="docutils literal"><span class="pre">error_t</span></tt>, similar to Unix's
error returns, except that error codes are positive:</p>
<pre class="literal-block">
enum {
- SUCCESS = 0,
+ SUCCESS = 0,
FAIL = 1,
ESIZE = 2, // Parameter passed in was too big.
...
signaled under some conditions). With such functions, the split-phase event
will be signaled iff the split-phase command returns <tt class="docutils literal"><span class="pre">SUCCESS</span></tt>.</p>
</div>
-<div class="section">
-<h2><a class="toc-backref" href="#id22" id="passing-pointers-between-components" name="passing-pointers-between-components">5.2 Passing pointers between components</a></h2>
+<div class="section" id="passing-pointers-between-components">
+<h2><a class="toc-backref" href="#id22" name="passing-pointers-between-components">5.2 Passing pointers between components</a></h2>
<p>Sharing data across components can easily lead to bugs such as data races,
overwriting data, etc. To minimise the likelyhood of these occurrences,
we discourage the use of pointers in TinyOS interfaces.</p>
<p>In the future, some tool may check that programs respect these ownership
transfer rules.</p>
</div>
-<div class="section">
-<h2><a class="toc-backref" href="#id23" id="usage-of-wiring-annotations" name="usage-of-wiring-annotations">5.3 Usage of wiring annotations</a></h2>
+<div class="section" id="usage-of-wiring-annotations">
+<h2><a class="toc-backref" href="#id23" name="usage-of-wiring-annotations">5.3 Usage of wiring annotations</a></h2>
<p>TinyOS checks constraints on a program's wiring graph specified by
annotations on a component's interfaces. Wiring constraints are specified
by placing <tt class="docutils literal"><span class="pre">@atmostonce()</span></tt>, <tt class="docutils literal"><span class="pre">@atleastonce()</span></tt> and <tt class="docutils literal"><span class="pre">@exactlyonce()</span></tt>
wire initialisation code.</p>
</div>
</div>
-<div class="section">
-<h1><a class="toc-backref" href="#id24" id="citations" name="citations">6 Citations</a></h1>
+<div class="section" id="citations">
+<h1><a class="toc-backref" href="#id24" name="citations">6 Citations</a></h1>
<table class="docutils citation" frame="void" id="tep-1" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
projects / tinyos-2.x.git / commitdiff