+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
+<title>TinyOS 2.0 Overview</title>
+<meta name="author" content="Philip Levis" />
+<meta name="date" content="Oct 30 2006" />
+<style type="text/css">
+
+/*
+:Author: David Goodger
+:Contact: goodger@users.sourceforge.net
+:date: $Date$
+:version: $Revision$
+:copyright: This stylesheet has been placed in the public domain.
+
+Default cascading style sheet for the HTML output of Docutils.
+*/
+body {
+ font-family: Times;
+ font-size: 16px;
+}
+
+.first {
+ margin-top: 0 ! important }
+
+.last {
+ margin-bottom: 0 ! important }
+
+.hidden {
+ display: none }
+
+a.toc-backref {
+ text-decoration: none ;
+ color: black }
+
+blockquote.epigraph {
+ margin: 2em 5em ; }
+
+dd {
+ margin-bottom: 0.5em }
+
+div.abstract {
+ margin: 2em 5em }
+
+div.abstract p.topic-title {
+ font-weight: bold ;
+ text-align: center }
+
+div.attention, div.caution, div.danger, div.error, div.hint,
+div.important, div.note, div.tip, div.warning, div.admonition {
+ margin: 2em ;
+ border: medium outset ;
+ padding: 1em }
+
+div.attention p.admonition-title, div.caution p.admonition-title,
+div.danger p.admonition-title, div.error p.admonition-title,
+div.warning p.admonition-title {
+ color: red ;
+ font-weight: bold ;
+ font-family: sans-serif }
+
+div.hint p.admonition-title, div.important p.admonition-title,
+div.note p.admonition-title, div.tip p.admonition-title,
+div.admonition p.admonition-title {
+ font-weight: bold ;
+ font-family: sans-serif }
+
+div.dedication {
+ margin: 2em 5em ;
+ text-align: center ;
+ font-style: italic }
+
+div.dedication p.topic-title {
+ font-weight: bold ;
+ font-style: normal }
+
+div.figure {
+ margin-left: 2em }
+
+div.footer, div.header {
+ font-size: smaller }
+
+div.line-block {
+ display: block ;
+ margin-top: 1em ;
+ margin-bottom: 1em }
+
+div.line-block div.line-block {
+ margin-top: 0 ;
+ margin-bottom: 0 ;
+ margin-left: 1.5em }
+
+div.sidebar {
+ margin-left: 1em ;
+ border: medium outset ;
+ padding: 0em 1em ;
+ background-color: #ffffee ;
+ width: 40% ;
+ float: right ;
+ clear: right }
+
+div.sidebar p.rubric {
+ font-family: sans-serif ;
+ font-size: medium }
+
+div.system-messages {
+ margin: 5em }
+
+div.system-messages h1 {
+ color: red }
+
+div.system-message {
+ border: medium outset ;
+ padding: 1em }
+
+div.system-message p.system-message-title {
+ color: red ;
+ font-weight: bold }
+
+div.topic {
+ margin: 2em }
+
+h1 {
+ font-family: Arial, sans-serif;
+ font-size: 20px;
+}
+
+h1.title {
+ text-align: center;
+ font-size: 32px;
+}
+
+h2 {
+ font-size: 16px;
+ font-family: Arial, sans-serif;
+}
+
+h2.subtitle {
+ text-align: center }
+
+h3 {
+ font-size: 12px;
+ font-family: Arial, sans-serif;
+}
+
+hr {
+ width: 75% }
+
+ol.simple, ul.simple {
+ margin-bottom: 1em }
+
+ol.arabic {
+ list-style: decimal }
+
+ol.loweralpha {
+ list-style: lower-alpha }
+
+ol.upperalpha {
+ list-style: upper-alpha }
+
+ol.lowerroman {
+ list-style: lower-roman }
+
+ol.upperroman {
+ list-style: upper-roman }
+
+p.attribution {
+ text-align: right ;
+ margin-left: 50% }
+
+p.caption {
+ font-style: italic }
+
+p.credits {
+ font-style: italic ;
+ font-size: smaller }
+
+p.label {
+ white-space: nowrap }
+
+p.rubric {
+ font-weight: bold ;
+ font-size: larger ;
+ color: maroon ;
+ text-align: center }
+
+p.sidebar-title {
+ font-family: sans-serif ;
+ font-weight: bold ;
+ font-size: larger }
+
+p.sidebar-subtitle {
+ font-family: sans-serif ;
+ font-weight: bold }
+
+p.topic-title {
+ font-weight: bold }
+
+pre.address {
+ margin-bottom: 0 ;
+ margin-top: 0 ;
+ font-family: serif ;
+ font-size: 100% }
+
+pre.line-block {
+ font-family: serif ;
+ font-size: 100% }
+
+pre.literal-block, pre.doctest-block {
+ margin-left: 2em ;
+ margin-right: 2em ;
+ background-color: #eeeeee }
+
+span.classifier {
+ font-family: sans-serif ;
+ font-style: oblique }
+
+span.classifier-delimiter {
+ font-family: sans-serif ;
+ font-weight: bold }
+
+span.interpreted {
+ font-family: sans-serif }
+
+span.option {
+ white-space: nowrap }
+
+span.option-argument {
+ font-style: italic }
+
+span.pre {
+ white-space: pre }
+
+span.problematic {
+ color: red }
+
+table {
+ margin-top: 0.5em ;
+ margin-bottom: 0.5em }
+
+table.citation {
+ border-left: solid thin gray ;
+ padding-left: 0.5ex }
+
+table.docinfo {
+ margin: 2em 4em;
+}
+
+table.footnote {
+ border-left: solid thin black ;
+ padding-left: 0.5ex }
+
+td, th {
+ padding-left: 0.5em ;
+ padding-right: 0.5em ;
+ vertical-align: top }
+
+th.docinfo-name, th.field-name {
+ font-weight: bold ;
+ text-align: left ;
+ white-space: nowrap;
+ }
+
+h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt {
+ font-size: 100% }
+
+tt {
+ font: Courier,monospaced;
+ font-size: 12px;
+ background-color: #eeeeee }
+
+ul.auto-toc {
+ list-style-type: none }
+
+</style>
+</head>
+<body>
+<div class="document" id="tinyos-2-0-overview">
+<h1 class="title">TinyOS 2.0 Overview</h1>
+<table class="docinfo" frame="void" rules="none">
+<col class="docinfo-name" />
+<col class="docinfo-content" />
+<tbody valign="top">
+<tr><th class="docinfo-name">Author:</th>
+<td>Philip Levis</td></tr>
+<tr><th class="docinfo-name">Date:</th>
+<td>Oct 30 2006</td></tr>
+</tbody>
+</table>
+<div class="note">
+<p class="first admonition-title">Note</p>
+<p class="last">This document gives a brief overview of TinyOS 2.0, highlighting how
+and where it departs from 1.1 and 1.0. Further detail on these changes
+is detailed in TEP (TinyOS Enhancement Proposal) documents.</p>
+</div>
+<div class="section">
+<h1><a id="introduction" name="introduction">1. Introduction</a></h1>
+<p>TinyOS 2.0 is a clean slate redesign and re-implementation of TinyOS.
+Its development was motivated by our belief that many aspects of 1.x
+strain to meet requirements and uses that were not foreseen
+when it was designed and implemented. The structure and interfaces 1.x
+defines have several fundamental limitations. While these limitations
+can be worked around, this practice has led to tightly coupled
+components, hard to find interactions, and a very steep learning curve
+for a newcomer to sensor network programming.</p>
+<p>TinyOS 2.0 is not backwards compatible with 1.x: code written for the
+latter will not compile for the former. However, one important aspect
+of 2.0's design is to minimize the difficulty of upgrading
+code. Therefore, while porting a 1.x application to 2.0 will require
+some work, it should not be very much.</p>
+<p>This document provides a high-level overview of 2.0 and describes some
+of the ways in which it departs from 1.x. It covers the basic TinyOS
+abstractions, such as hardware abstractions, communication, timers,
+the scheduler, booting and initialization. Further detail on each of
+these can be found in TEPs (TinyOS Enhancement Proposals), which
+document and describe these abstractions.</p>
+</div>
+<div class="section">
+<h1><a id="platforms-hardware-abstraction" name="platforms-hardware-abstraction">2. Platforms/Hardware Abstraction</a></h1>
+<p>Platforms exist in the <tt class="docutils literal"><span class="pre">tos/platforms</span></tt> subdirectory. In TinyOS 2.0, a
+<em>platform</em> is a collection of <em>chips</em> and some glue code that connects
+them together. For example, the mica2 platform is the CC1000 radio
+chip and the ATmega128 microcontroller, while the micaZ platform is
+the CC2420 radio and the ATmega128 microcontroller, and the Teloi
+platforms are the CC2420 radio and the MSP430 microcontroller. Chip
+code exists in <tt class="docutils literal"><span class="pre">tos/chips</span></tt>. A platform directory generally has a
+<tt class="docutils literal"><span class="pre">.platform</span></tt> file, which has options to pass to the nesC compiler. For
+example, the mica2 .platform file tells ncc to look in <tt class="docutils literal"><span class="pre">chips/cc1000</span></tt>
+and <tt class="docutils literal"><span class="pre">chips/atm128</span></tt> directories, as well as to use avr-gcc to compile a
+mote binary (Teloi platforms tell it to use msp430-gcc).</p>
+<p>Hardware abstractions in TinyOS 2.0 generally follow a three-level
+abstaction heirarchy, called the HAA (Hardware Abstraction
+Architecture).</p>
+<p>At the bottom of the HAA is the HPL (Hardware Presentation Layer). The
+HPL is a thin software layer on top of the raw hardware, presenting
+hardare such as IO pins or registers as nesC interfaces. The HPL
+generally has no state besides the hardware itself (it has no
+variables). HPL components usually have the prefix <tt class="docutils literal"><span class="pre">Hpl</span></tt>, followed by
+the name of the chip. For example, the HPL components of the CC1000
+begin with <tt class="docutils literal"><span class="pre">HplCC1000</span></tt>.</p>
+<p>The middle of the HAA is the HAL (Hardware Abstraction Layer). The HAL
+builds on top of the HPL and provides higher-level abstractions that
+are easier to use than the HPL but still provide the full
+functionality of the underlying hardware. The HAL components usually have
+a prefix of the chip name. For example, the HAL components of the CC1000
+begin with <tt class="docutils literal"><span class="pre">CC1000</span></tt>.</p>
+<p>The top of the HAA is the HIL (Hardware Independent Layer). The HIL
+builds on top of the HAL and provides abstractions that are hardware
+independent. This generalization means that the HIL usually does not
+provide all of the functionality that the HAL can. HIL components have
+no naming prefix, as they represent abstractions that applications can
+use and safely compile on multiple platforms. For example, the HIL
+component of the CC1000 on the mica2 is <tt class="docutils literal"><span class="pre">ActiveMessageC</span></tt>, representing
+a full active message communication layer.</p>
+<p>The HAA is described in TEP 2: Hardware Abstraction Architecture[<a class="reference" href="#tep2">TEP2</a>].</p>
+<p>Currently (as of the 2.0 release in November 2006), TinyOS 2.0 supports
+the following platforms:</p>
+<blockquote>
+<ul class="simple">
+<li>eyesIFXv2</li>
+<li>intelmote2</li>
+<li>mica2</li>
+<li>mica2dot</li>
+<li>micaZ</li>
+<li>telosb</li>
+<li>tinynode</li>
+<li>btnode3</li>
+</ul>
+</blockquote>
+<p>The btnode3 platform is not included in the RPM.</p>
+</div>
+<div class="section">
+<h1><a id="scheduler" name="scheduler">3. Scheduler</a></h1>
+<p>As with TinyOS 1.x, TinyOS 2.0 scheduler has a non-preemptive FIFO
+policy. However, tasks in 2.0 operate slightly differently than in
+1.x.</p>
+<p>In TinyOS 1.x, there is a shared task queue for all tasks, and a
+component can post a task multiple times. If the task queue is full,
+the post operation fails. Experience with networking stacks showed
+this to be problematic, as the task might signal completion of a
+split-phase operation: if the post fails, the component above might
+block forever, waiting for the completion event.</p>
+<p>In TinyOS 2.x, every task has its own reserved slot in the task queue,
+and a task can only be posted once. A post fails if and only if the
+task has already been posted. If a component needs to post a task
+multiple times, it can set an internal state variable so that when
+the task executes, it reposts itself.</p>
+<p>This slight change in semantics greatly simplifies a lot of component
+code. Rather than test to see if a task is posted already before
+posting it, a component can just post the task. Components do not have
+to try to recover from failed posts and retry. The cost is one byte of
+state per task. Even in large systems such as TinyDB, this cost is
+under one hundred bytes (in TinyDB is is approximately 50).</p>
+<p>Applications can also replace the scheduler, if they wish. This allows
+programmers to try new scheduling policies, such as priority- or
+deadline-based. It is important to maintain non-preemptiveness,
+however, or the scheduler will break all nesC's static concurrency
+analysis. Details on the new scheduler and how to extend it can be found
+in TEP 106: Schedulers and Tasks[<a class="reference" href="#tep106">TEP106</a>].</p>
+</div>
+<div class="section">
+<h1><a id="booting-initialization" name="booting-initialization">4. Booting/Initialization</a></h1>
+<p>TinyOS 2.0 has a different boot sequence than 1.x. The 1.x interface
+<tt class="docutils literal"><span class="pre">StdControl</span></tt> has been split into two interfaces: <tt class="docutils literal"><span class="pre">Init</span></tt> and
+<tt class="docutils literal"><span class="pre">StdControl</span></tt>. The latter only has two commands: <tt class="docutils literal"><span class="pre">start</span></tt> and <tt class="docutils literal"><span class="pre">stop</span></tt>.
+In TinyOS 1.x, wiring components to the boot sequence would cause them
+to be powered up and started at boot. That is no longer the case: the
+boot sequence only initializes components. When it has completed
+initializing the scheduler, hardware, and software, the boot sequence
+signals the <tt class="docutils literal"><span class="pre">Boot.booted</span></tt> event. The top-level application component
+handles this event and start services accordingly. Details on
+the new boot sequence can be found in TEP 107: TinyOS 2.x Boot
+Sequence[<a class="reference" href="#tep107">TEP107</a>].</p>
+</div>
+<div class="section">
+<h1><a id="virtualization" name="virtualization">5. Virtualization</a></h1>
+<p>TinyOS 2.0 is written with nesC 1.2, which introduces the concept
+of a 'generic' or instantiable component. Generic modules allow
+TinyOS to have reusable data structures, such as bit vectors and
+queues, which simplify development. More importantly, generic
+configurations allow services to encapsulate complex wiring
+relationships for clients that need them.</p>
+<p>In practice, this means that many basic TinyOS services are now
+<em>virtualized.</em> Rather than wire to a component with a parameterized
+interface (e.g., GenericComm or TimerC in 1.x), a program instantiates
+a service component that provides the needed interface. This
+service component does all of the wiring underneath (e.g., in the
+case of timers, to a unique) automatically, reducing wiring
+mistakes and simplifying use of the abstraction.</p>
+</div>
+<div class="section">
+<h1><a id="timers" name="timers">6. Timers</a></h1>
+<p>TinyOS 2.0 provides a much richer set of timer interfaces than
+1.x. Experience has shown that timers are one of the most critical
+abstractions a mote OS can provide, and so 2.0 expands the fidelity
+and form that timers take. Depending on the hardware resources of a
+platform, a component can use 32KHz as well as millisecond granularity
+timers, and the timer system may provide one or two high-precision
+timers that fire asynchronously (they have the async
+keyword). Components can query their timers for how much time
+remainins before they fire, and can start timers in the future (e.g.,
+'start firing a timer at 1Hz starting 31ms from now'). TEP 102:
+Timers[<a class="reference" href="#tep102">TEP102</a>] defines what HIL components a platform must provide
+in order to support standard TinyOS timers. Platforms are
+required to provide millisecond granularity timers, and can provide
+finer granularity timers (e.g., 32kHz) if needed.</p>
+<p>Timers present a good example of virtualization in 2.0. In 1.x,
+a program instantiates a timer by wiring to TimerC:</p>
+<pre class="literal-block">
+components App, TimerC;
+App.Timer -> TimerC.Timer[unique("Timer")];
+</pre>
+<p>In 2.0, a program instantiates a timer:</p>
+<pre class="literal-block">
+components App, new TimerMilliC();
+App.Timer -> TimerMilliC;
+</pre>
+</div>
+<div class="section">
+<h1><a id="communication" name="communication">7. Communication</a></h1>
+<p>In TinyOS 2.0, the message buffer type is <tt class="docutils literal"><span class="pre">message_t</span></tt>, and it is a
+buffer that is large enough to hold a packet from any of a node's
+communication interfaces. The structure itself is completely opaque:
+components cannot reference its fields. Instead, all buffer accesses
+go through interfaces. For example, to get the destination address of
+an AM packet named <tt class="docutils literal"><span class="pre">msg</span></tt>, a component calls <tt class="docutils literal"><span class="pre">AMPacket.destination(msg)</span></tt>.</p>
+<p>Send interfaces distinguish the addressing mode of communication
+abstractions. For example, active message communication has the
+<tt class="docutils literal"><span class="pre">AMSend</span></tt> interface, as sending a packet require an AM destination
+address. In contrast, broadcasting and collection tree abstractions
+have the address-free <tt class="docutils literal"><span class="pre">Send</span></tt> interface.</p>
+<p>Active messages are the network HIL. A platform's <tt class="docutils literal"><span class="pre">ActiveMessageC</span></tt>
+component defines which network interface is the standard
+communication medium. For example, a mica2 defines the CC1000 active
+message layer as ActiveMessageC, while the TMote defines the CC2420
+active message layer as ActiveMessageC.</p>
+<p>There is no longer a TOS_UART_ADDRESS for active message
+communication. Instead, a component should wire to
+SerialActiveMessageC, which provides active message communication over
+the serial port.</p>
+<p>Active message communication is virtualized through four generic
+components, which take the AM type as a parameter: AMSenderC,
+AMReceiverC, AMSnooperC, and AMSnoopingReceiverC. AMSenderC is
+virtualized in that the call to send() does not fail if some
+other component is sending (as it does with GenericComm in 1.x). Instead,
+it fails only if that particular AMSenderC already has a packet
+outstanding or if the radio is not in a sending state. Underneath,
+the active message system queues and sends these outstanding packets.
+This is different than the QueuedSendC approach of 1.x, in which there
+is an N-deep queue that is shared among all senders. With N AMSenderC
+components, there is an N-deep queue where each sender has a single
+reserved entry. This means that each AMSenderC receives
+1/n of the available post-MAC transmission opportunities, where
+n is the number of AMSenderC components with outstanding packets.
+In the worst case, n is the number of components; even when every
+protocol and component that sends packets is trying to send a packet,
+each one will receive its fair share of transmission opportunities.</p>
+<p>Further information on message_t can be found in TEP 111:
+message_t[<a class="reference" href="#tep111">TEP111</a>], while further information on AM can be
+found in TEP 116: Packet Protocols[<a class="reference" href="#tep116">TEP116</a>].</p>
+<p>The current TinyOS release has a low-power stack for the CC1000
+radio (mica2 platform) and an experimental low-power stack for
+the CC2420 radio (micaz, telosb, and intelmote2 platforms).</p>
+</div>
+<div class="section">
+<h1><a id="sensors" name="sensors">8. Sensors</a></h1>
+<p>In TinyOS 2.0, named sensor components comprise the HIL of a
+platform's sensors. TEP 114 describes a set of HIL data acquisition
+interfaces, such as Read, ReadStream, and Get, which sensors
+provide according to their acquisition capabilities.</p>
+<p>If a component needs
+high-frequency or very accurate sampling, it must use the HAL, which
+gives it the full power of the underlying platform (highly accurate
+platform-independent sampling is not really feasible, due to the
+particulars of individual platforms). <tt class="docutils literal"><span class="pre">Read</span></tt> assumes that the
+request can tolerate some latencies (for example, it might schedule
+competing requests using a FIFO policy).</p>
+<p>Details on the ADC subsystem can be found in
+TEP 101: Analog-to-Digital Converters[<a class="reference" href="#tep101">TEP101</a>]; details on
+the organization of sensor boards can be found in TEP 109:
+Sensorboards[<a class="reference" href="#tep109">TEP109</a>], and the details of the HIL sensor interfaces
+can be found in TEP 114: Source and Sink Independent Drivers[<a class="reference" href="#tep114">TEP114</a>].</p>
+</div>
+<div class="section">
+<h1><a id="error-codes" name="error-codes">9. Error Codes</a></h1>
+<p>The standard TinyOS 1.x return code is <tt class="docutils literal"><span class="pre">result_t</span></tt>, whose value is
+either SUCCESS (a non-zero value) or FAIL (a zero value). While this
+makes conditionals on calls very easy to write (e.g., <tt class="docutils literal"><span class="pre">if</span> <span class="pre">(call</span>
+<span class="pre">A.b())</span></tt>), it does not allow the callee to distinguish causes of error
+to the caller. In TinyOS 2.0, <tt class="docutils literal"><span class="pre">result_t</span></tt> is replaced by <tt class="docutils literal"><span class="pre">error_t</span></tt>,
+whose values include SUCCESS, FAIL, EBUSY, and ECANCEL. Interface
+commands and events define which error codes they may return and why.</p>
+<p>From the perspective of porting code, this is the most significant
+different in 2.0. Calls that were once:</p>
+<pre class="literal-block">
+if (call X.y()) {
+ busy = TRUE;
+}
+</pre>
+<p>now have their meanings reversed. In 1.x, the busy statement will execute
+if the call succeeds, while in 2.0 it will execute if the call fails.
+This encourages a more portable, upgradable, and readable approach:</p>
+<pre class="literal-block">
+if (call X.y() == SUCCESS) {
+ busy = TRUE;
+}
+</pre>
+</div>
+<div class="section">
+<h1><a id="arbitration" name="arbitration">10. Arbitration</a></h1>
+<p>While basic abstractions, such as packet communication and timers,
+can be virtualized, experiences with 1.x showed that some cannot
+without either adding significant complexity or limiting the system.
+The most pressing example of this is a shared bus on a microcontroller.
+Many different systems -- sensors, storage, the radio -- might need
+to use the bus at the same time, so some way of arbitrating access
+is needed.</p>
+<p>To support these kinds of abstractions, TinyOS 2.0 introduces
+the Resource interface, which components use to request and
+acquire shared resources, and arbiters, which provide a policy for
+arbitrating access between multiple clients. For some abstractions,
+the arbiter also provides a power management policy, as it can tell
+when the system is no longer needed and can be safely turned off.</p>
+<p>TEP 108: Resource Arbitration[<a class="reference" href="#tep108">TEP108</a>] describes the Resource interface
+and how arbiters work.</p>
+</div>
+<div class="section">
+<h1><a id="power-management" name="power-management">11. Power Management</a></h1>
+<p>Power management in 2.0 is divided into two parts: the power state
+of the microcontroller and the power state of devices. The former,
+discussed in TEP 112: Microcontroller Power Management[<a class="reference" href="#tep112">TEP112</a>],
+is computed in a chip-specific manner by examining which devices
+and interrupt souces are active. The latter, discussed in
+TEP 115: Power Management of Non-Virtualised Devices{<a class="reference" href="#tep115">TEP115</a>], is handled
+through resource abiters. Fully virtualized services have their
+own, individual power management policies.</p>
+<p>TinyOS 2.0 provides low-power stacks for the CC1000 (mica2)
+and CC2420 (micaz, telosb, imote2) radios. Both use a low-power
+listening apporach, where transmitters send long preambles or
+repeatedly send packets and receivers wake up periodically to
+sense the channel to hear if there is a packet being
+transmitted. The low-power stack CC1000 is standard, while
+the CC2420 stack is experimental. That is, the default CC1000
+stack (chips/cc1000) has low-power-listening, while the default
+CC2420 stack (chips/cc2420) does not. To use the low-power CC2420
+stack, you must include chips/cc2420_lpl in your application Makefile.</p>
+</div>
+<div class="section">
+<h1><a id="network-protocols" name="network-protocols">12. Network Protocols</a></h1>
+<p>TinyOS 2.0 provides simple reference implementations of two of
+the most basic protocols used in mote networks: dissemination
+and collection. Dissemination reliably delivers small (fewer
+than 20 byte) data items to every node in a network, while
+collection builds a routing tree rooted at a sink node. Together,
+these two protocols enable a wide range of data collection
+applications. Collection has advanced significantly since the
+most recent beta release; experimental tests in multiple
+network conditions have seen very high (>98%) deliver rates
+as long as the network is not saturated.</p>
+</div>
+<div class="section">
+<h1><a id="conclusion" name="conclusion">13. Conclusion</a></h1>
+<p>TinyOS 2.0 represents the next step of TinyOS development. Building on
+user experiences over the past few years, it has taken the basic
+TinyOS architecture and pushed it forward in several directions,
+hopefully leading to simpler and easier application development. It is
+still under active development: future prereleases will include
+non-volatile storage, basic multihop protocols (collection routing,
+dissemination), and further power management abstractions.</p>
+</div>
+<div class="section">
+<h1><a id="acknowledgments" name="acknowledgments">14. Acknowledgments</a></h1>
+<p>TinyOS 2.0 is the result of a lot of hard work from a lot of people,
+including (but not limited to) David Gay, Philip Levis, Cory Sharp,
+Vlado Handziski, Jan Hauer, Kevin Klues, Joe Polastre, Jonathan Hui,
+Prabal Dutta,
+Gilman Tolle, Martin Turon, Phil Buonodonna, Ben Greenstein, David Culler,
+Kristin Wright, Ion Yannopoulos, Henri Dubois-Ferriere, Jan Beutel,
+Robert Szewczyk, Rodrigo Fonseca, Kyle Jamieson, Omprakash Gnawali,
+David Moss, and Kristin Wright.</p>
+</div>
+<div class="section">
+<h1><a id="author-s-address" name="author-s-address">15. Author's Address</a></h1>
+<div class="line-block">
+<div class="line">Philip Levis</div>
+<div class="line">358 Gates</div>
+<div class="line">Computer Systems Laboratory</div>
+<div class="line">Stanford University</div>
+<div class="line">Stanford, CA 94305</div>
+<div class="line"><br /></div>
+<div class="line">phone - +1 650 725 9046</div>
+<div class="line"><br /></div>
+<div class="line">email - <a class="reference" href="mailto:pal@cs.stanford.edu">pal@cs.stanford.edu</a></div>
+</div>
+</div>
+<div class="section">
+<h1><a id="citations" name="citations">16. Citations</a></h1>
+<table class="docutils citation" frame="void" id="tep1" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a name="tep1">[TEP1]</a></td><td>TEP 1: TEP Structure and Keywords. <a class="reference" href="http://tinyos.cvs.sourceforge.net/">http://tinyos.cvs.sourceforge.net/</a><em>checkout</em>/tinyos/tinyos-2.x/doc/html/tep1.html?pathrev=tinyos-2_0_devel-BRANCH</td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="tep2" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a name="tep2">[TEP2]</a></td><td>TEP 2: Hardware Abstraction Architecture. <a class="reference" href="http://tinyos.cvs.sourceforge.net/">http://tinyos.cvs.sourceforge.net/</a><em>checkout</em>/tinyos/tinyos-2.x/doc/html/tep2.html?pathrev=tinyos-2_0_devel-BRANCH</td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="tep3" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a name="tep3">[TEP3]</a></td><td>TEP 3: Coding Standard. <a class="reference" href="http://tinyos.cvs.sourceforge.net/">http://tinyos.cvs.sourceforge.net/</a><em>checkout</em>/tinyos/tinyos-2.x/doc/html/tep3.html?pathrev=tinyos-2_0_devel-BRANCH</td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="tep101" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a name="tep101">[TEP101]</a></td><td>TEP 101: Analog-to-Digital Converters. <a class="reference" href="http://tinyos.cvs.sourceforge.net/">http://tinyos.cvs.sourceforge.net/</a><em>checkout</em>/tinyos/tinyos-2.x/doc/html/tep101.html?pathrev=tinyos-2_0_devel-BRANCH</td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="tep102" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a name="tep102">[TEP102]</a></td><td>TEP 102: Timers. <a class="reference" href="http://tinyos.cvs.sourceforge.net/">http://tinyos.cvs.sourceforge.net/</a><em>checkout</em>/tinyos/tinyos-2.x/doc/html/tep102.html?pathrev=tinyos-2_0_devel-BRANCH</td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="tep106" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a name="tep106">[TEP106]</a></td><td>TEP 106: Schedulers and Tasks. <a class="reference" href="http://tinyos.cvs.sourceforge.net/">http://tinyos.cvs.sourceforge.net/</a><em>checkout</em>/tinyos/tinyos-2.x/doc/html/tep106.html?pathrev=tinyos-2_0_devel-BRANCH</td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="tep107" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a name="tep107">[TEP107]</a></td><td>TEP 107: Boot Sequence. <a class="reference" href="http://tinyos.cvs.sourceforge.net/">http://tinyos.cvs.sourceforge.net/</a><em>checkout</em>/tinyos/tinyos-2.x/doc/html/tep107.html?pathrev=tinyos-2_0_devel-BRANCH</td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="tep108" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a name="tep108">[TEP108]</a></td><td>TEP 108: message_t. <a class="reference" href="http://tinyos.cvs.sourceforge.net/">http://tinyos.cvs.sourceforge.net/</a><em>checkout</em>/tinyos/tinyos-2.x/doc/html/tep108.html?pathrev=tinyos-2_0_devel-BRANCH</td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="tep109" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a name="tep109">[TEP109]</a></td><td>TEP 109: Sensorboards. <a class="reference" href="http://tinyos.cvs.sourceforge.net/">http://tinyos.cvs.sourceforge.net/</a><em>checkout</em>/tinyos/tinyos-2.x/doc/html/tep109.html?pathrev=tinyos-2_0_devel-BRANCH</td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="tep110" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a name="tep110">[TEP110]</a></td><td>TEP 110: Service Distributions. <a class="reference" href="http://tinyos.cvs.sourceforge.net/">http://tinyos.cvs.sourceforge.net/</a><em>checkout</em>/tinyos/tinyos-2.x/doc/html/tep110.html?pathrev=tinyos-2_0_devel-BRANCH</td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="tep111" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a name="tep111">[TEP111]</a></td><td>TEP 111: message_t. <a class="reference" href="http://tinyos.cvs.sourceforge.net/">http://tinyos.cvs.sourceforge.net/</a><em>checkout</em>/tinyos/tinyos-2.x/doc/html/tep111.html?pathrev=tinyos-2_0_devel-BRANCH</td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="tep112" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a name="tep112">[TEP112]</a></td><td>TEP 112: Microcontroller Power Management. <a class="reference" href="http://tinyos.cvs.sourceforge.net/">http://tinyos.cvs.sourceforge.net/</a><em>checkout</em>/tinyos/tinyos-2.x/doc/html/tep112.html?pathrev=tinyos-2_0_devel-BRANCH</td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="tep113" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a name="tep113">[TEP113]</a></td><td>TEP 113: Serial Communication. <a class="reference" href="http://tinyos.cvs.sourceforge.net/">http://tinyos.cvs.sourceforge.net/</a><em>checkout</em>/tinyos/tinyos-2.x/doc/html/tep113.html?pathrev=tinyos-2_0_devel-BRANCH</td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="tep114" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a name="tep114">[TEP114]</a></td><td>TEP 114: SIDs: Source and Sink Independent Drivers. <a class="reference" href="http://tinyos.cvs.sourceforge.net/">http://tinyos.cvs.sourceforge.net/</a><em>checkout</em>/tinyos/tinyos-2.x/doc/html/tep114.html?pathrev=tinyos-2_0_devel-BRANCH</td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="tep115" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a name="tep115">[TEP115]</a></td><td>TEP 115: Power Management of Non-Virtualised Devices. <a class="reference" href="http://tinyos.cvs.sourceforge.net/">http://tinyos.cvs.sourceforge.net/</a><em>checkout</em>/tinyos/tinyos-2.x/doc/html/tep115.html?pathrev=tinyos-2_0_devel-BRANCH</td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="tep116" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a name="tep116">[TEP116]</a></td><td>TEP 116: Packet Protocols. <a class="reference" href="http://tinyos.cvs.sourceforge.net/">http://tinyos.cvs.sourceforge.net/</a><em>checkout</em>/tinyos/tinyos-2.x/doc/html/tep116.html?pathrev=tinyos-2_0_devel-BRANCH</td></tr>
+</tbody>
+</table>
+</div>
+</div>
+</body>
+</html>
<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.6: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
<title>Porting TinyOS 1.x Code to TinyOS 2.0</title>
<meta name="author" content="Tahir Azim and Philip Levis" />
<meta name="date" content="October 26 2006" />
dd {
margin-bottom: 0.5em }
-/* Uncomment (& remove this text!) to get bold-faced definition list terms
-dt {
- font-weight: bold }
-*/
-
div.abstract {
margin: 2em 5em }
</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" id="porting-points">
-<h1><a name="porting-points">1. Porting Points</a></h1>
+<div class="section">
+<h1><a id="porting-points" name="porting-points">1. Porting Points</a></h1>
<p>As these observations come from porting a network protocol, they are
rather protocol-centric and do not consider other abstractions such
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" id="author-s-address">
-<h1><a name="author-s-address">2. Author's Address</a></h1>
+<div class="section">
+<h1><a id="author-s-address" name="author-s-address">2. Author's Address</a></h1>
<div class="line-block">
<div class="line">Tahir Azim</div>
<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" id="citations">
-<h1><a name="citations">3. Citations</a></h1>
+<div class="section">
+<h1><a id="citations" name="citations">3. Citations</a></h1>
<table class="docutils footnote" frame="void" id="id1" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<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.3.7: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
<title>TEP Structure and Keywords</title>
<meta name="author" content="Philip Levis" />
<style type="text/css">
dd {
margin-bottom: 0.5em }
-/* Uncomment (& remove this text!) to get bold-faced definition list terms
-dt {
- font-weight: bold }
-*/
-
div.abstract {
margin: 2em 5em }
TinyOS Community, and requests discussion and suggestions for
improvements. Distribution of this memo is unlimited.</p>
</div>
-<div class="section" id="abstract">
-<h1><a name="abstract">Abstract</a></h1>
+<div class="section">
+<h1><a id="abstract" name="abstract">Abstract</a></h1>
<p>This memo describes the structure all TinyOS Extension Proposal (TEP)
documents follow, and defines the meaning of several key words in
those documents.</p>
</div>
-<div class="section" id="introduction">
-<h1><a name="introduction">1. Introduction</a></h1>
+<div class="section">
+<h1><a id="introduction" name="introduction">1. Introduction</a></h1>
<p>In order to simplify management, reading, and tracking development,
all TinyOS Extension Proposals (TEPs) MUST have a particular
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" id="keywords">
-<h1><a name="keywords">2. Keywords</a></h1>
+<div class="section">
+<h1><a id="keywords" name="keywords">2. Keywords</a></h1>
<p>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in TEP 1.</p>
level of the document in which they are used. These words hold their
special meanings only when capitalized, and documents SHOULD avoid using
these words uncapitalized in order to minimize confusion.</p>
-<div class="section" id="must">
-<h2><a name="must">2.1 MUST</a></h2>
+<div class="section">
+<h2><a id="must" name="must">2.1 MUST</a></h2>
<p>MUST: This word, or the terms "REQUIRED" or "SHALL", mean that the
definition is an absolute requirement of the specification.</p>
</div>
-<div class="section" id="must-not">
-<h2><a name="must-not">2.2 MUST NOT</a></h2>
+<div class="section">
+<h2><a id="must-not" name="must-not">2.2 MUST NOT</a></h2>
<p>MUST NOT: This phrase, or the phrase "SHALL NOT", mean that the
definition is an absolute prohibition of the specification.</p>
</div>
-<div class="section" id="should">
-<h2><a name="should">2.3 SHOULD</a></h2>
+<div class="section">
+<h2><a id="should" name="should">2.3 SHOULD</a></h2>
<p>SHOULD: This word, or the adjective "RECOMMENDED", mean that there
may exist valid reasons in particular circumstances to ignore a
particular item, but the full implications must be understood and
carefully weighed before choosing a different course.</p>
</div>
-<div class="section" id="should-not">
-<h2><a name="should-not">2.4 SHOULD NOT</a></h2>
+<div class="section">
+<h2><a id="should-not" name="should-not">2.4 SHOULD NOT</a></h2>
<p>SHOULD NOT: This phrase, or the phrase "NOT RECOMMENDED" mean that
there may exist valid reasons in particular circumstances when the
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" id="may">
-<h2><a name="may">2.5 MAY</a></h2>
+<div class="section">
+<h2><a id="may" name="may">2.5 MAY</a></h2>
<p>MAY: This word, or the adjective "OPTIONAL", mean that an item is
truly optional. One implementer may choose to include the item
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" 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>
+<div class="section">
+<h2><a id="guidance-in-the-use-of-these-imperatives" name="guidance-in-the-use-of-these-imperatives">2.6 Guidance in the use of these Imperatives</a></h2>
<p>Imperatives of the type defined in this memo must be used with care
and sparingly. In particular, they MUST only be used where it is
actually required for interoperation or to limit behavior which has
interoperability.</p>
</div>
</div>
-<div class="section" id="tep-structure">
-<h1><a name="tep-structure">3. TEP Structure</a></h1>
+<div class="section">
+<h1><a id="tep-structure" name="tep-structure">3. TEP Structure</a></h1>
<p>TEPs have two major parts, a header and a body. The header states
-document metadata, for management and status. The body contains the
+document metadata, for management and status. The body contains the
content of the proposal.</p>
<p>All TEPs MUST conform to reStructuredText standards <a class="footnote-reference" href="#id2" id="id1" name="id1">[1]</a> and follow
the docutils template, to enable translation from reStructuredText
to HTML and LaTeX.</p>
-<div class="section" id="tep-header">
-<h2><a name="tep-header">3.1 TEP Header</a></h2>
+<div class="section">
+<h2><a id="tep-header" name="tep-header">3.1 TEP Header</a></h2>
<p>The TEP header has several fields which MUST be included, as well as
others which MAY be included. The TEP header MUST NOT include headers
which are not specified in TEP 1 or supplementary Best Current
Practice TEPs. 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 TEP number assignment. Generally,
when a document is ready to be a TEP, it is assigned the smallest
available number. BCP TEPs start at 1 and all other TEPs
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.
+progress, "Final," which means it is complete and will not change.
Once a TEP has the status "Final," the only change allowed is the
addition of an "Obsoleted By" field.</p>
<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" id="tep-body">
-<h2><a name="tep-body">3.2 TEP Body</a></h2>
+<div class="section">
+<h2><a id="tep-body" name="tep-body">3.2 TEP Body</a></h2>
<p>The first element of the TEP body MUST be the title of the document. A
TEP SHOULD follow the title with an Abstract, which gives a brief
overview of the content of the TEP. Longer TEPs MAY, after the
Appendices are lettered. Please refer to Appendix A for details.</p>
</div>
</div>
-<div class="section" id="reference">
-<h1><a name="reference">4. Reference</a></h1>
+<div class="section">
+<h1><a id="reference" name="reference">4. Reference</a></h1>
<p>The reference use of this document is TEP 1 (itself).</p>
</div>
-<div class="section" id="acknowledgments">
-<h1><a name="acknowledgments">5. Acknowledgments</a></h1>
+<div class="section">
+<h1><a id="acknowledgments" name="acknowledgments">5. Acknowledgments</a></h1>
<p>The definitions of the compliance terms are a direct copy of
definitions taken from IETF RFC 2119.</p>
</div>
-<div class="section" id="author-s-address">
-<h1><a name="author-s-address">6. Author's Address</a></h1>
+<div class="section">
+<h1><a id="author-s-address" name="author-s-address">6. Author's Address</a></h1>
<div class="line-block">
<div class="line">Philip Levis</div>
<div class="line">358 Gates Hall</div>
-<div class="line">Stanford University </div>
+<div class="line">Stanford University</div>
<div class="line">Stanford, CA 94305</div>
<div class="line"><br /></div>
<div class="line">phone - +1 650 725 9046</div>
<div class="line">email - <a class="reference" href="mailto:pal@cs.stanford.edu">pal@cs.stanford.edu</a></div>
</div>
</div>
-<div class="section" id="citations">
-<h1><a name="citations">7. Citations</a></h1>
+<div class="section">
+<h1><a id="citations" name="citations">7. Citations</a></h1>
<table class="docutils footnote" frame="void" id="id2" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
</tbody>
</table>
</div>
-<div class="section" id="appendix-a-example-appendix">
-<h1><a name="appendix-a-example-appendix">Appendix A. Example Appendix</a></h1>
+<div class="section">
+<h1><a id="appendix-a-example-appendix" name="appendix-a-example-appendix">Appendix A. Example Appendix</a></h1>
<p>This is an example appendix. Appendices begin with the letter A.</p>
</div>
</div>
<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.6: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
<title>Analog-to-Digital Converters (ADCs)</title>
<meta name="author" content="Jan-Hinrich Hauer, Philip Levis, Vlado Handziski, David Gay" />
<style type="text/css">
dd {
margin-bottom: 0.5em }
-/* Uncomment (& remove this text!) to get bold-faced definition list terms
-dt {
- font-weight: bold }
-*/
-
div.abstract {
margin: 2em 5em }
</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" id="abstract">
-<h1><a name="abstract">Abstract</a></h1>
+<div class="section">
+<h1><a id="abstract" name="abstract">Abstract</a></h1>
<p>This TEP proposes a hardware abstraction for analog-to-digital converters (ADCs)
in TinyOS 2.x, which is aligned to the three-layer Hardware Abstraction
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" id="introduction">
-<h1><a name="introduction">1. Introduction</a></h1>
+<div class="section">
+<h1><a id="introduction" name="introduction">1. Introduction</a></h1>
<p>Analog-to-digital converters (ADCs) are devices that convert analog input
signals to discrete digital output signals, typically voltage to a binary
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" id="interfaces">
-<h1><a name="interfaces">2. Interfaces</a></h1>
+<div class="section">
+<h1><a id="interfaces" name="interfaces">2. Interfaces</a></h1>
<p>This TEP proposes the <tt class="docutils literal"><span class="pre">AdcConfigure</span></tt> interface for ADC hardware configuration
and the <tt class="docutils literal"><span class="pre">Read</span></tt>, <tt class="docutils literal"><span class="pre">ReadStream</span></tt> and <tt class="docutils literal"><span class="pre">ReadNow</span></tt> interfaces to acquire
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" id="interface-for-configuring-the-adc-hardware">
-<h2><a name="interface-for-configuring-the-adc-hardware">Interface for configuring the ADC hardware</a></h2>
+<div class="section">
+<h2><a id="interface-for-configuring-the-adc-hardware" name="interface-for-configuring-the-adc-hardware">Interface for configuring the ADC hardware</a></h2>
<p>The <tt class="docutils literal"><span class="pre">AdcConfigure</span></tt> interface is defined as follows:</p>
<pre class="literal-block">
-interface AdcConfigure< config_type >
+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" id="interfaces-for-acquiring-conversion-results">
-<h2><a name="interfaces-for-acquiring-conversion-results">Interfaces for acquiring conversion results</a></h2>
+<div class="section">
+<h2><a id="interfaces-for-acquiring-conversion-results" name="interfaces-for-acquiring-conversion-results">Interfaces for acquiring conversion results</a></h2>
<p>This TEP proposes to adopt the following two source-independent data
collection interfaces from <a class="citation-reference" href="#tep114" id="id10" name="id10">[TEP114]</a> for the collection of ADC conversion
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" id="read">
-<h3><a name="read">Read</a></h3>
+<div class="section">
+<h3><a id="read" name="read">Read</a></h3>
<p>The <tt class="docutils literal"><span class="pre">Read</span></tt> interface can be used to sample an ADC channel once and return a
single conversion result as an uninterpreted value. The <tt class="docutils literal"><span class="pre">Read</span></tt> interface is
documented in <a class="citation-reference" href="#tep114" id="id11" name="id11">[TEP114]</a>.</p>
</div>
-<div class="section" id="readstream">
-<h3><a name="readstream">ReadStream</a></h3>
+<div class="section">
+<h3><a id="readstream" name="readstream">ReadStream</a></h3>
<p>The <tt class="docutils literal"><span class="pre">ReadStream</span></tt> interface can be used to sample an ADC channel multiple
times with a specified sampling period. The <tt class="docutils literal"><span class="pre">ReadStream</span></tt> interface is
documented in <a class="citation-reference" href="#tep114" id="id12" name="id12">[TEP114]</a> .</p>
</div>
-<div class="section" id="readnow">
-<h3><a name="readnow">ReadNow</a></h3>
+<div class="section">
+<h3><a id="readnow" name="readnow">ReadNow</a></h3>
<p>The <tt class="docutils literal"><span class="pre">ReadNow</span></tt> interface is intended for split-phase low-latency
reading of small values:</p>
<pre class="literal-block">
-interface ReadNow<val_t>
+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" id="hal-guidelines">
-<h1><a name="hal-guidelines">3. HAL guidelines</a></h1>
+<div class="section">
+<h1><a id="hal-guidelines" name="hal-guidelines">3. HAL guidelines</a></h1>
<p>As explained in <a class="reference" href="#introduction">1. Introduction</a> the HAL exposes the full capabilities of the
ADC hardware. Therefore only chip- and platform-dependent clients can wire to
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" id="resource-reservation">
-<h2><a name="resource-reservation">Resource reservation</a></h2>
+<div class="section">
+<h2><a id="resource-reservation" name="resource-reservation">Resource reservation</a></h2>
<p>As the ADC hardware is a shared resource that is usually multiplexed between
several clients some form of access arbitration is necessary. The HAL should
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" id="configuration-and-sampling">
-<h2><a name="configuration-and-sampling">Configuration and sampling</a></h2>
+<div class="section">
+<h2><a id="configuration-and-sampling" name="configuration-and-sampling">Configuration and sampling</a></h2>
<p>As the ADC hardware is a shared resource the HAL should support hardware
configuration and sampling per client (although per-port configuration is
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" id="hal-virtualization">
-<h2><a name="hal-virtualization">HAL virtualization</a></h2>
+<div class="section">
+<h2><a id="hal-virtualization" name="hal-virtualization">HAL virtualization</a></h2>
<p>In order to hide wiring complexities and/or export only a subset of all ADC
functions generic ADC wrapper components may be provided on the level of HAL.
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" id="hil-requirements">
-<h1><a name="hil-requirements">4. HIL requirements</a></h1>
+<div class="section">
+<h1><a id="hil-requirements" name="hil-requirements">4. HIL requirements</a></h1>
<p>The following generic components MUST be provided on all platforms that have an
ADC:</p>
<pre class="literal-block">
-AdcReadClientC
-AdcReadNowClientC
-AdcReadStreamClientC
+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" id="adcreadclientc">
-<h2><a name="adcreadclientc">AdcReadClientC</a></h2>
+<div class="section">
+<h2><a id="adcreadclientc" 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" id="adcreadnowclientc">
-<h2><a name="adcreadnowclientc">AdcReadNowClientC</a></h2>
+<div class="section">
+<h2><a id="adcreadnowclientc" 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" id="adcreadstreamclientc">
-<h2><a name="adcreadstreamclientc">AdcReadStreamClientC</a></h2>
+<div class="section">
+<h2><a id="adcreadstreamclientc" 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" id="hil-guidelines">
-<h1><a name="hil-guidelines">5. HIL guidelines</a></h1>
+<div class="section">
+<h1><a id="hil-guidelines" name="hil-guidelines">5. HIL guidelines</a></h1>
<p>The HIL implementation of an ADC stack has two main tasks: it translates a
<tt class="docutils literal"><span class="pre">Read</span></tt>, <tt class="docutils literal"><span class="pre">ReadNow</span></tt> or <tt class="docutils literal"><span class="pre">ReadStream</span></tt> request to a chip-specific HAL sampling
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" 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>
+<div class="section">
+<h1><a id="implementation" name="implementation">6. Implementation</a></h1>
+<div class="section">
+<h2><a id="testadc-application" name="testadc-application">TestAdc application</a></h2>
<p>An ADC HIL test application can be found in <tt class="docutils literal"><span class="pre">tinyos-2.x/apps/tests/TestAdc</span></tt>.
Note that this application instantiates generic DemoSensorC, DemoSensorStreamC
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" 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>
+<div class="section">
+<h2><a id="haa-on-the-msp430-and-atmega-128" name="haa-on-the-msp430-and-atmega-128">HAA on the MSP430 and Atmega 128</a></h2>
<p>The implementation of the ADC12 stack on the MSP430 can be found in
<tt class="docutils literal"><span class="pre">tinyos-2.x/tos/chips/msp430/adc12</span></tt>:</p>
<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" id="appendix-a-hardware-differences-between-platforms">
-<h1><a name="appendix-a-hardware-differences-between-platforms">Appendix A: Hardware differences between platforms</a></h1>
+<div class="section">
+<h1><a id="appendix-a-hardware-differences-between-platforms" name="appendix-a-hardware-differences-between-platforms">Appendix A: Hardware differences between platforms</a></h1>
<p>The following table compares the characteristics of two microcontrollers
commonly used in TinyOS platforms:</p>
<table border="1" class="docutils">
<col width="32%" />
</colgroup>
<thead valign="bottom">
-<tr><th> </th>
-<th>Atmel Atmega 128</th>
-<th>TI MSP430 ADC12</th>
+<tr><th class="head"> </th>
+<th class="head">Atmel Atmega 128</th>
+<th class="head">TI MSP430 ADC12</th>
</tr>
</thead>
<tbody valign="top">
</tbody>
</table>
</div>
-<div class="section" id="appendix-b-a-hal-representation-msp430-adc12">
-<h1><a name="appendix-b-a-hal-representation-msp430-adc12">Appendix B: a HAL representation: MSP430 ADC12</a></h1>
+<div class="section">
+<h1><a id="appendix-b-a-hal-representation-msp430-adc12" name="appendix-b-a-hal-representation-msp430-adc12">Appendix B: a HAL representation: MSP430 ADC12</a></h1>
<p>This section shows the HAL signature for the ADC12 of the TI MSP430 MCU. It
reflects the four MSP430 ADC12 conversion modes as it lets a client sample an
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" 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>
+<div class="section">
+<h1><a id="appendix-c-a-hil-representation-msp430-adc12" name="appendix-c-a-hil-representation-msp430-adc12">Appendix C: a HIL representation: MSP430 ADC12</a></h1>
<p>The signature of the AdcReadClientC component for the MSP430 ADC12 is as
follows:</p>
<pre class="literal-block">
dd {
margin-bottom: 0.5em }
-/* Uncomment (& remove this text!) to get bold-faced definition list terms
-dt {
- font-weight: bold }
-*/
-
div.abstract {
margin: 2em 5em }
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 ;
h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt {
font-size: 100% }
-tt {
- font: Courier,monospaced;
- font-size: 12px;
- background-color: #eeeeee }
+tt {}
ul.auto-toc {
list-style-type: none }
<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.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-05-23</td>
+<tr class="field"><th class="docinfo-name">Draft-Modified:</th><td class="field-body">2007-06-11</td>
</tr>
<tr class="field"><th class="docinfo-name">Draft-Discuss:</th><td class="field-body">TinyOS Developer List <tinyos-devel at mail.millennium.berkeley.edu></td>
</tr>
<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.6: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
<title>Permanent Data Storage (Flash)</title>
<meta name="author" content="David Gay, Jonathan Hui" />
<style type="text/css">
dd {
margin-bottom: 0.5em }
-/* Uncomment (& remove this text!) to get bold-faced definition list terms
-dt {
- font-weight: bold }
-*/
-
div.abstract {
margin: 2em 5em }
</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" id="abstract">
-<h1><a name="abstract">Abstract</a></h1>
+<div class="section">
+<h1><a id="abstract" 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" id="introduction">
-<h1><a name="introduction">1. Introduction</a></h1>
+<div class="section">
+<h1><a id="introduction" 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>X</th>
-<th>NOR
+<tr><th class="head">X</th>
+<th class="head">NOR
(ex: ST M25P40,
Intel PXA27x)</th>
-<th>AT45DB</th>
-<th><dl class="first last docutils">
-<dt>NAND</dt>
-<dd>(ex: Samsung
-K9K1G08R0B)</dd>
-</dl>
-</th>
+<th class="head">AT45DB</th>
+<th class="head">NAND
+(ex: Samsung
+K9K1G08R0B)</th>
</tr>
</thead>
<tbody valign="top">
support some applications (e.g., network reprogramming) very well.</li>
</ul>
</div>
-<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>
+<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>
<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" id="hpl-hal-hil-architecture">
-<h1><a name="hpl-hal-hil-architecture">3. HPL/HAL/HIL Architecture</a></h1>
+<div class="section">
+<h1><a id="hpl-hal-hil-architecture" 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" id="hardware-presentation-layer-hpl">
-<h2><a name="hardware-presentation-layer-hpl">3.1 Hardware Presentation Layer (HPL)</a></h2>
+<div class="section">
+<h2><a id="hardware-presentation-layer-hpl" 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" id="hardware-adaptation-layer-hal">
-<h2><a name="hardware-adaptation-layer-hal">3.2 Hardware Adaptation Layer (HAL)</a></h2>
+<div class="section">
+<h2><a id="hardware-adaptation-layer-hal" 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" id="hardware-interface-layer-hil">
-<h2><a name="hardware-interface-layer-hil">3.3 Hardware Interface Layer (HIL)</a></h2>
+<div class="section">
+<h2><a id="hardware-interface-layer-hil" 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" id="non-volatile-storage-abstractions">
-<h1><a name="non-volatile-storage-abstractions">4. Non-Volatile Storage Abstractions</a></h1>
+<div class="section">
+<h1><a id="non-volatile-storage-abstractions" 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" id="volumes">
-<h2><a name="volumes">4.1. Volumes</a></h2>
+<div class="section">
+<h2><a id="volumes" 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" id="large-objects">
-<h2><a name="large-objects">4.2 Large objects</a></h2>
+<div class="section">
+<h2><a id="large-objects" 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" id="logging">
-<h2><a name="logging">4.3 Logging</a></h2>
+<div class="section">
+<h2><a id="logging" 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" id="small-objects">
-<h2><a name="small-objects">4.4 Small objects:</a></h2>
+<div class="section">
+<h2><a id="small-objects" 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" id="implementations">
-<h1><a name="implementations">5. Implementations</a></h1>
+<div class="section">
+<h1><a id="implementations" 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" id="authors-addresses">
-<h1><a name="authors-addresses">6. Authors' Addresses</a></h1>
+<div class="section">
+<h1><a id="authors-addresses" 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" id="citations">
-<h1><a name="citations">7. Citations</a></h1>
+<div class="section">
+<h1><a id="citations" 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" 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>
+<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>
<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" id="a-2-st-m25p">
-<h2><a name="a-2-st-m25p">A.2 ST M25P</a></h2>
+<div class="section">
+<h2><a id="a-2-st-m25p" 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" id="appendix-b-storage-interfaces">
-<h1><a name="appendix-b-storage-interfaces">Appendix B. Storage interfaces</a></h1>
+<div class="section">
+<h1><a id="appendix-b-storage-interfaces" 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" id="b-1-blockstorage-interfaces">
-<h2><a name="b-1-blockstorage-interfaces">B.1 BlockStorage interfaces</a></h2>
+<div class="section">
+<h2><a id="b-1-blockstorage-interfaces" 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" id="b-2-configstorage-interfaces">
-<h2><a name="b-2-configstorage-interfaces">B.2 ConfigStorage interfaces</a></h2>
+<div class="section">
+<h2><a id="b-2-configstorage-interfaces" 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" id="b-3-logstorage-interfaces">
-<h2><a name="b-3-logstorage-interfaces">B.3 LogStorage interfaces</a></h2>
+<div class="section">
+<h2><a id="b-3-logstorage-interfaces" name="b-3-logstorage-interfaces">B.3 LogStorage interfaces</a></h2>
<p>The LogStorage interfaces are:</p>
<pre class="literal-block">
interface LogRead {
--- /dev/null
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
+<title>Low Power Listening</title>
+<meta name="author" content="David Moss, Jonathan Hui, Kevin Klues" />
+<style type="text/css">
+
+/*
+:Author: David Goodger
+:Contact: goodger@users.sourceforge.net
+:date: $Date$
+:version: $Revision$
+:copyright: This stylesheet has been placed in the public domain.
+
+Default cascading style sheet for the HTML output of Docutils.
+*/
+body {
+ font-family: Times;
+ font-size: 16px;
+}
+
+.first {
+ margin-top: 0 ! important }
+
+.last {
+ margin-bottom: 0 ! important }
+
+.hidden {
+ display: none }
+
+a.toc-backref {
+ text-decoration: none ;
+ color: black }
+
+blockquote.epigraph {
+ margin: 2em 5em ; }
+
+dd {
+ margin-bottom: 0.5em }
+
+div.abstract {
+ margin: 2em 5em }
+
+div.abstract p.topic-title {
+ font-weight: bold ;
+ text-align: center }
+
+div.attention, div.caution, div.danger, div.error, div.hint,
+div.important, div.note, div.tip, div.warning, div.admonition {
+ margin: 2em ;
+ border: medium outset ;
+ padding: 1em }
+
+div.attention p.admonition-title, div.caution p.admonition-title,
+div.danger p.admonition-title, div.error p.admonition-title,
+div.warning p.admonition-title {
+ color: red ;
+ font-weight: bold ;
+ font-family: sans-serif }
+
+div.hint p.admonition-title, div.important p.admonition-title,
+div.note p.admonition-title, div.tip p.admonition-title,
+div.admonition p.admonition-title {
+ font-weight: bold ;
+ font-family: sans-serif }
+
+div.dedication {
+ margin: 2em 5em ;
+ text-align: center ;
+ font-style: italic }
+
+div.dedication p.topic-title {
+ font-weight: bold ;
+ font-style: normal }
+
+div.figure {
+ margin-left: 2em }
+
+div.footer, div.header {
+ font-size: smaller }
+
+div.line-block {
+ display: block ;
+ margin-top: 1em ;
+ margin-bottom: 1em }
+
+div.line-block div.line-block {
+ margin-top: 0 ;
+ margin-bottom: 0 ;
+ margin-left: 1.5em }
+
+div.sidebar {
+ margin-left: 1em ;
+ border: medium outset ;
+ padding: 0em 1em ;
+ background-color: #ffffee ;
+ width: 40% ;
+ float: right ;
+ clear: right }
+
+div.sidebar p.rubric {
+ font-family: sans-serif ;
+ font-size: medium }
+
+div.system-messages {
+ margin: 5em }
+
+div.system-messages h1 {
+ color: red }
+
+div.system-message {
+ border: medium outset ;
+ padding: 1em }
+
+div.system-message p.system-message-title {
+ color: red ;
+ font-weight: bold }
+
+div.topic {
+ margin: 2em }
+
+h1 {
+ font-family: Arial, sans-serif;
+ font-size: 20px;
+}
+
+h1.title {
+ text-align: center;
+ font-size: 32px;
+}
+
+h2 {
+ font-size: 16px;
+ font-family: Arial, sans-serif;
+}
+
+h2.subtitle {
+ text-align: center }
+
+h3 {
+ font-size: 12px;
+ font-family: Arial, sans-serif;
+}
+
+hr {
+ width: 75% }
+
+ol.simple, ul.simple {
+ margin-bottom: 1em }
+
+ol.arabic {
+ list-style: decimal }
+
+ol.loweralpha {
+ list-style: lower-alpha }
+
+ol.upperalpha {
+ list-style: upper-alpha }
+
+ol.lowerroman {
+ list-style: lower-roman }
+
+ol.upperroman {
+ list-style: upper-roman }
+
+p.attribution {
+ text-align: right ;
+ margin-left: 50% }
+
+p.caption {
+ font-style: italic }
+
+p.credits {
+ font-style: italic ;
+ font-size: smaller }
+
+p.label {
+ white-space: nowrap }
+
+p.rubric {
+ font-weight: bold ;
+ font-size: larger ;
+ color: maroon ;
+ text-align: center }
+
+p.sidebar-title {
+ font-family: sans-serif ;
+ font-weight: bold ;
+ font-size: larger }
+
+p.sidebar-subtitle {
+ font-family: sans-serif ;
+ font-weight: bold }
+
+p.topic-title {
+ font-weight: bold }
+
+pre.address {
+ margin-bottom: 0 ;
+ margin-top: 0 ;
+ font-family: serif ;
+ font-size: 100% }
+
+pre.line-block {
+ font-family: serif ;
+ font-size: 100% }
+
+pre.literal-block, pre.doctest-block {
+ margin-left: 2em ;
+ margin-right: 2em ;
+ background-color: #eeeeee;
+ border-color: #000000;
+ border-width: thin;
+ font-size: 14px
+}
+
+span.classifier {
+ font-family: sans-serif ;
+ font-style: oblique }
+
+span.classifier-delimiter {
+ font-family: sans-serif ;
+ font-weight: bold }
+
+span.interpreted {
+ font-family: sans-serif }
+
+span.option {
+ white-space: nowrap }
+
+span.option-argument {
+ font-style: italic }
+
+span.pre {
+ white-space: pre }
+
+span.problematic {
+ color: red }
+
+table {
+ margin-top: 0.5em ;
+ margin-bottom: 0.5em }
+
+table.citation {
+ border-left: solid thin gray ;
+ padding-left: 0.5ex }
+
+table.docinfo {
+ margin: 2em 4em;
+}
+
+table.footnote {
+ border-left: solid thin black ;
+ padding-left: 0.5ex }
+
+td, th {
+ padding-left: 0.5em ;
+ padding-right: 0.5em ;
+ vertical-align: top }
+
+th.docinfo-name, th.field-name {
+ font-weight: bold ;
+ text-align: left ;
+ white-space: nowrap;
+ }
+
+h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt {
+ font-size: 100% }
+
+tt {}
+
+ul.auto-toc {
+ list-style-type: none }
+
+</style>
+</head>
+<body>
+<div class="document" id="low-power-listening">
+<h1 class="title">Low Power Listening</h1>
+<table class="docinfo" frame="void" rules="none">
+<col class="docinfo-name" />
+<col class="docinfo-content" />
+<tbody valign="top">
+<tr class="field"><th class="docinfo-name">TEP:</th><td class="field-body">105</td>
+</tr>
+<tr class="field"><th class="docinfo-name">Group:</th><td class="field-body">Core Working Group</td>
+</tr>
+<tr class="field"><th class="docinfo-name">Type:</th><td class="field-body">Documentary</td>
+</tr>
+<tr><th class="docinfo-name">Status:</th>
+<td>Final</td></tr>
+<tr class="field"><th class="docinfo-name">TinyOS-Version:</th><td class="field-body">2.x</td>
+</tr>
+<tr><th class="docinfo-name">Author:</th>
+<td>David Moss, Jonathan Hui, Kevin Klues</td></tr>
+</tbody>
+</table>
+<div class="note">
+<p class="first admonition-title">Note</p>
+<p class="last">This memo documents a part of TinyOS for the TinyOS Community, and
+requests discussion and suggestions for improvements. Distribution
+of this memo is unlimited. This memo is in full compliance with
+TEP 1.</p>
+</div>
+<div class="section">
+<h1><a id="abstract" name="abstract">Abstract</a></h1>
+<p>This TEP describes the structure and implementation of the TinyOS 2.x
+link layer abstractions. The architecture is designed to allow each radio
+type to implement its own low power strategy within the Hardware Adaptation
+Layer (HAL), while maintaining a common application interface. The
+history and strategies for low power listening are discussed, as well
+as expected behavior and implementation recommendations.</p>
+</div>
+<div class="section">
+<h1><a id="introduction" name="introduction">1. Introduction</a></h1>
+<p>Asynchronous low power listening is a strategy used to duty cycle
+the radio while ensuring reliable message delivery since TinyOS 1.x
+<a class="citation-reference" href="#mica2" id="id1" name="id1">[MICA2]</a>.</p>
+<p>While a CC1000 or CC2420 radio is turned on and listening, it can
+actively consume anywhere between 7.4 to 18.8 mA on top of the power
+consumed by other components in the system <a class="citation-reference" href="#cc1000" id="id2" name="id2">[CC1000]</a>,[CC2420]_.
+This can rapidly deplete batteries. In the interest of extending
+battery lifetime, it is best to duty cycle the radio on and off to
+prevent this idle waste of energy. In an asychronous low power
+message delivery scheme, the duty cycling receiver node saves the
+most energy by performing short, periodic receive checks. The power
+consumption burden is then placed on the transmitter node, which
+must modulate the radio channel long enough for the recipient?s
+receive check to detect an incoming message. A synchronous low
+power message delivery scheme takes this idea a step further by
+allowing the transmitter to only transmit when it knows the
+destination node is performing a receive check.</p>
+</div>
+<div class="section">
+<h1><a id="background" name="background">2. Background</a></h1>
+<div class="section">
+<h2><a id="early-tinyos-1-x-cc1000-low-power-listening-implementation" name="early-tinyos-1-x-cc1000-low-power-listening-implementation">2.1 Early TinyOS 1.x CC1000 Low Power Listening Implementation</a></h2>
+<p>TinyOS 1.x introduced low power listening on the CC1000 radio, but
+never introduced a similar scheme for the CC2420 radio in the baseline.
+The CC1000 radio had the following low power listening commands,
+provided directly by CC1000RadioIntM::</p>
+<pre class="literal-block">
+command result_t SetListeningMode(uint8_t power);
+command uint8_t GetListeningMode();
+command result_t SetTransmitMode(uint8_t power);
+command uint8_t GetTransmitMode();
+</pre>
+<p>The uint8_t 'power' mode parameter was initially defined as follows::</p>
+<pre class="literal-block">
+//Original CC1000 Low Power Listening Modes
+Power Mode 0 = 100% duty cycle
+Power Mode 1 = 35.5% duty cycle
+Power Mode 2 = 11.5% duty cycle
+Power Mode 3 = 7.53% duty cycle
+Power Mode 4 = 5.61% duty cycle
+Power Mode 5 = 2.22% duty cycle
+Power Mode 6 = 1.00% duty cycle
+</pre>
+<p>There were several issues with this interface and implementation.
+First, setting up a low power network was cumbersome. The low power
+listening commands had to be directly wired through CC1000RadioIntM,
+and called while the radio was not performing any transactions.
+Second, each node in a network was expected to have the same radio
+power mode. Finally, the pre-programmed duty cycles were not linear
+and offered a very limited selection of options.</p>
+<p>In this low power listening implementation, the transmitter mote would
+transmit a packet that consisted of an extremely long preamble. This
+preamble was long enough to span a complete receive check period. On
+the receiver?s end, the radio would turn on and read bits from the
+radio. If a preamble sequence was detected in the incoming bits, the
+receiver?s radio would remain on for the full duration of the
+transmitter?s preamble and wait for the packet at the end.</p>
+<p>This original low power listening scheme was rather inefficient on both
+the transmit and receive end. On the receive end, turning on the radio
+completely and reading in bits typically cost much more energy than
+necessary. The transmitter's long preamble could end up costing both
+nodes to have their radios on much longer than required, sending and
+receiving useless preamble bits.</p>
+</div>
+<div class="section">
+<h2><a id="cc1000-pulse-check-implementation" name="cc1000-pulse-check-implementation">2.2 CC1000 Pulse Check Implementation</a></h2>
+<p>Joe Polastre and Jason Hill developed a better receive check
+implementation in the CC1000 ?Pulse Check? radio stack for TinyOS 1.x,
+while maintaining the same interface. This implementation took advantage
+of a Clear Channel Assessment (CCA) to determine if a transmitter was
+nearby.</p>
+<p>In this implementation, the CC1000 radio did not have to be turned on
+completely, so it consumed less maximum current than the previous
+implementation. The radio on-time was also significantly reduced, only
+turning on long enough for a single ADC conversion to occur. If energy
+was detected on the channel after the first ADC conversion, subsequent
+ADC conversions would verify this before committing to turning the
+radio receiver on completely.</p>
+<p>In this implementation the receiver's efficiency dramatically improved,
+but the transmitter still sent a long, inefficient preamble. Energy
+consumption used to transmit messages was still high, while throughput
+was still low.</p>
+</div>
+<div class="section">
+<h2><a id="possible-improvements" name="possible-improvements">2.3 Possible Improvements</a></h2>
+<p>Low power listening is a struggle between minimizing energy efficiency
+and maximizing throughput. In an asynchronous low power listening
+scheme, several improvements can be made over earlier implementations.
+One improvement that could have been made to earlier implementations is
+to remove the long transmitted preamble and send many smaller messages
+instead. For example, the transmitter could send the same message over
+and over again for the duration of the receiver's receive check period.
+The receiver could wake up and see that another node is transmitting,
+receive a full message, and finally send back an acknowledgement for that
+message. The transmitter would see the acknowledgement and stop
+transmitting early, so both nodes can perform some high speed transaction
+or go back to sleep. Useless preamble bits are minimized while useful
+packet information is maximized. Incidentally, this is a good strategy
+for CC2420 low power listening. This strategy certainly improves energy
+efficiency and throughput, but further improvements may be possible by
+employing a synchronous delivery method on top of this type of
+asynchronous low power listening scheme.</p>
+<p>Improvements can also be made to the original low power listening
+interfaces. For example, instead of pre-programming power modes and
+duty cycles, a low power listening interface should allow the developer
+the flexibility to deploy a network of nodes with whatever duty cycle
+percentage or sleep time desired for each individual node. Nodes with
+different receive check periods should still have the ability to
+reliably communicate with each other with little difficulty.</p>
+</div>
+</div>
+<div class="section">
+<h1><a id="interfaces" name="interfaces">3. Interfaces</a></h1>
+</div>
+<div class="section">
+<h1><a id="low-power-listening-interface" name="low-power-listening-interface">3.1 Low Power Listening Interface</a></h1>
+<p>The LowPowerListening interface MUST be provided for each radio by the
+platform independent ActiveMessageC configuration.</p>
+<p>In some implementations, low power listening may have an option to
+compile into the radio stack for memory footprint reasons. If low
+power listening is not compiled in with the stack, calls to
+LowPowerListening MUST be handled by a dummy implementation.</p>
+<p>The TEP proposes this LowPowerListening interface::</p>
+<pre class="literal-block">
+interface LowPowerListening {
+ command void setLocalSleepInterval(uint16_t sleepIntervalMs);
+ command uint16_t getLocalSleepInterval();
+ command void setLocalDutyCycle(uint16_t dutyCycle);
+ command uint16_t getLocalDutyCycle();
+ command void setRxSleepInterval(message_t *msg, uint16_t sleepIntervalMs);
+ command uint16_t getRxSleepInterval(message_t *msg);
+ command void setRxDutyCycle(message_t *msg, uint16_t dutyCycle);
+ command uint16_t getRxDutyCycle(message_t *msg);
+ command uint16_t dutyCycleToSleepInterval(uint16_t dutyCycle);
+ command uint16_t sleepIntervalToDutyCycle(uint16_t sleepInterval);
+}
+</pre>
+<dl class="docutils">
+<dt>setLocalSleepInterval(uint16_t sleepIntervalMs)</dt>
+<dd><ul class="first last simple">
+<li>Sets the local node?s radio sleep interval, in milliseconds.</li>
+</ul>
+</dd>
+<dt>getLocalSleepInterval()</dt>
+<dd><ul class="first last simple">
+<li>Retrieves the local node?s sleep interval, in milliseconds. If duty cycle percentage was originally set, it is automatically converted to a sleep interval.</li>
+</ul>
+</dd>
+<dt>setLocalDutyCycle(uint16_t dutyCycle)</dt>
+<dd><ul class="first last simple">
+<li>Set the local node?s duty cycle percentage, in units of [percentage*100].</li>
+</ul>
+</dd>
+<dt>getLocalDutyCycle()</dt>
+<dd><ul class="first last simple">
+<li>Retrieves the local node?s duty cycle percentage. If sleep interval in milliseconds was originally set, it is automatically converted to a duty cycle percentage.</li>
+</ul>
+</dd>
+<dt>setRxSleepInterval(message_t *msg, uint16_t sleepIntervalMs)</dt>
+<dd><ul class="first last simple">
+<li>The given message will soon be sent to a low power receiver. The sleepIntervalMs is the sleep interval of that low power receiver, in milliseconds. When sent, the radio stack will automatically transmit the message so as to be detected by the low power receiver.</li>
+</ul>
+</dd>
+<dt>getRxSleepInterval(message_t *msg)</dt>
+<dd><ul class="first last simple">
+<li>Retrieves the message destination?s sleep interval. If a duty cycle was originally set for the outgoing message, it is automatically converted to a sleep interval.</li>
+</ul>
+</dd>
+<dt>setRxDutyCycle(message_t *msg, uint16_t dutyCycle)</dt>
+<dd><ul class="first last simple">
+<li>The given message will soon be sent to a low power receiver. The dutyCycle is the duty cycle percentage, in units of [percentage*100], of that low power receiver. When sent, the radio stack will automatically transmit the message so as to be detected by the low power receiver.</li>
+</ul>
+</dd>
+<dt>getRxDutyCycle(message_t *msg)</dt>
+<dd><ul class="first last simple">
+<li>Retrieves the message destination?s duty cycle percentage. If a sleep interval was originally set for the outgoing message, it is automatically converted to a duty cycle percentage.</li>
+</ul>
+</dd>
+<dt>dutyCycleToSleepInterval(uint16_t dutyCycle)</dt>
+<dd><ul class="first last simple">
+<li>Converts the given duty cycle percentage to a sleep interval in milliseconds.</li>
+</ul>
+</dd>
+<dt>sleepIntervalToDutyCycle(uint16_t sleepInterval)</dt>
+<dd><ul class="first last simple">
+<li>Converts the given sleep interval in milliseconds to a duty cycle percentage.</li>
+</ul>
+</dd>
+</dl>
+<div class="section">
+<h2><a id="split-control-behaviour" name="split-control-behaviour">3.2 Split Control Behaviour</a></h2>
+<p>Low power listening MUST be enabled and disabled through the radio?s
+standard SplitControl interface, returning exactly one SplitControl
+event upon completion. While the radio is duty cycling, it MUST NOT
+alert the application layer each time the radio turns on and off to
+perform a receive check or send a message.</p>
+</div>
+<div class="section">
+<h2><a id="send-interface-behaviour" name="send-interface-behaviour">3.3 Send Interface Behaviour</a></h2>
+<p>Attempts to send a message before SplitControl.start() has been called
+SHOULD return EOFF, signifying the radio has not been enabled. When
+SplitControl.start() has been called by the application layer, calls
+to Send MUST turn the radio on automatically if the radio is currently
+off due to duty cycling. If a message is already in the process of
+being sent, multiple calls to Send should return FAIL.</p>
+<p>The Send.sendDone(?) event SHOULD signal SUCCESS upon the successful
+completion of the message delivery process, regardless if any mote
+actually received the message.</p>
+</div>
+<div class="section">
+<h2><a id="receive-interface-behaviour" name="receive-interface-behaviour">3.4 Receive Interface Behaviour</a></h2>
+<p>Upon the successful reception of a message, the low power receive event
+handler SHOULD drop duplicate messages sent to the broadcast address.
+For example, the CC2420 implementation can perform this by checking
+the message_t?s dsn value, where each dsn value is identical for every
+message used in the delivery.</p>
+<p>After the first successful message reception, the receiver?s radio
+SHOULD stay on for a brief period of time to allow any further
+transactions to occur at high speed. If no subsequent messages are
+detected going inbound or outbound after some short delay, the radio
+MUST continue duty cycling as configured.</p>
+</div>
+</div>
+<div class="section">
+<h1><a id="low-power-listening-message-t-metadata" name="low-power-listening-message-t-metadata">4. Low Power Listening message_t Metadata</a></h1>
+<p>To store the extra 16-bit receiver low power listening value, the radio
+stack?s message_t footer MUST contain a parameter to store the message
+destination?s receive check sleep interval in milliseconds or duty cycle
+percentage. For example, the low power listening CC2420 message_t footer
+stores the message's receive check interval in milliseconds, as shown
+below <a class="citation-reference" href="#tep111" id="id3" name="id3">[TEP111]</a>.:</p>
+<pre class="literal-block">
+typedef nx_struct cc2420_metadata_t {
+ nx_uint8_t tx_power;
+ nx_uint8_t rssi;
+ nx_uint8_t lqi;
+ nx_bool crc;
+ nx_bool ack;
+ nx_uint16_t time;
+ nx_uint16_t rxInterval;
+} cc2420_metadata_t;
+</pre>
+</div>
+<div class="section">
+<h1><a id="recommendations-for-hal-implementation" name="recommendations-for-hal-implementation">5. Recommendations for HAL Implementation</a></h1>
+<p>In the interest of minimizing energy while maximizing throughput, it
+is RECOMMENDED that any asynchronous low power listening implementation
+use clear channel assessment methods to determine the presence of a
+nearby transmitter. It is also RECOMMENDED that the transmitter send
+duplicate messages continuously with minimum or no backoff period instead
+of one long message. Removing backoffs on a continuous send delivery
+scheme will allow the channel to be modulated sufficiently for a receiver
+to quickly detect; furthermore, enabling acknowledgements on each
+outgoing duplicate packet will allow the transmit period to be cut short
+based on when the receiver actually receives the message.</p>
+<p>Asynchronous low power listening requires some memory overhead, so
+sometimes it is better to leave the added architecture out when it is
+not required. When it is feasible to do so, it is RECOMMENDED that
+the preprocessor variable LOW_POWER_LISTENING be defined when low
+power listening functionality is to be compiled in with the radio stack,
+and not defined when low power listening functionality shouldn?t exist.</p>
+<p>It is RECOMMENDED that the radio on-time for actual receive checks be a
+measured value to help approximate the duty cycle percentage.</p>
+</div>
+<div class="section">
+<h1><a id="author-s-address" name="author-s-address">6. Author's Address</a></h1>
+<div class="line-block">
+<div class="line">David Moss</div>
+<div class="line">Rincon Research Corporation</div>
+<div class="line">101 N. Wilmot, Suite 101</div>
+<div class="line">Tucson, AZ 85750</div>
+<div class="line"><br /></div>
+<div class="line">phone - +1 520 519 3138</div>
+<div class="line">email ? <a class="reference" href="mailto:dmm@rincon.com">dmm@rincon.com</a></div>
+<div class="line"><br /></div>
+<div class="line">Jonathan Hui</div>
+<div class="line">657 Mission St. Ste. 600</div>
+<div class="line">Arched Rock Corporation</div>
+<div class="line">San Francisco, CA 94105-4120</div>
+<div class="line"><br /></div>
+<div class="line">phone - +1 415 692 0828</div>
+<div class="line">email - <a class="reference" href="mailto:jhui@archedrock.com">jhui@archedrock.com</a></div>
+<div class="line"><br /></div>
+<div class="line">Kevin Klues</div>
+<div class="line">503 Bryan Hall</div>
+<div class="line">Washington University</div>
+<div class="line">St. Louis, MO 63130</div>
+<div class="line"><br /></div>
+<div class="line">phone - +1-314-935-6355</div>
+<div class="line">email - <a class="reference" href="mailto:klueska@cs.wustl.edu">klueska@cs.wustl.edu</a></div>
+</div>
+</div>
+<div class="section">
+<h1><a id="citations" name="citations">7. Citations</a></h1>
+<table class="docutils citation" frame="void" id="mica2" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id1" name="mica2">[MICA2]</a></td><td>"MICA2 Radio Stack for TinyOS." <a class="reference" href="http://www.tinyos.net/tinyos-1.x/doc/mica2radio/CC1000.html">http://www.tinyos.net/tinyos-1.x/doc/mica2radio/CC1000.html</a></td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="tep111" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id3" name="tep111">[TEP111]</a></td><td>TEP 111: message_t.</td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="cc1000" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id2" name="cc1000">[CC1000]</a></td><td>TI/Chipcon CC1000 Datasheet. <a class="reference" href="http://www.chipcon.com/files/CC1000_Data_Sheet_2_2.pdf">http://www.chipcon.com/files/CC1000_Data_Sheet_2_2.pdf</a></td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="cc2420" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a name="cc2420">[CC2420]</a></td><td>TI/Chipcon CC2420 Datasheet. <a class="reference" href="http://www.chipcon.com/files/CC2420_Data_Sheet_1_3.pdf">http://www.chipcon.com/files/CC2420_Data_Sheet_1_3.pdf</a></td></tr>
+</tbody>
+</table>
+</div>
+</div>
+</body>
+</html>
<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.6: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
<title>Schedulers and Tasks</title>
<meta name="author" content="Philip Levis and Cory Sharp" />
<style type="text/css">
dd {
margin-bottom: 0.5em }
-/* Uncomment (& remove this text!) to get bold-faced definition list terms
-dt {
- font-weight: bold }
-*/
-
div.abstract {
margin: 2em 5em }
</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" id="abstract">
-<h1><a name="abstract">Abstract</a></h1>
+<div class="section">
+<h1><a id="abstract" name="abstract">Abstract</a></h1>
<p>This memo documents the structure and implementation of tasks
and task schedulers in TinyOS 2.x.</p>
</div>
-<div class="section" id="introduction">
-<h1><a name="introduction">1. Introduction</a></h1>
+<div class="section">
+<h1><a id="introduction" name="introduction">1. Introduction</a></h1>
<p>TinyOS has two basic computational abstractions: asynchronous events
and tasks. Early versions of TinyOS provided a single type of task --
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" 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>
+<div class="section">
+<h1><a id="tasks-and-the-scheduler-in-tinyos-1-x" name="tasks-and-the-scheduler-in-tinyos-1-x">2. Tasks and the Scheduler in TinyOS 1.x</a></h1>
<p>Tasks in TinyOS are a form of deferred procedure call (DPC) <a class="footnote-reference" href="#id5" id="id1" name="id1">[1]</a>, which
enable a program to defer a computation or operation until a later
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" id="tasks-in-tinyos-2-x">
-<h1><a name="tasks-in-tinyos-2-x">3. Tasks in TinyOS 2.x</a></h1>
+<div class="section">
+<h1><a id="tasks-in-tinyos-2-x" name="tasks-in-tinyos-2-x">3. Tasks in TinyOS 2.x</a></h1>
<p>The semantics of tasks in TinyOS 2.x are different than those in 1.x.
This change is based on experiences with the limitations and run time
errors that the 1.x model introduces. <strong>In TinyOS 2.x, a basic post will
-only fail if and only if the task has already been posted and has not
-started execution.</strong> A task can always run, but can only have one
+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" 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>
+<div class="section">
+<h1><a id="the-scheduler-in-tinyos-2-x" name="the-scheduler-in-tinyos-2-x">4. The Scheduler in TinyOS 2.x</a></h1>
<p>In TinyOS 2.x, the scheduler is a TinyOS component. Every scheduler
MUST support nesC tasks. It MAY also support any number of
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" id="replacing-the-scheduler">
-<h1><a name="replacing-the-scheduler">5. Replacing the Scheduler</a></h1>
+<div class="section">
+<h1><a id="replacing-the-scheduler" name="replacing-the-scheduler">5. Replacing the Scheduler</a></h1>
<p>The TinyOS scheduler is presented as a component named TinySchedulerC.
The default TinyOS scheduler implementation is a module named
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" id="implementation">
-<h1><a name="implementation">6. Implementation</a></h1>
+<div class="section">
+<h1><a id="implementation" name="implementation">6. Implementation</a></h1>
<p>The following files in <tt class="docutils literal"><span class="pre">tinyos-2.x/tos/system</span></tt> contain the reference
implementations of the scheduler:</p>
<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" id="author-s-address">
-<h1><a name="author-s-address">7. Author's Address</a></h1>
+<div class="section">
+<h1><a id="author-s-address" name="author-s-address">7. Author's Address</a></h1>
<div class="line-block">
<div class="line">Philip Levis</div>
<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" id="citations">
-<h1><a name="citations">8. Citations</a></h1>
+<div class="section">
+<h1><a id="citations" name="citations">8. Citations</a></h1>
<table class="docutils footnote" frame="void" id="id5" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
-<tr><td class="label"><a class="fn-backref" href="#id1" name="id5">[1]</a></td><td>Erik Cota-Robles and James P. Held. "A Comparison of Windows
+<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" id="appendix-a-changing-the-scheduler">
-<h1><a name="appendix-a-changing-the-scheduler">Appendix A: Changing the Scheduler</a></h1>
+<div class="section">
+<h1><a id="appendix-a-changing-the-scheduler" name="appendix-a-changing-the-scheduler">Appendix A: Changing the Scheduler</a></h1>
<p>The nesC compiler transforms the post and task keywords into
nesC interfaces, wirings, and calls. By default, the statement:</p>
<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.3.6: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
<title>TinyOS 2.x Boot Sequence</title>
<meta name="author" content="Philip Levis" />
<style type="text/css">
dd {
margin-bottom: 0.5em }
-/* Uncomment (& remove this text!) to get bold-faced definition list terms
-dt {
- font-weight: bold }
-*/
-
div.abstract {
margin: 2em 5em }
</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" id="abstract">
-<h1><a name="abstract">Abstract</a></h1>
+<div class="section">
+<h1><a id="abstract" 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" id="introduction">
-<h1><a name="introduction">1. Introduction</a></h1>
+<div class="section">
+<h1><a id="introduction" 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" id="tinyos-1-x-boot-sequence">
-<h1><a name="tinyos-1-x-boot-sequence">2. TinyOS 1.x Boot Sequence</a></h1>
+<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>
<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" id="tinyos-2-x-boot-interfaces">
-<h1><a name="tinyos-2-x-boot-interfaces">3. TinyOS 2.x Boot Interfaces</a></h1>
+<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>
<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" id="id2">
-<h1><a name="id2">4. TinyOS 2.x Boot Sequence</a></h1>
+<div class="section">
+<h1><a id="id2" 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" id="initialization">
-<h2><a name="initialization">4.1 Initialization</a></h2>
+<div class="section">
+<h2><a id="initialization" 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" id="interrupts-in-initialization">
-<h2><a name="interrupts-in-initialization">4.2 Interrupts in Initialization</a></h2>
+<div class="section">
+<h2><a id="interrupts-in-initialization" 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" id="implementation">
-<h1><a name="implementation">5. Implementation</a></h1>
+<div class="section">
+<h1><a id="implementation" 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" id="author-s-address">
-<h1><a name="author-s-address">6. Author's Address</a></h1>
+<div class="section">
+<h1><a id="author-s-address" name="author-s-address">6. Author's Address</a></h1>
<div class="line-block">
<div class="line">Philip Levis</div>
<div class="line">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" id="citations">
-<h1><a name="citations">7. Citations</a></h1>
+<div class="section">
+<h1><a id="citations" 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.3.6: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
<title>Resource Arbitration</title>
-<meta name="author" content="Kevin Klues" />
-<meta name="author" content="Philip Levis" />
-<meta name="author" content="David Gay" />
-<meta name="author" content="David Culler" />
-<meta name="author" content="Vlado Handziski" />
+<meta name="authors" content="Kevin Klues Philip Levis David Gay David Culler Vlado Handziski" />
<style type="text/css">
/*
dd {
margin-bottom: 0.5em }
-/* Uncomment (& remove this text!) to get bold-faced definition list terms
-dt {
- font-weight: bold }
-*/
-
div.abstract {
margin: 2em 5em }
</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">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>
+<tr><th class="docinfo-name">Authors:</th>
+<td>Kevin Klues
+<br />Philip Levis
+<br />David Gay
+<br />David Culler
+<br />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" id="abstract">
-<h1><a name="abstract">Abstract</a></h1>
+<div class="section">
+<h1><a id="abstract" 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" id="introduction">
-<h1><a name="introduction">1. Introduction</a></h1>
+<div class="section">
+<h1><a id="introduction" 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" 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
+<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
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" id="dedicated">
-<h2><a name="dedicated">2.1 Dedicated</a></h2>
+<div class="section">
+<h2><a id="dedicated" 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" id="virtualized">
-<h2><a name="virtualized">2.2 Virtualized</a></h2>
+<div class="section">
+<h2><a id="virtualized" 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" id="shared">
-<h2><a name="shared">2.3 Shared</a></h2>
+<div class="section">
+<h2><a id="shared" 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" id="resource-arbiters">
-<h1><a name="resource-arbiters">3. Resource Arbiters</a></h1>
+<div class="section">
+<h1><a id="resource-arbiters" 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" id="resource">
-<h2><a name="resource">3.1 Resource</a></h2>
-<p>Clients of an arbiter request access
+<div class="section">
+<h2><a id="resource" 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" id="arbiterinfo">
-<h2><a name="arbiterinfo">3.2 ArbiterInfo</a></h2>
+<div class="section">
+<h2><a id="arbiterinfo" 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" 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
+<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
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" id="resourceconfigure">
-<h2><a name="resourceconfigure">3.4 ResourceConfigure</a></h2>
-<p>The existence of the ResourceConfigure interface allows a resource to be
+<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
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" 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
+<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
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" id="cross-component-reservation">
-<h1><a name="cross-component-reservation">4. Cross-Component Reservation</a></h1>
+<div class="section">
+<h1><a id="cross-component-reservation" 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" id="implementation">
-<h1><a name="implementation">5. Implementation</a></h1>
+<div class="section">
+<h1><a id="implementation" 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" id="author-s-address">
-<h1><a name="author-s-address">6. Author's Address</a></h1>
+<div class="section">
+<h1><a id="author-s-address" name="author-s-address">6. Author's Address</a></h1>
<div class="line-block">
<div class="line">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" id="citations">
-<h1><a name="citations">7. Citations</a></h1>
+<div class="section">
+<h1><a id="citations" 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" 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>
+<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>
<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" 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
+<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
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" id="appendix-b-arbiter-interface-examples">
-<h1><a name="appendix-b-arbiter-interface-examples">Appendix B: Arbiter Interface Examples</a></h1>
+<div class="section">
+<h1><a id="appendix-b-arbiter-interface-examples" 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" id="id11">
-<h2><a 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">
+<h2><a id="id11" 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" id="id12">
-<h2><a name="id12">ArbiterInfo</a></h2>
+<div class="section">
+<h2><a id="id12" 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" id="id13">
-<h2><a name="id13">ResourceRequested</a></h2>
+<div class="section">
+<h2><a id="id13" 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" 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
+<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
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.6: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
<title>Sensors and Sensor Boards</title>
<meta name="author" content="David Gay, Phil Levis, Wei Hong, Joe Polastre, and Gilman Tolle" />
<style type="text/css">
dd {
margin-bottom: 0.5em }
-/* Uncomment (& remove this text!) to get bold-faced definition list terms
-dt {
- font-weight: bold }
-*/
-
div.abstract {
margin: 2em 5em }
</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" id="abstract">
-<h1><a name="abstract">Abstract</a></h1>
+<div class="section">
+<h1><a id="abstract" name="abstract">Abstract</a></h1>
<p>This memo documents how sensor drivers are organized in TinyOS and how
sets of sensor drivers are combined into sensor boards and sensor
platforms, along with general principles followed by the components
that provide access to sensors.</p>
</div>
-<div class="section" id="principles">
-<h1><a name="principles">1. Principles</a></h1>
+<div class="section">
+<h1><a id="principles" name="principles">1. Principles</a></h1>
<p>This section describes the basic organization principles for sensor
drivers in TinyOS.</p>
<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" id="sensor-hil-components">
-<h1><a name="sensor-hil-components">2. Sensor HIL Components</a></h1>
+<div class="section">
+<h1><a id="sensor-hil-components" name="sensor-hil-components">2. Sensor HIL Components</a></h1>
<p>A sensor HIL component MUST provide:</p>
<ul class="simple">
<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" id="sensor-hal-components">
-<h1><a name="sensor-hal-components">3. Sensor HAL Components</a></h1>
+<div class="section">
+<h1><a id="sensor-hal-components" name="sensor-hal-components">3. Sensor HAL Components</a></h1>
<p>Sensors with a richer interface than would be supported by the SID
interfaces MAY provide a HAL component in addition to a HIL
component.</p>
}
</pre>
</div>
-<div class="section" id="directory-organization-guidelines">
-<h1><a name="directory-organization-guidelines">4. Directory Organization Guidelines</a></h1>
+<div class="section">
+<h1><a id="directory-organization-guidelines" name="directory-organization-guidelines">4. Directory Organization Guidelines</a></h1>
<p>Because the same physical sensor can be attached to TinyOS platforms
in many different ways, the organization of sensor drivers SHOULD
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" id="authors-addresses">
-<h1><a name="authors-addresses">5. Authors' Addresses</a></h1>
+<div class="section">
+<h1><a id="authors-addresses" name="authors-addresses">5. Authors' Addresses</a></h1>
<div class="line-block">
<div class="line">David Gay</div>
<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" id="citations">
-<h1><a name="citations">6. Citations</a></h1>
+<div class="section">
+<h1><a id="citations" name="citations">6. Citations</a></h1>
<table class="docutils citation" frame="void" id="tep2" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
</tbody>
</table>
</div>
-<div class="section" id="appendix-a-sensor-driver-examples">
-<h1><a name="appendix-a-sensor-driver-examples">Appendix A: Sensor Driver Examples</a></h1>
-<div class="section" id="analog-adc-connected-sensor">
-<h2><a name="analog-adc-connected-sensor">1. Analog ADC-Connected Sensor</a></h2>
+<div class="section">
+<h1><a id="appendix-a-sensor-driver-examples" name="appendix-a-sensor-driver-examples">Appendix A: Sensor Driver Examples</a></h1>
+<div class="section">
+<h2><a id="analog-adc-connected-sensor" name="analog-adc-connected-sensor">1. Analog ADC-Connected Sensor</a></h2>
<p>The Analog sensor requires two components</p>
<ul class="simple">
<li>a component to present the sensor itself (HamamatsuS1087ParC)</li>
}
</pre>
</div>
-<div class="section" id="binary-pin-connected-sensor">
-<h2><a name="binary-pin-connected-sensor">2. Binary Pin-Connected Sensor</a></h2>
+<div class="section">
+<h2><a id="binary-pin-connected-sensor" name="binary-pin-connected-sensor">2. Binary Pin-Connected Sensor</a></h2>
<p>The Binary sensor gets a bit more complex, because it has three
components:</p>
<ul class="simple">
provides interface DeviceMetadata;
uses interface GeneralIO;
- uses interface GpioInterrupt;
+ uses interface GpioInterrupt;
}
implementation {
norace bool m_pinHigh;
task void sendEvent() {
bool pinHigh;
pinHigh = m_pinHigh;
-
+
signal Notify.notify( pinHigh );
-
+
if ( pinHigh ) {
call GpioInterrupt.enableFallingEdge();
} else {
}
</pre>
</div>
-<div class="section" id="digital-bus-connected-sensor">
-<h2><a name="digital-bus-connected-sensor">3. Digital Bus-Connected Sensor</a></h2>
+<div class="section">
+<h2><a id="digital-bus-connected-sensor" name="digital-bus-connected-sensor">3. Digital Bus-Connected Sensor</a></h2>
<p>The Digital sensor is the most complex out of the set, and includes
six components:</p>
<ul class="simple">
<pre class="literal-block">
tos/platforms/telosa/chips/sht11/SensirionSht11C.nc
-generic configuration SensirionSht11C() {
+generic configuration SensirionSht11C() {
provides interface Read<uint16_t> as Temperature;
provides interface DeviceMetadata as TemperatureDeviceMetadata;
provides interface Read<uint16_t> as Humidity;
provides interface DeviceMetadata as TemperatureDeviceMetadata;
provides interface Read<uint16_t> as Humidity;
provides interface DeviceMetadata as HumidityDeviceMetadata;
-
+
uses interface Resource as TempResource;
uses interface Resource as HumResource;
uses interface SensirionSht11 as Sht11Temp;
SensirionSht11LogicP.DATA -> HplSensirionSht11C.DATA;
SensirionSht11LogicP.CLOCK -> HplSensirionSht11C.SCK;
SensirionSht11LogicP.InterruptDATA -> HplSensirionSht11C.InterruptDATA;
-
+
components new TimerMilliC();
SensirionSht11LogicP.Timer -> TimerMilliC;
}
implementation {
components HplMsp430GeneralIOC;
-
+
components new Msp430GpioC() as DATAM;
DATAM -> HplMsp430GeneralIOC.Port15;
DATA = DATAM;
components new FcfsArbiterC( "Sht11.Resource" ) as Arbiter;
Resource = Arbiter;
-
+
components new SplitControlPowerManagerC();
SplitControlPowerManagerC.SplitControl -> HplSensirionSht11P;
SplitControlPowerManagerC.ArbiterInit -> Arbiter.Init;
call Timer.startOneShot( 11 );
return SUCCESS;
}
-
+
event void Timer.fired() {
signal SplitControl.startDone( SUCCESS );
}
<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.6: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
<title>Virtualization</title>
<meta name="author" content="Philip Levis" />
<style type="text/css">
dd {
margin-bottom: 0.5em }
-/* Uncomment (& remove this text!) to get bold-faced definition list terms
-dt {
- font-weight: bold }
-*/
-
div.abstract {
margin: 2em 5em }
</style>
</head>
<body>
+<div class="document" id="virtualization">
<h1 class="title">Virtualization</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
</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" id="abstract">
-<h1><a name="abstract">Abstract</a></h1>
+<div class="section">
+<h1><a id="abstract" 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" id="introduction">
-<h1><a name="introduction">1. Introduction</a></h1>
+<div class="section">
+<h1><a id="introduction" 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" id="distributions">
-<h1><a name="distributions">2. Distributions</a></h1>
+<div class="section">
+<h1><a id="distributions" 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" id="controlling-a-service">
-<h2><a name="controlling-a-service">2.1 Controlling a Service</a></h2>
+<div class="section">
+<h2><a id="controlling-a-service" 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" id="service-initialization">
-<h2><a name="service-initialization">2.2 Service Initialization</a></h2>
+<div class="section">
+<h2><a id="service-initialization" 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" id="oski-services">
-<h1><a name="oski-services">3. OSKI Services</a></h1>
+<div class="section">
+<h1><a id="oski-services" name="oski-services">3. OSKI Services</a></h1>
<p>This section briefly describes the services that OSKI, an example
distribution provides. It is intended to give a feel for how a
distribution presents its abstractions.</p>
-<div class="section" id="timers">
-<h2><a name="timers">3.1 Timers</a></h2>
+<div class="section">
+<h2><a id="timers" 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" id="active-messages">
-<h2><a name="active-messages">3.2 Active Messages</a></h2>
+<div class="section">
+<h2><a id="active-messages" 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" id="broadcasts">
-<h2><a name="broadcasts">3.3 Broadcasts</a></h2>
+<div class="section">
+<h2><a id="broadcasts" 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" 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.
+<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.
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" 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
+<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
UART interfaces.</strong></p>
</div>
</div>
-<div class="section" id="oski-service-structure-and-design">
-<h1><a name="oski-service-structure-and-design">4. OSKI Service Structure and Design</a></h1>
+<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>
<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" id="example-timers">
-<h2><a name="example-timers">4.1 Example: Timers</a></h2>
+<div class="section">
+<h2><a id="example-timers" 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" id="example-active-messages">
-<h2><a name="example-active-messages">4.2 Example: Active Messages</a></h2>
+<div class="section">
+<h2><a id="example-active-messages" 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" id="oski-requirements">
-<h2><a name="oski-requirements">4.3 OSKI Requirements</a></h2>
+<div class="section">
+<h2><a id="oski-requirements" 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" id="distribution-interfaces">
-<h1><a name="distribution-interfaces">5. Distribution Interfaces</a></h1>
+<div class="section">
+<h1><a id="distribution-interfaces" 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" id="author-s-address">
-<h1><a name="author-s-address">6. Author's Address</a></h1>
+<div class="section">
+<h1><a id="author-s-address" name="author-s-address">6. Author's Address</a></h1>
<div class="line-block">
<div class="line">Philip Levis</div>
<div class="line">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" id="citations">
-<h1><a name="citations">7. Citations</a></h1>
+<div class="section">
+<h1><a id="citations" 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.3.6: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
<title>message_t</title>
<meta name="author" content="Philip Levis" />
<style type="text/css">
dd {
margin-bottom: 0.5em }
-/* Uncomment (& remove this text!) to get bold-faced definition list terms
-dt {
- font-weight: bold }
-*/
-
div.abstract {
margin: 2em 5em }
</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" id="abstract">
-<h1><a name="abstract">Abstract</a></h1>
+<div class="section">
+<h1><a id="abstract" 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" id="introduction">
-<h1><a name="introduction">1. Introduction</a></h1>
+<div class="section">
+<h1><a id="introduction" 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" id="id1">
-<h1><a name="id1">2. message_t</a></h1>
+<div class="section">
+<h1><a id="id1" 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" id="the-message-t-fields">
-<h1><a name="the-message-t-fields">3. The message_t fields</a></h1>
+<div class="section">
+<h1><a id="the-message-t-fields" 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" 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
+<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
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" id="data">
-<h2><a name="data">3.2 Data</a></h2>
+<div class="section">
+<h2><a id="data" 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" id="footer">
-<h2><a name="footer">3.3 Footer</a></h2>
+<div class="section">
+<h2><a id="footer" 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" 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
+<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
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" id="variable-sized-structures">
-<h2><a name="variable-sized-structures">3.5 Variable Sized Structures</a></h2>
+<div class="section">
+<h2><a id="variable-sized-structures" 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" id="implementation">
-<h1><a name="implementation">4. Implementation</a></h1>
-<p>The definition of message_t can be found in
+<div class="section">
+<h1><a id="implementation" 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" id="author-s-address">
-<h1><a name="author-s-address">5. Author's Address</a></h1>
+<div class="section">
+<h1><a id="author-s-address" name="author-s-address">5. Author's Address</a></h1>
<div class="line-block">
<div class="line">Philip Levis</div>
<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" id="citations">
-<h1><a name="citations">6. Citations</a></h1>
+<div class="section">
+<h1><a id="citations" 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.3.6: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
<title>Microcontroller Power Management</title>
<meta name="author" content="Robert Szewczyk, Philip Levis, Martin Turon, Lama Nachman, Philip Buonadonna, Vlado Handziski" />
<style type="text/css">
dd {
margin-bottom: 0.5em }
-/* Uncomment (& remove this text!) to get bold-faced definition list terms
-dt {
- font-weight: bold }
-*/
-
div.abstract {
margin: 2em 5em }
</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" />
</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" id="abstract">
-<h1><a name="abstract">Abstract</a></h1>
+<div class="section">
+<h1><a id="abstract" name="abstract">Abstract</a></h1>
<p>This memo documents how TinyOS manages the lower power state of a
microcontroller.</p>
</div>
-<div class="section" id="introduction">
-<h1><a name="introduction">1. Introduction</a></h1>
+<div class="section">
+<h1><a id="introduction" name="introduction">1. Introduction</a></h1>
<p>Microcontrollers often have several power states, with varying power
draws, wakeup latencies, and peripheral support. The microcontroller
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" id="background">
-<h1><a name="background">2. Background</a></h1>
+<div class="section">
+<h1><a id="background" name="background">2. Background</a></h1>
<p>The TinyOS scheduler[<a class="reference" href="#id3">2</a>] puts a processor into a sleep state when
the task queue is empty. However, processors can have a spectrum of
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" id="id1">
-<h1><a name="id1">3. Microcontroller Power Management</a></h1>
+<div class="section">
+<h1><a id="id1" name="id1">3. Microcontroller Power Management</a></h1>
<p>TinyOS 2.x uses three basic mechanisms to manage and control
microcontroller power states: a dirty bit, a chip-specific low power
state calculation function, and a power state override function. The
</div>
<p>McuSleepC MAY have additional interfaces.</p>
</div>
-<div class="section" id="the-dirty-bit">
-<h1><a name="the-dirty-bit">3.1 The Dirty Bit</a></h1>
+<div class="section">
+<h1><a id="the-dirty-bit" name="the-dirty-bit">3.1 The Dirty Bit</a></h1>
<p>Whenever a Hardware Presentation Layer (HPL, see TEP 2: Hardware
Abstraction Architecture[<a class="reference" href="#id2">1</a>]) component changes an aspect of
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" id="low-power-state-calculation">
-<h1><a name="low-power-state-calculation">3.2 Low Power State Calculation</a></h1>
+<div class="section">
+<h1><a id="low-power-state-calculation" name="low-power-state-calculation">3.2 Low Power State Calculation</a></h1>
<p>McuSleepC is responsible for calculating the lowest power state that
it can safely put the microcontroller into without disrupting the
operation of TinyOS subsystems. McuSleepC SHOULD minimize how often it
</tbody>
</table>
</div>
-<div class="section" id="power-state-override">
-<h1><a name="power-state-override">3.3 Power State Override</a></h1>
+<div class="section">
+<h1><a id="power-state-override" name="power-state-override">3.3 Power State Override</a></h1>
<p>When McuSleepC computes the best low power state, it MUST call
<tt class="docutils literal"><span class="pre">PowerOverride.lowestState().</span></tt> McuSleepC SHOULD have a default
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" id="peripherals-and-subsystems">
-<h1><a name="peripherals-and-subsystems">4. Peripherals and Subsystems</a></h1>
+<div class="section">
+<h1><a id="peripherals-and-subsystems" name="peripherals-and-subsystems">4. Peripherals and Subsystems</a></h1>
<p>At the HIL level, TinyOS subsystems generally have a simple,
imperative power management interface. Depending on the latencies
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" 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>,
+<div class="section">
+<h1><a id="implementation" name="implementation">5. Implementation</a></h1>
+<p>An implementation of McuSleepC can be found in <tt class="docutils literal"><span class="pre">tinyos-2.x/tos/chips/atm128</span></tt>,
<tt class="docutils literal"><span class="pre">tinyos-2.x/tos/chips/msp430</span></tt>, and <tt class="docutils literal"><span class="pre">tinyos-2.x/tos/chips/px27ax</span></tt>.</p>
<p>An example of a use of McuPowerOverride can be found in the atmega128 timer
system. Because some low-power states have much longer wakeup latencies than
others, the timer system does not allow long latencies if it has a timer
-that is going to fire soon. The implementation can be found in
+that is going to fire soon. The implementation can be found in
<tt class="docutils literal"><span class="pre">tinyos-2.x/tos/chips/atm128/timer/HplAtm128Timer0AsyncP.nc</span></tt>, and
<tt class="docutils literal"><span class="pre">tinyos-2.x/tos/chips/atm128/timer/HplAtm128Timer0AsyncC.nc</span></tt> automatically
wires it to McuSleepC if it is included.</p>
</div>
-<div class="section" id="author-s-address">
-<h1><a name="author-s-address">6. Author's Address</a></h1>
+<div class="section">
+<h1><a id="author-s-address" name="author-s-address">6. Author's Address</a></h1>
<div class="line-block">
<div class="line">Robert Szewczyk</div>
<div class="line">Moteiv Corporation</div>
<div class="line"><br /></div>
</div>
</div>
-<div class="section" id="citations">
-<h1><a name="citations">6. Citations</a></h1>
+<div class="section">
+<h1><a id="citations" name="citations">6. Citations</a></h1>
<table class="docutils footnote" frame="void" id="id2" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<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.3.6: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
<title>Serial Communication</title>
<meta name="author" content="Ben Greenstein and Philip Levis" />
<style type="text/css">
dd {
margin-bottom: 0.5em }
-/* Uncomment (& remove this text!) to get bold-faced definition list terms
-dt {
- font-weight: bold }
-*/
-
div.abstract {
margin: 2em 5em }
</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" id="abstract">
-<h1><a name="abstract">Abstract</a></h1>
+<div class="section">
+<h1><a id="abstract" name="abstract">Abstract</a></h1>
<p>This memo describes the structure and standard implementation of the
TinyOS 2.x serial communication system for mote-to-PC data
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" id="introduction">
-<h1><a name="introduction">1. Introduction</a></h1>
+<div class="section">
+<h1><a id="introduction" name="introduction">1. Introduction</a></h1>
<p>Users need to read data out of a TinyOS network. The most common
approach is to attach a mote to a PC or laptop with a wired
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" id="serial-stack-structure">
-<h1><a name="serial-stack-structure">2. Serial Stack Structure</a></h1>
+<div class="section">
+<h1><a id="serial-stack-structure" name="serial-stack-structure">2. Serial Stack Structure</a></h1>
<p>The TinyOS 2.x serial communication stack is broken up into four
functional components. From bottom to top, they are</p>
<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" 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>
+<div class="section">
+<h1><a id="the-2-x-serial-stack-implementation" name="the-2-x-serial-stack-implementation">3. The 2.x Serial Stack Implementation</a></h1>
<p>Section 2 describes the basic structure of the TinyOS 2.x serial
stack. This section describes its actual implementation,
including SerialActiveMessageC, which sits on top of the Dispatcher.
All of the components except for UartC are part of the serial
library that lives in <tt class="docutils literal"><span class="pre">tos/lib/serial</span></tt>.</p>
-<div class="section" id="raw-uart-uartc">
-<h2><a name="raw-uart-uartc">3.1 Raw UART: UartC</a></h2>
+<div class="section">
+<h2><a id="raw-uart-uartc" name="raw-uart-uartc">3.1 Raw UART: UartC</a></h2>
<p>The UART HIL[<a class="reference" href="#tep2">TEP2</a>] is <tt class="docutils literal"><span class="pre">UartC</span></tt>, which provides a byte-level
interface to the underlying serial communication. It provides the
<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" id="encoder-framer-hdlctranslatec">
-<h2><a name="encoder-framer-hdlctranslatec">3.2 Encoder/Framer: HdlcTranslateC</a></h2>
+<div class="section">
+<h2><a id="encoder-framer-hdlctranslatec" name="encoder-framer-hdlctranslatec">3.2 Encoder/Framer: HdlcTranslateC</a></h2>
<p>HdlcTranslateC is the serial encoder/framer. It uses the
<tt class="docutils literal"><span class="pre">SerialByteComm</span></tt> interface and provides the <tt class="docutils literal"><span class="pre">SerialFrameComm</span></tt>
interface:</p>
and sends an escape byte. When the escape byte is sent, it sends the
stored data byte.</p>
</div>
-<div class="section" id="protocol-serialp">
-<h2><a name="protocol-serialp">3.3 Protocol: SerialP</a></h2>
+<div class="section">
+<h2><a id="protocol-serialp" name="protocol-serialp">3.3 Protocol: SerialP</a></h2>
<p>The SerialP component implements the serial protocol using PPP/HDLC-
like framing (See RFC 1662[<a class="reference" href="#rfc1662">RFC1662</a>]). Type dispatch and buffer
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" id="dispatcher-serialdispatcherc">
-<h2><a name="dispatcher-serialdispatcherc">3.4 Dispatcher: SerialDispatcherC</a></h2>
+<div class="section">
+<h2><a id="dispatcher-serialdispatcherc" name="dispatcher-serialdispatcherc">3.4 Dispatcher: SerialDispatcherC</a></h2>
<p>SerialDispatcherC handles the data packets that the Protocol component
receives. It uses the SendBytePacket and ReceiveBytePacket interfaces,
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" id="serialactivemessagec">
-<h2><a name="serialactivemessagec">3.5 SerialActiveMessageC</a></h2>
+<div class="section">
+<h2><a id="serialactivemessagec" name="serialactivemessagec">3.5 SerialActiveMessageC</a></h2>
<p>SerialActiveMessageC is a platform-independent active message layer
that operates on top of the serial communication
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" id="packet-format">
-<h2><a name="packet-format">3.6 Packet Format</a></h2>
+<div class="section">
+<h2><a id="packet-format" name="packet-format">3.6 Packet Format</a></h2>
<p>A data packet in the TinyOS 2.x serial stack has the following format
over the wire. Each protocol field is associated with a specific component:</p>
<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" id="access-abstractions">
-<h1><a name="access-abstractions">4. Access Abstractions</a></h1>
+<div class="section">
+<h1><a id="access-abstractions" name="access-abstractions">4. Access Abstractions</a></h1>
<p>Two generic components: SerialAMSenderC and SerialAMReceiverC connect
to SerialActiveMessageC to provide virtualized access to the serial
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" id="author-s-address">
-<h1><a name="author-s-address">5. Author's Address</a></h1>
+<div class="section">
+<h1><a id="author-s-address" name="author-s-address">5. Author's Address</a></h1>
<div class="line-block">
<div class="line">Philip Levis</div>
<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" id="citations">
-<h1><a name="citations">6. Citations</a></h1>
+<div class="section">
+<h1><a id="citations" name="citations">6. Citations</a></h1>
<table class="docutils citation" frame="void" id="tep2" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<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.3.6: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
<title>SIDs: Source and Sink Independent Drivers</title>
<meta name="author" content="Gilman Tolle, Philip Levis, and David Gay" />
<style type="text/css">
dd {
margin-bottom: 0.5em }
-/* Uncomment (& remove this text!) to get bold-faced definition list terms
-dt {
- font-weight: bold }
-*/
-
div.abstract {
margin: 2em 5em }
</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" />
</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" id="abstract">
-<h1><a name="abstract">Abstract</a></h1>
-<p>This memo documents a set of hardware- and sensor-independent interfaces
+<div class="section">
+<h1><a id="abstract" name="abstract">Abstract</a></h1>
+<p>This memo documents a set of hardware- and sensor-independent interfaces
for data sources and sinks in TinyOS 2.x.</p>
</div>
-<div class="section" id="introduction">
-<h1><a name="introduction">1. Introduction</a></h1>
+<div class="section">
+<h1><a id="introduction" name="introduction">1. Introduction</a></h1>
<p>Sensing is an integral part of any sensor network application. Having
a wide variety of sensor interfaces usually does not impose a large
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" id="sensors-in-tinyos-1-x">
-<h1><a name="sensors-in-tinyos-1-x">2. Sensors in TinyOS 1.x</a></h1>
+<div class="section">
+<h1><a id="sensors-in-tinyos-1-x" name="sensors-in-tinyos-1-x">2. Sensors in TinyOS 1.x</a></h1>
<p>Early TinyOS sensors were generally analog. To sample one of these
sensors, an application makes an analog-to-digital conversion using
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" id="sensors-in-tinyos-2-x">
-<h1><a name="sensors-in-tinyos-2-x">3. Sensors in TinyOS 2.x</a></h1>
+<div class="section">
+<h1><a id="sensors-in-tinyos-2-x" name="sensors-in-tinyos-2-x">3. Sensors in TinyOS 2.x</a></h1>
<p>TinyOS 2.x has several sensor-independent interfaces, which cover a
range of common use cases. These interfaces can be used to write a
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" 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>
+<div class="section">
+<h2><a id="split-phase-small-scalar-i-o" name="split-phase-small-scalar-i-o">3.1 Split-Phase Small Scalar I/O</a></h2>
<p>The first set of interfaces can be used for low-rate scalar I/O:</p>
<pre class="literal-block">
interface Read<val_t> {
include many basic sensors, such as photo, temp, voltage, and ADC
readings.</p>
</div>
-<div class="section" id="split-phase-large-scalar-i-o">
-<h2><a name="split-phase-large-scalar-i-o">3.2 Split-Phase Large Scalar I/O</a></h2>
+<div class="section">
+<h2><a id="split-phase-large-scalar-i-o" name="split-phase-large-scalar-i-o">3.2 Split-Phase Large Scalar I/O</a></h2>
<p>If the SID's data object is too big to be passed efficienctly on the
stack, it can provide read/write interfaces that pass parameters by
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" id="single-phase-scalar-i-o">
-<h2><a name="single-phase-scalar-i-o">3.4 Single-Phase Scalar I/O</a></h2>
+<div class="section">
+<h2><a id="single-phase-scalar-i-o" name="single-phase-scalar-i-o">3.4 Single-Phase Scalar I/O</a></h2>
<p>Some devices may have their state cached or readily available. In
these cases, the device can provide a single-phase instead of
split-phase operation. Examples include a node's MAC address (which
}
</pre>
</div>
-<div class="section" id="notification-based-scalar-i-o">
-<h2><a name="notification-based-scalar-i-o">3.5 Notification-Based Scalar I/O</a></h2>
+<div class="section">
+<h2><a id="notification-based-scalar-i-o" name="notification-based-scalar-i-o">3.5 Notification-Based Scalar I/O</a></h2>
<p>Some sensor devices represent triggers, rather than request-driven
data acquisition. Examples of such sensors include switches,
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" id="split-phase-streaming-i-o">
-<h2><a name="split-phase-streaming-i-o">3.7 Split-Phase Streaming I/O</a></h2>
+<div class="section">
+<h2><a id="split-phase-streaming-i-o" name="split-phase-streaming-i-o">3.7 Split-Phase Streaming I/O</a></h2>
<p>Some sensors can provide a continuous stream of readings, and some
actuators can accept a continuous stream of new data. Depending on the
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" id="summary">
-<h1><a name="summary">4. Summary</a></h1>
+<div class="section">
+<h1><a id="summary" name="summary">4. Summary</a></h1>
<p>According to the design principles described in the HAA[_haa], authors
should write device drivers that provide rich, device-specific
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" id="author-s-address">
-<h1><a name="author-s-address">5. Author's Address</a></h1>
+<div class="section">
+<h1><a id="author-s-address" name="author-s-address">5. Author's Address</a></h1>
<div class="line-block">
<div class="line">Gilman Tolle</div>
<div class="line">2168 Shattuck Ave.</div>
<div class="line"><br /></div>
</div>
</div>
-<div class="section" id="citations">
-<h1><a name="citations">6. Citations</a></h1>
+<div class="section">
+<h1><a id="citations" name="citations">6. Citations</a></h1>
<table class="docutils footnote" frame="void" id="id2" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<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.3.6: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
<title>Power Management of Non-Virtualised Devices</title>
<meta name="author" content="Kevin Klues, Vlado Handziski, Jan-Hinrich Hauer, Phil Levis" />
<style type="text/css">
dd {
margin-bottom: 0.5em }
-/* Uncomment (& remove this text!) to get bold-faced definition list terms
-dt {
- font-weight: bold }
-*/
-
div.abstract {
margin: 2em 5em }
</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" id="abstract">
-<h1><a name="abstract">Abstract</a></h1>
+<div class="section">
+<h1><a id="abstract" name="abstract">Abstract</a></h1>
<p>This memo documents how TinyOS 2.x manages the power state of physical
(not virtualised) abstractions.</p>
</div>
-<div class="section" id="introduction">
-<h1><a name="introduction">1. Introduction</a></h1>
+<div class="section">
+<h1><a id="introduction" name="introduction">1. Introduction</a></h1>
<p>TinyOS platforms have limited energy. A unified power management
strategy for all devices and peripherpals is not feasible, as
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" id="power-management-models">
-<h1><a name="power-management-models">2. Power Management Models</a></h1>
+<div class="section">
+<h1><a id="power-management-models" name="power-management-models">2. Power Management Models</a></h1>
<p>There are two different models to managing the power state of a
peripheral in TinyOS: <em>explicit power management</em> and <em>implicit
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" id="explicit-power-management">
-<h1><a name="explicit-power-management">3. Explicit Power Management</a></h1>
+<div class="section">
+<h1><a id="explicit-power-management" name="explicit-power-management">3. Explicit Power Management</a></h1>
<p>Just as in TinyOS 1.x, TinyOS 2.x has <tt class="docutils literal"><span class="pre">StdControl</span></tt> and <tt class="docutils literal"><span class="pre">SplitControl</span></tt>
interfaces in order to control the on and off
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" 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>
+<div class="section">
+<h2><a id="power-management-with-stdcontrol" name="power-management-with-stdcontrol">3.1 Power Management with <tt class="docutils literal"><span class="pre">StdControl</span></tt></a></h2>
<p>Whenever the powerup and powerdown times of a non-virtualised device
-are negligible, they SHOULD provide the <tt class="docutils literal"><span class="pre">StdControl</span></tt> interface as
+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>Call</th>
-<th>Device On</th>
-<th>Device Off</th>
+<tr><th class="head">Call</th>
+<th class="head">Device On</th>
+<th class="head">Device Off</th>
</tr>
</thead>
<tbody valign="top">
}
</pre>
</div>
-<div class="section" id="power-management-with-splitcontrol">
-<h2><a name="power-management-with-splitcontrol">3.2 Power Management with <tt class="docutils literal"><span class="pre">SplitControl</span></tt></a></h2>
+<div class="section">
+<h2><a id="power-management-with-splitcontrol" name="power-management-with-splitcontrol">3.2 Power Management with <tt class="docutils literal"><span class="pre">SplitControl</span></tt></a></h2>
<p>When a device's powerup and powerdown times are non-negligible, the
<em>``SplitControl``</em> interface MUST be used in place of the <em>``StdControl``</em>
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>Call</th>
-<th>Device On</th>
-<th>Device Off</th>
-<th>Starting</th>
-<th>Stopping</th>
+<tr><th class="head">Call</th>
+<th class="head">Device On</th>
+<th class="head">Device Off</th>
+<th class="head">Starting</th>
+<th class="head">Stopping</th>
</tr>
</thead>
<tbody valign="top">
}
</pre>
</div>
-<div class="section" id="power-management-with-asyncstdcontrol">
-<h2><a name="power-management-with-asyncstdcontrol">3.3 Power Management with <tt class="docutils literal"><span class="pre">AsyncStdControl</span></tt></a></h2>
+<div class="section">
+<h2><a id="power-management-with-asyncstdcontrol" name="power-management-with-asyncstdcontrol">3.3 Power Management with <tt class="docutils literal"><span class="pre">AsyncStdControl</span></tt></a></h2>
<p>The commands and the events of the <em>``StdControl``</em> and the <em>``SplitControl``</em>
interfaces are synchronous and can not be called from within
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" id="implicit-power-management">
-<h1><a name="implicit-power-management">4. Implicit Power Management</a></h1>
+<div class="section">
+<h1><a id="implicit-power-management" name="implicit-power-management">4. Implicit Power Management</a></h1>
<p>While explicit power management provides the mechanism for changing
power states, it does not specify a policy.
This does not represent a large problem for the simple case
-of <em>dedicated</em> devices, but can become crucial for non-trivial cases
-involving complex interdependencies between devices controlled by multiple
+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" id="power-management-policies">
-<h2><a name="power-management-policies">4.1. Power Management Policies</a></h2>
+<div class="section">
+<h2><a id="power-management-policies" name="power-management-policies">4.1. Power Management Policies</a></h2>
<p>Just as generic arbiters are offered in TinyOS 2.x to provide the
arbitration functionality required by shared resources, generic power
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" 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>
+<div class="section">
+<h2><a id="example-power-managers-powermanagerc-and-deferredpowermanagerc" name="example-power-managers-powermanagerc-and-deferredpowermanagerc">4.2. Example Power Managers: PowerManagerC and DeferredPowerManagerC</a></h2>
<p>TinyOS 2.x currently has two default power management policies
-that it provides. These policies are implemented by the various
-components located under tinyos-2.x/lib/power. The first policy
+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" id="author-s-address">
-<h1><a name="author-s-address">5. Author's Address</a></h1>
+<div class="section">
+<h1><a id="author-s-address" name="author-s-address">5. Author's Address</a></h1>
<div class="line-block">
<div class="line">Kevin Klues</div>
<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" id="citations">
-<h1><a name="citations">6. Citations</a></h1>
+<div class="section">
+<h1><a id="citations" name="citations">6. Citations</a></h1>
<table class="docutils citation" frame="void" id="tep102" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<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.3.6: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
<title>Packet Protocols</title>
<meta name="author" content="Philip Levis" />
<style type="text/css">
dd {
margin-bottom: 0.5em }
-/* Uncomment (& remove this text!) to get bold-faced definition list terms
-dt {
- font-weight: bold }
-*/
-
div.abstract {
margin: 2em 5em }
</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" />
</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" 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,
+<div class="section">
+<h1><a id="abstract" name="abstract">Abstract</a></h1>
+<p>The memo documents the interfaces used by packet protocol components in
+TinyOS 2.x as well as the structure and implementation of ActiveMessageC,
the basic data-link HIL component. It also documents the virtualized
active message interfaces AMSenderC and AMReceiverC.</p>
</div>
-<div class="section" id="introduction">
-<h1><a name="introduction">1. Introduction</a></h1>
+<div class="section">
+<h1><a id="introduction" name="introduction">1. Introduction</a></h1>
<p>Sensor nodes are network-centric devices. Much of their software
complexity comes from network protocols and their interactions.
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" id="communication-interfaces">
-<h1><a name="communication-interfaces">2. Communication interfaces</a></h1>
+<div class="section">
+<h1><a id="communication-interfaces" name="communication-interfaces">2. Communication interfaces</a></h1>
<p>Packet-level communication has three basic classes of interfaces.
-<em>Packet</em> interfaces are for accessing message fields and payloads.
+<em>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" 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
+<div class="section">
+<h2><a id="packet-interfaces" name="packet-interfaces">2.1 Packet interfaces</a></h2>
+<p>The basic TinyOS 2.x message buffer type is message_t, which is
described in TEP 111. message_t right-justifies data-link
-headers to the data payload so that higher-level components can
+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" id="sending-interfaces">
-<h2><a name="sending-interfaces">2.2 Sending interfaces</a></h2>
+<div class="section">
+<h2><a id="sending-interfaces" name="sending-interfaces">2.2 Sending interfaces</a></h2>
<p>There are multiple sending interfaces, corresponding to different
addressing modes. For example, address-free protocols, such as
collection routing, provide the basic <tt class="docutils literal"><span class="pre">Send</span></tt> interface. Active
message communication has a destination of an AM address, so
-it provides the <tt class="docutils literal"><span class="pre">AMSend</span></tt> interface. This, for example, is the
+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" id="receive-interface">
-<h2><a name="receive-interface">2.3 Receive interface</a></h2>
+<div class="section">
+<h2><a id="receive-interface" 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" id="dispatch">
-<h2><a name="dispatch">2.4 Dispatch</a></h2>
+<div class="section">
+<h2><a id="dispatch" 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" 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
+<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
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" 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>
+<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>
<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" 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>
+<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>
<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" id="amreceiverc">
-<h2><a name="amreceiverc">4.2 AMReceiverC</a></h2>
+<div class="section">
+<h2><a id="amreceiverc" 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" id="amsnooperc">
-<h2><a name="amsnooperc">4.3 AMSnooperC</a></h2>
+<div class="section">
+<h2><a id="amsnooperc" 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" id="amsnoopingreceiverc">
-<h2><a name="amsnoopingreceiverc">4.4 AMSnoopingReceiverC</a></h2>
+<div class="section">
+<h2><a id="amsnoopingreceiverc" 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" id="amsenderc">
-<h2><a name="amsenderc">4.5 AMSenderC</a></h2>
+<div class="section">
+<h2><a id="amsenderc" 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" id="power-management-and-local-address">
-<h1><a name="power-management-and-local-address">5. Power Management and Local Address</a></h1>
+<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>
<p>In addition to standard datapath interfaces for sending and
receiving packets, an active message layer also has control interfaces.</p>
-<div class="section" id="power-management">
-<h2><a name="power-management">5.1 Power Management</a></h2>
+<div class="section">
+<h2><a id="power-management" 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" 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
+<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
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" id="hal-requirements">
-<h1><a name="hal-requirements">5. HAL Requirements</a></h1>
+<div class="section">
+<h1><a id="hal-requirements" 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" id="message-t">
-<h1><a name="message-t">6. message_t</a></h1>
+<div class="section">
+<h1><a id="message-t" 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" 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
+<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
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" id="author-s-address">
-<h1><a name="author-s-address">8. Author's Address</a></h1>
+<div class="section">
+<h1><a id="author-s-address" 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" id="citations">
-<h1><a name="citations">9. Citations</a></h1>
+<div class="section">
+<h1><a id="citations" 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">
dd {
margin-bottom: 0.5em }
-/* Uncomment (& remove this text!) to get bold-faced definition list terms
-dt {
- font-weight: bold }
-*/
-
div.abstract {
margin: 2em 5em }
<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.6: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
<title>Dissemination</title>
<meta name="author" content="Philip Levis and Gilman Tolle" />
<style type="text/css">
dd {
margin-bottom: 0.5em }
-/* Uncomment (& remove this text!) to get bold-faced definition list terms
-dt {
- font-weight: bold }
-*/
-
div.abstract {
margin: 2em 5em }
</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.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-06-14</td>
</tr>
<tr class="field"><th class="docinfo-name">Draft-Discuss:</th><td class="field-body">TinyOS Developer List <tinyos-devel at mail.millennium.berkeley.edu></td>
</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" id="abstract">
-<h1><a name="abstract">Abstract</a></h1>
+<div class="section">
+<h1><a id="abstract" name="abstract">Abstract</a></h1>
<p>The memo documents the interfaces, components, and semantics for
disseminating small (smaller than a single packet payload) pieces of
data in TinyOS 2.x. Dissemination is reliably delivering a piece of
data to every node in a network.</p>
</div>
-<div class="section" id="introduction">
-<h1><a name="introduction">1. Introduction</a></h1>
+<div class="section">
+<h1><a id="introduction" name="introduction">1. Introduction</a></h1>
<p>Dissemination is a basic sensor network protocol. The ability to
reliably deliver a piece of data to every node allows administrators
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" id="dissemination-interfaces">
-<h1><a name="dissemination-interfaces">2. Dissemination interfaces</a></h1>
+<div class="section">
+<h1><a id="dissemination-interfaces" name="dissemination-interfaces">2. Dissemination interfaces</a></h1>
<p>Small-value dissemination has two interfaces: DisseminationValue and
DisseminationUpdate. The former is for consumers of a disseminated
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" id="dissemination-service">
-<h1><a name="dissemination-service">3 Dissemination Service</a></h1>
+<div class="section">
+<h1><a id="dissemination-service" name="dissemination-service">3 Dissemination Service</a></h1>
<p>A dissemination service MUST provide one component, DisseminatorC,
which has the following signature:</p>
<pre class="literal-block">
provides interface DisseminationUpdate <t>;
}
</pre>
-<p>The t argument MUST be able to fit in a single message_t[<a href="#id4" name="id5"><span class="problematic" id="id5">tep111_</span></a>] after
+<p>The t argument MUST be able to fit in a single message_t [TEP111] after
considering the headers that the dissemination protocol introduces.
A dissemination implementation SHOULD have a compile error if a larger
type than this is used.</p>
<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" id="dissemination-keys">
-<h1><a name="dissemination-keys">4 Dissemination Keys</a></h1>
+<div class="section">
+<h1><a id="dissemination-keys" name="dissemination-keys">4 Dissemination Keys</a></h1>
<p>One issue that comes up when using this interfaces is the selection of
a key for each value. On one hand, using unique() is easy, but this
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" id="more-complex-dissemination">
-<h1><a name="more-complex-dissemination">5. More Complex Dissemination</a></h1>
+<div class="section">
+<h1><a id="more-complex-dissemination" name="more-complex-dissemination">5. More Complex Dissemination</a></h1>
<p>An application can use this low-level networking primitive to build
more complex dissemination systems. For example, if you want have a
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" id="implementation">
-<h1><a name="implementation">6. Implementation</a></h1>
+<div class="section">
+<h1><a id="implementation" name="implementation">6. Implementation</a></h1>
<p>An implementation of this TEP can be found in
<tt class="docutils literal"><span class="pre">tinyos-2.x/tos/lib/net</span></tt>. This dissemination implementation uses
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" id="author-s-address">
-<h1><a name="author-s-address">6. Author's Address</a></h1>
+<div class="section">
+<h1><a id="author-s-address" name="author-s-address">6. Author's Address</a></h1>
<div class="line-block">
<div class="line">Philip Levis</div>
<div class="line">358 Gates Hall</div>
<div class="line">email - <a class="reference" href="mailto:gtolle@archedrock.com">gtolle@archedrock.com</a></div>
</div>
</div>
-<div class="section" id="citations">
-<h1><a name="citations">7. Citations</a></h1>
+<div class="section">
+<h1><a id="citations" name="citations">7. Citations</a></h1>
<table class="docutils footnote" frame="void" id="id2" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
</tbody>
</table>
</div>
-<div class="system-messages section">
-<h1><a>Docutils System Messages</a></h1>
-<div class="system-message" id="id4">
-<p class="system-message-title">System Message: <a name="id4">ERROR/3</a> (<tt class="docutils">txt/tep118.txt</tt>, line 116); <em><a href="#id5">backlink</a></em></p>
-Unknown target name: "tep111".</div>
-</div>
</div>
</body>
</html>
<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.6: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
<title>Collection</title>
<meta name="author" content="Rodrigo Fonseca, Omprakash Gnawali, Kyle Jamieson, and Philip Levis" />
<style type="text/css">
dd {
margin-bottom: 0.5em }
-/* Uncomment (& remove this text!) to get bold-faced definition list terms
-dt {
- font-weight: bold }
-*/
-
div.abstract {
margin: 2em 5em }
</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" id="abstract">
-<h1><a name="abstract">Abstract</a></h1>
+<div class="section">
+<h1><a id="abstract" name="abstract">Abstract</a></h1>
<p>The memo documents the interfaces, components, and semantics used by
collection protocol in TinyOS 2.x. Collection provides a best-effort,
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" id="introduction">
-<h1><a name="introduction">1. Introduction</a></h1>
+<div class="section">
+<h1><a id="introduction" name="introduction">1. Introduction</a></h1>
<p>Collecting data at a base station is a common requirement of sensor
network applications. The general approach used is to build one
or more collection <em>trees</em>, each of which is rooted at a base
-station. When a node has data which needs to be collected, it
+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" id="collection-interfaces">
-<h1><a name="collection-interfaces">2. Collection interfaces</a></h1>
+<div class="section">
+<h1><a id="collection-interfaces" name="collection-interfaces">2. Collection interfaces</a></h1>
<p>A node can perform four different roles in collection: producer,
consumer, snooper, and in-network processor. Depending on their role,
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" id="collection-services">
-<h1><a name="collection-services">3 Collection Services</a></h1>
+<div class="section">
+<h1><a id="collection-services" name="collection-services">3 Collection Services</a></h1>
<p>A collection service MUST provide one component, CollectionC,
which has the following signature:</p>
<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" id="collectionsenderc">
-<h2><a name="collectionsenderc">3.1 CollectionSenderC</a></h2>
+<div class="section">
+<h2><a id="collectionsenderc" name="collectionsenderc">3.1 CollectionSenderC</a></h2>
<p>Collection has a virtualized sending abstraction, the generic
component CollectionSenderC:</p>
<pre class="literal-block">
based on its collection ID and contents.</p>
</div>
</div>
-<div class="section" id="implementation">
-<h1><a name="implementation">4 Implementation</a></h1>
+<div class="section">
+<h1><a id="implementation" name="implementation">4 Implementation</a></h1>
<p>An implementation of this TEP can be found in
<tt class="docutils literal"><span class="pre">tinyos-2.x/tos/lib/net/ctp</span></tt> and <tt class="docutils literal"><span class="pre">tinyos-2.x/tos/lib/net/le</span></tt>, in
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" id="linkestimatorp">
-<h2><a name="linkestimatorp">4.1 LinkEstimatorP</a></h2>
+<div class="section">
+<h2><a id="linkestimatorp" name="linkestimatorp">4.1 LinkEstimatorP</a></h2>
<p>LinkEstimatorP estimates the quality of link to or from each
neighbor. Link estimation can be done in a variety of ways, and we
do not impose one here. It is decoupled from the establishment of
}
</pre>
</div>
-<div class="section" id="ctproutingenginep">
-<h2><a name="ctproutingenginep">4.2 CtpRoutingEngineP</a></h2>
+<div class="section">
+<h2><a id="ctproutingenginep" name="ctproutingenginep">4.2 CtpRoutingEngineP</a></h2>
<p>CtpRoutingEngineP is responsible for computing routes to the roots of a
tree. In traditional networking terminology, this is part of the
control plane of the network, and is does not directly forward any
-data packets, which is the responsibility of CtpForwardingEngine.
+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" id="ctpforwardingenginep">
-<h2><a name="ctpforwardingenginep">4.3 CtpForwardingEngineP</a></h2>
+<div class="section">
+<h2><a id="ctpforwardingenginep" name="ctpforwardingenginep">4.3 CtpForwardingEngineP</a></h2>
<p>The CtpForwardingEngineP component provides all the top level interfaces
-(except RootControl) which CollectionC provides and an application
+(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" id="author-addresses">
-<h1><a name="author-addresses">5. Author Addresses</a></h1>
+<div class="section">
+<h1><a id="author-addresses" name="author-addresses">5. Author Addresses</a></h1>
<div class="line-block">
-<div class="line">Rodrigo Fonseca </div>
+<div class="line">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" id="citations">
-<h1><a name="citations">6. Citations</a></h1>
+<div class="section">
+<h1><a id="citations" name="citations">6. Citations</a></h1>
<table class="docutils footnote" frame="void" id="id1" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
dd {
margin-bottom: 0.5em }
-/* Uncomment (& remove this text!) to get bold-faced definition list terms
-dt {
- font-weight: bold }
-*/
-
div.abstract {
margin: 2em 5em }
<br />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.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">2007-05-15</td>
+<tr class="field"><th class="docinfo-name">Draft-Modified:</th><td class="field-body">2007-06-21</td>
</tr>
<tr class="field"><th class="docinfo-name">Draft-Discuss:</th><td class="field-body">TinyOS Alliance <tinyos-alliance at mail.millennium.berkeley.edu></td>
</tr>
<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.6: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.4: 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">
dd {
margin-bottom: 0.5em }
-/* Uncomment (& remove this text!) to get bold-faced definition list terms
-dt {
- font-weight: bold }
-*/
-
div.abstract {
margin: 2em 5em }
</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" id="abstract">
-<h1><a name="abstract">Abstract</a></h1>
+<div class="section">
+<h1><a id="abstract" 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" id="project-outline">
-<h1><a name="project-outline">1. Project Outline</a></h1>
+<div class="section">
+<h1><a id="project-outline" 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" id="project-approach">
-<h1><a name="project-approach">2. Project Approach</a></h1>
+<div class="section">
+<h1><a id="project-approach" 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" id="development-environment-and-tool-chain">
-<h1><a name="development-environment-and-tool-chain">3. Development Environment and Tool Chain</a></h1>
+<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>
<p>The following subsections describe the different development tools,
their selection and interconnection.</p>
-<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>
+<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>
<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" id="our-recommendation">
-<h2><a name="our-recommendation">3.1.1 Our Recommendation</a></h2>
+<div class="section">
+<h2><a id="our-recommendation" 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" id="tool-chain-overview">
-<h2><a name="tool-chain-overview">3.2 Tool Chain Overview</a></h2>
+<div class="section">
+<h2><a id="tool-chain-overview" 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" id="description-of-the-tool-chain">
-<h2><a name="description-of-the-tool-chain">3.3 Description of the Tool Chain</a></h2>
+<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>
<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" id="description-of-the-mangling-script">
-<h2><a name="description-of-the-mangling-script">3.4 Description of the Mangling Script</a></h2>
+<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>
<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" id="sfr-and-sbit-declarations">
-<h2><a name="sfr-and-sbit-declarations">3.4.1 SFR and SBIT Declarations</a></h2>
+<div class="section">
+<h2><a id="sfr-and-sbit-declarations" 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" id="sdcc-keil-data-types">
-<h2><a name="sdcc-keil-data-types">3.4.2 SDCC/KEIL Data Types</a></h2>
+<div class="section">
+<h2><a id="sdcc-keil-data-types" 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" id="reserved-keywords-in-sdcc">
-<h2><a name="reserved-keywords-in-sdcc">3.4.3 Reserved Keywords in SDCC</a></h2>
+<div class="section">
+<h2><a id="reserved-keywords-in-sdcc" 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" id="removal-of-inlining">
-<h2><a name="removal-of-inlining">3.4.4 Removal of inlining</a></h2>
+<div class="section">
+<h2><a id="removal-of-inlining" 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" id="removal-of-preprocessor-line-numbering">
-<h2><a name="removal-of-preprocessor-line-numbering">3.4.5 Removal of Preprocessor Line Numbering</a></h2>
+<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>
<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" id="change-in-identifiers">
-<h2><a name="change-in-identifiers">3.4.6 Change $ in Identifiers</a></h2>
+<div class="section">
+<h2><a id="change-in-identifiers" 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" id="interrupt-vectors">
-<h2><a name="interrupt-vectors">3.4.7 Interrupt Vectors</a></h2>
+<div class="section">
+<h2><a id="interrupt-vectors" 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" id="tinyos-modifications">
-<h1><a name="tinyos-modifications">4. TinyOS Modifications</a></h1>
+<div class="section">
+<h1><a id="tinyos-modifications" 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
+----------+ +---------------------+ +---------+
- \/ /\ \/ \/ /\ \/ /\ -----
-+----------+ +--------+ +--------+ +---------+ +--------+
-| Timer2 | | Timer1 | > | Serial | | Sensors | | Port | HW
-+----------+ +--------+ | Port | +---------+ +--------+
+| HPLClock | | HPLUART | | HPLADC | \/ HPL
++----------+ +---------------------+ +---------+
+ \/ /\ \/ \/ /\ \/ /\ -----
++----------+ +--------+ +--------+ +---------+ +--------+
+| 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" id="hplclock-and-related-modules">
-<h2><a name="hplclock-and-related-modules">4.1 HPLClock and related modules</a></h2>
+<div class="section">
+<h2><a id="hplclock-and-related-modules" 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" id="timer">
-<h2><a name="timer">4.1.1 Timer</a></h2>
+<div class="section">
+<h2><a id="timer" 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" id="hpluart">
-<h2><a name="hpluart">4.2 HPLUART</a></h2>
+<div class="section">
+<h2><a id="hpluart" 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" id="hpladc">
-<h2><a name="hpladc">4.3 HPLADC</a></h2>
+<div class="section">
+<h2><a id="hpladc" 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" id="leds">
-<h2><a name="leds">4.4 LEDS</a></h2>
+<div class="section">
+<h2><a id="leds" 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" id="interrupts">
-<h2><a name="interrupts">4.5 Interrupts</a></h2>
+<div class="section">
+<h2><a id="interrupts" 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" id="conclusion">
-<h1><a name="conclusion">5. Conclusion</a></h1>
+<div class="section">
+<h1><a id="conclusion" 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" id="future-work">
-<h1><a name="future-work">6. Future Work</a></h1>
+<div class="section">
+<h1><a id="future-work" 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" id="authors">
-<h1><a name="authors">7. Authors</a></h1>
+<div class="section">
+<h1><a id="authors" 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">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">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" id="citations">
-<h1><a name="citations">8. Citations</a></h1>
+<div class="section">
+<h1><a id="citations" 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>
--- /dev/null
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
+<title>IEEE EUI-64 Unique Node Identifier</title>
+<meta name="author" content="Gilman Tolle, Jonathan Hui" />
+<style type="text/css">
+
+/*
+:Author: David Goodger
+:Contact: goodger@users.sourceforge.net
+:date: $Date$
+:version: $Revision$
+:copyright: This stylesheet has been placed in the public domain.
+
+Default cascading style sheet for the HTML output of Docutils.
+*/
+body {
+ font-family: Times;
+ font-size: 16px;
+}
+
+.first {
+ margin-top: 0 ! important }
+
+.last {
+ margin-bottom: 0 ! important }
+
+.hidden {
+ display: none }
+
+a.toc-backref {
+ text-decoration: none ;
+ color: black }
+
+blockquote.epigraph {
+ margin: 2em 5em ; }
+
+dd {
+ margin-bottom: 0.5em }
+
+div.abstract {
+ margin: 2em 5em }
+
+div.abstract p.topic-title {
+ font-weight: bold ;
+ text-align: center }
+
+div.attention, div.caution, div.danger, div.error, div.hint,
+div.important, div.note, div.tip, div.warning, div.admonition {
+ margin: 2em ;
+ border: medium outset ;
+ padding: 1em }
+
+div.attention p.admonition-title, div.caution p.admonition-title,
+div.danger p.admonition-title, div.error p.admonition-title,
+div.warning p.admonition-title {
+ color: red ;
+ font-weight: bold ;
+ font-family: sans-serif }
+
+div.hint p.admonition-title, div.important p.admonition-title,
+div.note p.admonition-title, div.tip p.admonition-title,
+div.admonition p.admonition-title {
+ font-weight: bold ;
+ font-family: sans-serif }
+
+div.dedication {
+ margin: 2em 5em ;
+ text-align: center ;
+ font-style: italic }
+
+div.dedication p.topic-title {
+ font-weight: bold ;
+ font-style: normal }
+
+div.figure {
+ margin-left: 2em }
+
+div.footer, div.header {
+ font-size: smaller }
+
+div.line-block {
+ display: block ;
+ margin-top: 1em ;
+ margin-bottom: 1em }
+
+div.line-block div.line-block {
+ margin-top: 0 ;
+ margin-bottom: 0 ;
+ margin-left: 1.5em }
+
+div.sidebar {
+ margin-left: 1em ;
+ border: medium outset ;
+ padding: 0em 1em ;
+ background-color: #ffffee ;
+ width: 40% ;
+ float: right ;
+ clear: right }
+
+div.sidebar p.rubric {
+ font-family: sans-serif ;
+ font-size: medium }
+
+div.system-messages {
+ margin: 5em }
+
+div.system-messages h1 {
+ color: red }
+
+div.system-message {
+ border: medium outset ;
+ padding: 1em }
+
+div.system-message p.system-message-title {
+ color: red ;
+ font-weight: bold }
+
+div.topic {
+ margin: 2em }
+
+h1 {
+ font-family: Arial, sans-serif;
+ font-size: 20px;
+}
+
+h1.title {
+ text-align: center;
+ font-size: 32px;
+}
+
+h2 {
+ font-size: 16px;
+ font-family: Arial, sans-serif;
+}
+
+h2.subtitle {
+ text-align: center }
+
+h3 {
+ font-size: 12px;
+ font-family: Arial, sans-serif;
+}
+
+hr {
+ width: 75% }
+
+ol.simple, ul.simple {
+ margin-bottom: 1em }
+
+ol.arabic {
+ list-style: decimal }
+
+ol.loweralpha {
+ list-style: lower-alpha }
+
+ol.upperalpha {
+ list-style: upper-alpha }
+
+ol.lowerroman {
+ list-style: lower-roman }
+
+ol.upperroman {
+ list-style: upper-roman }
+
+p.attribution {
+ text-align: right ;
+ margin-left: 50% }
+
+p.caption {
+ font-style: italic }
+
+p.credits {
+ font-style: italic ;
+ font-size: smaller }
+
+p.label {
+ white-space: nowrap }
+
+p.rubric {
+ font-weight: bold ;
+ font-size: larger ;
+ color: maroon ;
+ text-align: center }
+
+p.sidebar-title {
+ font-family: sans-serif ;
+ font-weight: bold ;
+ font-size: larger }
+
+p.sidebar-subtitle {
+ font-family: sans-serif ;
+ font-weight: bold }
+
+p.topic-title {
+ font-weight: bold }
+
+pre.address {
+ margin-bottom: 0 ;
+ margin-top: 0 ;
+ font-family: serif ;
+ font-size: 100% }
+
+pre.line-block {
+ font-family: serif ;
+ font-size: 100% }
+
+pre.literal-block, pre.doctest-block {
+ margin-left: 2em ;
+ margin-right: 2em ;
+ background-color: #eeeeee;
+ border-color: #000000;
+ border-width: thin;
+ font-size: 14px
+}
+
+span.classifier {
+ font-family: sans-serif ;
+ font-style: oblique }
+
+span.classifier-delimiter {
+ font-family: sans-serif ;
+ font-weight: bold }
+
+span.interpreted {
+ font-family: sans-serif }
+
+span.option {
+ white-space: nowrap }
+
+span.option-argument {
+ font-style: italic }
+
+span.pre {
+ white-space: pre }
+
+span.problematic {
+ color: red }
+
+table {
+ margin-top: 0.5em ;
+ margin-bottom: 0.5em }
+
+table.citation {
+ border-left: solid thin gray ;
+ padding-left: 0.5ex }
+
+table.docinfo {
+ margin: 2em 4em;
+}
+
+table.footnote {
+ border-left: solid thin black ;
+ padding-left: 0.5ex }
+
+td, th {
+ padding-left: 0.5em ;
+ padding-right: 0.5em ;
+ vertical-align: top }
+
+th.docinfo-name, th.field-name {
+ font-weight: bold ;
+ text-align: left ;
+ white-space: nowrap;
+ }
+
+h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt {
+ font-size: 100% }
+
+tt {}
+
+ul.auto-toc {
+ list-style-type: none }
+
+</style>
+</head>
+<body>
+<div class="document" id="ieee-eui-64-unique-node-identifier">
+<h1 class="title">IEEE EUI-64 Unique Node Identifier</h1>
+<table class="docinfo" frame="void" rules="none">
+<col class="docinfo-name" />
+<col class="docinfo-content" />
+<tbody valign="top">
+<tr class="field"><th class="docinfo-name">TEP:</th><td class="field-body">122</td>
+</tr>
+<tr class="field"><th class="docinfo-name">Group:</th><td class="field-body">Core Working Group</td>
+</tr>
+<tr class="field"><th class="docinfo-name">Type:</th><td class="field-body">Documentary</td>
+</tr>
+<tr><th class="docinfo-name">Status:</th>
+<td>Draft</td></tr>
+<tr class="field"><th class="docinfo-name">TinyOS-Version:</th><td class="field-body">2.x</td>
+</tr>
+<tr><th class="docinfo-name">Author:</th>
+<td>Gilman Tolle, Jonathan Hui</td></tr>
+<tr class="field"><th class="docinfo-name">Draft-Created:</th><td class="field-body">26-Apr-2006</td>
+</tr>
+<tr class="field"><th class="docinfo-name">Draft-Version:</th><td class="field-body"></td>
+</tr>
+<tr class="field"><th class="docinfo-name">Draft-Modified:</th><td class="field-body"></td>
+</tr>
+<tr class="field"><th class="docinfo-name">Draft-Discuss:</th><td class="field-body">TinyOS Developer List <tinyos-devel at mail.millennium.berkeley.edu></td>
+</tr>
+</tbody>
+</table>
+<div class="note">
+<p class="first admonition-title">Note</p>
+<p class="last">This memo documents a part of TinyOS for the TinyOS Community, and
+requests discussion and suggestions for improvements. Distribution
+of this memo is unlimited. This memo is in full compliance with
+TEP 1.</p>
+</div>
+<div class="section">
+<h1><a id="abstract" name="abstract">Abstract</a></h1>
+<p>A TinyOS application developer may desire a globally-unique node
+identifier within the IEEE EUI-64 namespace. This document describes
+the TinyOS components used to access such an identifier.</p>
+</div>
+<div class="section">
+<h1><a id="interfaces" name="interfaces">1. Interfaces</a></h1>
+<p>A platform that can provide a valid IEEE EUI-64 globally-unique node
+identifier SHOULD provide it through a component with the signature
+defined here, enabling platform-independent access to the identifier:</p>
+<pre class="literal-block">
+configuration LocalIeeeEui64C {
+ provides interface LocalIeeeEui64;
+}
+</pre>
+<p>The identifier is accessed through the following interface:</p>
+<pre class="literal-block">
+interface LocalIeeeEui64 {
+ command ieee_eui64_t getId();
+}
+</pre>
+<p>The ieee_eui64_t type is defined in <tt class="docutils literal"><span class="pre">tos/types/IeeeEui64.h</span></tt> as:</p>
+<pre class="literal-block">
+enum { IEEE_EUI64_LENGTH = 8; }
+
+typedef struct ieee_eui64 {
+ uint8_t data[IEEE_EUI64_LENGTH];
+} ieee_eui64_t;
+</pre>
+<p>If the platform can provide a valid IEEE EUI-64, the value returned
+from this call MUST follow the IEEE EUI-64 standard.</p>
+<p>If a platform can provide a unique identifier that is not a valid IEEE
+EUI-64 identifier, it SHOULD provide its unique identifier through a
+component with a different name and a different interface. The
+definition of such an interface is outside the scope of this TEP.</p>
+</div>
+<div class="section">
+<h1><a id="ieee-eui-64" name="ieee-eui-64">2. IEEE EUI-64</a></h1>
+<p>The IEEE EUI-64 structure is copied here:</p>
+<pre class="literal-block">
+| company_id | extension identifier |
+|addr+0 | addr+1 | addr+2 | addr+3 | addr+4 | addr+5 | addr+6 | addr+7|
+| AC | DE | 48 | 23 | 45 | 67 | AB | CD |
+10101100 11011110 01001000 00100011 01000101 01100111 10101011 11001101
+| | | |
+| most significant byte least significant byte |
+most-significant bit least-significant bit
+
+If provided in byte-addressable media, the original byte-address order
+of the manufacturer is specified: the most through least significant
+bytes of the EUI-64 value are contained within the lowest through
+highest byte addresses, as illustrated above.
+</pre>
+<p>See: <a class="reference" href="http://standards.ieee.org/regauth/oui/tutorials/EUI64.html">http://standards.ieee.org/regauth/oui/tutorials/EUI64.html</a></p>
+<p>The author of the LocalIeeeEui64C component MUST ensure that the
+getId() call returns a valid EUI-64 identifier that follows the
+standard, with the bytes in the order described above.</p>
+</div>
+<div class="section">
+<h1><a id="implementation-notes" name="implementation-notes">3. Implementation Notes</a></h1>
+<p>Some TinyOS node platforms contain a unique hardware identifier that
+can be used to build the EUI-64 node identifier. That hardware
+identifier may be obtained from several places, e.g. a dedicated
+serial ID chip or a flash storage device. Users of the interface
+described in this document MUST NOT require knowledge of how the
+unique identifier is generated.</p>
+<p>The EUI-64 node identifier MUST be available before the Boot.booted()
+event is signalled. If the EUI-64 is derived from a hardware device,
+the hardware device should be accessed during the Init portion of the
+boot sequence.</p>
+</div>
+<div class="section">
+<h1><a id="author-s-address" name="author-s-address">4. Author's Address</a></h1>
+<div class="line-block">
+<div class="line">Gilman Tolle</div>
+<div class="line">Arch Rock Corporation</div>
+<div class="line">657 Mission St. Suite 600</div>
+<div class="line">San Francisco, CA 94105</div>
+<div class="line"><br /></div>
+<div class="line">phone - +1 415 692 0828</div>
+<div class="line">email - <a class="reference" href="mailto:gtolle@archrock.com">gtolle@archrock.com</a></div>
+</div>
+<div class="line-block">
+<div class="line">Jonathan Hui</div>
+<div class="line">Arch Rock Corporation</div>
+<div class="line">657 Mission St. Suite 600</div>
+<div class="line">San Francisco, CA 94105</div>
+<div class="line"><br /></div>
+<div class="line">phone - +1 415 692 0828</div>
+<div class="line">email - <a class="reference" href="mailto:jhui@archrock.com">jhui@archrock.com</a></div>
+</div>
+</div>
+</div>
+</body>
+</html>
<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.6: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
<title>The Collection Tree Protocol (CTP)</title>
<meta name="author" content="Rodrigo Fonseca, Omprakash Gnawali, Kyle Jamieson, Sukun Kim, Philip Levis, and Alec Woo" />
<style type="text/css">
dd {
margin-bottom: 0.5em }
-/* Uncomment (& remove this text!) to get bold-faced definition list terms
-dt {
- font-weight: bold }
-*/
-
div.abstract {
margin: 2em 5em }
</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" 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
+<div class="section">
+<h1><a id="abstract" name="abstract">Abstract</a></h1>
+<p>This memo documents the Collection Tree Protocol (CTP), which
+provides best-effort anycast datagram communication to one of the
collection roots in a network.</p>
</div>
-<div class="section" id="introduction">
-<h1><a name="introduction">1. Introduction</a></h1>
+<div class="section">
+<h1><a id="introduction" name="introduction">1. Introduction</a></h1>
</div>
-<div class="section" id="assumptions-and-limitations">
-<h1><a name="assumptions-and-limitations">2. Assumptions and Limitations</a></h1>
+<div class="section">
+<h1><a id="assumptions-and-limitations" name="assumptions-and-limitations">2. Assumptions and Limitations</a></h1>
<p>CTP is a tree-based collection protocol. Some number of nodes in a
network advertise themselves as tree roots. Nodes form a set of routing
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" id="collection-and-ctp">
-<h1><a name="collection-and-ctp">3. Collection and CTP</a></h1>
+<div class="section">
+<h1><a id="collection-and-ctp" name="collection-and-ctp">3. Collection and CTP</a></h1>
<p>CTP uses expected transmissions (ETX) as its routing gradient. A root
has an ETX of 0. The ETX of a node is the ETX of its parent plus the
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" id="ctp-data-frame">
-<h1><a name="ctp-data-frame">4. CTP Data Frame</a></h1>
+<div class="section">
+<h1><a id="ctp-data-frame" name="ctp-data-frame">4. CTP Data Frame</a></h1>
<p>The CTP data frame format is as follows:</p>
<pre class="literal-block">
- 1
- 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6
+ 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" id="ctp-routing-frame">
-<h1><a name="ctp-routing-frame">5. CTP Routing Frame</a></h1>
+<div class="section">
+<h1><a id="ctp-routing-frame" name="ctp-routing-frame">5. CTP Routing Frame</a></h1>
<p>The CTP routing frame format is as follows:</p>
<pre class="literal-block">
- 1
- 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6
+ 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" id="implementation">
-<h1><a name="implementation">6. Implementation</a></h1>
+<div class="section">
+<h1><a id="implementation" name="implementation">6. Implementation</a></h1>
<p>An implementation of CTP can be found in the tos/lib/net/ctp directory
of TinyOS 2.0. This section describes the structure of that implementation
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" id="link-estimation">
-<h2><a name="link-estimation">6.1 Link Estimation</a></h2>
+<div class="section">
+<h2><a id="link-estimation" name="link-estimation">6.1 Link Estimation</a></h2>
<p>The implementation uses two mechanisms to estimate the quality of a link:
periodic LEEP <a class="footnote-reference" href="#id4" id="id1" name="id1">[1]</a> packets and data packets. The implementation sends
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" id="routing-engine">
-<h2><a name="routing-engine">6.2 Routing Engine</a></h2>
+<div class="section">
+<h2><a id="routing-engine" name="routing-engine">6.2 Routing Engine</a></h2>
<p>The implementation's routing engine is responsible for picking the next
hop for a data transmission. It keeps track of the path ETX values of
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" id="forwarding-engine">
-<h2><a name="forwarding-engine">6.3 Forwarding Engine</a></h2>
+<div class="section">
+<h2><a id="forwarding-engine" name="forwarding-engine">6.3 Forwarding Engine</a></h2>
<p>The component <tt class="docutils literal"><span class="pre">tos/lib/net/ctp/CtpForwardingEngineP</span></tt> implements the
forwarding engine. It has five repsonsibilities:</p>
<blockquote>
along the path.</p>
</div>
</div>
-<div class="section" id="citations">
-<h1><a name="citations">7. Citations</a></h1>
+<div class="section">
+<h1><a id="citations" name="citations">7. Citations</a></h1>
<div class="line-block">
-<div class="line">Rodrigo Fonseca </div>
+<div class="line">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" id="id3">
-<h1><a name="id3">8. Citations</a></h1>
+<div class="section">
+<h1><a id="id3" name="id3">8. Citations</a></h1>
<table class="docutils footnote" frame="void" id="id4" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<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.3.6: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
<title>The Link Estimation Exchange Protocol (LEEP)</title>
<meta name="author" content="Omprakash Gnawali" />
<style type="text/css">
dd {
margin-bottom: 0.5em }
-/* Uncomment (& remove this text!) to get bold-faced definition list terms
-dt {
- font-weight: bold }
-*/
-
div.abstract {
margin: 2em 5em }
</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" id="abstract">
-<h1><a name="abstract">Abstract</a></h1>
+<div class="section">
+<h1><a id="abstract" name="abstract">Abstract</a></h1>
<p>The memo documents the Link Estimation Exchange Protocol (LEEP). Nodes
use LEEP to estimate and exchange information about the quality of
links to the neighbors.</p>
</div>
-<div class="section" id="introduction">
-<h1><a name="introduction">1. Introduction</a></h1>
+<div class="section">
+<h1><a id="introduction" name="introduction">1. Introduction</a></h1>
<p>Routing protocols often require bi-directional link qualities to
compute the routes. Nodes can estimate the quality of the in-bound
link from a neighbor by estimating the ratio of successfully received
messages and the total transmitted messages. LEEP appends in-bound
-packet reception rate (PRR) estimates to packets. Other nodes hearing
+packet reception rate (PRR) estimates to packets. Other nodes hearing
these packets can combine the in-bound PRR values with their own
in-bound values to compute bi-directional link quality.</p>
</div>
-<div class="section" id="definitions">
-<h1><a name="definitions">2. Definitions</a></h1>
-<div class="section" id="link-quality">
-<h2><a name="link-quality">2.1 Link Quality</a></h2>
+<div class="section">
+<h1><a id="definitions" name="definitions">2. Definitions</a></h1>
+<div class="section">
+<h2><a id="link-quality" name="link-quality">2.1 Link Quality</a></h2>
<p>The link quality between a directed node pair (A,B) is the probability
that a packet transmitted by A will be successfully received by B. The
-bidirectional link quality of an undirected node pair (A,B) is the
+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" id="in-bound-link-quality">
-<h2><a name="in-bound-link-quality">2.2 In-bound Link Quality</a></h2>
+<div class="section">
+<h2><a id="in-bound-link-quality" name="in-bound-link-quality">2.2 In-bound Link Quality</a></h2>
<p>In a node pair (A,B), with B as the node of reference, in-bound link
quality is a value in the range of 0 to 255 that describes the quality
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" id="out-bound-link-quality">
-<h2><a name="out-bound-link-quality">2.3 Out-bound Link Quality</a></h2>
+<div class="section">
+<h2><a id="out-bound-link-quality" name="out-bound-link-quality">2.3 Out-bound Link Quality</a></h2>
<p>In a node pair (A,B), with B as the node of reference, out-bound link
quality is defined as the quality of the link from B to A. B can
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" id="link-information-entry">
-<h2><a name="link-information-entry">2.4 Link Information Entry</a></h2>
+<div class="section">
+<h2><a id="link-information-entry" name="link-information-entry">2.4 Link Information Entry</a></h2>
<p>Link Information Entry created by node k is a tuple (n,q) where q is
the in-bound link quality from node n to k.</p>
</div>
</div>
-<div class="section" 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>
+<div class="section">
+<h1><a id="id1" name="id1">3. The Link Estimation Exchange Protocol (LEEP)</a></h1>
+<div class="section">
+<h2><a id="assumptions" name="assumptions">3.1 Assumptions</a></h2>
<p>Following are the assumptions made by LEEP:</p>
<p>3.1.1. The data link frame has a single-hop source field.
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" id="the-protocol">
-<h2><a name="the-protocol">3.2 The Protocol</a></h2>
+<div class="section">
+<h2><a id="the-protocol" name="the-protocol">3.2 The Protocol</a></h2>
<p>To compute the bi-directional link quality, in-bound link quality must
be exchanged among the neighbors. LEEP maintains a sequence number
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" id="leep-frame">
-<h2><a name="leep-frame">3.3 LEEP Frame</a></h2>
+<div class="section">
+<h2><a id="leep-frame" name="leep-frame">3.3 LEEP Frame</a></h2>
<p>A LEEP frame has a header, the payload, and a footer with the Link
Information (LI) entries as shown in this diagram:</p>
<pre class="literal-block">
allowed by the data link layer. A LEEP frame can have 0 Link
Information entry.</p>
</div>
-<div class="section" id="leep-header">
-<h2><a name="leep-header">3.3.1 LEEP header</a></h2>
+<div class="section">
+<h2><a id="leep-header" name="leep-header">3.3.1 LEEP header</a></h2>
<p>The following diagram shows the LEEP header format:</p>
<pre class="literal-block">
1
</ul>
</blockquote>
</div>
-<div class="section" id="id2">
-<h2><a name="id2">3.3.2 Link Information Entry</a></h2>
+<div class="section">
+<h2><a id="id2" name="id2">3.3.2 Link Information Entry</a></h2>
<p>The following diagram shows the Link Information Entry format:</p>
<pre class="literal-block">
1
</blockquote>
</div>
</div>
-<div class="section" id="implementation">
-<h1><a name="implementation">4. Implementation</a></h1>
+<div class="section">
+<h1><a id="implementation" name="implementation">4. Implementation</a></h1>
<p>The following files in <tt class="docutils literal"><span class="pre">tinyos-2.x/tos/lib/net/le</span></tt> provide a
reference implementation of LEEP described in this TEP.</p>
<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" id="author-s-address">
-<h1><a name="author-s-address">5. Author's Address</a></h1>
+<div class="section">
+<h1><a id="author-s-address" name="author-s-address">5. Author's Address</a></h1>
<div class="line-block">
<div class="line">Omprakash Gnawali</div>
-<div class="line">Ronald Tutor Hall (RTH) 418 </div>
+<div class="line">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" id="citations">
-<h1><a name="citations">6. Citations</a></h1>
+<div class="section">
+<h1><a id="citations" name="citations">6. Citations</a></h1>
<table class="docutils footnote" frame="void" id="id4" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<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.3.6: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
<title>TinyOS 802.15.4 Frames</title>
<meta name="author" content="Jonathan Hui, Philip Levis, and David Moss" />
<style type="text/css">
dd {
margin-bottom: 0.5em }
-/* Uncomment (& remove this text!) to get bold-faced definition list terms
-dt {
- font-weight: bold }
-*/
-
div.abstract {
margin: 2em 5em }
</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" />
</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" id="abstract">
-<h1><a name="abstract">Abstract</a></h1>
+<div class="section">
+<h1><a id="abstract" name="abstract">Abstract</a></h1>
<p>This memo documents the frame format for 802.15.4 packets in TinyOS
2.0.</p>
</div>
-<div class="section" id="introduction">
-<h1><a name="introduction">1. Introduction</a></h1>
+<div class="section">
+<h1><a id="introduction" name="introduction">1. Introduction</a></h1>
<p>802.15.4 is a data-link and physical packet format for
low-power wireless networks that is used in many TinyOS platforms.
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" id="id1">
-<h1><a name="id1">2. 802.15.4</a></h1>
+<div class="section">
+<h1><a id="id1" name="id1">2. 802.15.4</a></h1>
<p>802.15.4 supports several different source and destination addressing
modes, and so has a variable sized packet header.[2]_ A TinyOS device MUST
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" id="frame-format">
-<h1><a name="frame-format">3. Frame Format</a></h1>
+<div class="section">
+<h1><a id="frame-format" name="frame-format">3. Frame Format</a></h1>
<p>TinyOS has two 802.15.4 frame formats. The first format, the T-Frame, is
for TinyOS networks which do not share their channel with other wireless
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" id="implementation">
-<h1><a name="implementation">4. Implementation</a></h1>
+<div class="section">
+<h1><a id="implementation" name="implementation">4. Implementation</a></h1>
<p>An implementation of the T-Frame can be found in tinyos-2.x/tos/chips/cc2420.</p>
-<p>An implementation of the I-Frame will soon be found in
+<p>An implementation of the I-Frame will soon be found in
tinyos-2.x/tos/chips/cc2420.</p>
</div>
-<div class="section" id="author-addresses">
-<h1><a name="author-addresses">5. Author Addresses</a></h1>
+<div class="section">
+<h1><a id="author-addresses" 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.3.6: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.4: 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">
dd {
margin-bottom: 0.5em }
-/* Uncomment (& remove this text!) to get bold-faced definition list terms
-dt {
- font-weight: bold }
-*/
-
div.abstract {
margin: 2em 5em }
</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.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">2007-04-20</td>
+<tr class="field"><th class="docinfo-name">Draft-Modified:</th><td class="field-body">2007-06-14</td>
</tr>
<tr class="field"><th class="docinfo-name">Draft-Discuss:</th><td class="field-body">TinyOS Developer List <tinyos-devel at mail.millennium.berkeley.edu></td>
</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" id="abstract">
-<h1><a name="abstract">Abstract</a></h1>
+<div class="section">
+<h1><a id="abstract" 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 stack can help guide development
+the construction of the stack can help guide development
of future TinyOS radio stacks.</p>
</div>
-<div class="section" id="introduction">
-<h1><a name="introduction">1. Introduction</a></h1>
+<div class="section">
+<h1><a id="introduction" 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
+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="#id13" id="id1" name="id1">[1]</a>.</p>
+These details can be found in the CC2420 datasheet <a class="footnote-reference" href="#id11" id="id1" name="id1">[1]</a>.</p>
</div>
-<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
+<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
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>
<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" id="layer-descriptions">
-<h2><a name="layer-descriptions">2.1 Layer Descriptions</a></h2>
+<div class="section">
+<h2><a id="layer-descriptions" 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
+<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="#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
+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.</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
+<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>
+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>.</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
+acknowledgement was heard from the receiver. PacketLink is
activated on a per-message basis, meaning the outgoing packet will
not use PacketLink unless it is configured ahead of time to do so.
-PacketLink is most reliable when software acknowledgements are enabled
+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
+<li><p class="first">CC2420AckLplP / CC2420NoAckLplP <a class="footnote-reference" href="#id14" 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
+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
and DSN byte of the past few packets it has received, and helps
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
+<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="#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.</p>
</li>
<li><p class="first">CsmaC: This layer is responsible for defining 802.15.4 FCF
</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%" />
</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%" />
</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%" />
</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%" />
</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%" />
</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>
-</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%" />
</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%" />
</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%" />
</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>
+<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>
<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_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="#id17" id="id9" name="id9">[5]</a> only to be included when the
-6LowPAN TinyosNetwork layer is included. 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="#id15" id="id7" name="id7">[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 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>
+<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="#id12" id="id8" name="id8">[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
+<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
(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,
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
+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>
+<div class="section">
+<h2><a id="radio-backoff" 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" 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>
+<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>
<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 PacketLink interfaces
to determine if a packet was successfully acknowledged.</p>
</div>
-<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>
+<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>
<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="#id15" id="id11" name="id11">[3]</a>.</p>
-<p>The UniqueSend interface at the top of the CC2420 radio stack is
+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. Upon boot, an initial DSN
-byte is generated using a pseudo-random number generator with a
+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
+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>
-<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
+<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
+runs out, UniqueReceive uses a best effort method to avoid replacing
recently updated DSN/Source information entries.</p>
</div>
</div>
-<div class="section" id="packetlink-implementation">
-<h1><a name="packetlink-implementation">6. PacketLink Implementation</a></h1>
+<div class="section">
+<h1><a id="packetlink-implementation" 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
+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 PacketLink layer helps to remove the reliable delivery
responsibility and functional baggage from application layers.</p>
-<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>
+<div class="section">
+<h2><a id="compiling-in-the-packetlink-layer" 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 PACKET_LINK to compile the functionality
of the PacketLink layer in with the CC2420 stack.</p>
</div>
-<div class="section" id="implementation-and-usage">
-<h2><a name="implementation-and-usage">6.2 Implementation and Usage</a></h2>
+<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 PacketLink, the PacketLink
interface must be called ahead of time to specify two fields in the outbound
message's metadata::</p>
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 PacketLink relies on acknowledgements, false acknowledgements
+<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" id="asynchronous-low-power-listening-implementation">
-<h1><a name="asynchronous-low-power-listening-implementation">7. Asynchronous Low Power Listening Implementation</a></h1>
+<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>
<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" id="design-considerations">
-<h2><a name="design-considerations">7.1 Design Considerations</a></h2>
+<div class="section">
+<h2><a id="design-considerations" 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">
</tbody>
</table>
</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
+<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" id="minimizing-power-consumption">
-<h2><a name="minimizing-power-consumption">7.2 Minimizing Power Consumption</a></h2>
+<div class="section">
+<h2><a id="minimizing-power-consumption" 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>
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
+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
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
+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
+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,
+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
+continuously, with the goal of turning the radio off as quickly as
possible without interruption.</blockquote>
</div>
</div>
-<div class="section" id="cc2420-settings-and-registers">
-<h1><a name="cc2420-settings-and-registers">8. CC2420 Settings and Registers</a></h1>
+<div class="section">
+<h1><a id="cc2420-settings-and-registers" 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
+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="#id13" id="id12" name="id12">[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="#id11" id="id10" name="id10">[1]</a>.</p>
</div>
-<div class="section" id="cross-platform-portability">
-<h1><a name="cross-platform-portability">9. Cross-platform Portability</a></h1>
+<div class="section">
+<h1><a id="cross-platform-portability" 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" id="future-improvement-recommendations">
-<h1><a name="future-improvement-recommendations">10. Future Improvement Recommendations</a></h1>
+<div class="section">
+<h1><a id="future-improvement-recommendations" 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" id="aes-encryption">
-<h2><a name="aes-encryption">10.1 AES Encryption</a></h2>
+<div class="section">
+<h2><a id="aes-encryption" 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" id="authentication">
-<h2><a name="authentication">10.2 Authentication</a></h2>
-<p>In many cases, authentication is more desirable than encryption.
+<div class="section">
+<h2><a id="authentication" 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" 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
+<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
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" id="neighbor-tables">
-<h2><a name="neighbor-tables">10.4 Neighbor Tables</a></h2>
+<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
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
CC2420 radio stack, RAM can be conserved throughout the radio stack
and TinyOS applications.</p>
</div>
-<div class="section" id="radio-independant-layers">
-<h2><a name="radio-independant-layers">10.5 Radio Independant Layers</a></h2>
+<div class="section">
+<h2><a id="radio-independant-layers" 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
+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
layers and radio-independant layers, and operates with the same
behavior across any radio chip.</p>
</div>
-<div class="section" id="extendable-metadata">
-<h2><a name="extendable-metadata">10.6 Extendable Metadata</a></h2>
+<div class="section">
+<h2><a id="extendable-metadata" name="extendable-metadata">10.6 Extendable Metadata</a></h2>
<p>Layers added into the radio stack may require extra bytes of metadata.
The PacketLink layer, for example, requires two extra fields
in each message's metadata to hold the message's max retries and
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" id="error-correcting-codes-ecc">
-<h2><a name="error-correcting-codes-ecc">10.7 Error Correcting Codes (ECC)</a></h2>
+<div class="section">
+<h2><a id="error-correcting-codes-ecc" 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" id="author-s-address">
-<h1><a name="author-s-address">11. Author's Address</a></h1>
+<div class="section">
+<h1><a id="author-s-address" 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" id="citations">
-<h1><a name="citations">12. Citations</a></h1>
-<table class="docutils footnote" frame="void" id="id13" rules="none">
+<div class="section">
+<h1><a id="citations" name="citations">12. Citations</a></h1>
+<table class="docutils footnote" frame="void" id="id11" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
-<tr><td class="label"><a name="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>
+<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>
</tbody>
</table>
-<table class="docutils footnote" frame="void" id="id14" rules="none">
+<table class="docutils footnote" frame="void" id="id12" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
-<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>
+<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>
</tbody>
</table>
-<table class="docutils footnote" frame="void" id="id15" rules="none">
+<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
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>
+<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>
</tbody>
</table>
-<table class="docutils footnote" frame="void" id="id16" 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 class="fn-backref" href="#id5" name="id16">[4]</a></td><td>TEP105: Low Power Listening</td></tr>
+<tr><td class="label"><a class="fn-backref" href="#id5" name="id14">[4]</a></td><td>TEP105: Low Power Listening</td></tr>
</tbody>
</table>
-<table class="docutils footnote" frame="void" id="id17" 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="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>
+<tr><td class="label"><a name="id15">[5]</a></td><td><em>(<a class="fn-backref" href="#id6">1</a>, <a class="fn-backref" href="#id7">2</a>)</em> TEP125: TinyOS 802.15.4 Frames</td></tr>
</tbody>
</table>
</div>
--- /dev/null
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
+<title>Packet Link Layer</title>
+<meta name="author" content="David Moss, Philip Levis" />
+<style type="text/css">
+
+/*
+:Author: David Goodger
+:Contact: goodger@users.sourceforge.net
+:date: $Date$
+:version: $Revision$
+:copyright: This stylesheet has been placed in the public domain.
+
+Default cascading style sheet for the HTML output of Docutils.
+*/
+body {
+ font-family: Times;
+ font-size: 16px;
+}
+
+.first {
+ margin-top: 0 ! important }
+
+.last {
+ margin-bottom: 0 ! important }
+
+.hidden {
+ display: none }
+
+a.toc-backref {
+ text-decoration: none ;
+ color: black }
+
+blockquote.epigraph {
+ margin: 2em 5em ; }
+
+dd {
+ margin-bottom: 0.5em }
+
+div.abstract {
+ margin: 2em 5em }
+
+div.abstract p.topic-title {
+ font-weight: bold ;
+ text-align: center }
+
+div.attention, div.caution, div.danger, div.error, div.hint,
+div.important, div.note, div.tip, div.warning, div.admonition {
+ margin: 2em ;
+ border: medium outset ;
+ padding: 1em }
+
+div.attention p.admonition-title, div.caution p.admonition-title,
+div.danger p.admonition-title, div.error p.admonition-title,
+div.warning p.admonition-title {
+ color: red ;
+ font-weight: bold ;
+ font-family: sans-serif }
+
+div.hint p.admonition-title, div.important p.admonition-title,
+div.note p.admonition-title, div.tip p.admonition-title,
+div.admonition p.admonition-title {
+ font-weight: bold ;
+ font-family: sans-serif }
+
+div.dedication {
+ margin: 2em 5em ;
+ text-align: center ;
+ font-style: italic }
+
+div.dedication p.topic-title {
+ font-weight: bold ;
+ font-style: normal }
+
+div.figure {
+ margin-left: 2em }
+
+div.footer, div.header {
+ font-size: smaller }
+
+div.line-block {
+ display: block ;
+ margin-top: 1em ;
+ margin-bottom: 1em }
+
+div.line-block div.line-block {
+ margin-top: 0 ;
+ margin-bottom: 0 ;
+ margin-left: 1.5em }
+
+div.sidebar {
+ margin-left: 1em ;
+ border: medium outset ;
+ padding: 0em 1em ;
+ background-color: #ffffee ;
+ width: 40% ;
+ float: right ;
+ clear: right }
+
+div.sidebar p.rubric {
+ font-family: sans-serif ;
+ font-size: medium }
+
+div.system-messages {
+ margin: 5em }
+
+div.system-messages h1 {
+ color: red }
+
+div.system-message {
+ border: medium outset ;
+ padding: 1em }
+
+div.system-message p.system-message-title {
+ color: red ;
+ font-weight: bold }
+
+div.topic {
+ margin: 2em }
+
+h1 {
+ font-family: Arial, sans-serif;
+ font-size: 20px;
+}
+
+h1.title {
+ text-align: center;
+ font-size: 32px;
+}
+
+h2 {
+ font-size: 16px;
+ font-family: Arial, sans-serif;
+}
+
+h2.subtitle {
+ text-align: center }
+
+h3 {
+ font-size: 12px;
+ font-family: Arial, sans-serif;
+}
+
+hr {
+ width: 75% }
+
+ol.simple, ul.simple {
+ margin-bottom: 1em }
+
+ol.arabic {
+ list-style: decimal }
+
+ol.loweralpha {
+ list-style: lower-alpha }
+
+ol.upperalpha {
+ list-style: upper-alpha }
+
+ol.lowerroman {
+ list-style: lower-roman }
+
+ol.upperroman {
+ list-style: upper-roman }
+
+p.attribution {
+ text-align: right ;
+ margin-left: 50% }
+
+p.caption {
+ font-style: italic }
+
+p.credits {
+ font-style: italic ;
+ font-size: smaller }
+
+p.label {
+ white-space: nowrap }
+
+p.rubric {
+ font-weight: bold ;
+ font-size: larger ;
+ color: maroon ;
+ text-align: center }
+
+p.sidebar-title {
+ font-family: sans-serif ;
+ font-weight: bold ;
+ font-size: larger }
+
+p.sidebar-subtitle {
+ font-family: sans-serif ;
+ font-weight: bold }
+
+p.topic-title {
+ font-weight: bold }
+
+pre.address {
+ margin-bottom: 0 ;
+ margin-top: 0 ;
+ font-family: serif ;
+ font-size: 100% }
+
+pre.line-block {
+ font-family: serif ;
+ font-size: 100% }
+
+pre.literal-block, pre.doctest-block {
+ margin-left: 2em ;
+ margin-right: 2em ;
+ background-color: #eeeeee;
+ border-color: #000000;
+ border-width: thin;
+ font-size: 14px
+}
+
+span.classifier {
+ font-family: sans-serif ;
+ font-style: oblique }
+
+span.classifier-delimiter {
+ font-family: sans-serif ;
+ font-weight: bold }
+
+span.interpreted {
+ font-family: sans-serif }
+
+span.option {
+ white-space: nowrap }
+
+span.option-argument {
+ font-style: italic }
+
+span.pre {
+ white-space: pre }
+
+span.problematic {
+ color: red }
+
+table {
+ margin-top: 0.5em ;
+ margin-bottom: 0.5em }
+
+table.citation {
+ border-left: solid thin gray ;
+ padding-left: 0.5ex }
+
+table.docinfo {
+ margin: 2em 4em;
+}
+
+table.footnote {
+ border-left: solid thin black ;
+ padding-left: 0.5ex }
+
+td, th {
+ padding-left: 0.5em ;
+ padding-right: 0.5em ;
+ vertical-align: top }
+
+th.docinfo-name, th.field-name {
+ font-weight: bold ;
+ text-align: left ;
+ white-space: nowrap;
+ }
+
+h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt {
+ font-size: 100% }
+
+tt {}
+
+ul.auto-toc {
+ list-style-type: none }
+
+</style>
+</head>
+<body>
+<div class="document" id="packet-link-layer">
+<h1 class="title">Packet Link Layer</h1>
+<table class="docinfo" frame="void" rules="none">
+<col class="docinfo-name" />
+<col class="docinfo-content" />
+<tbody valign="top">
+<tr class="field"><th class="docinfo-name">TEP:</th><td class="field-body">127</td>
+</tr>
+<tr class="field"><th class="docinfo-name">Group:</th><td class="field-body">Core Working Group</td>
+</tr>
+<tr class="field"><th class="docinfo-name">Type:</th><td class="field-body">Documentary</td>
+</tr>
+<tr><th class="docinfo-name">Status:</th>
+<td>Draft</td></tr>
+<tr class="field"><th class="docinfo-name">TinyOS-Version:</th><td class="field-body">2.x</td>
+</tr>
+<tr><th class="docinfo-name">Author:</th>
+<td>David Moss, Philip Levis</td></tr>
+</tbody>
+</table>
+<div class="note">
+<p class="first admonition-title">Note</p>
+<p class="last">This memo documents a part of TinyOS for the TinyOS Community, and
+requests discussion and suggestions for improvements. Distribution
+of this memo is unlimited. This memo is in full compliance with
+TEP 1.</p>
+</div>
+<div class="section">
+<h1><a id="abstract" name="abstract">Abstract</a></h1>
+<p>This TEP describes the behavior and interfaces of the TinyOS 2.x
+Packet Link Layer. The Packet Link Layer is an optional radio stack
+layer responsible for the reliable delivery of a packet from node to
+node. Packet Link provides error correction functionality found in
+Layer 2 of the OSI model <a class="footnote-reference" href="#id2" id="id1" name="id1">[1]</a>.</p>
+</div>
+<div class="section">
+<h1><a id="introduction" name="introduction">1. Introduction</a></h1>
+<p>In wireless networks, packets are regularly dropped between point to point
+communications due to interference or RF range. Correcting these dropped
+packets requires the transmitter to first recognize that the packet was
+not acknowledged, and then retransmit that packet.</p>
+<p>Retransmitting the packet adds its own set of issues. Specifically, the
+receiver will receive duplicate packets due to its own dropped acknowledgements.
+Logic is therefore required to allow receiver to recognize and dump duplicate
+packets, but only after the acknowledgement has been sent back to the
+transmitter.</p>
+<p>With these two pieces of functionality: the ability for a transmitter to
+keep retrying until it gets an acknowledgement and the ability
+for a receiver to accept only a single copy of the packet, a Packet Link Layer
+can be formed to reliably deliver a single packet from point to point.</p>
+</div>
+<div class="section">
+<h1><a id="design-considerations" name="design-considerations">2. Design Considerations</a></h1>
+<div class="section">
+<h2><a id="time-spent-retrying-a-delivery" name="time-spent-retrying-a-delivery">2.1 Time spent retrying a delivery</a></h2>
+<p>Some networks have different timing characteristics than others.
+Consider a person carrying a wireless device while walking in and out
+of RF range of another node. In this case, the device may want to
+retry the transmission a few times over the course of a few seconds before
+declaring the delivery unsuccessful. A robust Packet Link Layer should
+allow the developer to specify the amount of time spent retrying as well
+as the number of retries to send.</p>
+</div>
+<div class="section">
+<h2><a id="setting-the-packet-sequence-number" name="setting-the-packet-sequence-number">2.2 Setting the packet sequence number</a></h2>
+<p>To detect duplicate packets, a sequence number byte can be used
+within the packet to verify against previously received
+packets. If the source address and sequence number of a newly received
+packet matches that of a previously received packet, then the newly received
+packet is a duplicate and may be dumped. To prevent the packet sequence
+number byte from changing on each retransmission, the byte should be set
+at or above the Packet Link Layer and never changed below.</p>
+</div>
+<div class="section">
+<h2><a id="false-acknowledgements" name="false-acknowledgements">2.3 False Acknowledgements</a></h2>
+<p>The low levels of a radio stack or the radio chip itself are typically
+responsible for generating packet acknowledgements. It has been
+observed in some platforms that the radio chip will generate false
+auto-acknowledgements. This occurs when the radio receives the packet and
+sends an acknowledgement but the microcontroller never gets the message
+due to some error. In this case, the transmitter would believe the
+packet got to the destination successfully but the receiver would have
+no knowledge that a packet was received. Software initiated
+acknowledgements prevent this issue by removing the possibility of
+false acknowledgements.</p>
+</div>
+</div>
+<div class="section">
+<h1><a id="interface" name="interface">3. Interface</a></h1>
+<div class="section">
+<h2><a id="packetlink-interface" name="packetlink-interface">3.1 PacketLink Interface</a></h2>
+<p>The TEP proposes this PacketLink interface::</p>
+<pre class="literal-block">
+interface PacketLink {
+ command void setRetries(message_t *msg, uint16_t maxRetries);
+ command void setRetryDelay(message_t *msg, uint16_t retryDelay);
+ command uint16_t getRetries(message_t *msg);
+ command uint16_t getRetryDelay(message_t *msg);
+ command bool wasDelivered(message_t *msg);
+}
+</pre>
+<p>PacketLinks interface functions:</p>
+<blockquote>
+<tt class="docutils literal"><span class="pre">setRetries(message_t</span> <span class="pre">*msg,</span> <span class="pre">uint16_t</span> <span class="pre">maxRetries)</span></tt></blockquote>
+<ul>
+<li><p class="first">Sets the maximum number of times to retry the transmission of the message</p>
+<p><tt class="docutils literal"><span class="pre">setRetryDelay(message_t</span> <span class="pre">*msg,</span> <span class="pre">uint16_t</span> <span class="pre">retryDelay)</span></tt></p>
+</li>
+<li><p class="first">Set the delay, in milliseconds, between each retransmission</p>
+<p><tt class="docutils literal"><span class="pre">getRetries(message_t</span> <span class="pre">*msg)</span></tt></p>
+</li>
+<li><p class="first">Returns the maximum number of retries configured for the given message</p>
+<p><tt class="docutils literal"><span class="pre">getRetryDelay(message_t</span> <span class="pre">*msg)</span></tt></p>
+</li>
+<li><p class="first">Returns the delay, in milliseconds, between each retransmission for the given
+message</p>
+<p><tt class="docutils literal"><span class="pre">wasDelivered(message_t</span> <span class="pre">*msg)</span></tt></p>
+</li>
+<li><p class="first">This command may be called after the sendDone() event is signaled. It is the
+equivalent of <tt class="docutils literal"><span class="pre">PacketAcknowledgements.wasAcked(message_t</span> <span class="pre">*msg)</span></tt>, so is only
+a helper function to make the PacketLink interface easier to use.</p>
+</li>
+</ul>
+</div>
+<div class="section">
+<h2><a id="expected-behavior" name="expected-behavior">3.2 Expected Behavior</a></h2>
+<p>The PacketLink interface is accessed by the application layer before
+the packet is passed to the radio stack for transmission. The application
+layer will call setRetries(...) and setRetryDelay(...), passing in the
+message it is about to send.</p>
+<p>The interface MUST configure metadata for the packet to specify the maximum
+number of retries and the amount of delay between each retry. When the
+send process reaches the Packet Link Layer, it MUST automatically check the
+packet's metadata and retry sending the packet as previously configured.</p>
+<p>For example, to configure a packet to be retried a maximum of 50 times
+over the next 5 seconds, the developer would execute the following commands
+before sending the packet::</p>
+<pre class="literal-block">
+call PacketLink.setRetries(msg, 50);
+call PacketLink.setRetryDelay(msg, 100);
+</pre>
+<p>By placing a 100 ms delay between each retry and allowing up to 50 retries
+maximum, the maximum amount of time the message will be transmitted is
+(50 * 100) ms, or 5000 ms.</p>
+<p>When transmitting a packet configured for reliable delivery to the
+broadcast address, the Packet Link Layer SHOULD allow the packet to be
+retried. This will let the transmitter know that at least one node
+received the message.</p>
+</div>
+</div>
+<div class="section">
+<h1><a id="author-s-address" name="author-s-address">4. Author's Address</a></h1>
+<div class="line-block">
+<div class="line">David Moss</div>
+<div class="line">Rincon Research Corporation</div>
+<div class="line">101 N. Wilmot, Suite 101</div>
+<div class="line">Tucson, AZ 85750</div>
+<div class="line"><br /></div>
+<div class="line">phone - +1 520 519 3138</div>
+<div class="line">email ? <a class="reference" href="mailto:dmm@rincon.com">dmm@rincon.com</a></div>
+<div class="line"><br /></div>
+<div class="line"><br /></div>
+<div class="line">Philip Levis</div>
+<div class="line">358 Gates Hall</div>
+<div class="line">Stanford University</div>
+<div class="line">Stanford, CA 94305-9030</div>
+<div class="line"><br /></div>
+<div class="line">phone - +1 650 725 9046</div>
+<div class="line">email - <a class="reference" href="mailto:pal@cs.stanford.edu">pal@cs.stanford.edu</a></div>
+<div class="line"><br /></div>
+</div>
+</div>
+<div class="section">
+<h1><a id="citations" name="citations">5. Citations</a></h1>
+<table class="docutils footnote" frame="void" id="id2" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id1" name="id2">[1]</a></td><td>"OSI model" <a class="reference" href="http://en.wikipedia.org/wiki/OSI_model">http://en.wikipedia.org/wiki/OSI_model</a></td></tr>
+</tbody>
+</table>
+</div>
+</div>
+</body>
+</html>
--- /dev/null
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
+<title>Platform Independent Non-Volatile Storage Abstractions</title>
+<meta name="authors" content="David Moss Junzhao Du Prabal Dutta Deepak Ganesan Kevin Klues Manju Ajay Martin and Gaurav Mathur" />
+<style type="text/css">
+
+/*
+:Author: David Goodger
+:Contact: goodger@users.sourceforge.net
+:date: $Date$
+:version: $Revision$
+:copyright: This stylesheet has been placed in the public domain.
+
+Default cascading style sheet for the HTML output of Docutils.
+*/
+body {
+ font-family: Times;
+ font-size: 16px;
+}
+
+.first {
+ margin-top: 0 ! important }
+
+.last {
+ margin-bottom: 0 ! important }
+
+.hidden {
+ display: none }
+
+a.toc-backref {
+ text-decoration: none ;
+ color: black }
+
+blockquote.epigraph {
+ margin: 2em 5em ; }
+
+dd {
+ margin-bottom: 0.5em }
+
+div.abstract {
+ margin: 2em 5em }
+
+div.abstract p.topic-title {
+ font-weight: bold ;
+ text-align: center }
+
+div.attention, div.caution, div.danger, div.error, div.hint,
+div.important, div.note, div.tip, div.warning, div.admonition {
+ margin: 2em ;
+ border: medium outset ;
+ padding: 1em }
+
+div.attention p.admonition-title, div.caution p.admonition-title,
+div.danger p.admonition-title, div.error p.admonition-title,
+div.warning p.admonition-title {
+ color: red ;
+ font-weight: bold ;
+ font-family: sans-serif }
+
+div.hint p.admonition-title, div.important p.admonition-title,
+div.note p.admonition-title, div.tip p.admonition-title,
+div.admonition p.admonition-title {
+ font-weight: bold ;
+ font-family: sans-serif }
+
+div.dedication {
+ margin: 2em 5em ;
+ text-align: center ;
+ font-style: italic }
+
+div.dedication p.topic-title {
+ font-weight: bold ;
+ font-style: normal }
+
+div.figure {
+ margin-left: 2em }
+
+div.footer, div.header {
+ font-size: smaller }
+
+div.line-block {
+ display: block ;
+ margin-top: 1em ;
+ margin-bottom: 1em }
+
+div.line-block div.line-block {
+ margin-top: 0 ;
+ margin-bottom: 0 ;
+ margin-left: 1.5em }
+
+div.sidebar {
+ margin-left: 1em ;
+ border: medium outset ;
+ padding: 0em 1em ;
+ background-color: #ffffee ;
+ width: 40% ;
+ float: right ;
+ clear: right }
+
+div.sidebar p.rubric {
+ font-family: sans-serif ;
+ font-size: medium }
+
+div.system-messages {
+ margin: 5em }
+
+div.system-messages h1 {
+ color: red }
+
+div.system-message {
+ border: medium outset ;
+ padding: 1em }
+
+div.system-message p.system-message-title {
+ color: red ;
+ font-weight: bold }
+
+div.topic {
+ margin: 2em }
+
+h1 {
+ font-family: Arial, sans-serif;
+ font-size: 20px;
+}
+
+h1.title {
+ text-align: center;
+ font-size: 32px;
+}
+
+h2 {
+ font-size: 16px;
+ font-family: Arial, sans-serif;
+}
+
+h2.subtitle {
+ text-align: center }
+
+h3 {
+ font-size: 12px;
+ font-family: Arial, sans-serif;
+}
+
+hr {
+ width: 75% }
+
+ol.simple, ul.simple {
+ margin-bottom: 1em }
+
+ol.arabic {
+ list-style: decimal }
+
+ol.loweralpha {
+ list-style: lower-alpha }
+
+ol.upperalpha {
+ list-style: upper-alpha }
+
+ol.lowerroman {
+ list-style: lower-roman }
+
+ol.upperroman {
+ list-style: upper-roman }
+
+p.attribution {
+ text-align: right ;
+ margin-left: 50% }
+
+p.caption {
+ font-style: italic }
+
+p.credits {
+ font-style: italic ;
+ font-size: smaller }
+
+p.label {
+ white-space: nowrap }
+
+p.rubric {
+ font-weight: bold ;
+ font-size: larger ;
+ color: maroon ;
+ text-align: center }
+
+p.sidebar-title {
+ font-family: sans-serif ;
+ font-weight: bold ;
+ font-size: larger }
+
+p.sidebar-subtitle {
+ font-family: sans-serif ;
+ font-weight: bold }
+
+p.topic-title {
+ font-weight: bold }
+
+pre.address {
+ margin-bottom: 0 ;
+ margin-top: 0 ;
+ font-family: serif ;
+ font-size: 100% }
+
+pre.line-block {
+ font-family: serif ;
+ font-size: 100% }
+
+pre.literal-block, pre.doctest-block {
+ margin-left: 2em ;
+ margin-right: 2em ;
+ background-color: #eeeeee;
+ border-color: #000000;
+ border-width: thin;
+ font-size: 14px
+}
+
+span.classifier {
+ font-family: sans-serif ;
+ font-style: oblique }
+
+span.classifier-delimiter {
+ font-family: sans-serif ;
+ font-weight: bold }
+
+span.interpreted {
+ font-family: sans-serif }
+
+span.option {
+ white-space: nowrap }
+
+span.option-argument {
+ font-style: italic }
+
+span.pre {
+ white-space: pre }
+
+span.problematic {
+ color: red }
+
+table {
+ margin-top: 0.5em ;
+ margin-bottom: 0.5em }
+
+table.citation {
+ border-left: solid thin gray ;
+ padding-left: 0.5ex }
+
+table.docinfo {
+ margin: 2em 4em;
+}
+
+table.footnote {
+ border-left: solid thin black ;
+ padding-left: 0.5ex }
+
+td, th {
+ padding-left: 0.5em ;
+ padding-right: 0.5em ;
+ vertical-align: top }
+
+th.docinfo-name, th.field-name {
+ font-weight: bold ;
+ text-align: left ;
+ white-space: nowrap;
+ }
+
+h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt {
+ font-size: 100% }
+
+tt {}
+
+ul.auto-toc {
+ list-style-type: none }
+
+</style>
+</head>
+<body>
+<div class="document" id="platform-independent-non-volatile-storage-abstractions">
+<h1 class="title">Platform Independent Non-Volatile Storage Abstractions</h1>
+<table class="docinfo" frame="void" rules="none">
+<col class="docinfo-name" />
+<col class="docinfo-content" />
+<tbody valign="top">
+<tr class="field"><th class="docinfo-name">TEP:</th><td class="field-body">128</td>
+</tr>
+<tr class="field"><th class="docinfo-name">Group:</th><td class="field-body">Storage Working Group</td>
+</tr>
+<tr class="field"><th class="docinfo-name">Type:</th><td class="field-body">Documentary</td>
+</tr>
+<tr><th class="docinfo-name">Status:</th>
+<td>DRAFT</td></tr>
+<tr class="field"><th class="docinfo-name">TinyOS-Version:</th><td class="field-body">2.x</td>
+</tr>
+<tr><th class="docinfo-name">Authors:</th>
+<td>David Moss
+<br />Junzhao Du
+<br />Prabal Dutta
+<br />Deepak Ganesan
+<br />Kevin Klues
+<br />Manju
+<br />Ajay Martin
+<br />and Gaurav Mathur</td></tr>
+</tbody>
+</table>
+<div class="note">
+<p class="first admonition-title">Note</p>
+<p class="last">This memo documents a part of TinyOS for the TinyOS Community, and
+requests discussion and suggestions for improvements. Distribution
+of this memo is unlimited. This memo is in full compliance with
+TEP 1.</p>
+</div>
+<div class="section">
+<h1><a id="abstract" name="abstract">Abstract</a></h1>
+<p>The storage abstractions proposed by TEP 103 are implemented on a
+platform-dependent basis. A version of BlockStorage, ConfigStorage,
+and LogStorage were created from the ground up for both the
+AT45DB and ST M25P80 flash chips. Looking forward into the further
+growth and development of hardware, rebuilding each of these storage
+layers for every new flash chip will be time consuming and cause
+compatibility issues.</p>
+<p>We propose a layer of abstraction to reside between a chip-dependent
+flash chip implementation and platform-independent storage
+implementations. This abstraction layer should provide methods
+to perform basic flash operations (read, write, erase, flush, crc),
+as well as provide information about the physical properties of the
+flash chip. Efficiency concerns are mitigated by the fact that each
+platform-independent abstraction is implemented in a platform-dependent
+manner, allowing it to exist on different types of memory such as
+NAND flash, NOR flash, and EEPROM. This abstraction layer should
+allow one implementation of each storage solution to operate across
+many different platforms.</p>
+</div>
+<div class="section">
+<h1><a id="introduction" name="introduction">1. Introduction</a></h1>
+<p>The implementations of the BlockStorage, ConfigStorage, and LogStorage
+layers described in TEP 103 [1] are platform dependent. Platform-
+dependent implementations can cause behavioral and usage differences
+as well as compiling problems when attempting to port an application
+written on one platform to another. A true abstraction layer would
+exhibit the same set of interfaces and no differences in behavior when
+implemented across various types of non-volatile memory.</p>
+<p>A well defined non-volatile memory abstraction layer should allow core
+functionality to work on a variety of platforms without modification.
+Some flash chips may provide extra functionality. If a particular
+applications on a specific platform wants to take advantage of
+extra functionality provided by a flash chip, it still has the opportunity
+to access those features directly with the understanding that its
+implementation is no longer considered platform-independent.</p>
+<div class="section">
+<h2><a id="platform-dependent-volume-settings" name="platform-dependent-volume-settings">1.1 Platform-dependent volume settings</a></h2>
+<p>Differences exist between the TEP 103 storage implementations
+on the AT45DB, ST M25P80, and PXA27X P30 flash chips.</p>
+<p>First, volume information is defined using two distinct methods. As
+was discussed in TEP 103, an XML file is responsible for the
+allocation of flash memory into volumes at compile time. Individual
+storage layers can then mount to the defined volumes, which
+allows those layers to share the flash memory resource amongst
+each other.</p>
+<p>The AT45DB implementation running on mica* platforms converts the
+information presented in the application's volumes XML file into
+information accessible through macros::</p>
+<pre class="literal-block">
+#ifndef STORAGE_VOLUMES_H
+#define STORAGE_VOLUMES_H
+
+enum {
+ VOLUME_BLOCKTEST,
+};
+
+#endif
+#if defined(VS)
+VS(VOLUME_BLOCKTEST, 1024)
+#undef VS
+#endif
+#if defined(VB)
+VB(VOLUME_BLOCKTEST, 0)
+#undef VB
+#endif
+</pre>
+<p>The ST M25P80 implementation running on TelosB/Tmote platforms,
+on the other hand, converts the information in the volumes XML
+file into an array of constants::</p>
+<pre class="literal-block">
+#ifndef __STORAGE_VOLUME_H__
+#define __STORAGE_VOLUME_H__
+
+#include "Stm25p.h"
+
+#define VOLUME_BLOCKTEST 0
+
+static const stm25p_volume_info_t STM25P_VMAP[ 1 ] = {
+ { base : 0, size : 4 },
+};
+
+#endif
+</pre>
+<p>Furthermore, the two implementations defined incompatible interfaces for
+accessing information about volumes. For example, the AT45DB interface
+provides the following::</p>
+<pre class="literal-block">
+interface At45dbVolume {
+ command at45page_t remap(at45page_t volumePage);
+ command at45page_t volumeSize();
+}
+</pre>
+<p>The ST M25P80 interface defines a different interface, which allows
+applications to access the volume settings directly through the
+stm25p_volume_info_t array::</p>
+<pre class="literal-block">
+interface Stm25pVolume {
+ async event volume_id_t getVolumeId();
+}
+</pre>
+<p>Accessing volume information is very platform-dependent.
+A single method should be integrated to access volume
+settings and non-volatile memory properties across any platform.</p>
+<p>Another issue exists with the previous concept of volumes. Any storage
+solution that wishes to retain valid data while erasing invalid data
+MUST have access to at least two erase units. Circular logging,
+configuration storage, variable storage, dictionary storage, file
+systems, and more all require a minimum of two erase units to be
+implemented effectively. One erase unit can be used to erase
+all the invalid data while other erase unit(s) retains any valid data.</p>
+<p>Therefore, the minimum allowable volume size should be twice the size
+of a single erase unit to effectively support the majority of
+storage applications. The XML tools that process and allocate
+volumes should prevent a user from defining a volume too small::</p>
+<pre class="literal-block">
++------------+--------+------------+-----------+------------+
+| | AT45DB | ST M25P | PXA27x | K9K1G08R0B |
++------------+--------+------------+-----------+------------+
+| Min.Volume | 512B | 512B-128kB | 128-256kB | 16kB-64kB |
++------------+--------+------------+-----------+------------+
+</pre>
+</div>
+<div class="section">
+<h2><a id="platform-dependent-component-signatures" name="platform-dependent-component-signatures">1.2 Platform-dependent component signatures</a></h2>
+<p>The storage components' signatures differ across implementations.
+For example, the PXA27X P30 flash defines "P30BlockC", "P30ConfigC",
+and "P30LogC" in place of "BlockStorageC", "ConfigStorageC", and
+"LogStorageC". Furthermore, the BlockStorageC configuration in the
+AT45DB implementation takes the following form::</p>
+<pre class="literal-block">
+generic configuration BlockStorageC(volume_id_t volid) {
+ provides {
+ interface BlockWrite;
+ interface BlockRead;
+ }
+}
+</pre>
+<p>while the ST M25P80 implementation adds another interface::</p>
+<pre class="literal-block">
+generic configuration BlockStorageC( volume_id_t volume_id ) {
+ provides interface BlockRead;
+ provides interface BlockWrite;
+ provides interface StorageMap;
+}
+</pre>
+<p>The StorageMap interface on the M25P80 flash chip simply allows
+an application to convert a volume-based virtual address into
+a physical address on flash. Although it is a good idea, it
+is not consistent with other platforms' defined interfaces.</p>
+</div>
+</div>
+<div class="section">
+<h1><a id="directstorage" name="directstorage">2. DirectStorage</a></h1>
+<div class="section">
+<h2><a id="differences-and-advantages" name="differences-and-advantages">3.1 Differences and advantages</a></h2>
+<p>The core current BlockStorage, ConfigStorage, and LogStorage
+layers can all be implemented on a platform-independent abstraction
+layer. Providing an interface that allows direct, unimpeded
+access to the memory below while offering information about
+the properties of that memory is the first step in doing so.</p>
+<p>The DirectStorage interface was created to as part of the answer to this
+issue. DirectStorage resembles the BlockStorage interface in many ways,
+with two significant exceptions:</p>
+<p>1. Erase operation
+BlockStorage's behavior erases the entire volume at a time, which may
+consist of multiple erase units. DirectStorage allows erases to occur
+on per-erase unit basis. Therefore, if only a portion of the volume
+needs to be erased, it can.</p>
+<p>2. Organization
+BlockStorage defines two different interfaces for interacting with the
+flash: BlockRead and BlockWrite. These two interfaces are combined
+into one interface. The getSize() command provided by the BlockRead
+interface is removed and replaced with VolumeSettings, which will be
+discussed later. Also, sync()/syncDone() is replaced with
+flush/flushDone(), which is responsible for writing any data that
+has not already been written to non-volatile memory. Although
+the crc() command can technically exist above BlockStorage as
+well as DirectStorage, it remains in DirectStorage for its ease
+of use.</p>
+<p>Finally, layers should have the ability to be added beneath DirectStorage
+to further optimize and enable memory operation. For example, the
+ST M25P80 flash does not have any on-board RAM buffers, so it
+is up to the microcontroller to buffer and flush out data to write units.
+This functionality may not be desirable on all applications because
+it uses valuable microcontroller resources; therefore, it should
+be removable as layers can be added and removed from radio stack
+architecture.</p>
+<p>Other memory types may require extra support in and underneath
+the hood of DirectStorage as well. NAND flash, for example,
+requires bad block management and error correction. This functionality
+can be implemented without changing the behavior of the DirectStorage
+interface above.</p>
+</div>
+<div class="section">
+<h2><a id="directstorage-interface" name="directstorage-interface">3.2 DirectStorage Interface</a></h2>
+<p>The DirectStorage interface is described below. Each "addr" variable
+is a virtual address, with 0x0 relative to the base address of the
+volume. This base address may actually be physically located
+somewhere else on the non-volatile memory::</p>
+<pre class="literal-block">
+interface DirectStorage {
+
+ command error_t read(uint32_t addr, void *buf, uint32_t len);
+
+ command error_t write(uint32_t addr, void *buf, uint32_t len);
+
+ command error_t erase(uint16_t eraseUnitIndex);
+
+ command error_t flush();
+
+ command error_t crc(uint32_t addr, uint32_t len, uint16_t baseCrc);
+
+
+
+ event void readDone(uint32_t addr, void *buf, uint32_t len, error_t error);
+
+ event void writeDone(uint32_t addr, void *buf, uint32_t len, error_t error);
+
+ event void eraseDone(uint16_t eraseUnitIndex, error_t error);
+
+ event void flushDone(error_t error);
+
+ event void crcDone(uint16_t calculatedCrc, uint32_t addr, uint32_t len, error_t error);
+
+}
+</pre>
+<dl class="docutils">
+<dt><tt class="docutils literal"><span class="pre">read(uint32_t</span> <span class="pre">addr,</span> <span class="pre">void</span> <span class="pre">'*buf',</span> <span class="pre">uint32_t</span> <span class="pre">len);</span></tt></dt>
+<dd><ul class="first last simple">
+<li>Read 'len' bytes into <tt class="docutils literal"><span class="pre">*buf</span></tt> from the given address</li>
+<li>Returns FAIL if the volume is already in use</li>
+<li>Signals readDone(...) when complete.</li>
+</ul>
+</dd>
+<dt><tt class="docutils literal"><span class="pre">write(uint32_t</span> <span class="pre">addr,</span> <span class="pre">void</span> <span class="pre">'*buf',</span> <span class="pre">uint32_t</span> <span class="pre">len);</span></tt></dt>
+<dd><ul class="first last simple">
+<li>Write 'len' bytes from <tt class="docutils literal"><span class="pre">*buf</span></tt> starting at the given address</li>
+<li>Returns FAIL if the volume is already in use</li>
+<li>Signals writeDone(...) when complete.</li>
+</ul>
+</dd>
+<dt><tt class="docutils literal"><span class="pre">erase(uint16_t</span> <span class="pre">eraseUnitIndex);</span></tt></dt>
+<dd><ul class="first last simple">
+<li>Erase a single 0-indexed erase unit</li>
+<li>Returns FAIL if the volume is already in use</li>
+<li>Signals eraseDone(...) when complete.</li>
+</ul>
+</dd>
+<dt>flush()</dt>
+<dd><ul class="first last simple">
+<li>All data that has been previously written and is not yet located on
+non-volatile memory should be immediately stored to non-volatile memory.</li>
+<li>Returns FAIL if the operation cannot be completed at this time</li>
+<li>Signals flushDone(...) when complete.</li>
+</ul>
+</dd>
+<dt>crc(uint32_t addr, uint32_t len, uint16_t baseCrc);</dt>
+<dd><ul class="first last simple">
+<li>Calculate the CRC of 'len' bytes starting at the given address, using
+the given baseCrc as a seed.</li>
+<li>Returns FAIL if the volume is already in use</li>
+<li>Signals crcDone(...) when complete.</li>
+</ul>
+</dd>
+</dl>
+</div>
+<div class="section">
+<h2><a id="directmodify-interface" name="directmodify-interface">3.3 DirectModify Interface</a></h2>
+<p>Some memory types have the ability to modify their contents without
+destroying surrounding data.</p>
+<p>The AT45DB NOR-flash, for example, is able to do this because
+it has built in RAM buffers coupled with small erase unit sizes.
+The physical RAM buffers perform a read-modify-write operation to
+effectively change the contents of flash, allowing it to emulate
+the behavior of an EEPROM with the speed and efficiency of NOR-flash.</p>
+<p>The ATmega128 microcontroller has 4kB of internal EEPROM memory which
+can be directly modified. Also, the MSP430 has 256 bytes of internal
+NOR-flash memory which is divided into two segments of 128 bytes each.
+When implemented properly, this NOR-flash memory can be modified in a
+fault-tolerant manner.</p>
+<p>The ST M25P80 NOR-flash cannot support modification without sacrificing
+significant overhead. It has 16 erase units that are 64kB each,
+which is too large to effectively modify bytes.</p>
+<p>While not all memories support modification, a unified interface
+should exist to interact with memories that do. This interface
+should be access with the understanding that applications built
+on top may not be portable to all memory types. Also, DirectStorage
+and DirectModify are mounted to their own individual volumes, so
+DirectModify cannot share its allocated memory resources with
+a DirectStorage interface::</p>
+<pre class="literal-block">
+interface DirectModify {
+
+ command error_t modify(uint32_t addr, void *buf, uint32_t len);
+
+ command error_t read(uint32_t addr, void *buf, uint32_t len);
+
+ command error_t erase(uint16_t eraseUnitIndex);
+
+ command error_t flush();
+
+ command error_t crc(uint32_t addr, uint32_t len, uint16_t baseCrc);
+
+ command bool isSupported();
+
+
+ event void modified(uint32_t addr, void *buf, uint32_t len, error_t error);
+
+ event void readDone(uint32_t addr, void *buf, uint32_t len, error_t error);
+
+ event void eraseDone(uint16_t eraseUnitIndex, error_t error);
+
+ event void flushDone(error_t error);
+
+ event void crcDone(uint16_t calculatedCrc, uint32_t addr, uint32_t len, error_t error);
+
+}
+</pre>
+<dl class="docutils">
+<dt><tt class="docutils literal"><span class="pre">modify(uint32_t</span> <span class="pre">addr,</span> <span class="pre">void</span> <span class="pre">*buf,</span> <span class="pre">uint32_t</span> <span class="pre">len)</span></tt></dt>
+<dd><ul class="first last simple">
+<li>Modify 'len' bytes located on non-volatile memory at the given address,
+replacing them with data from the given buffer</li>
+<li>Returns FAIL if the volume is already in use</li>
+<li>Signals modified(...) when the operation is complete</li>
+</ul>
+</dd>
+<dt><tt class="docutils literal"><span class="pre">read(uint32_t</span> <span class="pre">addr,</span> <span class="pre">void</span> <span class="pre">*buf,</span> <span class="pre">uint32_t</span> <span class="pre">len)</span></tt></dt>
+<dd><ul class="first last simple">
+<li>Read 'len' bytes into <tt class="docutils literal"><span class="pre">*buf</span></tt> from the given address</li>
+<li>Same as DirectStorage.read(...)</li>
+<li>Returns FAIL if the volume is already in use</li>
+<li>Signals readDone(...) when complete.</li>
+</ul>
+</dd>
+<dt><tt class="docutils literal"><span class="pre">erase(uint16_t</span> <span class="pre">eraseUnitIndex);</span></tt></dt>
+<dd><ul class="first last simple">
+<li>Erase a single 0-indexed erase unit</li>
+<li>Returns FAIL if the volume is already in use</li>
+<li>Signals eraseDone(...) when complete.</li>
+</ul>
+</dd>
+<dt><tt class="docutils literal"><span class="pre">flush()</span></tt></dt>
+<dd><ul class="first last simple">
+<li>All data that has been previously written and is not yet located on
+non-volatile memory should be immediately stored to non-volatile memory.</li>
+<li>Same behavior as flush() methods found in Java</li>
+<li>Returns FAIL if the operation cannot be completed at this time</li>
+<li>Signals flushDone(...) when complete.</li>
+</ul>
+</dd>
+<dt><tt class="docutils literal"><span class="pre">crc(uint32_t</span> <span class="pre">addr,</span> <span class="pre">uint32_t</span> <span class="pre">len,</span> <span class="pre">uint16_t</span> <span class="pre">baseCrc);</span></tt></dt>
+<dd><ul class="first last simple">
+<li>Calculate the CRC of 'len' bytes starting at the given address, using
+the given baseCrc as a seed.</li>
+<li>Returns FAIL if the volume is already in use</li>
+<li>Signals crcDone(...) when complete.</li>
+</ul>
+</dd>
+<dt><tt class="docutils literal"><span class="pre">isSupported()</span></tt></dt>
+<dd><ul class="first last simple">
+<li>Returns TRUE if DirectModify is available on the current memory type</li>
+</ul>
+</dd>
+</dl>
+</div>
+<div class="section">
+<h2><a id="volumesettings-interface" name="volumesettings-interface">3.4 VolumeSettings Interface</a></h2>
+<p>As was shown in Section 1.1, finding information about the current
+volume required platform-dependent methods of access. VolumeSettings
+provides a unified method of accessing information about the underlying
+memory chip and volume settings.</p>
+<p>VolumeSettings MUST be implemented separately for DirectStorage and
+DirectModify, not only because those abstractions will exist on
+separate volumes, but also because the DirectModify interface may
+change the available size of the volume to support certain memory
+types such as NAND- and NOR-flash::</p>
+<pre class="literal-block">
+interface VolumeSettings {
+
+ command uint32_t getVolumeSize();
+
+ command uint32_t getTotalEraseUnits();
+
+ command uint32_t getEraseUnitSize();
+
+ command uint32_t getTotalWriteUnits();
+
+ command uint32_t getWriteUnitSize();
+
+ command uint8_t getFillByte();
+
+ command uint8_t getEraseUnitSizeLog2();
+
+ command uint8_t getWriteUnitSizeLog2();
+
+}
+</pre>
+<dl class="docutils">
+<dt>getVolumeSize()</dt>
+<dd><ul class="first last simple">
+<li>Returns the size of the volume the DirectStorage layer
+is mounted to, in bytes</li>
+</ul>
+</dd>
+<dt>getTotalEraseUnits()</dt>
+<dd><ul class="first last simple">
+<li>Returns the total number of erase units on the mounted volume</li>
+</ul>
+</dd>
+<dt>getEraseUnitSize()</dt>
+<dd><ul class="first last simple">
+<li>Returns the size of an individual erase unit, in bytes</li>
+</ul>
+</dd>
+<dt>getTotalWriteUnits()</dt>
+<dd><ul class="first last simple">
+<li>Returns the total number of write units on the mounted volume</li>
+</ul>
+</dd>
+<dt>getWriteUnitSize()</dt>
+<dd><ul class="first last simple">
+<li>Returns the size of an individual write unit, in bytes</li>
+</ul>
+</dd>
+<dt>getFillByte()</dt>
+<dd><ul class="first last simple">
+<li>Returns the default byte value found on the memory after an erase,
+which is typically 0xFF</li>
+</ul>
+</dd>
+<dt>getEraseUnitSizeLog2()</dt>
+<dd><ul class="first last simple">
+<li>Returns the size of an erase unit in Log2 format for ease of
+calculations</li>
+</ul>
+</dd>
+<dt>getWriteUnitSizeLog2()</dt>
+<dd><ul class="first last simple">
+<li>Returns the size of a write unit in Log2 format for ease of
+calculations</li>
+</ul>
+</dd>
+</dl>
+</div>
+</div>
+<div class="section">
+<h1><a id="author-s-address" name="author-s-address">4. Author's Address</a></h1>
+<div class="line-block">
+<div class="line">David Moss</div>
+<div class="line">Rincon Research Corporation</div>
+<div class="line">101 N. Wilmot, Suite 101</div>
+<div class="line">Tucson, AZ 85750</div>
+<div class="line"><br /></div>
+<div class="line">phone - +1 520 519 3138</div>
+<div class="line">phone - +1 520 519 3146</div>
+<div class="line">email ? <a class="reference" href="mailto:dmm@rincon.com">dmm@rincon.com</a></div>
+<div class="line"><br /></div>
+<div class="line">Junzhao Du</div>
+<div class="line">Contact -</div>
+<div class="line"><br /></div>
+<div class="line">Prabal Dutta</div>
+<div class="line">Contact -</div>
+<div class="line"><br /></div>
+<div class="line">Deepak Ganesan</div>
+<div class="line">Contact -</div>
+<div class="line"><br /></div>
+<div class="line">Kevin Klues</div>
+<div class="line">Contact -</div>
+<div class="line"><br /></div>
+<div class="line">Manju</div>
+<div class="line">Contact -</div>
+<div class="line"><br /></div>
+<div class="line">Ajay Martin</div>
+<div class="line">Contact -</div>
+<div class="line"><br /></div>
+<div class="line">Gaurav Mathur</div>
+<div class="line">Contact -</div>
+</div>
+</div>
+<div class="section">
+<h1><a id="citations" name="citations">5. Citations</a></h1>
+<table class="docutils footnote" frame="void" id="id1" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a name="id1">[1]</a></td><td>TEP 103: Permanent Data Storage (Flash). <a class="reference" href="http://tinyos.cvs.sourceforge.net/">http://tinyos.cvs.sourceforge.net/</a><em>checkout</em>/tinyos/tinyos-2.x/doc/html/tep103.html</td></tr>
+</tbody>
+</table>
+<table class="docutils footnote" frame="void" id="id2" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a name="id2">[2]</a></td><td>Atmel AT45DB041B datasheet. <a class="reference" href="http://www.atmel.com/dyn/resources/prod_documents/DOC1432.PDF">http://www.atmel.com/dyn/resources/prod_documents/DOC1432.PDF</a></td></tr>
+</tbody>
+</table>
+<table class="docutils footnote" frame="void" id="id3" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a name="id3">[3]</a></td><td>ST M25P80 datasheet. <a class="reference" href="http://www.st.com/stonline/products/literature/ds/8495/m25p80.pdf">http://www.st.com/stonline/products/literature/ds/8495/m25p80.pdf</a></td></tr>
+</tbody>
+</table>
+<table class="docutils footnote" frame="void" id="id4" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a name="id4">[4]</a></td><td>K9K1G08R0B datasheet. <a class="reference" href="http://www.samsung.com/Products/Semiconductor/NANDFlash/SLC_SmallBlock/1Gbit/K9K1G08R0B/ds_k9k1g08x0b_rev10.pdf">http://www.samsung.com/Products/Semiconductor/NANDFlash/SLC_SmallBlock/1Gbit/K9K1G08R0B/ds_k9k1g08x0b_rev10.pdf</a></td></tr>
+</tbody>
+</table>
+</div>
+</div>
+</body>
+</html>
--- /dev/null
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
+<title>Basic Platform Independent Non-Volatile Storage Layers</title>
+<meta name="authors" content="David Moss Junzhao Du Prabal Dutta Deepak Ganesan Kevin Klues Manju Ajay Martin and Gaurav Mathur" />
+<style type="text/css">
+
+/*
+:Author: David Goodger
+:Contact: goodger@users.sourceforge.net
+:date: $Date$
+:version: $Revision$
+:copyright: This stylesheet has been placed in the public domain.
+
+Default cascading style sheet for the HTML output of Docutils.
+*/
+body {
+ font-family: Times;
+ font-size: 16px;
+}
+
+.first {
+ margin-top: 0 ! important }
+
+.last {
+ margin-bottom: 0 ! important }
+
+.hidden {
+ display: none }
+
+a.toc-backref {
+ text-decoration: none ;
+ color: black }
+
+blockquote.epigraph {
+ margin: 2em 5em ; }
+
+dd {
+ margin-bottom: 0.5em }
+
+div.abstract {
+ margin: 2em 5em }
+
+div.abstract p.topic-title {
+ font-weight: bold ;
+ text-align: center }
+
+div.attention, div.caution, div.danger, div.error, div.hint,
+div.important, div.note, div.tip, div.warning, div.admonition {
+ margin: 2em ;
+ border: medium outset ;
+ padding: 1em }
+
+div.attention p.admonition-title, div.caution p.admonition-title,
+div.danger p.admonition-title, div.error p.admonition-title,
+div.warning p.admonition-title {
+ color: red ;
+ font-weight: bold ;
+ font-family: sans-serif }
+
+div.hint p.admonition-title, div.important p.admonition-title,
+div.note p.admonition-title, div.tip p.admonition-title,
+div.admonition p.admonition-title {
+ font-weight: bold ;
+ font-family: sans-serif }
+
+div.dedication {
+ margin: 2em 5em ;
+ text-align: center ;
+ font-style: italic }
+
+div.dedication p.topic-title {
+ font-weight: bold ;
+ font-style: normal }
+
+div.figure {
+ margin-left: 2em }
+
+div.footer, div.header {
+ font-size: smaller }
+
+div.line-block {
+ display: block ;
+ margin-top: 1em ;
+ margin-bottom: 1em }
+
+div.line-block div.line-block {
+ margin-top: 0 ;
+ margin-bottom: 0 ;
+ margin-left: 1.5em }
+
+div.sidebar {
+ margin-left: 1em ;
+ border: medium outset ;
+ padding: 0em 1em ;
+ background-color: #ffffee ;
+ width: 40% ;
+ float: right ;
+ clear: right }
+
+div.sidebar p.rubric {
+ font-family: sans-serif ;
+ font-size: medium }
+
+div.system-messages {
+ margin: 5em }
+
+div.system-messages h1 {
+ color: red }
+
+div.system-message {
+ border: medium outset ;
+ padding: 1em }
+
+div.system-message p.system-message-title {
+ color: red ;
+ font-weight: bold }
+
+div.topic {
+ margin: 2em }
+
+h1 {
+ font-family: Arial, sans-serif;
+ font-size: 20px;
+}
+
+h1.title {
+ text-align: center;
+ font-size: 32px;
+}
+
+h2 {
+ font-size: 16px;
+ font-family: Arial, sans-serif;
+}
+
+h2.subtitle {
+ text-align: center }
+
+h3 {
+ font-size: 12px;
+ font-family: Arial, sans-serif;
+}
+
+hr {
+ width: 75% }
+
+ol.simple, ul.simple {
+ margin-bottom: 1em }
+
+ol.arabic {
+ list-style: decimal }
+
+ol.loweralpha {
+ list-style: lower-alpha }
+
+ol.upperalpha {
+ list-style: upper-alpha }
+
+ol.lowerroman {
+ list-style: lower-roman }
+
+ol.upperroman {
+ list-style: upper-roman }
+
+p.attribution {
+ text-align: right ;
+ margin-left: 50% }
+
+p.caption {
+ font-style: italic }
+
+p.credits {
+ font-style: italic ;
+ font-size: smaller }
+
+p.label {
+ white-space: nowrap }
+
+p.rubric {
+ font-weight: bold ;
+ font-size: larger ;
+ color: maroon ;
+ text-align: center }
+
+p.sidebar-title {
+ font-family: sans-serif ;
+ font-weight: bold ;
+ font-size: larger }
+
+p.sidebar-subtitle {
+ font-family: sans-serif ;
+ font-weight: bold }
+
+p.topic-title {
+ font-weight: bold }
+
+pre.address {
+ margin-bottom: 0 ;
+ margin-top: 0 ;
+ font-family: serif ;
+ font-size: 100% }
+
+pre.line-block {
+ font-family: serif ;
+ font-size: 100% }
+
+pre.literal-block, pre.doctest-block {
+ margin-left: 2em ;
+ margin-right: 2em ;
+ background-color: #eeeeee;
+ border-color: #000000;
+ border-width: thin;
+ font-size: 14px
+}
+
+span.classifier {
+ font-family: sans-serif ;
+ font-style: oblique }
+
+span.classifier-delimiter {
+ font-family: sans-serif ;
+ font-weight: bold }
+
+span.interpreted {
+ font-family: sans-serif }
+
+span.option {
+ white-space: nowrap }
+
+span.option-argument {
+ font-style: italic }
+
+span.pre {
+ white-space: pre }
+
+span.problematic {
+ color: red }
+
+table {
+ margin-top: 0.5em ;
+ margin-bottom: 0.5em }
+
+table.citation {
+ border-left: solid thin gray ;
+ padding-left: 0.5ex }
+
+table.docinfo {
+ margin: 2em 4em;
+}
+
+table.footnote {
+ border-left: solid thin black ;
+ padding-left: 0.5ex }
+
+td, th {
+ padding-left: 0.5em ;
+ padding-right: 0.5em ;
+ vertical-align: top }
+
+th.docinfo-name, th.field-name {
+ font-weight: bold ;
+ text-align: left ;
+ white-space: nowrap;
+ }
+
+h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt {
+ font-size: 100% }
+
+tt {}
+
+ul.auto-toc {
+ list-style-type: none }
+
+</style>
+</head>
+<body>
+<div class="document" id="basic-platform-independent-non-volatile-storage-layers">
+<h1 class="title">Basic Platform Independent Non-Volatile Storage Layers</h1>
+<table class="docinfo" frame="void" rules="none">
+<col class="docinfo-name" />
+<col class="docinfo-content" />
+<tbody valign="top">
+<tr class="field"><th class="docinfo-name">TEP:</th><td class="field-body">129</td>
+</tr>
+<tr class="field"><th class="docinfo-name">Group:</th><td class="field-body">Storage Working Group</td>
+</tr>
+<tr class="field"><th class="docinfo-name">Type:</th><td class="field-body">Documentary</td>
+</tr>
+<tr><th class="docinfo-name">Status:</th>
+<td>DRAFT</td></tr>
+<tr class="field"><th class="docinfo-name">TinyOS-Version:</th><td class="field-body">2.x</td>
+</tr>
+<tr><th class="docinfo-name">Authors:</th>
+<td>David Moss
+<br />Junzhao Du
+<br />Prabal Dutta
+<br />Deepak Ganesan
+<br />Kevin Klues
+<br />Manju
+<br />Ajay Martin
+<br />and Gaurav Mathur</td></tr>
+</tbody>
+</table>
+<div class="note">
+<p class="first admonition-title">Note</p>
+<p class="last">This memo documents a part of TinyOS for the TinyOS Community, and
+requests discussion and suggestions for improvements. Distribution
+of this memo is unlimited. This memo is in full compliance with
+TEP 1.</p>
+</div>
+<div class="section">
+<h1><a id="abstract" name="abstract">Abstract</a></h1>
+<p>The storage abstractions proposed by TEP 103 are implemented on a
+platform-dependent basis. A version of BlockStorage, ConfigStorage,
+and LogStorage were created from the ground up for both the
+AT45DB and ST M25P80 flash chips. Looking forward into the further
+growth and development of hardware, rebuilding each of these storage
+layers for every new flash chip will be time consuming and cause
+compatibility issues.</p>
+<p>We propose versions of BlockStorage, ConfigStorage, and LogStorage
+be built on top of a platform-independent interface. This would
+allow one version of each to exist on multiple platforms.
+Platform-independent implementation concepts are discussed
+along with recommended solutions, and changes are proposed to the
+interfaces defined by TEP 103.</p>
+</div>
+<div class="section">
+<h1><a id="introduction" name="introduction">1. Introduction</a></h1>
+<p>The implementations of the BlockStorage, ConfigStorage, and LogStorage
+layers described in TEP 103 <a class="footnote-reference" href="#id6" id="id1" name="id1">[1]</a> are platform-dependent. Platform-
+dependent implementations can cause behavioral and usage differences
+as well as compiling problems when attempting to port an application
+written on one platform to another.</p>
+<p>Building upon the DirectStorage, DirectModify, and VolumeSettings
+abstraction layers defined in TEP128 <a class="footnote-reference" href="#id7" id="id2" name="id2">[2]</a>, the three basic storage
+solutions can be implemented in a platform-independent manner.
+This requires combining all properties of various memory types,
+which aids in the creation of platform-independent storage solutions.
+Behavioral differences are minimized, and applications using
+the platform-independent storage layers can expect to work the
+same way on different types of non-volatile memory.</p>
+</div>
+<div class="section">
+<h1><a id="implementing-a-platform-independent-blockstorage" name="implementing-a-platform-independent-blockstorage">2. Implementing a platform-independent BlockStorage</a></h1>
+<p>The DirectStorage interface initially stemmed from the BlockStorage
+interface with differences in interfaces, organization, and
+erase behavior, as well as the additional VolumeSettings interface.
+To implement BlockStorage on DirectStorage, the erase behavior must
+be extended to erase the entire volume instead of an individual erase unit.</p>
+<p>VolumeSettings can first be accessed to determine the total number of erase
+units in the currently mounted volume. Looping through these erase units,
+DirectStorage is accessed to erase() each one. At the end of the erase
+operation, the entire volume is set back to fill bytes (0xFF).</p>
+<div class="section">
+<h2><a id="improved-blockstorage-interface" name="improved-blockstorage-interface">2.1 Improved BlockStorage interface</a></h2>
+<p>Previous BlockStorage interfaces were divided into BlockRead and
+BlockWrite. This was found to be cumbersome because applications
+typically required access to both interfaces. The getSize() is
+unnecessary due to the addition of the VolumeSettings interface.
+All other BlockStorage commands can simply pass through to their
+respective DirectStorage functions. This TEP proposes the following
+unified BlockStorage interface::</p>
+<pre class="literal-block">
+interface BlockStorage {
+
+ command error_t read(uint32_t addr, void *buf, uint32_t len);
+
+ command error_t write(uint32_t addr, void *buf, uint32_t len);
+
+ command error_t erase();
+
+ command error_t flush();
+
+ command error_t crc(uint32_t addr, uint32_t len, uint16_t baseCrc);
+
+
+
+ event void readDone(uint32_t addr, void *buf, uint32_t len, error_t error);
+
+ event void writeDone(uint32_t addr, void *buf, uint32_t len, error_t error);
+
+ event void eraseDone(error_t error);
+
+ event void flushDone(error_t error);
+
+ event void crcDone(uint16_t calculatedCrc, uint32_t addr, uint32_t len, error_t error);
+
+}
+</pre>
+<dl class="docutils">
+<dt><tt class="docutils literal"><span class="pre">read(uint32_t</span> <span class="pre">addr,</span> <span class="pre">void</span> <span class="pre">*buf,</span> <span class="pre">uint32_t</span> <span class="pre">len);</span></tt></dt>
+<dd><ul class="first last simple">
+<li>Read 'len' bytes into <tt class="docutils literal"><span class="pre">*buf</span></tt> from the given address</li>
+<li>Returns FAIL if the request cannot be handled</li>
+<li>Signals readDone(...) when complete.</li>
+</ul>
+</dd>
+<dt><tt class="docutils literal"><span class="pre">write(uint32_t</span> <span class="pre">addr,</span> <span class="pre">void</span> <span class="pre">*buf,</span> <span class="pre">uint32_t</span> <span class="pre">len);</span></tt></dt>
+<dd><ul class="first last simple">
+<li>Write 'len' bytes from <tt class="docutils literal"><span class="pre">*buf</span></tt> starting at the given address</li>
+<li>Returns FAIL if the request cannot be handled</li>
+<li>Signals writeDone(...) when complete.</li>
+</ul>
+</dd>
+<dt>erase();</dt>
+<dd><ul class="first last simple">
+<li>Erase the entire volume</li>
+<li>Returns FAIL if the request cannot be handled</li>
+<li>Signals eraseDone(...) when complete.</li>
+</ul>
+</dd>
+<dt>flush()</dt>
+<dd><ul class="first last simple">
+<li>All data that has been previously written and is not yet located on
+non-volatile memory should be immediately stored to non-volatile memory.</li>
+<li>Returns FAIL if the operation cannot be completed at this time</li>
+<li>Signals flushDone(...) when complete.</li>
+</ul>
+</dd>
+<dt>crc(uint32_t addr, uint32_t len, uint16_t baseCrc);</dt>
+<dd><ul class="first last simple">
+<li>Calculate the CRC of 'len' bytes starting at the given address, using
+the given baseCrc as a seed.</li>
+<li>Returns FAIL if the request cannot be handled</li>
+<li>Signals crcDone(...) when complete.</li>
+</ul>
+</dd>
+</dl>
+</div>
+</div>
+<div class="section">
+<h1><a id="implementing-a-platform-independent-logstorage" name="implementing-a-platform-independent-logstorage">3. Implementing a platform-independent LogStorage</a></h1>
+<p>As described in TEP 103, logging can be implemented using two
+different methods: linear and circular. A linear log fills up
+its volume and stops when it comes to the end. A circular log allows
+at least half of its volume to remain valid while continuing to write
+the other half. As previously described, this requires at least
+two erase units to be effective.</p>
+<p>Both logging behaviors can be implemented using the same code.
+A flag for linear log behavior prevents the logger from
+freeing up an erase unit in which to continue writing.</p>
+<p>It should also be noted that the use of a circular log mandates
+the use of at least two erase units on the volume. As discussed
+in TEP128 <a class="footnote-reference" href="#id7" id="id3" name="id3">[2]</a>, forcing volumes to contain at least two erase
+units solves this issue.</p>
+<div class="section">
+<h2><a id="logstorage-boot-behavior" name="logstorage-boot-behavior">3.1 LogStorage Boot Behavior</a></h2>
+<p>In the previous LogStorage implementations, reboots cause data to be
+lost or overwritten because the beginning and ends of the log were
+never located. Preventing previously stored data from being lost
+or overwritten after reboot is critical for the successful use and
+integration of logging storage components within a practical,
+deployable system.</p>
+<p>A method is required on boot to locate the first memory location to
+read from as well as the next available memory location to write to.
+Although one method is to use microcontroller user memory
+to store the information, the goal is to avoid relying on external
+support due to cross-platform compatibility reasons. Luckily, storing
+and updating this information on the volume itself is easier than
+it seems.</p>
+<p>Flash cannot overwrite areas of memory it has already written without
+performing a read-modify-write operation, and this operation is
+not supported on many flash types. Regardless of whether the memory
+type can support modifications, all types of memory - including EEPROM -
+should take wear-leveling into account. Combining these properties,
+it is possible to design a method of maintaining and updating logging
+start and stop information in a cross-platform compatible manner.</p>
+<p>The method of locating logging properties on boot is simplified by making
+entries aligned to erase unit boundaries, never allowing a single
+entry to bridge erase units. This also prevents invalid entries
+from being created as a result of erasing an erase unit.</p>
+<p>To find the first available write address to add new log entries,
+the first header entry on each erase unit is evaluated to find the
+greatest 32-bit "cookie" value that is not fill-bytes (0xFFFFFFFF).
+The erase unit with the largest value contains the newest data.
+Next, each entry in that erase unit can be iterated through by reading
+each header and skipping the length of the header + data, until a
+header with the value 0xFFFFFFFF is located. The address of this
+location is the first available address to write.</p>
+<p>Finding the first available address for reading involves the same process.
+The first header entry on each erase unit is evaluated to find the lowest
+32-bit "cookie" value. The entry with the lowest value is the beginning
+of the log.</p>
+<p>The first entry to read from and last address to write to MUST be
+located on platform boot.</p>
+</div>
+<div class="section">
+<h2><a id="appending-log-entries" name="appending-log-entries">3.2 Appending log entries</a></h2>
+<p>The previous M25P80 log storage implementation is a good place to start.
+In it, each write consists of a 32-bit header "cookie" and the data to
+be appended to the log. Locating the beginning of the log is therefore
+a matter of finding the lowest header cookie value. If this were to be
+implemented so entries align with erase unit boundaries, only the
+first header of each erase unit needs to be checked for the lowest value.</p>
+<p>32-bits leaves plenty of space to increment log entry values for.
+If the log were to append one chunk of data every second, it would
+take 136.1 years before the 32-bit header recycles to 0 and causes
+an issue in properly locating the first and last log entries.
+This is well beyond the expected lifetime of a deployed system.</p>
+<p>Each header entry can provide additional support for every
+data entry by allowing it to track the amount of appended data as well
+as an optional 8-bit CRC to verify the data is valid::</p>
+<pre class="literal-block">
+typedef struct log_header_t {
+ uint32_t cookie;
+ uint8_t length;
+ uint8_t crc;
+} log_header_t;
+</pre>
+<p>When the logger appends to the next erase unit boundary, it can first erase
+it to ensure future appends are not corrupted by existing bytes. At the
+point where it reaches the end of its volume, the 'circular' logging
+flag can be used to determine if the logger should go back to the
+beginning of the volume and continue writing. Again, this is performed
+in conjunction with the VolumeStorage interface to determine erase unit
+properties.</p>
+</div>
+<div class="section">
+<h2><a id="reading-log-entries" name="reading-log-entries">3.3 Reading log entries</a></h2>
+<p>After the first log entry is located, entries are extracted by first
+reading the header of a single entry, and using the information from
+the header to pull out the subsequent log information. After each read,
+the read pointer is updated to point to the read location of the next header.</p>
+<p>If the header ID is fill bytes (0xFFFFFFFF), then the entry is
+invalid and the read process has reached the end of the log. As with
+the ST M25P80 implementation, entries may be randomly seeked by
+providing the 32-bit "cookie" identifier to locate.</p>
+</div>
+<div class="section">
+<h2><a id="logging-conclusions" name="logging-conclusions">3.5 Logging conclusions</a></h2>
+<p>This proposed logging storage solution will provide the
+ability to maintain and locate previously logged data as well as
+support truly circular logs by mandating more than one erase unit per
+volume. Behavioral differences between flash chip implementations
+are eliminated so one application can access logging storage across
+all platforms. Furthermore, reboots will not cause logged information
+to be lost or overwritten.</p>
+<p>Existing LogRead and LogWrite interfaces defined in TEP 103 <a class="footnote-reference" href="#id7" id="id4" name="id4">[2]</a> are
+sufficient to implement cross-platform logging abilities.</p>
+</div>
+</div>
+<div class="section">
+<h1><a id="implementing-a-platform-independent-configstorage" name="implementing-a-platform-independent-configstorage">4. Implementing a platform-independent ConfigStorage</a></h1>
+<p>The previous interface to ConfigStorage looks very similar to that
+of BlockStorage. The ConfigStorage interface allows reads and
+writes to arbitrary addresses, which is not optimal. One critical
+concept behind the storage of configuration data is the ability to
+modify and overwrite existing parameters while preventing surrounding
+data from being corrupted. The former ConfigStorage definition did
+not support this, so a new solution should be explored and developed.</p>
+<p>This new solution should prevent an application from specifying
+addresses to read and write to on the volume. Instead, it should dictate
+addresses underneath, not allowing applications to see those addresses.
+In essence, the solution should handle the allocation of memory and
+take the burden of determining valid addresses off of the application
+layer. This will allow it to support multiple components written by
+different authors on the same system.</p>
+<div class="section">
+<h2><a id="hash-based-configuration-storage" name="hash-based-configuration-storage">4.1 Hash-based configuration storage</a></h2>
+<p>Several practical deployments have demonstrated the effectiveness of
+a hash-based configuration storage solution. In it, any module
+in a system can store and update any type of data of any size without
+destroying other modules' information.</p>
+<p>The implementation is similar to that of ConfigStorage in that each
+entry contains a header followed by a variable amount of data.
+The header is different than ConfigStorage headers in that instead
+of containing a 32-bit cookie, it contains a 32-bit hash key and
+a magic number to keep track of state::</p>
+<pre class="literal-block">
+typedef struct config_header_t {
+ uint32_t hashId;
+ uint8_t magic;
+ uint8_t length;
+ uint8_t crc;
+} config_header_t;
+</pre>
+<p>The magic number allows Configuration storage to determine if the
+entry is valid or has been deleted. Because non-volatile memory typically
+writes from 1's to 0's, the magic number can take on a finite number of
+values before it is filled with 0's. For example::</p>
+<pre class="literal-block">
+enum {
+ ENTRY_EMPTY = 0xFF,
+ ENTRY_VALID = 0xEE,
+ ENTRY_INVALID = 0xDD,
+};
+</pre>
+<p>Configuration data can be stored and retrieved by indexing it with
+a hash key. Like AM types in the radio stack <a class="footnote-reference" href="#id8" id="id5" name="id5">[3]</a>, each key is uniquely
+defined by the developer.</p>
+<p>Each new update to the configuration storage should create an entirely
+new entry while invalidating any previous entry containing the same hash key.
+Optionally, a small cache in RAM can be used to maintain information about
+where existing hash ID's are located in memory, so non-volatile memory
+does not need to be traversed each time.</p>
+<p>When space runs out on one erase unit, the next erase unit can be used
+to copy in all valid data from the first. The first erase unit can
+then be erased. This allows parameters and configuration data to be
+infinitely updated so long as the amount of valid data plus supporting
+headers is less than half the volume's total erase unit size.</p>
+</div>
+<div class="section">
+<h2><a id="improved-configstorage-interface" name="improved-configstorage-interface">4.2 Improved ConfigStorage interface</a></h2>
+<p>The interface to access the configuration storage mechanism is proposed
+as follows, allowing the application layer to continually update
+previously stored parameters while preventing it from accessing
+memory addresses directly::</p>
+<pre class="literal-block">
+interface ConfigStorage {
+
+ command error_t getTotalKeys();
+
+ command error_t insert(uint32_t key, void *value, uint16_t valueSize);
+
+ command error_t retrieve(uint32_t key, void *valueHolder, uint16_t maxValueSize);
+
+ command error_t remove(uint32_t key);
+
+ command error_t getFirstKey();
+
+ command uint32_t getLastKey();
+
+ command error_t getNextKey(uint32_t presentKey);
+
+
+ event void inserted(uint32_t key, void *value, uint16_t valueSize, error_t error);
+
+ event void retrieved(uint32_t key, void *valueHolder, uint16_t valueSize, error_t error);
+
+ event void removed(uint32_t key, error_t error);
+
+ event void nextKey(uint32_t nextKey, error_t error);
+
+ event void totalKeys(uint16_t totalKeys);
+
+}
+</pre>
+<dl class="docutils">
+<dt>getTotalKeys()</dt>
+<dd><ul class="first last simple">
+<li>Determine the total number of valid keys stored on non-volatile memory</li>
+<li>Signals totalKeys(...) when complete</li>
+</ul>
+</dd>
+<dt><tt class="docutils literal"><span class="pre">insert(uint32_t</span> <span class="pre">key,</span> <span class="pre">void</span> <span class="pre">*value,</span> <span class="pre">uint16_t</span> <span class="pre">valueSize)</span></tt></dt>
+<dd><ul class="first last simple">
+<li>Insert some data into the configuration storage associated with the
+given key</li>
+<li>Signals inserted(...) when complete</li>
+</ul>
+</dd>
+<dt><tt class="docutils literal"><span class="pre">retrieve(uint32_t</span> <span class="pre">key,</span> <span class="pre">void</span> <span class="pre">*valueHolder,</span> <span class="pre">uint16_t</span> <span class="pre">maxValueSize)</span></tt></dt>
+<dd><ul class="first last simple">
+<li>Retrieve the value associated with the given key. The maximum value
+size is the maximum amount of data that can be loaded into the
+<tt class="docutils literal"><span class="pre">*valueHolder</span></tt> location, to avoid overflow</li>
+<li>Signals retrieved(...) when complete</li>
+</ul>
+</dd>
+<dt>remove(uint32_t key)</dt>
+<dd><ul class="first last simple">
+<li>Removes the given key and its associated values from non-volatile memory</li>
+<li>Signals removed(...) when complete</li>
+</ul>
+</dd>
+<dt>getFirstKey()</dt>
+<dd><ul class="first last simple">
+<li>Determines the first key available for reading on non-volatile memory</li>
+<li>Signals nextKey(...) when complete</li>
+</ul>
+</dd>
+<dt>getNextKey(uint32_t presentKey)</dt>
+<dd><ul class="first last simple">
+<li>Obtain the next available key on non-volatile memory based on the
+current key. Allows the application to traverse through all stored
+keys.</li>
+<li>Signals nextKey(...) when complete</li>
+</ul>
+</dd>
+<dt>getLastKey()</dt>
+<dd><ul class="first last simple">
+<li>Returns last key available for reading on non-volatile memory.</li>
+<li>This value is assumed to be located in cache, so it can
+return immediately</li>
+</ul>
+</dd>
+</dl>
+</div>
+</div>
+<div class="section">
+<h1><a id="author-s-address" name="author-s-address">5. Author's Address</a></h1>
+<div class="line-block">
+<div class="line">David Moss</div>
+<div class="line">Rincon Research Corporation</div>
+<div class="line">101 N. Wilmot, Suite 101</div>
+<div class="line">Tucson, AZ 85750</div>
+<div class="line"><br /></div>
+<div class="line">phone - +1 520 519 3138</div>
+<div class="line">phone - +1 520 519 3146</div>
+<div class="line">email ? <a class="reference" href="mailto:dmm@rincon.com">dmm@rincon.com</a></div>
+<div class="line"><br /></div>
+<div class="line">Junzhao Du</div>
+<div class="line">Contact -</div>
+<div class="line"><br /></div>
+<div class="line">Prabal Dutta</div>
+<div class="line">Contact -</div>
+<div class="line"><br /></div>
+<div class="line">Deepak Ganesan</div>
+<div class="line">Contact -</div>
+<div class="line"><br /></div>
+<div class="line">Kevin Klues</div>
+<div class="line">Contact -</div>
+<div class="line"><br /></div>
+<div class="line">Manju</div>
+<div class="line">Contact -</div>
+<div class="line"><br /></div>
+<div class="line">Ajay Martin</div>
+<div class="line">Contact -</div>
+<div class="line"><br /></div>
+<div class="line">Gaurav Mathur</div>
+<div class="line">Contact -</div>
+</div>
+</div>
+<div class="section">
+<h1><a id="citations" name="citations">6. Citations</a></h1>
+<table class="docutils footnote" frame="void" id="id6" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id1" name="id6">[1]</a></td><td>TEP 103: Permanent Data Storage (Flash).</td></tr>
+</tbody>
+</table>
+<table class="docutils footnote" frame="void" id="id7" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a name="id7">[2]</a></td><td><em>(<a class="fn-backref" href="#id2">1</a>, <a class="fn-backref" href="#id3">2</a>, <a class="fn-backref" href="#id4">3</a>)</em> TEP 128: Platform independent Non-Volatile Storage Abstraction Layers</td></tr>
+</tbody>
+</table>
+<table class="docutils footnote" frame="void" id="id8" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id5" name="id8">[3]</a></td><td>TEP 116: Packet Protocols</td></tr>
+</tbody>
+</table>
+<table class="docutils footnote" frame="void" id="id9" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a name="id9">[4]</a></td><td>Atmel AT45DB041B datasheet. <a class="reference" href="http://www.atmel.com/dyn/resources/prod_documents/DOC1432.PDF">http://www.atmel.com/dyn/resources/prod_documents/DOC1432.PDF</a></td></tr>
+</tbody>
+</table>
+<table class="docutils footnote" frame="void" id="id10" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a name="id10">[5]</a></td><td>ST M25P80 datasheet. <a class="reference" href="http://www.st.com/stonline/products/literature/ds/8495/m25p80.pdf">http://www.st.com/stonline/products/literature/ds/8495/m25p80.pdf</a></td></tr>
+</tbody>
+</table>
+<table class="docutils footnote" frame="void" id="id11" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a name="id11">[6]</a></td><td>K9K1G08R0B datasheet. <a class="reference" href="http://www.samsung.com/Products/Semiconductor/NANDFlash/SLC_SmallBlock/1Gbit/K9K1G08R0B/ds_k9k1g08x0b_rev10.pdf">http://www.samsung.com/Products/Semiconductor/NANDFlash/SLC_SmallBlock/1Gbit/K9K1G08R0B/ds_k9k1g08x0b_rev10.pdf</a></td></tr>
+</tbody>
+</table>
+</div>
+</div>
+</body>
+</html>
--- /dev/null
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
+<title>Testbeds - Setup and Interfaces</title>
+<meta name="author" content="Jan Beutel" />
+<style type="text/css">
+
+/*
+:Author: David Goodger
+:Contact: goodger@users.sourceforge.net
+:date: $Date$
+:version: $Revision$
+:copyright: This stylesheet has been placed in the public domain.
+
+Default cascading style sheet for the HTML output of Docutils.
+*/
+body {
+ font-family: Times;
+ font-size: 16px;
+}
+
+.first {
+ margin-top: 0 ! important }
+
+.last {
+ margin-bottom: 0 ! important }
+
+.hidden {
+ display: none }
+
+a.toc-backref {
+ text-decoration: none ;
+ color: black }
+
+blockquote.epigraph {
+ margin: 2em 5em ; }
+
+dd {
+ margin-bottom: 0.5em }
+
+div.abstract {
+ margin: 2em 5em }
+
+div.abstract p.topic-title {
+ font-weight: bold ;
+ text-align: center }
+
+div.attention, div.caution, div.danger, div.error, div.hint,
+div.important, div.note, div.tip, div.warning, div.admonition {
+ margin: 2em ;
+ border: medium outset ;
+ padding: 1em }
+
+div.attention p.admonition-title, div.caution p.admonition-title,
+div.danger p.admonition-title, div.error p.admonition-title,
+div.warning p.admonition-title {
+ color: red ;
+ font-weight: bold ;
+ font-family: sans-serif }
+
+div.hint p.admonition-title, div.important p.admonition-title,
+div.note p.admonition-title, div.tip p.admonition-title,
+div.admonition p.admonition-title {
+ font-weight: bold ;
+ font-family: sans-serif }
+
+div.dedication {
+ margin: 2em 5em ;
+ text-align: center ;
+ font-style: italic }
+
+div.dedication p.topic-title {
+ font-weight: bold ;
+ font-style: normal }
+
+div.figure {
+ margin-left: 2em }
+
+div.footer, div.header {
+ font-size: smaller }
+
+div.line-block {
+ display: block ;
+ margin-top: 1em ;
+ margin-bottom: 1em }
+
+div.line-block div.line-block {
+ margin-top: 0 ;
+ margin-bottom: 0 ;
+ margin-left: 1.5em }
+
+div.sidebar {
+ margin-left: 1em ;
+ border: medium outset ;
+ padding: 0em 1em ;
+ background-color: #ffffee ;
+ width: 40% ;
+ float: right ;
+ clear: right }
+
+div.sidebar p.rubric {
+ font-family: sans-serif ;
+ font-size: medium }
+
+div.system-messages {
+ margin: 5em }
+
+div.system-messages h1 {
+ color: red }
+
+div.system-message {
+ border: medium outset ;
+ padding: 1em }
+
+div.system-message p.system-message-title {
+ color: red ;
+ font-weight: bold }
+
+div.topic {
+ margin: 2em }
+
+h1 {
+ font-family: Arial, sans-serif;
+ font-size: 20px;
+}
+
+h1.title {
+ text-align: center;
+ font-size: 32px;
+}
+
+h2 {
+ font-size: 16px;
+ font-family: Arial, sans-serif;
+}
+
+h2.subtitle {
+ text-align: center }
+
+h3 {
+ font-size: 12px;
+ font-family: Arial, sans-serif;
+}
+
+hr {
+ width: 75% }
+
+ol.simple, ul.simple {
+ margin-bottom: 1em }
+
+ol.arabic {
+ list-style: decimal }
+
+ol.loweralpha {
+ list-style: lower-alpha }
+
+ol.upperalpha {
+ list-style: upper-alpha }
+
+ol.lowerroman {
+ list-style: lower-roman }
+
+ol.upperroman {
+ list-style: upper-roman }
+
+p.attribution {
+ text-align: right ;
+ margin-left: 50% }
+
+p.caption {
+ font-style: italic }
+
+p.credits {
+ font-style: italic ;
+ font-size: smaller }
+
+p.label {
+ white-space: nowrap }
+
+p.rubric {
+ font-weight: bold ;
+ font-size: larger ;
+ color: maroon ;
+ text-align: center }
+
+p.sidebar-title {
+ font-family: sans-serif ;
+ font-weight: bold ;
+ font-size: larger }
+
+p.sidebar-subtitle {
+ font-family: sans-serif ;
+ font-weight: bold }
+
+p.topic-title {
+ font-weight: bold }
+
+pre.address {
+ margin-bottom: 0 ;
+ margin-top: 0 ;
+ font-family: serif ;
+ font-size: 100% }
+
+pre.line-block {
+ font-family: serif ;
+ font-size: 100% }
+
+pre.literal-block, pre.doctest-block {
+ margin-left: 2em ;
+ margin-right: 2em ;
+ background-color: #eeeeee;
+ border-color: #000000;
+ border-width: thin;
+ font-size: 14px
+}
+
+span.classifier {
+ font-family: sans-serif ;
+ font-style: oblique }
+
+span.classifier-delimiter {
+ font-family: sans-serif ;
+ font-weight: bold }
+
+span.interpreted {
+ font-family: sans-serif }
+
+span.option {
+ white-space: nowrap }
+
+span.option-argument {
+ font-style: italic }
+
+span.pre {
+ white-space: pre }
+
+span.problematic {
+ color: red }
+
+table {
+ margin-top: 0.5em ;
+ margin-bottom: 0.5em }
+
+table.citation {
+ border-left: solid thin gray ;
+ padding-left: 0.5ex }
+
+table.docinfo {
+ margin: 2em 4em;
+}
+
+table.footnote {
+ border-left: solid thin black ;
+ padding-left: 0.5ex }
+
+td, th {
+ padding-left: 0.5em ;
+ padding-right: 0.5em ;
+ vertical-align: top }
+
+th.docinfo-name, th.field-name {
+ font-weight: bold ;
+ text-align: left ;
+ white-space: nowrap;
+ }
+
+h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt {
+ font-size: 100% }
+
+tt {}
+
+ul.auto-toc {
+ list-style-type: none }
+
+</style>
+</head>
+<body>
+<div class="document" id="testbeds-setup-and-interfaces">
+<h1 class="title">Testbeds - Setup and Interfaces</h1>
+<table class="docinfo" frame="void" rules="none">
+<col class="docinfo-name" />
+<col class="docinfo-content" />
+<tbody valign="top">
+<tr class="field"><th class="docinfo-name">TEP:</th><td class="field-body">130</td>
+</tr>
+<tr class="field"><th class="docinfo-name">Group:</th><td class="field-body">Testbeds Working Group</td>
+</tr>
+<tr class="field"><th class="docinfo-name">Type:</th><td class="field-body">Documentary</td>
+</tr>
+<tr><th class="docinfo-name">Status:</th>
+<td>Draft</td></tr>
+<tr class="field"><th class="docinfo-name">TinyOS-Version:</th><td class="field-body">All</td>
+</tr>
+<tr><th class="docinfo-name">Author:</th>
+<td>Jan Beutel</td></tr>
+<tr class="field"><th class="docinfo-name">Draft-Created:</th><td class="field-body">14-Jun-2007</td>
+</tr>
+<tr class="field"><th class="docinfo-name">Draft-Version:</th><td class="field-body">1.2</td>
+</tr>
+<tr class="field"><th class="docinfo-name">Draft-Modified:</th><td class="field-body">2007-06-28</td>
+</tr>
+<tr class="field"><th class="docinfo-name">Draft-Discuss:</th><td class="field-body">TinyOS Testbed WG <<a class="reference" href="mailto:tinyos-testbed-wg@eecs.harvard.edu">tinyos-testbed-wg@eecs.harvard.edu</a>>></td>
+</tr>
+</tbody>
+</table>
+<div class="note">
+<p class="first admonition-title">Note</p>
+<p class="last">This document specifies a Best Current Practices for the
+TinyOS Community, and requests discussion and suggestions for
+improvements. Distribution of this memo is unlimited.</p>
+</div>
+<div class="section">
+<h1><a id="abstract" name="abstract">Abstract</a></h1>
+<p>This memo describes the structure and interfaces required for TinyOS compliant
+testbeds.</p>
+</div>
+<div class="section">
+<h1><a id="introduction" name="introduction">1. Introduction</a></h1>
+<p>The testing and validation of embedded code on real hardware is key to
+successful development of TinyOS applications. Although popular and powerful for
+high level analysis, current simulation methods lack in terms of level of
+detail and accuracy when used accross multiple system layers where abstractions
+and models used are inherently imperfect and impair results. Methods such as
+hardware emulation commonly used in embedded system development allow the
+execution of code on a hardware platform and therefore can guarantee timing but
+are very limited in terms of scalability and often confined to a lab usage only.</p>
+<p>Sensor network testbeds try to overcome these deficiencies by allowing to execute
+software code under realistic operating conditions on real hardware embedded in
+a target environment. This approach allows to generate a level of detail especially
+in respect to the whole system (radio. processor, storage, sensors, interfaces)
+and the wireless environment (noise, fading, shading, errors, failures) while
+maintaining a certain degree of scalability. Remote programming as well as a
+feedback of status and debugging information from the nodes using testbed
+infrastructure alleviates the need for integrated services in sensor network
+applications. Additionally testbeds allow to operate a set of nodes in a
+controlled environment, i.e. using temperature variations or a controlled
+wireless environment.</p>
+<p>A typical testbed is made up of a number of nodes (?do we state amounts here?)
+connected to a central resource for control and logging that are deployed in a
+physical space (testing area). Typically the central resource is a server with
+integrated datalogging capability. Often a web front end serves as a simple control and
+visualization resource. For the submission of testing jobs and the analysis of
+testing results external tools are attached to the central resource using a
+standardized interface. This document serves as a key specification document for
+such an interface and its intended usage.</p>
+<p>MISSING: Difference of a testbed vs. a desktop test (e.g. single nodes with a
+programmer or a simple usb grid)</p>
+<p>Examples of currently used sensor network testbeds are MoteLab [<a class="reference" href="#id1">1</a>] and the
+Deployment-Support Network [<a class="reference" href="#id2">2</a>].</p>
+</div>
+<div class="section">
+<h1><a id="testbed-usage" name="testbed-usage">2. Testbed Usage</a></h1>
+<p>A testbed can serve different purposes depending on the development status and
+requirements of a specific project. While this document does not target to restrict
+such usage it defines a set of mandatory modes of operation that a testbed must
+be able to support:</p>
+<p>Modes of Operation:</p>
+<ul class="simple">
+<li>Single Shot Operation</li>
+</ul>
+<p>Execute a testing job consisting of an uploading of a specific code image onto a
+set of nodes, remote programming of nodes using a testbed resource, the
+synchronized start of this software, capture of resulting target response, the
+centralized storage and timestamping of all actions and target response, ending
+of test execution, notification of a user of the end of test execution, output
+of all stored data on demand.</p>
+<ul class="simple">
+<li>Repetitive (e.g. using continuous integration or for regression testing)</li>
+</ul>
+<p>A concatenation of single shot testing jobs, that in practice often will be used
+with the variation of one or more parameters.</p>
+<ul class="simple">
+<li>Long Term Operation (Profiling)</li>
+</ul>
+<p>Other Topics:</p>
+<ul class="simple">
+<li>Federated Testbeds (in multiple environments)</li>
+<li>Access/Resource Arbitration</li>
+<li>Scheduling of testing jobs</li>
+</ul>
+</div>
+<div class="section">
+<h1><a id="testbed-services" name="testbed-services">3. Testbed Services</a></h1>
+<p>Required Services:</p>
+<ul class="simple">
+<li>identification of target devices (presence, type, hw rev)</li>
+<li>programming of target devices</li>
+<li>resetting of target devices</li>
+<li>logging of target response (UART mandatory, IRQ optional)</li>
+<li>versioning/identification of uploaded software</li>
+<li>identification/versioning/archiving of testing jobs</li>
+<li>testbed status information</li>
+<li>identification of testbed services</li>
+<li>user authentification</li>
+</ul>
+<p>Optional:
+- power measurements
+- stimuli
+- distributed scheduling of actions (at nodes)</p>
+</div>
+<div class="section">
+<h1><a id="implementation" name="implementation">4. Implementation</a></h1>
+<ul class="simple">
+<li>Server, DB/Storage, Interface XMLRPC</li>
+<li>Connection fabric</li>
+<li>On- and offline logging</li>
+<li>Supplied Power</li>
+<li>Mote Hardware</li>
+</ul>
+<p>THINGS TO DISCUSS</p>
+<ul class="simple">
+<li>?Do we state minimum requirements?</li>
+<li>number of nodes</li>
+<li>power supply (fixed/batt)</li>
+<li>power profiling</li>
+<li>power on/off of targets? is simple reset/erasing enough?</li>
+<li>feedback channel capabilities (delay, errors, lost packets...)</li>
+<li>target control? is control of (writing to) targets required or is it an optional feature?</li>
+<li>scheduling of actions (time synched???)</li>
+</ul>
+</div>
+<div class="section">
+<h1><a id="reference" name="reference">5. Reference</a></h1>
+</div>
+<div class="section">
+<h1><a id="acknowledgments" name="acknowledgments">6. Acknowledgments</a></h1>
+</div>
+<div class="section">
+<h1><a id="author-s-address" name="author-s-address">7. Author's Address</a></h1>
+<div class="line-block">
+<div class="line">Jan Beutel</div>
+<div class="line">Gloriastr 35</div>
+<div class="line">ETH Zurich</div>
+<div class="line">8092 Zurich</div>
+<div class="line">Switzerland</div>
+<div class="line"><br /></div>
+<div class="line">phone - +41 44 632 7032</div>
+<div class="line"><br /></div>
+<div class="line">email - <a class="reference" href="mailto:j.beutel@ieee.org">j.beutel@ieee.org</a></div>
+</div>
+</div>
+<div class="section">
+<h1><a id="citations" name="citations">8. Citations</a></h1>
+<table class="docutils footnote" frame="void" id="id1" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a name="id1">[1]</a></td><td>G. Werner-Allen, P. Swieskowski, and M. Welsh. MoteLab: A wireless sensor
+network testbed. In Proc. 4th Int'l Conf. Information Processing Sensor
+Networks (IPSN '05), pages 483-488. IEEE, Piscataway, NJ, April 2005.</td></tr>
+</tbody>
+</table>
+<table class="docutils footnote" frame="void" id="id2" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a name="id2">[2]</a></td><td>M. Dyer, J. Beutel, L. Thiele, T. Kalt, P. Oehen, K. Martin, and P. Blum.
+Deployment support network - a toolkit for the development of WSNs. In Proc.
+4th European Workshop on Sensor Networks (EWSN 2007), volume 4373 of Lecture
+Notes in Computer Science, pages 195-211. Springer, Berlin, January 2007.</td></tr>
+</tbody>
+</table>
+</div>
+<div class="section">
+<h1><a id="appendix-a-example-appendix" name="appendix-a-example-appendix">Appendix A. Example Appendix</a></h1>
+<p>This is an example appendix. Appendices begin with the letter A.</p>
+</div>
+</div>
+</body>
+</html>
<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.6: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
<title>Hardware Abstraction Architecture</title>
-<meta name="author" content="Vlado Handziski, Joseph Polastre, Jan-Hinrich Hauer, Cory Sharp, Adam Wolisz, David Culler, David Gay" />
+<meta name="author" content="Vlado Handziski, Joseph Polastre, Jan-Hinrich Hauer, Cory Sharp, Adam Wolisz, David Culler, David Gay" />
<style type="text/css">
/*
dd {
margin-bottom: 0.5em }
-/* Uncomment (& remove this text!) to get bold-faced definition list terms
-dt {
- font-weight: bold }
-*/
-
div.abstract {
margin: 2em 5em }
</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" id="abstract">
-<h1><a name="abstract">Abstract</a></h1>
+<div class="section">
+<h1><a id="abstract" name="abstract">Abstract</a></h1>
<p>This TEP documents a <em>Hardware Abstraction Architecture (HAA)</em> for
TinyOS 2.0 that balances the conflicting requirements of code
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" id="introduction">
-<h1><a name="introduction">1. Introduction</a></h1>
+<div class="section">
+<h1><a id="introduction" name="introduction">1. Introduction</a></h1>
<p>The introduction of hardware abstraction in operating systems has
proved valuable for increasing portability and simplifying application
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" id="architecture">
-<h1><a name="architecture">2. Architecture</a></h1>
+<div class="section">
+<h1><a id="architecture" name="architecture">2. Architecture</a></h1>
<p>In the proposed architecture (<a class="reference" href="#fig-1">Fig.1</a>), the hardware abstraction
functionality is organized in three distinct layers of components.
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>
-<a class="target" id="fig-1" name="fig-1"></a><pre class="literal-block">
+<pre class="literal-block" id="fig-1">
+-----------------------------+
| |
| 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" id="hardware-presentation-layer-hpl">
-<h2><a name="hardware-presentation-layer-hpl">Hardware Presentation Layer (HPL)</a></h2>
+<div class="section">
+<h2><a id="hardware-presentation-layer-hpl" name="hardware-presentation-layer-hpl">Hardware Presentation Layer (HPL)</a></h2>
<p>The components belonging to the <em>HPL</em> are positioned directly over the
HW/SW interface. As the name suggests, their major task is to
"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" id="hardware-adaptation-layer-hal">
-<h2><a name="hardware-adaptation-layer-hal">Hardware Adaptation Layer (HAL)</a></h2>
+<div class="section">
+<h2><a id="hardware-adaptation-layer-hal" name="hardware-adaptation-layer-hal">Hardware Adaptation Layer (HAL)</a></h2>
<p>The adaptation layer components represent the core of the
architecture. They use the raw interfaces provided by the <em>HPL</em>
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" id="hardware-interface-layer-hil">
-<h2><a name="hardware-interface-layer-hil">Hardware Interface Layer (HIL)</a></h2>
+<div class="section">
+<h2><a id="hardware-interface-layer-hil" name="hardware-interface-layer-hil">Hardware Interface Layer (HIL)</a></h2>
<p>The final tier in the architecture is formed by the <em>HIL</em> components
that take the platform-specific abstractions provided by the <em>HAL</em> and
convert them to hardware-independent interfaces used by cross-platform
increasing levels of functionality.</p>
</div>
</div>
-<div class="section" id="combining-different-levels-of-abstraction">
-<h1><a name="combining-different-levels-of-abstraction">3. Combining different levels of abstraction</a></h1>
+<div class="section">
+<h1><a id="combining-different-levels-of-abstraction" name="combining-different-levels-of-abstraction">3. Combining different levels of abstraction</a></h1>
<p>Providing two levels of abstraction to the application --the <em>HIL</em> and
<em>HAL</em>-- means that a hardware asset may be accessed at two levels in
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>
-<a class="target" id="fig-2" name="fig-2"></a><pre class="literal-block">
+<pre class="literal-block" id="fig-2">
+--------------------------------+
| APP |
+-+----------------------------+-+
so that a safe shared access to the <em>HPL</em> exported resources can be
guaranteed.</p>
</div>
-<div class="section" id="horizontal-decomposition">
-<h1><a name="horizontal-decomposition">4. Horizontal decomposition</a></h1>
+<div class="section">
+<h1><a id="horizontal-decomposition" name="horizontal-decomposition">4. Horizontal decomposition</a></h1>
<p>In addition to the <em>vertical</em> decomposition of the <em>HAA</em>, a
<em>horizontal</em> decomposition can promote reuse of the hardware resource
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>
-<a class="target" id="fig-3" name="fig-3"></a><pre class="literal-block">
+<pre class="literal-block" id="fig-3">
+----------------------------------------------------+
| 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" id="cpu-abstraction">
-<h1><a name="cpu-abstraction">5. CPU abstraction</a></h1>
+<div class="section">
+<h1><a id="cpu-abstraction" name="cpu-abstraction">5. CPU abstraction</a></h1>
<p>In TinyOS most of the variability between the processing units is
hidden from the OS simply by using a nesC/C based programming language
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" id="hil-alignment">
-<h1><a name="hil-alignment">6. HIL alignment</a></h1>
+<div class="section">
+<h1><a id="hil-alignment" name="hil-alignment">6. HIL alignment</a></h1>
<p>While the <em>HAA</em> requires that the <em>HIL</em> provides full hardware
independence (<a class="reference" href="#strong-real-hils">Strong/Real HILs</a>), some abstractions might only
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" id="strong-real-hils">
-<h2><a name="strong-real-hils">Strong/Real HILs</a></h2>
+<div class="section">
+<h2><a id="strong-real-hils" name="strong-real-hils">Strong/Real HILs</a></h2>
<p><em>Strong/Real HILs</em> mean that "code using these abstractions can
reasonably be expected to behave the same on all implementations".
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" id="weak-hils">
-<h2><a name="weak-hils">Weak HILs</a></h2>
+<div class="section">
+<h2><a id="weak-hils" name="weak-hils">Weak HILs</a></h2>
<p><em>Weak HILs</em> mean that one "can write portable code over these
abstractions, but any use of them involves platform-specific
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" id="hardware-independent-interfaces-hii">
-<h2><a name="hardware-independent-interfaces-hii">Hardware Independent Interfaces (HII)</a></h2>
+<div class="section">
+<h2><a id="hardware-independent-interfaces-hii" name="hardware-independent-interfaces-hii">Hardware Independent Interfaces (HII)</a></h2>
<p><em>Hardware Independent Interfaces (HII)</em>, is just an interface
definition intended for use across multiple platforms.</p>
<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" id="utility-components">
-<h2><a name="utility-components">Utility components</a></h2>
+<div class="section">
+<h2><a id="utility-components" name="utility-components">Utility components</a></h2>
<p><em>Utility components</em> are pieces of clearly portable code (typically
generic components), which aren't exposing a self-contained service.
Examples include the components in tos/lib/timer and the
ArbitratedRead* components. These provide and use HIIs.</p>
</div>
</div>
-<div class="section" id="conclusion">
-<h1><a name="conclusion">6. Conclusion</a></h1>
+<div class="section">
+<h1><a id="conclusion" name="conclusion">6. Conclusion</a></h1>
<p>The proposed hardware abstraction architecture provides a set of core
services that eliminate duplicated code and provide a coherent view of
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" id="author-s-address">
-<h1><a name="author-s-address">Author's Address</a></h1>
+<div class="section">
+<h1><a id="author-s-address" name="author-s-address">Author's Address</a></h1>
<div class="line-block">
-<div class="line">Vlado Handziski (handzisk at tkn.tu-berlin.de) <a class="footnote-reference" href="#id27" id="id20" name="id20">[1]</a> </div>
-<div class="line">Joseph Polastre (polastre at cs.berkeley.edu) <a class="footnote-reference" href="#id28" id="id21" name="id21">[2]</a> </div>
+<div class="line">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" id="citations">
-<h1><a name="citations">Citations</a></h1>
+<div class="section">
+<h1><a id="citations" name="citations">Citations</a></h1>
<table class="docutils citation" frame="void" id="haa2005" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<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.3.6: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
<title>Coding Standard</title>
<meta name="author" content="Ion Yannopoulos, David Gay" />
<style type="text/css">
dd {
margin-bottom: 0.5em }
-/* Uncomment (& remove this text!) to get bold-faced definition list terms
-dt {
- font-weight: bold }
-*/
-
div.abstract {
margin: 2em 5em }
</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" />
</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" id="contents">
-<p class="topic-title first"><a name="contents">Contents</a></p>
+<div class="contents topic">
+<p class="topic-title first"><a id="contents" 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" id="introduction">
-<h1><a class="toc-backref" href="#id7" name="introduction">1 Introduction</a></h1>
+<div class="section">
+<h1><a class="toc-backref" href="#id7" id="introduction" 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" 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>
+<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>
<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" id="packages">
-<h1><a class="toc-backref" href="#id10" name="packages">3 Packages</a></h1>
+<div class="section">
+<h1><a class="toc-backref" href="#id10" id="packages" 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" id="directory-structure">
-<h2><a class="toc-backref" href="#id11" name="directory-structure">3.1 Directory structure</a></h2>
+<div class="section">
+<h2><a class="toc-backref" href="#id11" id="directory-structure" 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" 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>
+<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>
<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" id="id5">
-<h3><a class="toc-backref" href="#id15" name="id5">4.1.2 Packages</a></h3>
+<div class="section">
+<h3><a class="toc-backref" href="#id15" id="id5" 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" id="preprocessor">
-<h3><a class="toc-backref" href="#id16" name="preprocessor">4.1.3 Preprocessor</a></h3>
+<div class="section">
+<h3><a class="toc-backref" href="#id16" id="preprocessor" 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" id="c-convention">
-<h2><a class="toc-backref" href="#id17" name="c-convention">4.2 C Convention</a></h2>
+<div class="section">
+<h2><a class="toc-backref" href="#id17" id="c-convention" 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" id="java-convention">
-<h2><a class="toc-backref" href="#id18" name="java-convention">4.3 Java convention</a></h2>
+<div class="section">
+<h2><a class="toc-backref" href="#id18" id="java-convention" 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" id="other-languages">
-<h2><a class="toc-backref" href="#id19" name="other-languages">4.4 Other languages</a></h2>
+<div class="section">
+<h2><a class="toc-backref" href="#id19" id="other-languages" name="other-languages">4.4 Other languages</a></h2>
<blockquote>
<ul class="simple">
<li>No established conventions.</li>
</blockquote>
</div>
</div>
-<div class="section" id="tinyos-conventions">
-<h1><a class="toc-backref" href="#id20" name="tinyos-conventions">5 TinyOS Conventions</a></h1>
+<div class="section">
+<h1><a class="toc-backref" href="#id20" id="tinyos-conventions" 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" id="error-returns">
-<h2><a class="toc-backref" href="#id21" name="error-returns">5.1 Error returns</a></h2>
+<div class="section">
+<h2><a class="toc-backref" href="#id21" id="error-returns" 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" 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>
+<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>
<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" 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>
+<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>
<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" id="citations">
-<h1><a class="toc-backref" href="#id24" name="citations">6 Citations</a></h1>
+<div class="section">
+<h1><a class="toc-backref" href="#id24" id="citations" 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">
dd {
margin-bottom: 0.5em }
-/* Uncomment (& remove this text!) to get bold-faced definition list terms
-dt {
- font-weight: bold }
-*/
-
div.abstract {
margin: 2em 5em }
dd {
margin-bottom: 0.5em }
-/* Uncomment (& remove this text!) to get bold-faced definition list terms
-dt {
- font-weight: bold }
-*/
-
div.abstract {
margin: 2em 5em }
projects / tinyos-2.x.git / commitdiff