Full update.

[tinyos-2.x.git] / doc / txt / tep111.txt

diff --git a/doc/txt/tep111.txt b/doc/txt/tep111.txt
index 0dc1ca4487bbab94bf03c5419694c4eeb48db5b7..17fe6f61ae8ddbeeab9d14653467486ae06a8c2f 100644 (file)
--- a/doc/txt/tep111.txt
+++ b/doc/txt/tep111.txt
@@ -126,6 +126,11 @@ 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 ``TOS_Msg`` very difficult.
 
+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 ``recv(2)`` for details). 
+TinyOS 2.x continues this approach.
+
 2. message_t
 ====================================================================
 
@@ -143,7 +148,11 @@ This format keeps data at a fixed offset, 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 ``memmove(3)``
-operation (essentially, a copy).
+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.
 
 The header, footer, and metadata formats are all opaque. Source code
 cannot access fields directly. Instead, data-link layers provide access
@@ -259,10 +268,11 @@ for other components.
 
 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.
+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.
 
-A packet header does not necessarily start at the beginning of
+A packet header MAY start somewhere besides the beginning of
 the message_t. For example, consider the Telos platform::
 
   typedef union message_header {
@@ -377,21 +387,60 @@ the CC2420 metadata structure::
     nx_uint16_t time;
   } cc2420_metadata_t;
 
-5. Implementation
+3.5 Variable Sized Structures
+----------------------------------------------------------------
+
+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.
+
+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.
+
+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 ``memmove(3)``
+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 ``data`` 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.
+
+
+
+4. Implementation
 ====================================================================
 
 The definition of message_t can be found in 
-``tinyos-2.x/tos/types/message.h``. The definition of the CC2420
+``tinyos-2.x/tos/types/message.h``. 
+
+The definition of the CC2420
 message format can be found in ``tinyos-2.x/tos/chips/cc2420/CC2420.h``.
+
 The defintion of the CC1000 message format can be found in 
-``tinyos-2.x/tos/chips/cc1000/CC1000Msg.h``. The definition
+``tinyos-2.x/tos/chips/cc1000/CC1000Msg.h``. 
+
+The definition
 of the standard serial stack packet format can be found in
-``tinyos-2.x/tos/lib/serial/Serial.h''. The definition of
-the telosb packet format can be found in 
+``tinyos-2.x/tos/lib/serial/Serial.h`` 
+
+The definition of
+the telos family packet format can be found in 
 ``tinyos-2.x/tos/platform/telosa/platform_message.h`` and the micaz format can be found in
 ``tinyos-2.x/tos/platforms/micaz/platform_message.h``.
 
-6. Author's Address
+5. Author's Address
 ====================================================================
 
 | Philip Levis