[Tinyos-2-commits] CVS: tinyos-2.x/doc/html tep116.html,1.13,1.14
Phil Levis
scipio at users.sourceforge.net
Thu Sep 13 16:09:21 PDT 2007
Update of /cvsroot/tinyos/tinyos-2.x/doc/html
In directory sc8-pr-cvs10.sourceforge.net:/tmp/cvs-serv26986/html
Modified Files:
tep116.html
Log Message:
116 updated.
Index: tep116.html
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/doc/html/tep116.html,v
retrieving revision 1.13
retrieving revision 1.14
diff -C2 -d -r1.13 -r1.14
*** tep116.html 14 Aug 2007 18:58:00 -0000 1.13
--- tep116.html 13 Sep 2007 23:09:19 -0000 1.14
***************
*** 4,8 ****
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
! <meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
<title>Packet Protocols</title>
<meta name="author" content="Philip Levis" />
--- 4,8 ----
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
! <meta name="generator" content="Docutils 0.4.1: http://docutils.sourceforge.net/" />
<title>Packet Protocols</title>
<meta name="author" content="Philip Levis" />
***************
*** 293,297 ****
<tr><th class="docinfo-name">Status:</th>
<td>Draft</td></tr>
! <tr class="field"><th class="docinfo-name">TinyOS-Version:</th><td class="field-body">2.x</td>
</tr>
<tr><th class="docinfo-name">Author:</th>
--- 293,297 ----
<tr><th class="docinfo-name">Status:</th>
<td>Draft</td></tr>
! <tr class="field"><th class="docinfo-name">TinyOS-Version:</th><td class="field-body">> 2.1</td>
</tr>
<tr><th class="docinfo-name">Author:</th>
***************
*** 405,429 ****
command void setPayLoadLength(message_t* msg, uint8_t len);
command uint8_t maxPayloadLength();
! command void* getPayload(message_t* msg, uint8_t* len);
}
</pre>
<p>A component can obtain a pointer to its data region within a packet by
! calling <tt class="docutils literal"><span class="pre">getPayload()</span></tt> the optional <tt class="docutils literal"><span class="pre">len</span></tt> argument is for also
! obtaining the size of the data region. A provider of a Packet
! interface MUST check if <tt class="docutils literal"><span class="pre">len</span></tt> is NULL and ignore it if it is. A
! component can also obtain the size of the data region with a call to
! <tt class="docutils literal"><span class="pre">payloadLength</span></tt>.</p>
! <p>A component can set the payload length with
! <tt class="docutils literal"><span class="pre">setPayLoadLength.</span></tt> 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.</p>
<p>The distinction between <tt class="docutils literal"><span class="pre">payloadLength</span></tt> and <tt class="docutils literal"><span class="pre">maxPayloadLength</span></tt>
! 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.</p>
<p>The Packet interface assumes that headers have a fixed size.
It is difficult to return a pointer into the data region when its
--- 405,432 ----
command void setPayLoadLength(message_t* msg, uint8_t len);
command uint8_t maxPayloadLength();
! command void* getPayload(message_t* msg, uint8_t len);
}
</pre>
<p>A component can obtain a pointer to its data region within a packet by
! calling <tt class="docutils literal"><span class="pre">getPayload()</span></tt>. A call to this command includes the length
! the caller requires. The command <tt class="docutils literal"><span class="pre">maxPayloadLength</span></tt> returns the maximum
! length the payload can be: if the <tt class="docutils literal"><span class="pre">len</span></tt> parameter to <tt class="docutils literal"><span class="pre">getPayload</span></tt>
! is greater than the value <tt class="docutils literal"><span class="pre">maxPayloadLength``would</span> <span class="pre">return,</span>
! <span class="pre">``getPayload</span></tt> MUST return NULL.</p>
! <p>A component can set the payload length with <tt class="docutils literal"><span class="pre">setPayLoadLength.</span></tt> A
! component can obtain the size of the data region of packet in use with
! a call to <tt class="docutils literal"><span class="pre">payloadLength</span></tt>. As Send interfaces always include a
! length parameter in their send call, <tt class="docutils literal"><span class="pre">setPayLoadLength</span></tt> 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.</p>
<p>The distinction between <tt class="docutils literal"><span class="pre">payloadLength</span></tt> and <tt class="docutils literal"><span class="pre">maxPayloadLength</span></tt>
! 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
! <tt class="docutils literal"><span class="pre">payloadLength</span></tt> must be less than or equal to the return value of
! <tt class="docutils literal"><span class="pre">maxPayloadLength</span></tt>.</p>
<p>The Packet interface assumes that headers have a fixed size.
It is difficult to return a pointer into the data region when its
***************
*** 450,454 ****
command void Packet.clear(message_t* msg) {
uint8_t len;
! void* payload = call SubPacket.getPayload(msg, &len);
memset(payload, len, 0);
}
--- 453,457 ----
command void Packet.clear(message_t* msg) {
uint8_t len;
! void* payload = call SubPacket.getPayload(msg, call SubPacket.maxPayloadLength());
memset(payload, len, 0);
}
***************
*** 466,475 ****
}
! 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;
}
}
--- 469,478 ----
}
! 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;
}
}
***************
*** 531,535 ****
command uint8_t maxPayloadLength();
! command void* getPayload(message_t* msg);
}
</pre>
--- 534,538 ----
command uint8_t maxPayloadLength();
! command void* getPayload(message_t* msg, uint8_t len);
}
</pre>
***************
*** 542,546 ****
command uint8_t maxPayloadLength();
! command void* getPayload(message_t* msg);
}
</pre>
--- 545,549 ----
command uint8_t maxPayloadLength();
! command void* getPayload(message_t* msg, uint8_t len);
}
</pre>
***************
*** 548,555 ****
The duplication of some of the commands in Packet is solely for ease
of use: <tt class="docutils literal"><span class="pre">maxPayloadLength</span></tt> and <tt class="docutils literal"><span class="pre">getPayload</span></tt> MUST behave
! identically as <tt class="docutils literal"><span class="pre">Packet.maxPayloadLength</span></tt> and <tt class="docutils literal"><span class="pre">Packet.getPayload</span></tt>,
! with the exception that the latter has no length parameter (it should
! behave as if the length parameter of the <tt class="docutils literal"><span class="pre">Packet</span></tt> 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.</p>
<p>When called with a length that is too long for the underlying
--- 551,556 ----
The duplication of some of the commands in Packet is solely for ease
of use: <tt class="docutils literal"><span class="pre">maxPayloadLength</span></tt> and <tt class="docutils literal"><span class="pre">getPayload</span></tt> MUST behave
! identically as <tt class="docutils literal"><span class="pre">Packet.maxPayloadLength</span></tt> and <tt class="docutils literal"><span class="pre">Packet.getPayload.</span></tt>
! Their inclusion is so that components do not have to wire to
both Packet and the sending interface for basic use cases.</p>
<p>When called with a length that is too long for the underlying
***************
*** 583,588 ****
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);
}
</pre>
--- 584,587 ----
More information about the Tinyos-2-commits
mailing list