core/sys/compower.h

   1 /** \addtogroup sys
   2  * @{ */
   3
   4 /**
   5  * \defgroup compower Communication power accounting
   6  * @{
   7  *
   8  * The compower module accumulates power consumption information and
   9  * attributes it to communication activities. Examples of
  10  * communication activities are packet transmission, packet reception,
  11  * and idle listening.
  12  *
  13  */
  14
  15 /*
  16  * Copyright (c) 2009, Swedish Institute of Computer Science.
  17  * All rights reserved.
  18  *
  19  * Redistribution and use in source and binary forms, with or without
  20  * modification, are permitted provided that the following conditions
  21  * are met:
  22  * 1. Redistributions of source code must retain the above copyright
  23  *    notice, this list of conditions and the following disclaimer.
  24  * 2. Redistributions in binary form must reproduce the above copyright
  25  *    notice, this list of conditions and the following disclaimer in the
  26  *    documentation and/or other materials provided with the distribution.
  27  * 3. Neither the name of the Institute nor the names of its contributors
  28  *    may be used to endorse or promote products derived from this software
  29  *    without specific prior written permission.
  30  *
  31  * THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
  32  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  33  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  34  * ARE DISCLAIMED.  IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
  35  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  36  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  37  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  38  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  39  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  40  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  41  * SUCH DAMAGE.
  42  *
  43  * This file is part of the Contiki operating system.
  44  *
  45  * $Id: compower.h,v 1.2 2009/03/12 21:58:21 adamdunkels Exp $
  46  */
  47
  48 /**
  49  * \file
  50  *         Header file for the communication power accounting module
  51  * \author
  52  *         Adam Dunkels <adam@sics.se>
  53  */
  54
  55 #ifndef __COMPOWER_H__
  56 #define __COMPOWER_H__
  57
  58 /**
  59  * \brief      An activity record that contains power consumption information for a specific communication activity.
  60  *
  61  *             This is a structure that holds power information about
  62  *             a communication activity. It is an opaque structure
  63  *             with no user-visible elements.
  64  */
  65 struct compower_activity {
  66   uint32_t listen, transmit;
  67 };
  68
  69 /**
  70  * \brief      The default idle communication activity.
  71  *
  72  *             This is the idle communication activity, to which all
  73  *             energy that is not possible to attribute to individual
  74  *             packets, is attributed. Examples include idle listening
  75  *             for incoming packets and MAC-level beacon
  76  *             transmissions.
  77  */
  78 extern struct compower_activity compower_idle_activity;
  79
  80 /**
  81  * \brief      Initialize the communication power accounting module.
  82  *
  83  *             This function initializes the communication power
  84  *             accounting module. The function is called by the system
  85  *             during boot-up.
  86  */
  87 void compower_init(void);
  88
  89 /**
  90  * \brief      Accumulate power contumption for a communication activity
  91  * \param a    A pointer to an activity structure.
  92  *
  93  *             This function accumulates power consumption information
  94  *             for a communication activity. The function typically is
  95  *             called by a power-saving MAC protocol when the radio is
  96  *             switched off, or when a packet is received or
  97  *             transmitted.
  98  *
  99  */
 100 void compower_accumulate(struct compower_activity *a);
 101
 102 /**
 103  * \brief      Clear power consumption information for a communication activity
 104  * \param a    A pointer to an activity structure.
 105  *
 106  *             This function clears any power contumption information
 107  *             that has previously been accumulated in an activity
 108  *             structure.
 109  *
 110  */
 111 void compower_clear(struct compower_activity *a);
 112
 113 /**
 114  * \brief      Convert power contumption information to packet attributes
 115  * \param a    A pointer to an activity structure.
 116  *
 117  *             This function converts accumulated power consumption
 118  *             information for a communication activity to packet
 119  *             attributes (see \ref packetbufattr "packet attributes").
 120  */
 121 void compower_attrconv(struct compower_activity *a);
 122
 123 /**
 124  * \brief      Accumulate power contumption for a communication activity based on energy data in packet attributes
 125  * \param a    A pointer to an activity structure.
 126  *
 127  *             This function accumulates power consumption information
 128  *             for a communication activity from packet attributes
 129  *             (see \ref packetbufattr "packet attributes").
 130  */
 131 void compower_accumulate_attrs(struct compower_activity *a);
 132
 133 #endif /* __COMPOWER_H__ */
 134
 135 /** @} */
 136 /** @} */