:TEP: 111
:Group: Core Working Group
:Type: Documentary
-:Status: Draft
+:Status: Final
:TinyOS-Version: 2.x
:Author: Philip Levis
-:Draft-Created: 11-Jul-2005
-:Draft-Version: $Revision$
-:Draft-Modified: $Date$
-:Draft-Discuss: TinyOS Developer List <tinyos-devel at mail.millennium.berkeley.edu>
-
.. Note::
This memo documents a part of TinyOS for the TinyOS Community, and
This memo covers the TinyOS 2.x message buffer abstraction, ``message_t``.
It describes the message buffer design considerations, how and where
-``message_t`` is specified, and how data link layers should access it.
+``message_t`` is specified, and how data link layers should access it.
+The major goal of ``message_t`` is to allow datagrams to be passed between
+different link layers as a contiguous region of memory with zero copies.
1. Introduction
====================================================================
uint8_t receiveSecurityMode;
} TOS_Msg;
-while on a mote with a CC420 radio (e.g., micaZ), ``TOS_Msg`` is defined as::
+while on a mote with a CC2420 radio (e.g., micaZ), ``TOS_Msg`` is defined as::
typedef struct TOS_Msg {
// The following fields are transmitted/received on the radio.
header fields. This is very difficult to do in C.
The ``data`` 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
nx_uint8_t metadata[sizeof(message_metadata_t)];
} message_t;
-This format keeps data at a fixed but platform dependent offset, which
+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
Every link layer defines its header, footer, and metadata
structures. These structures MUST be external structs (``nx_struct``),
and all of their fields MUST be external types (``nx_*``), for two
-reasons. First, external types ensure cross-platform compatibility.
+reasons. First, external types ensure cross-platform compatibility [1]_.
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 ``CC1000Msg.h``::
needed. These definitions MUST be in a file in a platform directory
named ``platform_message.h``. The mica2 platform, for example, has
two data link layers: the CC1000 radio and the TinyOS serial
-stack [1]_. The serial packet format does not have a footer
+stack [2]_. The serial packet format does not have a footer
or metadata section. The ``platform_message.h`` of the mica2
looks like this::
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.
+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.
+
For example, active messages have an interface named ``AMPacket``
which provides access commands to AM fields. In TinyOS 1.x, a
component would directly access ``TOS_Msg.addr``; in TinyOS 2.x,
a component calls ``AMPacket.getAddress(msg)``.
The most basic of these interfaces is Packet, which provides
access to a packet payload. TEP 116 describes common TinyOS
-packet ADT interfaces [2]_.
+packet ADT interfaces [3]_.
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.
+for other components.
+
3.1 Headers
----------------------------------------------------------------
Serial | hdr | data |
+-----+------------+
+
Neither the CC2420 nor the serial stack has packet footers, and
the serial stack does not have any metadata.
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.
+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.
3.3 Footer
----------------------------------------------------------------
6. Citations
====================================================================
-.. [1] TEP 113: Serial Communication.
+.. [1] `nesC: A Programming Language for Deeply Embedded Networks. <http://nescc.sourceforge.net>`_
+
+.. [2] TEP 113: Serial Communication.
-.. [2] TEP 116: Packet Protocols.
+.. [3] TEP 116: Packet Protocols.
projects / tinyos-2.x.git / blobdiff