[Tinyos-2-commits] CVS: tinyos-2.x/doc/txt tep116.txt,1.10,1.11

[Phil Levis]

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

Modified Files:
	tep116.txt 
Log Message:
116 updated.


Index: tep116.txt
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/doc/txt/tep116.txt,v
retrieving revision 1.10
retrieving revision 1.11
diff -C2 -d -r1.10 -r1.11
*** tep116.txt	28 Mar 2007 05:46:28 -0000	1.10
--- tep116.txt	13 Sep 2007 23:09:19 -0000	1.11
***************
*** 7,11 ****
  :Type: Documentary
  :Status: Draft
! :TinyOS-Version: 2.x
  :Author: Philip Levis
  
--- 7,11 ----
  :Type: Documentary
  :Status: Draft
! :TinyOS-Version: > 2.1
  :Author: Philip Levis
  
***************
*** 123,149 ****
      command void setPayLoadLength(message_t* msg, uint8_t len);
      command uint8_t maxPayloadLength();
!     command void* getPayload(message_t* msg, uint8_t* len);
    }
  
  A component can obtain a pointer to its data region within a packet by
! calling ``getPayload()`` the optional ``len`` argument is for also
! obtaining the size of the data region. A provider of a Packet
! interface MUST check if ``len`` is NULL and ignore it if it is. A
! component can also obtain the size of the data region with a call to
! ``payloadLength``. 
  
! A component can set the payload length with
! ``setPayLoadLength.`` 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. 
  
  The distinction between ``payloadLength`` and ``maxPayloadLength``
! 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. 
  
  The Packet interface assumes that headers have a fixed size. 
--- 123,153 ----
      command void setPayLoadLength(message_t* msg, uint8_t len);
      command uint8_t maxPayloadLength();
!     command void* getPayload(message_t* msg, uint8_t len);
    }
  
  A component can obtain a pointer to its data region within a packet by
! calling ``getPayload()``. A call to this command includes the length
! the caller requires. The command ``maxPayloadLength`` returns the maximum
! length the payload can be: if the ``len`` parameter to ``getPayload``
! is greater than the value ``maxPayloadLength``would return,
! ``getPayload`` MUST return NULL.
  
! 
! A component can set the payload length with ``setPayLoadLength.`` A
! component can obtain the size of the data region of packet in use with
! a call to ``payloadLength``. As Send interfaces always include a
! length parameter in their send call, ``setPayLoadLength`` 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.
  
  The distinction between ``payloadLength`` and ``maxPayloadLength``
! 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
! ``payloadLength`` must be less than or equal to the return value of
! ``maxPayloadLength``.
  
  The Packet interface assumes that headers have a fixed size. 
***************
*** 172,176 ****
      command void Packet.clear(message_t* msg) {
        uint8_t len;
!       void* payload = call SubPacket.getPayload(msg, &len);
        memset(payload, len, 0);
      }
--- 176,180 ----
      command void Packet.clear(message_t* msg) {
        uint8_t len;
!       void* payload = call SubPacket.getPayload(msg, call SubPacket.maxPayloadLength());
        memset(payload, len, 0);
      }
***************
*** 188,197 ****
      }
  
!     command void* Packet.getPayload(message_t* msg, uint8_t* len) {
!       uint8_t* payload = call SubPacket.getPayload(msg, len);
!       if (len != NULL) {
!         *len -= SEQNO_OFFSET;
        }
!       return payload + SEQNO_OFFSET; 
      } 
    }
--- 192,201 ----
      }
  
!     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;
      } 
    }
***************
*** 258,262 ****
  
      command uint8_t maxPayloadLength();
!     command void* getPayload(message_t* msg);
    }
  
--- 262,266 ----
  
      command uint8_t maxPayloadLength();
!     command void* getPayload(message_t* msg, uint8_t len);
    }
  
***************
*** 269,273 ****
  
      command uint8_t maxPayloadLength();
!     command void* getPayload(message_t* msg); 
    }
  
--- 273,277 ----
  
      command uint8_t maxPayloadLength();
!     command void* getPayload(message_t* msg, uint8_t len); 
    }
  
***************
*** 275,282 ****
  The duplication of some of the commands in Packet is solely for ease
  of use: ``maxPayloadLength`` and ``getPayload`` MUST behave
! identically as ``Packet.maxPayloadLength`` and ``Packet.getPayload``,
! with the exception that the latter has no length parameter (it should
! behave as if the length parameter of the ``Packet`` call were
! NULL). Their inclusion is so that components do not have to wire to
  both Packet and the sending interface for basic use cases.
  
--- 279,284 ----
  The duplication of some of the commands in Packet is solely for ease
  of use: ``maxPayloadLength`` and ``getPayload`` MUST behave
! identically as ``Packet.maxPayloadLength`` and ``Packet.getPayload.``
! Their inclusion is so that components do not have to wire to
  both Packet and the sending interface for basic use cases.
  
***************
*** 314,319 ****
    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);
    }
  
--- 316,319 ----
***************
*** 682,686 ****
  .. [4] TEP 113: Serial Communication.
  
- 
- 
-  
--- 682,683 ----