2.1 Dedicated

An abstraction is dedicated if it is a resource which a subsystem needs exclusive access to at all times. In this class of resources, no sharing policy is needed since only a single component ever requires use of the resource. Examples of dedicated abstractions include interrupts and counters.

Dedicated abstractions MAY be annotated with the nesC attribute @atmostonce or @exactlyonce to provide compile-time checks that their usage assumptions are not violated.

Please refer to Appendix A for an example of how a dedicated resource might be represented, including the use of the nesC @exactlyonce attribute.

2.2 Virtualized

Virtual abstractions hide multiple clients from each other through software virtualization. Every client of a virtualized resource interacts with it as if it were a dedicated resource, with all virtualized instances being multiplexed on top of a single underlying resource. Because the virtualization is done in software, there is no upper bound on the number of clients using the abstraction, barring memory or efficiency constraints. As virtualization usually requires keeping state that scales with the number of virtualized instances, virtualized resources often use the Service Instance pattern [3], which is based on a parameterized interface.

Virtualization generally provides a very simple interface to its clients. This simplicity comes at the cost of reduced efficiency and an inability to precisely control the underlying resource. For example, a virtualized timer resource introduces CPU overhead from dispatching and maintaining each individual virtual timer, as well as introducing jitter whenever two timers happen to fire at the same time. Please refer to Appendix A for an example of how such a virtualized timer resource might be implemented.

2.3 Shared

Dedicated abstractions are useful when a resource is always controlled by a single component. Virtualized abstractions are useful when clients are willing to pay a bit of overhead and sacrifice control in order to share a resource in a simple way. There are situations, however, when many clients need precise control of a resource. Clearly, they can't all have such control at the same time: some degree of multiplexing is needed.

A motivating example of a shared resource is a bus. The bus may have multiple peripherals on it, corresponding to different subsystems. For example, on the Telos platform the flash chip (storage) and the radio (network) share a bus. The storage and network stacks need exclusive access to the bus when using it, but they also need to share it with the other subsystem. In this case, virtualization is problematic, as the radio stack needs to be able to perform a series of operations in quick succession without having to reacquire the bus in each case. Having the bus be a shared resource allows the radio stack to send a series of operations to the radio atomically, without having to buffer them all up in memory beforehand (introducing memory pressure in the process).

In TinyOS 2.x, a resource arbiter is responsible for multiplexing between the different clients of a shared resource. It determines which client has access to the resource at which time. While a client holds a resource, it has complete and unfettered control. Arbiters assume that clients are cooperative, only acquiring the resource when needed and holding on to it no longer than necessary. Clients explicitly release resources: there is no way for an arbiter to forcibly reclaim it. The following section is dedicated to describing the arbiter and its interfaces.

3.1 Resource

Clients of a shared resource arbiter request access using the Resource interface:

interface Resource {
  async command error_t request();
  async command error_t immediateRequest();
  event void granted();
  async command error_t release();
  async command bool isOwner();
}

A client lets an arbiter know it needs access to a resource by making a call to request(). If the resource is free, SUCCESS is returned, and a granted event is signaled back to the client. If the resource is busy, SUCCESS will still be returned, but the request will be queued according to the queuing policy of the arbiter. Whenever a client is done with the resource, it calls the release() command, and the next client in the request queue is given access to the resource and is signaled its granted() event. If a client ever makes multiple requests before receiving a granted event, an EBUSY value is returned, and the request is not queued. Using this policy, clients are not able to hog the resource queue by making multiple requests, but they may still be able to hog the resource if they do not release it in a timely manner.

Clients can also request the use of a resource through the immediateRequest() command. A call to immediateRequest() can either return SUCCESS or FAIL, with requests made through this command never being queued. If a call to immediateRequest() returns SUCCESS, the client is granted access to the resource immediately after the call has returned, and no granted event is ever signaled. If it returns FAIL, the client is not granted access to the resource and the request does not get queued. The client will have to try and gain access to the resource again later.

A client can use the isOwner command of the Resource interface to check if it is the current owner of the resource. This command is mostly used to perform runtime checks to make sure that clients not owning a resource are not able to use it. If a call to isOwner fails, then no call should be made to commands provided by that resource.

An arbiter MUST provide exactly one parameterized Resource interface, where the parameter is a client ID, following the Service Instance pattern[3]_. An arbitrated component SomeNameP MUST #define SOME_NAME_RESOURCE to a string which can be passed to unique() to obtain a client id. This #define must be placed in a separate file because of the way nesC files are preprocessed: including the SomeNameP component isn't enough to ensure that macros #define'd in SomeNameP are visible in the referring component.

Please refer to Appendix B for an example of how to wrap this component inside a generic configuration. Wrapping the component in this way ensures that each Resource client is given a unique client ID, with the added benefit of properly coupling multiple components that all need to refer to the same client ID.

For a complete example of how the I2C resource might be abstracted according to this pattern, please refer to Appendix B. For further examples please refer to the various chip implementations in the tinyos-2.x source tree under tinyos-2.x/chips/

3.2 ArbiterInfo

Arbiters MUST provide an instance of the ArbiterInfo interface. The ArbiterInfo interface allows a component to query the current status of an arbiter:

interface ArbiterInfo {
  async command bool inUse();
  async command uint8_t userId();
}

The ArbiterInfo interface has a variety of uses. For example, the resource implementation can use it to refuse requests from clients that do not currently have access. For an example of how this interface is used in this fashion please refer to Appendix B.

3.3 ResourceRequested

Sometimes it is useful for a client to be able to hold onto a resource until someone else needs it and only at that time decide to release it. Using the ResourceRequested interface, this information is made available to the current owner of a resource:

interface ResourceRequested {
  async event void requested();
  async event void immediateRequested();
}

A requested event is signaled to the current owner of the resource if another client makes a request for the resource through the request() command of its Resource interface. If a request is made through the immediateRequest() command, then the immediateRequested() event is signaled.

An arbiter SHOULD provide a parameterized ResourceRequested interface to its clients, but is not required to. The client id of the parameterized ResourceRequested interface should be coupled with the client id of the Resource interface to ensure that all events are signaled to the proper clients. Please refer to Appendix B for an example of how this interface might be used.

3.4 ResourceConfigure

The ResourceConfigure interface provides a mechanism for clients that need to use a resource with different configurations to do so. Rather than forcing a client to reconfigure the resource itself, the component representing a client can wire to an arbiter's ResourceConfigure interface, which is called just before granting the client the resource:

interface ResourceConfigure {
  async command void configure();
  async command void unconfigure();
}

The arbiter SHOULD use a parameterized ResourceConfigure interface, with its client ID parameter coupled with the client id of its parameterized Resource interface. If an arbiter uses the ResourceConfigure interface, it MUST call ResourceConfigure.configure() on the granted client ID before it signals the Resource.granted() event. Similarly, after a valid call to Resource.release(), it MUST call ResourceConfigure.unconfigure() on the releasing client ID. By calling ResourceConfigure.configure() just before granting a client access to a resource and calling ResourceConfigure.unconfigure() just before fully releasing it, it is guaranteed that a resource is always unconfigured before an attempt to configure it can be made again.

Using the parameterized ResourceConfigure interface that calls out rather than additional commands being put into the Resource interface simplifies code reuse. Introducing these new commands into the Resource interface could lead to a large number of clients all including redundant configuration code, while using the call out approach provided by the parameterized interface will only have one instance of the code.

For an example of how the three different modes of the Msp430 Usart component can take advantage of this ResourceConfigure interface please refer to Appendix B as well as section 4 on the use of cross-component reservation.

3.5 ResourceController

The normal Resource interface is for use by clients that all share the resource in an equal fashion. The ResourceController interface is for use by a single client that needs to be given control of the resource whenever no one else is using it. An arbiter MAY provide a single instance of the ResourceController interface.:

interface ResourceController {
  async event void granted();
  async command error_t release();
  async command bool isOwner();
  async event void requested();
  async event void immediateRequested();
}

The Arbiter MUST guarantee that the user of the ResourceController interface is made the owner of the resource before the boot initialization sequence is completed. When a normal resource client makes a request for the resource, the ResourceController will receive either a requested() or an immediateRequested() event depending on how the request was made. It must then decide if and when to release it. Once released, all clients that have pending requests will be granted access to the resource in the order determined by the queuing policy of the arbiter in use. Once all pending requests have been granted (including those that came in while other clients had access to the resource), the ResourceController is automatically given control of the resource, receiving its granted() event in the process. The ResourceController interface also contains the same isOwner() command as the normal Resource interface, and the semantics of its use are exactly the same.

Although the ResourceController interface looks similar to a combination of the normal Resource interface and the ResourceRequested interface, its intended use is quite different. The ResourceController interface should only be used by clients that wish to have access to a resource only when no other clients are using it. They do not actively seek out access to the resource, but rather use it to perform operations when it would otherwise simply be idle.

Combining the use of the Resource and ResourceRequested interfaces could be made to operate in a similar manner as the ResourceController interface, except that there is no way to tell a client with these interfaces that a resource has gone completely idle. Each client must actively request the use of the resource and be granted that resource in the order determined by the queuing policy of its arbiter. With the ResourceController interface, there is no active request of the resource. The arbiter simply signals the granted event to the ResourceController whenever there are no more pending requests and the last client that owned the resource releases it.

The primary motivation behind the definition of the ResourceController interface was to allow for an easy integration of the power management policy used by the resource with the arbitration of the resource itself. Arbiters that want to allow a resource to be controlled by a particular power management policy can provide the ResourceController interface for use by a component that implements that policy. The power management component will receive the granted() event whenever the resource has gone idle, and will then proceed in powering it down. When another client requests the resource, the power manager will be notified through either the requested() or immediateRequested() events as appropriate. It can then power up the resource and release it once the power up has completed. Note that if power up is a split-phase operation (takes a while), then calls by clients to immediateRequest() when in the powered down state will not return SUCCESS. Please see the TEP on the Power Management of Non-Virtualized devices ([4]) for more details.

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

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;
  I2CPacket = I2C;
  ...
}

where I2CPacketImplP contains the actual implementation of the I2C service, and I2CPacket.h contains the #define for the name of the resource required by the arbiter:

#ifndef I2CPACKETC_H
#define I2CPACKETC_H
#define I2CPACKET_RESOURCE "I2CPacket.Resource"
#endif

This service would then be made available to a user through the generic configuration seen below:

#include I2CPacket.h
generic configuration I2CPacketC {
  provides interface Resource;
  provides interface I2CPacket<I2CAddrSize>;
}
implementation {
  enum { CLIENT_ID = unique(I2CPACKET_RESOURCE) };

  components I2CPacketP as I2C;
  Resource = I2C.Resource[CLIENT_ID];
  I2CPacket = I2C.I2CPacket[CLIENT_ID];
}

In this example, an instance of the I2CPacket interface is coupled with an instance of the Resource interface on every new instantiation of the I2CPacketC component. In this way, a single Resource and a single I2CPacket interface can be exported by this component together for use by a client.

Clients of the I2C service would use it as follows:

module I2CClientP {
  uses interface Resource as I2CResource;
  uses interface I2CPacket<I2CAddrSize>;
} ...

configuration I2CClientC { }
implementation {
  components I2CClientP, new I2CPacketC();

  I2CClientP.I2CResource -> I2CPacketC.Resource;
  I2CUserM.I2CPacket -> I2CPacket.I2CPacket;
}

ArbiterInfo

In the implementation of the ADC component on the Msp430 microcontroller, a simple arbiter is used to provide a round robin sharing policy between clients of the ADC:

configuration Msp430Adc12C {
  provides interface Resource[uint8_t id];
  provides interface Msp430Adc12SingleChannel[uint8_t id];
  provides interface Msp430Adc12FastSingleChannel[uint8_t id];
}
implementation {
  components Msp430Adc12P,MainC,
             new SimpleRoundRobinArbiterC(MSP430ADC12_RESOURCE) as Arbiter,
             ...

  Resource = Arbiter;
  SingleChannel = Msp430Adc12P.SingleChannel;
  FastSingleChannel = Msp430Adc12P.FastSingleChannel;

  Msp430Adc12P.Init <- MainC;
  Msp430Adc12P.ADCArbiterInfo -> Arbiter;
  ...
}

In this configuration we see that the Resource interface provided by Msp430Adc12C is wired directly to the instance of the SimpleRoundRobinArbiterC component that is created. The ArbiterInfo interface provided by SimpleRoundRobinArbiterC is then wired to Msp430Adc12P. The Msp430Adc12P component then uses this interface to perform run time checks to ensure that only the client that currently has access to the ADC resource is able to use it:

async command error_t Msp430Adc12SingleChannel.getSingleData[uint8_t id]() {
  if (call ADCArbiterInfo.userId() == id){
    configureChannel()
    // Start getting data
  }
  else return ERESERVE;
}

async command error_t Msp430Adc12FastSingleChannel.configure[uint8_t id]() {
  if (call ADCArbiterInfo.userId() == id){
    clientID = id
    configureChannel()
  }
  else return ERESERVE;
}

async command error_t Msp430Adc12FastSingleChannel.getSingleData[uint8_t id]()
{
  if (clientID = id)
    // Start getting data
  else return ERESERVE;
}

In order for these runtime checks to succeed, users of the Msp430Adc12SingleChannel and Msp430Adc12FastSingleChannel interfaces will have to match their client id's with the client id of a corresponding Resource interface. This can be done in the following way:

generic configuration Msp430Adc12ClientC() {
  provides interface Resource;
  provides interface Msp430Adc12SingleChannel;
}
implementation {
  components Msp430Adc12C;
  enum { ID = unique(MSP430ADC12_RESOURCE) };

  Resource = Msp430Adc12C.Resource[ID];
  Msp430Adc12SingleChannel = Msp430Adc12C.SingleChannel[ID];
}

generic configuration Msp430Adc12FastClientC() {
  provides interface Resource;
  provides interface Msp430Adc12FastSingleChannel;
}
implementation {
  components Msp430Adc12C;
  enum { ID = unique(MSP430ADC12_RESOURCE) };

  Resource = Msp430Adc12C.Resource[ID];
  Msp430Adc12FastSingleChannel = Msp430Adc12C.SingleChannel[ID];
}

Since these are generic components, users simply need to instantiate them in order to get access to a single Resource interface that is already properly coupled with a Msp430Adc12SingleChannel or Msp430Adc12FastSingleChannel interface.

Take a look in the tinyos-2.x source tree under tinyos-2.x/tos/chips/adc12 to see the full implementation of these components in their original context.

ResourceRequested

On the eyesIFXv2 platform, both the radio and the flash need access to the bus provided by the Usart0 component on the Msp430 microcontroller. Using a simple cooperative arbitration policy, these two components should able to share the Usart resource by only holding on to it as long as they need it and then releasing it for use by the other component. In the case of the MAC implementation of the Tda5250 radio component, however, the Msp430 Usart resource needs be held onto indefinitely. It only ever considers releasing the resource if a request from the flash component comes in through its ResourceRequested interface. If it cannot release it right away (i.e. it is in the middle of receiving a packet), it defers the release until some later point in time. Once it is ready to release the resource, it releases it, but then immediately requests it again. The flash is then able to do what it wants with the Usart, with the radio regaining control soon thereafter.

In the CsmaMacP implementation of the Tda5250 radio we see the ResourceRequested event being implemented:

async event void ResourceRequested.requested() {
  atomic {
    /* This gives other devices the chance to get the Resource
       because RxMode implies a new arbitration round.  */
    if (macState == RX) call Tda5250Control.RxMode()();
  }
}

Through several levels of wiring, the Tda5250 interface is provided to this component by the Tda5250RadioP component:

module Tda5250RadioP {
  provides interface Tda5250Control;
  uses interface Resource as UsartResource;
  ...
}
implementation {
  async command error_t Tda5250Control.RxMode() {
    if(radioBusy() == FALSE)
      call UsartResource.release();
      call UsartResource.request();
  }
  event void UsartResource.granted() {
    // Finish setting to RX Mode
  }
  ...
}

Although the full implementation of these components is not provided, the functionality they exhibit should be clear. The CsmaMacP component receives the ResourceRequested.requested() event when the flash requests the use of the Msp430 Usart0 resource. If it is already in the receive state, it tries to reset the receive state through a call to a lower level component. This component checks to see if the radio is in the middle of doing anything (i.e. the radioBusy() == FALSE check), and if not, releases the resource and then requests it again.

To see the full implementations of these components and their wirings to one another, please refer to the tinyos-2.x source tree under tinyos-2.x/tos/chips/tda5250, tinyos-2.x/tos/chips/tda5250/mac, tinyos-2.x/tos/platforms/eyesIFX/chips/tda5250, and tinyos-2.x/tos/platforms/eyesIFX/chips/msp430.

Resource Configure

The Msp430 Usart0 bus can operate in three modes: SPI, I2C, and UART. Using all three concurrently is problematic: only one should be enabled at any given time. However, different clients of the bus might require the bus to be configured for different protocols. On Telos, for example many of the available sensors use an I2C bus, while the radio and flash chip use SPI.

A component providing the SPI service on top of the shared Usart component looks like this:

generic configuration Msp430Spi0C() {
  provides interface Resource;
  provides interface SpiByte;
  provides interface SpiPacket;
  ...
}
implementation {
  enum { CLIENT_ID = unique( MSP430_SPIO_BUS ) };

  components Msp430SpiNoDma0P as SpiP;
  components new Msp430Usart0C() as UsartC;
  SpiP.ResourceConfigure[ CLIENT_ID ] <- UsartC.ResourceConfigure;
  SpiP.UsartResource[ CLIENT_ID ] -> UsartC.Resource;
  SpiP.UsartInterrupts -> UsartC.HplMsp430UsartInterrupts;
  ...
}

And one providing the I2C service looks like this:

generic configuration Msp430I2CC() {
  provides interface Resource;
  provides interface I2CPacket<TI2CBasicAddr> as I2CBasicAddr;
   ...
}
implementation {
  enum { CLIENT_ID = unique( MSP430_I2CO_BUS ) };

   components Msp430I2C0P as I2CP;
   components new Msp430Usart0C() as UsartC;
   I2CP.ResourceConfigure[ CLIENT_ID ] <- UsartC.ResourceConfigure;
   I2CP.UsartResource[ CLIENT_ID ] -> UsartC.Resource;
   I2CP.I2CInterrupts -> UsartC.HplMsp430UsartInterrupts;
   ...
}

The implementation of the ResourceConfigure interface is provided by both the Msp430SpiNoDma0P and the Msp430I2C0P. In the two different components, the same Msp430Usart0C component is used, but wired to the proper implementation of the ResourceConfigure interface. In this way, different instances of the Msp430Usart0C can each have different configurations associated with them, but still provide the same functionality.

Take a look in the tinyos-2.x source tree under tinyos-2.x/tos/chips/msp430/usart to see the full implementation of these components along with the corresponding Uart implementation.