2.1 Explicit Power Management using StdControl

When a devices powerup and powerdown times are negligible, they SHOULD provide the StdControl interface as defined below:

interface StdControl {
  command error_t start();
  command error_t stop();
}

An external component MUST call StdControl.start() to power a device on and StdControl.stop() to power a device off. Calls to either command return SUCCESS or FAIL.

Upon the successful return of a call to StdControl.start(), a device MUST be completely powered, and calls to commands of other interfaces implemented by the device abstraction CAN succeed.

Upon the successful return of a call to StdControl.stop(), a device MUST be completely powered down, and any subsequent operation requests through calls to commands of other interfaces implemented by that device abstraction MUST return FAIL or EOFF.

If a device is not able to complete the StdControl.start() or StdControl.stop() requests for any reason, they MUST return FAIL.

Based on these specifications, this matrix describes the valid return values of calls based on the compoenent's power state:

Devices adhereing to this power management model would provide this interface as shown below:

configuration DeviceC {
  provides {
    interface Init;
    interface StdControl;  //For Power Management
    ....
  }
}

2.2 Power Management with SplitControl

When a devices powerup and powerdown times are non-negligible, the SplitControl interface MUST be used in place of the StdControl interface. The definition of this interface can be seen below:

interface SplitControl {
  command error_t start();
  event void startDone(error_t error);
  command error_t stop();
  event void stopDone(error_t error);
}

An external component MUST call SplitControl.start() to power a device on and SplitControl.stop() to power a device off. Calls to either command return one of SUCCESS, FAIL, or EBUSY.

Successful calls to SplitControl.startDone() MUST signal one of SplitControl.startDone(SUCCESS) or SplitControl.startDone(FAIL).

Successful calls to SplitControl.stopDone() MUST signal one of SplitControl.stopDone(SUCCESS) or SplitControl.stopDone(FAIL).

Upon signalling either a SplitControl.startDone(SUCCESS) or a SplitControl.stopDone(FAIL) event, a device MUST be completely powered, and operation requests through calls to commands of other interfaces implemented by the device abstraction SHOULD succeed.

Upon signalling either a SplitControl.stopDone(SUCCESS) or a SplitControl.startDone(FAIL) event, a device MUST be completely powered down, and any subsequent calls to commands of other interfaces implemented by the device abstraction MUST return EOFF or FAIL.

If a device is not able to complete the SplitControl.start() or SplitControl.stop() requests for any reason, they MUST return FAIL.

Calls to either StdControl.start() or StdControl.stop() while a start or top operattion is pending MUST return an EBUSY.

Devices adhereing to this power management model would provide this interface as shown below:

configuration DeviceC {
  provides {
    interface Init;
    interface SplitControl; \\ For Power Management
    ....
  }
}

2.3 Power Management with AsyncStdControl

The commands and the events of the StdControl and the SplitControl interfaces are synchronous and can not be called from within asynchronous code (such as interrupt service routines, etc.). For the cases when the power state of the device needs to be controlled from within asynchronous code, the AsyncStdControl interface MUST be used in place of the StdControl interface. The definition of this interface can be seen below:

interface AsyncStdControl {
  async command error_t start();
  async command error_t stop();
}

All of the semantics that held true for devices providing the StdControl interface also hold for this interface.

Devices adhereing to this power management model would provide this interface as shown below:

configuration DeviceC {
  provides {
    interface Init;
    interface AsyncStdControl; \\ For Power Management
    ....
  }
}


.. Note::

Determining exactly when to use the AsyncStdControl interface
instead of simply posting a task and using the StdControl interface
can be tricky.  One must consider the advantages and disadvantages
of using one interface over the other.  How complex is the code
being I am trying to execute?  Do I really want to execute all of
my startup code in async context?  Do I gain some performance in
terms of startup latency or code size if I run my startup code in
async context?  These are just a few of the factors that need to be
considered when making this decision, and unfortunately there just
is no easy answer. Note that a component with an AsyncStdControl
cannot call SplitControl or StdControl. In practice, AsyncStdControl
is used for low-level hardware resources.

4. Implicit Power Management for Physical and Shared Resources

The physical and shared resource class defined in Section 2.3 of [TEP108], provides a well defined component interdependency, where a single resource is shared among multiple clients. This relationship enables definition of a simple default power-management policy that powers the resource off when no potential users are waiting for access to the resource. Conversely, the resource is powered on whenever a client requests its use. When the resource being controlled happens to be an actual physical device, the implicit power management model for physical devices as described in section two applies.

The realization of a specific power-control policy for shared reources does not need to be resource specific. Just as generic arbiters are offered in TinyOS 2.x to provide the arbitration functionality required by shared resources, generic power management policies are also offered to allow the power management of devices to be automated.

The PowerManager component implementing one of these polices acts as the lowest-priority user of the shared resource. In contrast to "normal" clients, the PowerManager interacts with the resource arbiter using the richer ResourceController interface:

interface ResourceController {
    async command error_t request();
    async command error_t immediateRequest();
    event void granted();
    async command void release();
    async event void requested();
    async event void idle();
}

Acting as a lowest priority client, the Power Manager waits for the ResourceController.idle() event to be signalled before trying to gain ownership over the resource. It does so using the ResourceController.immediateRequest() command in order to gain control of the resource as quickly as possible.

Once it owns the resource, the PowerManager is free to execute its power-management policy using the mechanisms provided by the resource via the explicit power-management model. Different managers can implement different policies. In the simplest case, this would involve an immediate power-down via one of the .stop() commands. When the power-state transition involves non-negligible costs in terms of wake-up latency or power consumption, the PowerManager might revert to a more intelligent strategy that tries to reduce these effects. One strategy might involve using a delayed power-down timer to defer the powers-down of a resource to some later point in time unless some normal-priority client requests the device in the meantime.

Regardless of the power-off policy, the PowerManager remains owner of the resource as long as the resource is not requested by a normal user. When one of these "normal" users finally makes a request, the PowerManager component will receive a ResourceController.requested() from the arbiter it is associated with. Upon receiving this event, the PowerManager MUST power the resource back on (in case it was powered-off) through one of the explicit power-management interfaces provided by the lower level abstraction of the physical device. The PowerManager can release the ownership of the resource (using the ResourceController.release() command) ONLY after the resource has been fully powered-on.

Modeling devices as shared resources and allowing them to be controlled in the way described here, solves the problems outlined in section 3 regarding how to keep track of who, when, and how the powerdown of nested resources should proceed. The PowerManager component answers the question of who, the combination of the power management policy being used and the reception of the ResourceController.idle() and ResourceController.requested() events answers the question of when, and through one of the explicit power-management interfaces provided by the lower level abstraction of the physical device answers how. As long as the device resource at the bottom of a large set of nested resource users is released at the proper time, the power mananger will ba ble to power down its device appropriately.

Using the model described above, a device resource that follows the implicitly powere management model could be built as shown below:

module MyFlashP {
  provides {
    interface Init;
    interface SplitControl;
    interface Resource;
    ...
  }
}
implementation {
...
}

generic module PowerManagerC(uint8_t POWERDOWN_DELAY) {
  provides {
    interface Init;
  }
  uses {
    interface SplitControl;
    interface ResourceController;
  }
}
implementation {
...
}

#define MYFLASH_RESOURCE "MyFlash.resource"
configuration MyFlashC {
  provides {
    interface Init;
    interface Resource;
  }
}
implementation {
  components new PowerManagerC(MYFLASH_POWERDOWN_DELAY)
           , FcfsArbiter(MYFLASH_RESOURCE)
           , MyFlashP;

  Init = MyFlashP;
  Resource = FcfsArbiter;

  PowerManagerC.ResourceController -> FcfsArbiter;
  PowerManagerC.SplitControl -> MyFlashP;
}

This example implementation is built out of three components. The first component (MyFlashP) follows the explicit power management model for defining the interfaces to the physical flash device. The second component (PowerManagerC) is the generic powermanager component that will be used to implement the specific power management policy for this device. The third component (MyFlashC) is the configuration file that wires together all of the components required by the implementation of device adhereing to the implicit power management model. It includes the MyflashP and PowerManagerC components, as well as an arbiter component for managing shared users of the device. Notice how the powermanager is wired to both the resourcecontroller interface provided by the arbiter, and the SplitControl interface provided by the flash. All normal users of the resource are directly connected to the resource interface provided by the arbiter. As outlined above, the PowerManagerC component will use the events signalled through the ResourceController interface from the arbiter to determine when to make calls to the commands provided by the SplitControl interface coming from the FlashP component in order to power it up and power it down.