<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 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>
+<td>Final</td></tr>
+<tr class="field"><th class="docinfo-name">TinyOS-Version:</th><td class="field-body">> 2.1</td>
</tr>
<tr><th class="docinfo-name">Author:</th>
<td>Philip Levis</td></tr>
-<tr class="field"><th class="docinfo-name">Draft-Created:</th><td class="field-body">10-Dec-2004</td>
-</tr>
-<tr class="field"><th class="docinfo-name">Draft-Version:</th><td class="field-body">1.10</td>
-</tr>
-<tr class="field"><th class="docinfo-name">Draft-Modified:</th><td class="field-body">2007-03-28</td>
-</tr>
-<tr class="field"><th class="docinfo-name">Draft-Discuss:</th><td class="field-body">TinyOS Developer List <tinyos-devel at mail.millennium.berkeley.edu></td>
-</tr>
</tbody>
</table>
-<div class="document" id="packet-protocols">
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">This memo documents a part of TinyOS for the TinyOS Community, and
of this memo is unlimited. This memo is in full compliance with
TEP 1.</p>
</div>
-<div class="section" 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.
command uint8_t payloadLength(message_t* msg);
command void setPayLoadLength(message_t* msg, uint8_t len);
command uint8_t maxPayloadLength();
- command void* getPayload(message_t* msg, uint8_t* len);
+ command void* getPayload(message_t* msg, uint8_t len);
}
</pre>
<p>A component can obtain a pointer to its data region within a packet by
-calling <tt class="docutils literal"><span class="pre">getPayload()</span></tt> the optional <tt class="docutils literal"><span class="pre">len</span></tt> argument is for also
-obtaining the size of the data region. A provider of a Packet
-interface MUST check if <tt class="docutils literal"><span class="pre">len</span></tt> is NULL and ignore it if it is. A
-component can also obtain the size of the data region with a call to
-<tt class="docutils literal"><span class="pre">payloadLength</span></tt>.</p>
-<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,
-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>
+calling <tt class="docutils literal"><span class="pre">getPayload()</span></tt>. A call to this command includes the length
+the caller requires. The command <tt class="docutils literal"><span class="pre">maxPayloadLength</span></tt> returns the
+maximum length the payload can be: if the <tt class="docutils literal"><span class="pre">len</span></tt> parameter to
+<tt class="docutils literal"><span class="pre">getPayload</span></tt> is greater than the value <tt class="docutils literal"><span class="pre">maxPayloadLength</span></tt> would
+return, <tt class="docutils literal"><span class="pre">getPayload</span></tt> MUST return NULL.</p>
+<p>A component can set the payload length with <tt class="docutils literal"><span class="pre">setPayLoadLength.</span></tt> A
+component can obtain the size of the data region of packet in use with
+a call to <tt class="docutils literal"><span class="pre">payloadLength</span></tt>. As Send interfaces always include a
+length parameter in their send call, <tt class="docutils literal"><span class="pre">setPayLoadLength</span></tt> is not
+required for sending, and so is never called in common use
+cases. Instead, it is a way for queues and other packet buffering
+components to store the full state of a packet without requiring
+additional memory allocation.</p>
<p>The distinction between <tt class="docutils literal"><span class="pre">payloadLength</span></tt> and <tt class="docutils literal"><span class="pre">maxPayloadLength</span></tt>
-comes from whether the packet is being received or sent. In the receive
-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
-position will only be known once the header values are bound.</p>
-<p>Generally, an incoming call to the Packet interface of a protocol
-has an accompanying outgoing call to the Packet interface of the
-component below it. The one exception to this is the data link
-layer. For example, if there is a network that introduces
-16-bit sequence numbers to packets, it might look like this:</p>
+comes from whether the packet is being received or sent. In the
+receive 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. By definition, the return value of
+<tt class="docutils literal"><span class="pre">payloadLength</span></tt> must be less than or equal to the return value of
+<tt class="docutils literal"><span class="pre">maxPayloadLength</span></tt>.</p>
+<p>The Packet interface assumes that headers have a fixed size. It is
+difficult to return a pointer into the data region when its position
+will only be known once the header values are bound.</p>
+<p>The <tt class="docutils literal"><span class="pre">clear</span></tt> command clears out all headers, footers, and metadata
+for lower layers. For example, calling <tt class="docutils literal"><span class="pre">clear</span></tt> on a routing
+component, such as CollectionSenderC[4]_, will clear out the
+collection headers and footers. Furthermore, CollectionSenderC will
+recursively call <tt class="docutils literal"><span class="pre">clear</span></tt> on the layer below it, clearing out the
+link layer headers and footers. Calling <tt class="docutils literal"><span class="pre">clear</span></tt> is typically
+necessary when moving a packet across two link layers. Otherwise, the
+destination link layer may incorrectly interpret metadata from the
+source link layer, and, for example, transmit the packet on the wrong
+RF channel. Because <tt class="docutils literal"><span class="pre">clear</span></tt> prepares a packet for a particular link
+layer, in this example correct code would call the command on the
+destination link layer, not the source link layer.</p>
+<p>Typically, an incoming call to the Packet interface of a protocol has
+an accompanying outgoing call to the Packet interface of the component
+below it. The one exception to this is the data link layer. For
+example, if there is a network that introduces 16-bit sequence numbers
+to packets, it might look like this:</p>
<pre class="literal-block">
generic module SequenceNumber {
provides interface Packet;
};
command void Packet.clear(message_t* msg) {
- uint8_t len;
- void* payload = call SubPacket.getPayload(msg, &len);
- memset(payload, len, 0);
+ void* payload = call SubPacket.getPayload(msg, call SubPacket.maxPayloadLength());
+ call SubPacket.clear();
+ if (payload != NULL) {
+ memset(payload, sizeof(seq_header_t), 0);
+ }
}
command uint8_t Packet.payloadLength(message_t* msg) {
return SubPacket.maxPayloadLength(msg) - SEQNO_OFFSET;
}
- command void* Packet.getPayload(message_t* msg, uint8_t* len) {
- uint8_t* payload = call SubPacket.getPayload(msg, len);
- if (len != NULL) {
- *len -= SEQNO_OFFSET;
+ command void* Packet.getPayload(message_t* msg, uint8_t len) {
+ uint8_t* payload = call SubPacket.getPayload(msg, len + SEQNO_OFFSET);
+ if (payload != NULL) {
+ payload += SEQNO_OFFSET;
}
- return payload + SEQNO_OFFSET;
- }
+ return payload;
+ }
}
</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
command bool isForMe(message_t* amsg);
command am_id_t type(message_t* amsg);
command void setType(message_t* amsg, am_id_t t);
+ command am_group_t group(message_t* amsg);
+ command void setGroup(message_t* amsg, am_group_t grp);
+ command am_group_t localGroup();
}
</pre>
<p>The command address() returns the local AM address of the
-node. AMPacket provides accessors for its two fields, destination and
-type. It also provides commands to set these fields, for the same
-reason that Packet allows a caller to set the payload length.
-Packet interfaces SHOULD provide accessors
-and mutators for all of their fields to enable queues and other
-buffering to store values in a packet buffer. Typically, a component
-stores these values in the packet buffer itself (where the field is),
-but when necessary it may use the metadata region of message_t or other
-locations.</p>
+node. AMPacket provides accessors for its four fields, destination,
+source, type and group. It also provides commands to set these
+fields, for the same
+reason that Packet allows a caller to set the payload length. Packet
+interfaces SHOULD provide accessors and mutators for all of their
+fields to enable queues and other buffering to store values in a
+packet buffer. Typically, a component stores these values in the
+packet buffer itself (where the field is), but when necessary it may
+use the metadata region of message_t or other locations.</p>
+<p>The group field refers to the AM group, a logical network identifier.
+Link layers will typically only signal reception for packets whose AM
+group matches the node's, which <tt class="docutils literal"><span class="pre">localGroup</span></tt> returns.</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);
+ command void* getPayload(message_t* msg, uint8_t len);
}
</pre>
<p>while this is the AMSend interface:</p>
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, uint8_t len);
}
</pre>
<p>Sending interfaces MUST include these four commands and one event.
The duplication of some of the commands in Packet is solely for ease
of use: <tt class="docutils literal"><span class="pre">maxPayloadLength</span></tt> and <tt class="docutils literal"><span class="pre">getPayload</span></tt> MUST behave
-identically as <tt class="docutils literal"><span class="pre">Packet.maxPayloadLength</span></tt> and <tt class="docutils literal"><span class="pre">Packet.getPayload</span></tt>,
-with the exception that the latter has no length parameter (it should
-behave as if the length parameter of the <tt class="docutils literal"><span class="pre">Packet</span></tt> call were
-NULL). Their inclusion is so that components do not have to wire to
+identically as <tt class="docutils literal"><span class="pre">Packet.maxPayloadLength</span></tt> and <tt class="docutils literal"><span class="pre">Packet.getPayload.</span></tt>
+Their inclusion is so that components do not have to wire to
both Packet and the sending interface for basic use cases.</p>
<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 serialize them onto sending interface, or they can introduce
a new sending interface that supports multiple pending transmissions.</p>
<p>The cancel command allows a sender to cancel the current transmission.
-A call to cancel when there is no pending sendDone event MUST return FAIL.
-If there is a pending sendDone event and the cancel returns SUCCESS, then
-the packet layer MUST NOT transmit the packet and MUST signal sendDone
-with ECANCEL as its error code. If there is a pending sendDone event
-and cancel returns FAIL, then sendDone SHOULD occur as if the cancel
-was not called.</p>
+A call to cancel when there is no pending sendDone event MUST return
+FAIL. If there is a pending sendDone event and the cancel returns
+SUCCESS, then the packet layer MUST NOT transmit the packet and MUST
+signal sendDone with ECANCEL as its error code. If there is a pending
+sendDone event and cancel returns FAIL, then sendDone MUST 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 {
event message_t* receive(message_t* msg, void* payload, uint8_t len);
- command void* getPayload(message_t* msg, uint8_t* len);
- command uint8_t payloadLength(message_t* msg);
}
</pre>
-<p>A call to <tt class="docutils literal"><span class="pre">Receive.getPayload()</span></tt> MUST behave identically to a call
-to <tt class="docutils literal"><span class="pre">Packet.getPayload()</span></tt>. The <tt class="docutils literal"><span class="pre">receive()</span></tt> event's <tt class="docutils literal"><span class="pre">payload</span></tt>
-parameter MUST be identical to what a call to <tt class="docutils literal"><span class="pre">getPayload()</span></tt> would
-return, and the <tt class="docutils literal"><span class="pre">len</span></tt> parameter MUST be identical to the length that
-a call to <tt class="docutils literal"><span class="pre">getPayload</span></tt> would return. These parameters are for
+<p>The <tt class="docutils literal"><span class="pre">receive()</span></tt> event's <tt class="docutils literal"><span class="pre">payload</span></tt> parameter MUST be identical to
+what a call to the corresponding <tt class="docutils literal"><span class="pre">Packet.getPayload()</span></tt> would return,
+and the <tt class="docutils literal"><span class="pre">len</span></tt> parameter MUST be identical to the length that a call
+to <tt class="docutils literal"><span class="pre">Packet.getPayload</span></tt> would return. These parameters are for
convenience, as they are commonly used by receive handlers, and their
-presence removes the need for a call to <tt class="docutils literal"><span class="pre">getPayload()</span></tt>, while
-<tt class="docutils literal"><span class="pre">getPayload()</span></tt> is a convenience so a component does not have to wire
-to <tt class="docutils literal"><span class="pre">Packet.</span></tt> The command <tt class="docutils literal"><span class="pre">payloadLength</span></tt> has a similar motivation
-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
-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
+presence removes the need for a call to <tt class="docutils literal"><span class="pre">getPayload()</span></tt>. Unlike Send,
+Receive does not have a convenience <tt class="docutils literal"><span class="pre">getPayload</span></tt> call, because doing
+so prevents fan-in. As Receive has only a single event, users of
+Receive can be wired multiple times.</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 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
-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
+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
upper layer cannot handle packets quickly enough it will end up
holding all of them, starving lower layers and possibly preventing
packet reception.</p>
<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">
projects / tinyos-2.x.git / blobdiff