tep108.txt

tinyos-2.x.rar

called, and calling the underlying command on the shared resource. 
With such a mapping, inserting these operations is made possible.

Having such a mapping is also important for services that need to
explicitly keep track of the number of clients they have,
independent from how many total clients the underlying shared
resource has.  For example, a sensor implementation that uses an
underlying ADC resource may wish to power down its sensor whenever it
has no clients.  It doesn't want to have to wait until the entire ADC
is free to do so.  Providing this mapping allows the implicit power
manager components described in TEP 115 to be wired in at both levels
of the abstraction without interfering with one another.  In this
way, implementations of these components become much simpler, and code
reuse is encouraged.

Implementations of components similar to this one can be found in the
tinyos-2.x source tree in the tos/chips/msp430/uart directory

5. Implementation 
====================================================================

Because most components use one of a small number of arbitration
policies, tinyos-2.x includes a number of default resource arbiters. These
arbiters can be found in ``tinyos-2.x/tos/system`` and are all
generic components that include one of the two signatures seen below::

  generic module SimpleArbiter {
    provides interface Resource[uint8_t id];
    provides interface ResourceRequested[uint8_t id];
    provides interface ArbiterInfo;
    uses interface ResourceConfigure[uint8_t id];
  }

  generic module Arbiter {
    provides interface Resource[uint8_t id];
    provides interface ResourceRequested[uint8_t id];
    provides interface ResourceDefaultOwner;
    provides interface ArbiterInfo;
    uses interface ResourceConfigure[uint8_t id];
  } 
  
The "Simple" arbiters are intended for use by resources that 
do not require the additional overhead incurred by providing the
ResourceDefaultOwner interface.

For many situations, changing an arbitration policy requires nothing
more than changing the queuing policy it uses to decide the order in
which incoming requests should be granted. In this way, separating 
queuing policy implementations from actual arbitration implementations 
encourages code reuse.  The introduction of the SimpleArbiterP and 
ArbiterP components found under tinyos-2.x/tos/system help in this
separation.  They can be wired to components providing
a particular queuing policy through the use of the ResourceQueue  
interface.::

  interface ResourceQueue {
    async command bool isEmpty();
    async command bool isEnqueued(resource_client_id_t id);
    async command resource_client_id_t dequeue();
    async command error_t enqueue(resource_client_id_t id);
  }   
  
An example of wiring a First-Come-First-Serve (FCFS) queuing policy to 
the SimpleArbiterP component using the ResourceQueue interface
defined above can be seen below:: 

  generic configuration SimpleFcfsArbiterC(char resourceName[]) {
    provides {
      interface Resource[uint8_t id];
      interface ResourceRequested[uint8_t id];
      interface ArbiterInfo;
    }
    uses interface ResourceConfigure[uint8_t id];
  }
  implementation {
    components MainC;
    components new FcfsResourceQueueC(uniqueCount(resourceName)) as Queue;
    components new SimpleArbiterP() as Arbiter;

    MainC.SoftwareInit -> Queue;

    Resource = Arbiter;
    ResourceRequested = Arbiter;
    ArbiterInfo = Arbiter;
    ResourceConfigure = Arbiter;

    Arbiter.Queue -> Queue;
  }

This generic configuration can be instantiated by a resource in order
to grant requests made by its clients in an FCFS fashion.
  
All of the default queuing policies provided in tinyos-2.x along with the 
respective arbitration components that have been built using them are 
given below:

Queuing Policies:

- FcfsResourceQueueC
- RoundRobinResourceQueueC
    
Arbiters:

- SimpleFcfsArbiterC
- FcfsArbiterC
- SimpleRoundRobinArbiterC
- RoundRobinArbiterC 
  
Keep in mind that neither the implementation of an arbiter nor its 
queuing policy can be used to explicitly restrict access to an 
underlying shared resource.  The arbiter simply provides a standardized
way of managing client ids so that shared resources don't have to duplicate 
this functionality themselves every time they are implemented.  In order to
actually restrict clients from using a resource without first requesting it,
a shared resource must use the functionality provided by the ArbiterInfo interface
to perform runtime checks on the current owner of a resource.  Please refer 
to the section on the ArbiterInfo interface in Appendix B for more information
on how such runtime checks can be performed. 
  
6. Author's Address
====================================================================

| Kevin Klues
| 503 Bryan Hall
| Washington University
| St. Louis, MO 63130
|
| phone - [phone]
| email - [e-mail]
|
| Philip Levis
| 358 Gates Hall
| Stanford University
| Stanford, CA 94305-9030
|
| phone - [phone]
| email - [e-mail]
|
| David Gay
| 2150 Shattuck Ave, Suite 1300
| Intel Research
| Berkeley, CA 94704
|
| phone - [phone]
| email - [e-mail]
|
| David Culler
| 627 Soda Hall
| UC Berkeley
| Berkeley, CA 94720
|
| phone - [phone]
| email - [e-mail]
|
| Vlado Handziski
| Sekr FT5
| Einsteinufer 25
| 10587 Berlin
| GERMANY
|
| email - [e-mail]

7. Citations
====================================================================

.. [1] TEP 2: Hardware Abstraction Architecture. 
.. [2] TEP 102: Timers. 
.. [3] Service Instance Pattern. In *Software Design Patterns for TinyOS.* David Gay, Philip Levis, and David Culler. Published in Proceedings of the ACM SIGPLAN/SIGBED 2005 Conference on Languages, Compilers, and Tools for Embedded Systems (LCTES'05).
.. [4] TEP 115: Power Management of Non-Virtualized Devices. 
.. [5] TinyOS Programming. http://csl.stanford.edu/~pal/pubs/tinyos-programming-1-0.pdf

Appendix A: Resource Class Examples
====================================================================

Dedicated Resource
--------------------------------------------------------------------
Timer 2 on the Atmega128 microprocessor is a dedicated resource
represented by the HplAtm128Timer2C component::
 	
  module HplAtm128Timer2C {
    provides {
      interface HplTimer<uint8_t>   as Timer2     @exactlyonce();
      interface HplTimerCtrl8       as Timer2Ctrl @exactlyonce();
      interface HplCompare<uint8_t> as Compare2   @exactlyonce();
    }
  }
  
Only a single client can wire to any of these interfaces as enforced through
the nesC @exactlyonce attribute.  Keep in mind that although the interfaces of
this component are only allowed to be wired to once, nothing prevents the 
component wiring to them from virtualizing the services they provide at some 
higher level.  If you are unfamiliar with how @exactlyonce and other nesC 
attributes are used to by the nesC compiler, please refer to section 9.1 of the 
TinyOS Programming Manual [5]_.

Virtualized Resource
--------------------------------------------------------------------

The TimerMilliC component provides a virtual abstraction of millisecond 
precision timers to application components [2]_. It encapsulates the required 
parameterized Timer interface through the use of a generic configuration.  
Clients wishing to use a millisecond timer need only instantiate a single 
instance of the TimerMilliC generic, leaving the fact that it is virtualized 
underneath transparent.::

  generic configuration TimerMilliC {
    provides interface Timer<TMilli>;
  }
  implementation {
    components TimerMilliP;
    Timer = TimerMilliP.TimerMilli[unique(UQ_TIMER_MILLI)];
  }
	
The actual parameterized Timer interface is provided by the chip specific 
HilTimerMilliC component.  This interface is exposed through  
the TimerMilliP component which wires HilTimerMilliC to the boot 
initialization sequence::

  configuration TimerMilliP {
    provides interface Timer<TMilli> as TimerMilli[uint8_t num];
  }
  implementation {
    components HilTimerMilliC, MainC;
    MainC.SoftwareInit -> HilTimerMilliC;
    TimerMilli = HilTimerMilliC;
  }

Appendix B: Arbiter Interface Examples
====================================================================

.. Note:
  Most of the examples provided in this section use complex nesC syntax that may 
  be unfamiliar to the novice nesC programmer.  Please refer to the TinyOS 
  programming Manual [5]_ for clarification as necessary. 
 
Resource
--------------------------------------------------------------------
Examples of how to use the Resource interface for arbitrating
between multiple clients can be found in the tinyos-2.x
source tree under tinyos-2.x/apps/tests/TestArbiter.
  	 
A specific example of where the Resource.isOwner() is used 
can be seen in the HplTda5250DataP component of the Infineon 
Tda5250 radio implementation::

  async command error_t HplTda5250Data.tx(uint8_t data) {
    if(call UartResource.isOwner() == FALSE)
      return FAIL;
    call Usart.tx(data);
    return SUCCESS;
  }

A call to the HplTda5250Data.tx command will fail if the radio does
not currently have control of the underlying Usart resource.  If it
does, then the Usart.tx(data) command is called as requested.

A component using the Resource interface to implement an I2C
service might look like this::

  #include I2CPacket.h
  configuration I2CPacketP {
    provides interface Resource[uint8_t client];
    provides interface I2CPacket<I2CAddrSize>[uint8_t client];
  }
  implementation {
    components new FcfsArbiterC(I2CPACKET_RESOURCE) as Arbiter;
    components I2CPacketImplP() as I2C;
    ...
  
    Resource  = Arbiter;