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 }
<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>
+<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>Philip Levis</td></tr>
-<tr class="field"><th class="docinfo-name">Draft-Created:</th><td class="field-body">11-Jul-2005</td>
-</tr>
-<tr class="field"><th class="docinfo-name">Draft-Version:</th><td class="field-body">1.1.2.12</td>
-</tr>
-<tr class="field"><th class="docinfo-name">Draft-Modified:</th><td class="field-body">2006-06-13</td>
-</tr>
-<tr class="field"><th class="docinfo-name">Draft-Discuss:</th><td class="field-body">TinyOS Developer List <tinyos-devel at mail.millennium.berkeley.edu></td>
-</tr>
</tbody>
</table>
<div class="note">
<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
-<tt class="docutils literal"><span class="pre">message_t</span></tt> is specified, and how data link layers should access it.</p>
+<tt class="docutils literal"><span class="pre">message_t</span></tt> is specified, and how data link layers should access it.
+The major goal of <tt class="docutils literal"><span class="pre">message_t</span></tt> is to allow datagrams to be passed between
+different link layers as a contiguous region of memory with zero copies.</p>
</div>
<div class="section">
<h1><a id="introduction" name="introduction">1. Introduction</a></h1>
uint8_t receiveSecurityMode;
} TOS_Msg;
</pre>
-<p>while on a mote with a CC420 radio (e.g., micaZ), <tt class="docutils literal"><span class="pre">TOS_Msg</span></tt> is defined as:</p>
+<p>while on a mote with a CC2420 radio (e.g., micaZ), <tt class="docutils literal"><span class="pre">TOS_Msg</span></tt> is defined as:</p>
<pre class="literal-block">
typedef struct TOS_Msg {
// The following fields are transmitted/received on the radio.
of their headers while allowing implementations to directly access
header fields. This is very difficult to do in C.</p>
<p>The <tt class="docutils literal"><span class="pre">data</span></tt> payload is especially problematic. Many
-components refer to this field, so it must be at a fixed offset.
+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
preceding it might have different lengths, and packet-level radios
often require packets to be contiguous memory regions. Overall, these
complexities make specifying the format of <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).
+TinyOS 2.x continues this approach.</p>
</div>
<div class="section">
<h1><a id="id1" name="id1">2. message_t</a></h1>
nx_uint8_t metadata[sizeof(message_metadata_t)];
} message_t;
</pre>
-<p>This format keeps data at a fixed offset, which is important when
+<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).</p>
+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
+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
<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
-reasons. First, external types ensure cross-platform compatibility.
+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
-alignment of packet buffers and field offsets within them.
+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.
For example, the CC1000 radio implementation defines
its structures in <tt class="docutils literal"><span class="pre">CC1000Msg.h</span></tt>:</p>
<pre class="literal-block">
needed. These definitions MUST be in a file in a platform directory
named <tt class="docutils literal"><span class="pre">platform_message.h</span></tt>. The mica2 platform, for example, has
two data link layers: the CC1000 radio and the TinyOS serial
-stack <a class="footnote-reference" href="#id4" id="id2" name="id2">[1]</a>. The serial packet format does not have a footer
+stack <a class="footnote-reference" href="#id6" id="id3" name="id3">[2]</a>. The serial packet format does not have a footer
or metadata section. The <tt class="docutils literal"><span class="pre">platform_message.h</span></tt> of the mica2
looks like this:</p>
<pre class="literal-block">
<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.
-For example, active messages have an interface named <tt class="docutils literal"><span class="pre">AMPacket</span></tt>
+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,
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
-packet ADT interfaces <a class="footnote-reference" href="#id5" id="id3" name="id3">[2]</a>.</p>
+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
components, as they are aware of the actual packet format. They can
therefore implement the interfaces that provide access to the fields
<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 packets are stored contiguously, the layout of a packet
-in memory is not the same as the layout of its nesC structure.</p>
-<p>A packet header does not necessarily start at the beginning of
+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>
<pre class="literal-block">
typedef union message_header {
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
-longer than TOSH_DATA_LENGTH, it MUST discard the packet.</p>
+longer than TOSH_DATA_LENGTH, it MUST discard the packet. As
+headers are right justified to the beginning of the data payload,
+the data payloads of all link layers on a platform start
+at the same fixed offset from the beginning of the message buffer.</p>
</div>
<div class="section">
<h2><a id="footer" name="footer">3.3 Footer</a></h2>
} cc2420_metadata_t;
</pre>
</div>
+<div class="section">
+<h2><a id="variable-sized-structures" name="variable-sized-structures">3.5 Variable Sized Structures</a></h2>
+<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.
+There are three general approaches that can be used.</p>
+<p>If the underlying link hardware is byte-based, the header can
+just be stored at the beginning of the message_t, giving it
+a known offset. There may be padding between the header and
+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
+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
+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
+on completion of transmission, they need to be moved back.
+Alternatively, the radio stack can institute a single
+copy at the botttom layer.</p>
+</div>
</div>
<div class="section">
-<h1><a id="implementation" name="implementation">5. Implementation</a></h1>
+<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>. 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>.
-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>. The definition
+<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
+<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> <span class="pre">The</span> <span class="pre">definition</span> <span class="pre">of</span>
-<span class="pre">the</span> <span class="pre">telosb</span> <span class="pre">packet</span> <span class="pre">format</span> <span class="pre">can</span> <span class="pre">be</span> <span class="pre">found</span> <span class="pre">in</span>
-<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/lib/serial/Serial.h</span></tt></p>
+<p>The definition of
+the telos family packet format can be found in
+<tt class="docutils literal"><span class="pre">tinyos-2.x/tos/platform/telosa/platform_message.h</span></tt> and the micaz format can be found in
<tt class="docutils literal"><span class="pre">tinyos-2.x/tos/platforms/micaz/platform_message.h</span></tt>.</p>
</div>
<div class="section">
-<h1><a id="author-s-address" name="author-s-address">6. Author's Address</a></h1>
+<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>
<div class="section">
<h1><a id="citations" name="citations">6. Citations</a></h1>
-<table class="docutils footnote" frame="void" id="id4" rules="none">
+<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="#id2" name="id4">[1]</a></td><td>TEP 113: Serial Communication.</td></tr>
+<tr><td class="label"><a class="fn-backref" href="#id2" name="id5">[1]</a></td><td><a class="reference" href="http://nescc.sourceforge.net">nesC: A Programming Language for Deeply Embedded Networks.</a></td></tr>
</tbody>
</table>
-<table class="docutils footnote" frame="void" id="id5" rules="none">
+<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="#id3" name="id6">[2]</a></td><td>TEP 113: Serial Communication.</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 class="fn-backref" href="#id3" name="id5">[2]</a></td><td>TEP 116: Packet Protocols.</td></tr>
+<tr><td class="label"><a class="fn-backref" href="#id4" name="id7">[3]</a></td><td>TEP 116: Packet Protocols.</td></tr>
</tbody>
</table>
</div>
projects / tinyos-2.x.git / blobdiff