[Tinyos-2-commits] CVS: tinyos-2.x/doc/txt tep111.txt,1.6,1.7

[Phil Levis]

Update of /cvsroot/tinyos/tinyos-2.x/doc/txt
In directory sc8-pr-cvs10.sourceforge.net:/tmp/cvs-serv15311/txt

Modified Files:
	tep111.txt 
Log Message:
Include suggestions from community review.


Index: tep111.txt
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/doc/txt/tep111.txt,v
retrieving revision 1.6
retrieving revision 1.7
diff -C2 -d -r1.6 -r1.7
*** tep111.txt	10 Jan 2007 18:33:38 -0000	1.6
--- tep111.txt	5 Feb 2007 20:23:35 -0000	1.7
***************
*** 27,31 ****
  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. 
  
  1. Introduction
--- 27,33 ----
  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.
! 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
***************
*** 121,125 ****
  
  The ``data`` payload is especially problematic. Many
! components refer to this field, so it must be at a fixed offset.
  Depending on the underlying link layer, the header fields 
  preceding it might have different lengths, and packet-level radios
--- 123,128 ----
  
  The ``data`` 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 
  preceding it might have different lengths, and packet-level radios
***************
*** 145,149 ****
    } message_t;
  
! This format keeps data at a fixed but platform dependent offset, which 
  is important when
  passing a message buffer between two different link layers. If the
--- 148,152 ----
    } message_t;
  
! 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
***************
*** 164,171 ****
  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. 
  Second, it forces structures to be aligned on byte boundaries, 
  circumventing issues with the 
! alignment of packet buffers and field offsets within them.
  For example, the CC1000 radio implementation defines
  its structures in ``CC1000Msg.h``::
--- 167,176 ----
  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 [1]_.
  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.
  For example, the CC1000 radio implementation defines
  its structures in ``CC1000Msg.h``::
***************
*** 197,201 ****
  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
  or metadata section. The ``platform_message.h`` of the mica2
  looks like this::
--- 202,206 ----
  named ``platform_message.h``. The mica2 platform, for example, has
  two data link layers: the CC1000 radio and the TinyOS serial
! stack [2]_. The serial packet format does not have a footer
  or metadata section. The ``platform_message.h`` of the mica2
  looks like this::
***************
*** 251,255 ****
  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 ``AMPacket`` 
  which provides access commands to AM fields. In TinyOS 1.x, a 
--- 256,263 ----
  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.
! 
  For example, active messages have an interface named ``AMPacket`` 
  which provides access commands to AM fields. In TinyOS 1.x, a 
***************
*** 258,267 ****
  The most basic of these interfaces is Packet, which provides
  access to a packet payload. TEP 116 describes common TinyOS 
! packet ADT interfaces [2]_. 
  
  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. 
  
  3.1 Headers
--- 266,276 ----
  The most basic of these interfaces is Packet, which provides
  access to a packet payload. TEP 116 describes common TinyOS 
! 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.
! 
  
  3.1 Headers
***************
*** 301,304 ****
--- 310,314 ----
                    +-----+------------+                 
  
+ 
  Neither the CC2420 nor the serial stack has packet footers, and
  the serial stack does not have any metadata. 
***************
*** 457,463 ****
  ====================================================================
  
! .. [1] TEP 113: Serial Communication.
  
! .. [2] TEP 116: Packet Protocols.
  
  
--- 467,475 ----
  ====================================================================
  
! .. [1] `nesC: A Programming Language for Deeply Embedded Networks. <http://nescc.sourceforge.net>`_
  
! .. [2] TEP 113: Serial Communication.
! 
! .. [3] TEP 116: Packet Protocols.