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

Mon Feb 11 10:11:23 PST 2008

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

Modified Files:
	tep116.txt 
Log Message:
Incorporated 116 comments.

Index: tep116.txt
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/doc/txt/tep116.txt,v
retrieving revision 1.11
retrieving revision 1.12
diff -C2 -d -r1.11 -r1.12
*** tep116.txt	13 Sep 2007 23:09:19 -0000	1.11
--- tep116.txt	11 Feb 2008 18:11:20 -0000	1.12
***************
*** 128,135 ****
  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.

--- 128,135 ----
  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.

***************
*** 151,163 ****
  ``maxPayloadLength``.

! The Packet interface assumes that headers have a fixed size. 
! It is difficult to return a pointer into the data region when its 
! position will only be known once the header values are bound.

! Generally, an incoming call to the Packet interface of a protocol
! has an accompanying outgoing call to the Packet interface of the 
! component below it. The one exception to this is the data link
! layer. For example, if there is a network that introduces
! 16-bit sequence numbers to packets, it might look like this::

    generic module SequenceNumber {
--- 151,176 ----
  ``maxPayloadLength``.

! The Packet interface assumes that headers have a fixed size. It is
! difficult to return a pointer into the data region when its position
! will only be known once the header values are bound.

! The ``clear`` command clears out all headers, footers, and metadata
! for lower layers. For example, calling ``clear`` on a routing
! component, such as CollectionSenderC[4]_, will clear out the
! collection headers and footers. Furthermore, CollectionSenderC will
! recursively call ``clear`` on the layer below it, clearing out the
! link layer headers and footers. Calling ``clear`` is typically
! necessary when moving a packet across two link layers. Otherwise, the
! destination link layer may incorrectly interpret metadata from the
! source link layer, and, for example, transmit the packet on the wrong
! RF channel. Because ``clear`` prepares a packet for a particular link
! layer, in this example correct code would call the command on the
! destination link layer, not the source link layer.
! 
! Typically, an incoming call to the Packet interface of a protocol has
! an accompanying outgoing call to the Packet interface of the component
! below it. The one exception to this is the data link layer. For
! example, if there is a network that introduces 16-bit sequence numbers
! to packets, it might look like this::

    generic module SequenceNumber {
***************
*** 177,181 ****
        uint8_t len;
        void* payload = call SubPacket.getPayload(msg, call SubPacket.maxPayloadLength());
!       memset(payload, len, 0);
      }

--- 190,197 ----
        uint8_t len;
        void* payload = call SubPacket.getPayload(msg, call SubPacket.maxPayloadLength());
!       call SubPacket.clear();
!       if (payload != NULL) {
!         memset(payload, sizeof(seq_header_t), 0);
!       }
      }

***************
*** 232,235 ****
--- 248,254 ----
      command am_id_t type(message_t* amsg);
      command void setType(message_t* amsg, am_id_t t);
+     command am_group_t group(message_t* amsg);
+     command void setGroup(message_t* amsg, am_group_t grp);
+     command am_group_t localGroup();
    }

***************
*** 238,248 ****
  node. AMPacket provides accessors for its two fields, destination and
  type. It also provides commands to set these fields, for the same
! reason that Packet allows a caller to set the payload length.
! Packet interfaces SHOULD provide accessors
! and mutators for all of their fields to enable queues and other
! buffering to store values in a packet buffer. Typically, a component
! stores these values in the packet buffer itself (where the field is),
! but when necessary it may use the metadata region of message_t or other
! locations.

  2.2 Sending interfaces
--- 257,270 ----
  node. AMPacket provides accessors for its two fields, destination and
  type. It also provides commands to set these fields, for the same
! reason that Packet allows a caller to set the payload length.  Packet
! interfaces SHOULD provide accessors and mutators for all of their
! fields to enable queues and other buffering to store values in a
! packet buffer. Typically, a component stores these values in the
! packet buffer itself (where the field is), but when necessary it may
! use the metadata region of message_t or other locations.
! 
! The group field refers to the AM group, a logical network identifier.
! Link layers will typically only signal reception for packets whose AM
! group matches the node's, which ``localGroup`` returns.

  2.2 Sending interfaces
***************
*** 302,311 ****

  The cancel command allows a sender to cancel the current transmission.
! A call to cancel when there is no pending sendDone event MUST return FAIL.
! If there is a pending sendDone event and the cancel returns SUCCESS, then
! the packet layer MUST NOT transmit the packet and MUST signal sendDone
! with ECANCEL as its error code. If there is a pending sendDone event
! and cancel returns FAIL, then sendDone SHOULD occur as if the cancel
! was not called. 

  2.3 Receive interface
--- 324,333 ----

  The cancel command allows a sender to cancel the current transmission.
! A call to cancel when there is no pending sendDone event MUST return
! FAIL.  If there is a pending sendDone event and the cancel returns
! SUCCESS, then the packet layer MUST NOT transmit the packet and MUST
! signal sendDone with ECANCEL as its error code. If there is a pending
! sendDone event and cancel returns FAIL, then sendDone MUST occur as if
! the cancel was not called.

  2.3 Receive interface
***************
*** 318,343 ****
    }

! A call to ``Receive.getPayload()`` MUST behave identically to a call
! to ``Packet.getPayload()``. The ``receive()`` event's ``payload``
! parameter MUST be identical to what a call to ``getPayload()`` would
! return, and the ``len`` parameter MUST be identical to the length that
! a call to ``getPayload`` would return. These parameters are for
  convenience, as they are commonly used by receive handlers, and their
! presence removes the need for a call to ``getPayload()``, while
! ``getPayload()`` is a convenience so a component does not have to wire
! to ``Packet.`` The command ``payloadLength`` has a similar motivation
! and the same semantics as its twin in ``Packet``.

! Receive has a *buffer-swap* policy. The handler of the event MUST return
! a pointer to a valid message buffer for the signaler to use. This
! approach enforces an equilibrium between upper and lower packet 
! layers. If an upper layer cannot handle packets as quickly as they
! are arriving, it still has to return a valid buffer to the lower
  layer. This buffer could be the ``msg`` parameter passed to it: it
  just returns the buffer it was given without looking at it. Following
! this policy means that a data-rate mismatch in an upper-level component 
! will be isolated to that component. It will drop packets, but it will
! not prevent other components from receiving packets. If an upper
! layer did not have to return a buffer immediately, then when an
  upper layer cannot handle packets quickly enough it will end up
  holding all of them, starving lower layers and possibly preventing
--- 340,364 ----
    }

! The ``receive()`` event's ``payload`` parameter MUST be identical to
! what a call to the corresponding ``Packet.getPayload()`` would return,
! and the ``len`` parameter MUST be identical to the length that a call
! to ``Packet.getPayload`` would return. These parameters are for
  convenience, as they are commonly used by receive handlers, and their
! presence removes the need for a call to ``getPayload()``. Unlike Send,
! Receive does not have a convenience ``getPayload`` call, because doing
! so prevents fan-in. As Receive has only a single event, users of
! Receive can be wired multiple times.

! Receive has a *buffer-swap* policy. The handler of the event MUST
! return a pointer to a valid message buffer for the signaler to
! use. This approach enforces an equilibrium between upper and lower
! packet layers. If an upper layer cannot handle packets as quickly as
! they are arriving, it still has to return a valid buffer to the lower
  layer. This buffer could be the ``msg`` parameter passed to it: it
  just returns the buffer it was given without looking at it. Following
! this policy means that a data-rate mismatch in an upper-level
! component will be isolated to that component. It will drop packets,
! but it will not prevent other components from receiving packets. If an
! upper layer did not have to return a buffer immediately, then when an
  upper layer cannot handle packets quickly enough it will end up
  holding all of them, starving lower layers and possibly preventing