[Tinyos-devel] Interface change proposals for 2.1

[Matt Welsh]

I vote yes.

On Aug 10, 2007, at 12:55 PM, Philip Levis wrote:

> 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
>
>
> _______________________________________________
> Tinyos-devel mailing list
> Tinyos-devel at Millennium.Berkeley.EDU
> https://mail.millennium.berkeley.edu/cgi-bin/mailman/listinfo/ 
> tinyos-devel