tep116.txt

tinyos-2.x.rar

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
packet reception.

A *user* of the Receive interface has three basic options when it
handles a receive event:

  1) Return ``msg`` without touching it.
  2) Copy some data out of ``payload`` and return ``msg``.
  3) Store ``msg`` in its local frame and return a different ``message_t*`` for the lower layer to use.

These are simple code examples of the three cases::

  // Case 1
  message_t* Receive.receive(message_t* msg, void* payload, uint8_t len) {
    return msg; 
  }  

  // Case 2
  uint16_t value;
  message_t* Receive.receive(message_t* msg, void* payload, uint8_t len) {
    if (len >= sizeof(uint16_t)) {
      nx_uint16_t* nval = (nx_uint16_t*)payload;
      value = *nval;
    }
    return msg;
  }

  //Case 3
  message_t buf;
  message_t* ptr = &buf;
  message_t* Receive.receive(message_t* msg, void* payload, uint8_t len) {
    message_t* tmp = ptr;
    ptr = msg;
    post processTask();
    return tmp;
  }


Because of case 3), a lower layer MUST respect the buffer swap semantics
and use the pointer returned from ``receive``. The pointer passed as
a parameter to ``receive`` MUST NOT be touched, used, or stored after
the signaling of ``receive.``

2.4 Dispatch
--------------------------------------------------------------------

A packet protocol MAY have a dispatch identifier. This generally manifests
as the protocol component providing parameterized interfaces (rather than
a single interface instance). A dispatch identifier allows multiple 
services to use a protocol independently. If a protocol provides a
dispatch mechanism, then each dispatch identifier SHOULD correspond to
a single packet format: if an identifier corresponds to multiple packet
formats, then there is no way to disambiguate them. Packets whose internal 
structure depends on their fields (for example,
a packet that has a control field which indicates which optional fields
are present) do not pose such problems.

3. HIL: ActiveMessageC
============================================================================

A platform MUST provide ActiveMessageC as a basic HIL to 
packet-level communication.  ActiveMessageC provides a best-effort, 
single-hop communication abstraction.  Every active message has a 
16-bit destination address and an 8-bit type. There is one reserved 
destination address, ``AM_BROADCAST_ADDR``, which has the value 
of ``0xffff``. ActiveMessageC has the following signature::

  configuration ActiveMessageC {
    provides {
      interface Init;
      interface SplitControl;  

      interface AMSend[uint8_t id];
      interface Receive[uint8_t id];
      interface Receive as Snoop[uint8_t id];
 
      interface Packet;
      interface AMPacket;
      interface PacketAcknowledgements;
    }
  }

The Receive interface is for packets destined to the node, while 
the Snoop interface is for packets destined to other nodes. A 
packet is destined for a node if its destination AM address is 
either the AM broadcast address or an address associated with 
the AM stack. Different link layers have different snooping 
capabilities. The Snoop interface does not assume always-on 
listening, for example, in the case of a TDMA or RTS/CTS data 
link layer. By separating out these two interfaces, ActiveMessageC
avoids the complications encountered in 1.x with regards to
GenericComm vs. GenericCommPromiscuous.

ActiveMessageC is usually just a configuration that has
pass-through wiring to a chip-specific HAL active message
implementation. The definition of ActiveMessageC is left
to the platform for when a node has more than one
radio. In this case, the platform decides how to map the
basic packet abstraction to the hardware underneath. Approaches 
include choosing one radio or having some form of address-based
dispatch.


4. AM Services: AMSenderC, AMReceiverC, AMSnooperC, AMSnoopingReceiverC
============================================================================

TinyOS 2.x provides four component single-hop communication
virtualizations to applications:
AMReceiverC, AMSnooperC, AMSnoopingReceiverC, and AMSenderC. Each is a
generic component that takes an active message ID as a
parameter. These components assume the existence of ActiveMessageC.

4.1 Dispatch: ``am_id_t``
--------------------------------------------------------------------

Active messages have an 8-bit type field, which allows multiple
protocols to all use AM communication without conflicting. Following
the guidelines for protocol dispatch identifiers, each
am_id_t used in a network SHOULD have a single packet format, so
that the am_id_t, combined with the packet contents, are sufficient
to determine the exact packet format.

4.2 AMReceiverC
--------------------------------------------------------------------

AMReceiverC has the following signature::

  generic configuration AMReceiverC(am_id_t t) {
    provides{
      interface Receive;
      interface Packet;
      interface AMPacket;
    }
  }

AMReceiver.Receive.receive is signalled whenever the packet layer
receives an active message of the corresponding AM type whose
destination address is the local address or the broadcast
address. Note that since Receive.receive swaps buffers, a program MUST
NOT instantiate two AMReceivers with the same am_id_t and MUST NOT
instantiate an AMReceiver and an AMSnoopingReceiver with the same
am_id_t.

4.3 AMSnooperC
--------------------------------------------------------------------

AMSnooper has an identical signature to AMReceiver::

  generic configuration AMSnooperC(am_id_t t) {
    provides{
      interface Receive;
      interface Packet;
      interface AMPacket;
    }
  }

AMSnooper.Receive.receive is signalled whenever the packet layer
receives an active message of the corresponding AM type whose
destination address is neither to the local address nor the broadcast
address. Note that since Receive.receive swaps buffers, a program MUST
NOT instantiate two AMSnoopers with the same am_id_t and MUST NOT
instantiate an AMSnooper and an AMSnoopingReceiver with the same
am_id_t.

4.4 AMSnoopingReceiverC
--------------------------------------------------------------------

AMSnoopingReceiverC has an identical signature to AMReceiverC::

  generic configuration AMSnoopingReceiverC(am_id_t t) {
    provides{
      interface Receive;
      interface Packet;
      interface AMPacket;
    }
  }

AMSnoopingReceiverC.Receive.receive is signalled whenever the packet
layer receives an active message of the corresponding AM type,
regardless of destination address. Note that since Receive.receive
swaps buffers, a program that instantiates an AMSnoopingReceiverC with
a certain am_id_t MUST NOT instantiate another AMSnoopingReceiverC,
AMSnooperC, or AMReceiverC with the same am_id_t.

4.5 AMSenderC 
--------------------------------------------------------------------

AMSenderC has the following signature::

  generic configuration AMSenderC(am_id_t AMId) {
    provides {
      interface AMSend;
      interface Packet;
      interface AMPacket;
      interface PacketAcknowledgements as Acks;
    }
  }

Because this is a send virtualization, AMSenderC.AMSend.send returns
EBUSY only if there is a send request outstanding on this particular
AMSenderC. That is, each AMSenderC has a queue of depth one. The exact
order in which pending AMSenderC requests are serviced is undefined,
but it MUST be fair, where fair means that each client with outstanding
packets receives a reasonable approximation of an equal share of the 
available transmission bandwidth.

5. Power Management and Local Address
============================================================================

In addition to standard datapath interfaces for sending and
receiving packets, an active message layer also has control interfaces.


5.1 Power Management
--------------------------------------------------------------------

The communication virtualizations do not support power management.
ActiveMessageC provides SplitControl for explicit power control.
For packet communication to operate properly, a component in an 
application has to call ActiveMessageC.SplitControl.start().
The HAL underneath ActiveMessageC  MAY employ power management 
techniques, such as TDMA scheduling or low power listening, when
"on."

5.2 Local Active Message Address
--------------------------------------------------------------------

An application can change ActiveMessageC's local AM address 
at runtime. This will change which packets a node receives and
the source address it embeds in packets. To change the local AM
address at runtime, a component can wire to the component
``ActiveMessageAddressC``. This component only changes the
AM address of the default radio stack (AMSenderC, etc.); if
a radio has multiple stacks those may have other components
for changing their addresses in a stack-specific fashion.

5. HAL Requirements
============================================================================

A radio chip *X* MUST have a packet abstraction with the following
signature::

  provides interface Init;
  provides interface SplitControl;
  provides interface AMSend[am_id_t type];
  provides interface Receive[am_id_t type];
  provides interface Receive as Snoop[am_id_t type];
  provides interface Packet;
  provides interface AMPacket;
  provides interface PacketAcknowledgments;


The component SHOULD be named *XActiveMessageC*, where *X* is 
the name of the radio chip. The component MAY have additional interfaces. 
These interfaces can either be chip-specific or chip-independent. 

6. message_t
============================================================================

Active messages are a basic single-hop packet abstraction. Therefore,
following TEP 111 [3]_, all data link and active message headers
MUST be in the ``message_header_t`` structure of message_t. This ensures
that an active message received from one data link layer (e.g., the radio)
can be passed to another data link layer (e.g., the UART) without
shifting the data payload. This means that the ``message_header_t`` must
include all data needed for AM fields, which might introduce headers
in addition to those of the data link. For example, this is an example 
structure for a CC2420 (802.15.4) header::

  typedef nx_struct cc2420_header_t {
    nx_uint8_t length;
    nx_uint16_t fcf;
    nx_uint8_t dsn;
    nx_uint16_t destpan;
    nx_uint16_t dest;
    nx_uint16_t src;
    nx_uint8_t type;
  } cc2420_header_t;


The first six fields (length through src) are all 802.15.4 headers. The
type field, however, has been added to the header structure in order
to support AM dispatch.

7. Implementation
============================================================================

The following files in ``tinyos-2.x/tos/system`` provide reference 
implementations of the abstractions described in this TEP.

  * ``AMSenderC.nc``, ``AMReceiverC.nc``, ``AMSnooperC.nc``,
    and ``AMSnoopingReceiverC.nc`` are implementations of 
    virtualized AM services.
  * ``AMQueueP`` provides a send queue of *n* entries for *n*
    AMSenderC clients, such that each client has a dedicated entry.
  * ``AMQueueImplP`` is the underlying queue implementation,
    which is reusable for different clients (it is also used
    in the serial stack [4]_).
  * ``AMQueueEntryP`` sits on top of ``AMQueueP`` and stores
    the parameters to ``AMSend.send`` in an outstanding
    packet with the ``AMPacket`` interface.

The following files in ``tinyos-2.x/tos/interfaces`` contain
example implementations of packet protocol interfaces:

  * ``Packet.nc`` is the basic interface that almost all
    packet protocols provide.
  * ``Send.nc`` is the transmission interface for address-free 
     protocols.
  * ``AMSend.nc`` is the transmission interface for AM address
     send protocols.
  * ``AMPacket.nc`` is the packet interface for AM-specific
    fields.

An active messaging implementation for the CC2420 radio chip
can be found in ``tos/chips/CC2420/CC2420ActiveMessageC.nc``.
The micaz platform and telos family have an ``ActiveMessageC.nc``
which exports the interfaces of ``CC2420ActiveMessageC``.

8. Author's Address
============================================================================

| Philip Levis
| 358 Gates Hall
| Computer Science Laboratory
| Stanford University
| Stanford, CA 94305
|
| phone - [phone]

9. Citations
============================================================================

.. [1] The MintRoute protocol. ``tinyos-1.x/tos/lib/MintRoute``. Also, A. Woo, T. Tong, and D. Culler. "Taming the Underlying Challenges of Reliable Multihop Routing in Sensor Networks." SenSys 2003.

.. [2] Tiny AGgregation, one protocol of the TinyDB system.  ``tinyos-1.x/tos/lib/TinyDB``. Also, S. Madden and M. Franklin and J. Hellerstein and W. Hong. "TinyDB: An Acquisitional Query Processing System for Sensor Networks." Transactions on Database Systems (TODS) 2005.

.. [3] TEP 111: message_t.

.. [4] TEP 113: Serial Communication.