[Tinyos-devel] Interface change proposals for 2.1

[Philip Levis]

After using 2.0 for almost a year, the core WG has identified what it  
thinks are two issues with the current communication interfaces.  
Fixing both of them would require changing the interfaces in minor  
ways that would make them incompatible with prior versions. While the  
code WG currently thinks these changes are a good idea, we wanted to  
get community feedback and suggestions before deciding on whether to  
make the changes.

----

Change 1: The Receive interface.

PROBLEM: Between beta2 and 2.0, utility commands were added to the  
Receive interface (e.g., getPayload), so that users of the interface  
do not have to wire to Packet if they need to obtain payload pointers  
outside the Receive.receive event. This means that components can no  
longer wire Receive multiple times, as those commands fan-out. Wiring  
Receive multiple times is useful for snooping code (you wire both  
Receive and Receive as Snoop to your handler).

PROPOSED SOLUTION: Remove the utility commands from Receive. After  
looking at all of the source code in the repository, these utility  
commands are used only a handful of times, and in all cases the  
component using them also wired other interfaces that provide the  
same functionality (i.e., Packet).

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);
}

becomes

interface Receive {
   event message_t* receive(message_t* msg, void* payload, uint8_t len);
}

NOTE: Providing Receive will also be simpler, as the provider does  
not have to implement the utility commands.

----

Change 2: The Packet interface (and depending on 1, the Receive  
interface)

PROBLEM: David Gay and John Regehr have been developing code checking  
tools that enable lightweight run-time memory access checks. They  
hope to incorporate these as optional add-ons to the TinyOS build  
process (i.e., make telosb memcheck). It turns out that the  
getPayload call is a major source of possible errors yet is very  
difficult to check efficiently. They have proposed an alternative  
version of getPayload that these tools will be able to check much  
more easily. Source code comparisons using the two versions suggest  
that neither is particularly more or less complex to use, and in  
terms of coding taste people seem evenly split on which is "prettier."

PROPOSED SOLUTION: The getPayload call will change from

   command void* getPayload(message_t* msg, uint8_t* len);

to

   command void* getPayload(message_t* msg, uint8_t minLen);

such that the caller tells the callee the size it requires. If the  
callee cannot provide a payload of that size, then it returns NULL.  
(The memory checking tools handle null pointers, so you don't smash  
your control registers.)

NOTE: If the old command was sorely needed (e.g., used by a binary  
component), it is possible to translate the old call into the new one"

command void* OldPacket.getPayload(message_t* msg, uint8_t* len) {
   if (len != NULL) {
     *len = call NewPacket.payloadLength(msg);
   }
   return call NewPacket.getPayload(msg, 0);
}

----

Thoughts and comments are greatly appreciated.

Phil