tos/interfaces/McuPowerOverride.nc

   1 /// $Id$
   2
   3 /**
   4  * "Copyright (c) 2005 Stanford University. All rights reserved.
   5  *
   6  * Permission to use, copy, modify, and distribute this software and
   7  * its documentation for any purpose, without fee, and without written
   8  * agreement is hereby granted, provided that the above copyright
   9  * notice, the following two paragraphs and the author appear in all
  10  * copies of this software.
  11  *
  12  * IN NO EVENT SHALL STANFORD UNIVERSITY BE LIABLE TO ANY PARTY FOR
  13  * DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
  14  * ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN
  15  * IF STANFORD UNIVERSITY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
  16  * DAMAGE.
  17  *
  18  * STANFORD UNIVERSITY SPECIFICALLY DISCLAIMS ANY WARRANTIES,
  19  * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
  20  * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE
  21  * PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND STANFORD UNIVERSITY
  22  * HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES,
  23  * ENHANCEMENTS, OR MODIFICATIONS."
  24  *
  25  */
  26
  27 /**
  28  * Interface to allow high-level components to set a lower bound for a
  29  * microcontroller's low power state. This is sometimes necessary,
  30  * e.g., if a very low power state has a long wakeup latency that will
  31  * violate application timing requirements. TEP 112 describes how
  32  * TinyOS incorporates this information when the Scheduler tells
  33  * the MCU to enter a low power state.
  34  *
  35  * @author Philip Levis
  36  * @date   Oct 26, 2005
  37  * @see    TEP 112: Microconroller Power Management
  38  */
  39
  40 #include "hardware.h"
  41
  42 interface McuPowerOverride {
  43
  44   /**
  45    * Called when computing the low power state, in order to allow
  46    * a high-level component to institute a lower bound. Because
  47    * this command originates deep within the basic TinyOS scheduling
  48    * mechanisms, it should be used very sparingly. Refer to TEP 112 for
  49    * details.
  50    *
  51    * @return    the lowest power state the system can enter to meet the
  52    *            requirements of this component
  53    */
  54   async command mcu_power_t lowestState();
  55 }