Contiki 2.6

compower.h

Go to the documentation of this file.
00001 /** \addtogroup sys
00002  * @{ */
00003 
00004 /**
00005  * \defgroup compower Communication power accounting
00006  * @{
00007  *
00008  * The compower module accumulates power consumption information and
00009  * attributes it to communication activities. Examples of
00010  * communication activities are packet transmission, packet reception,
00011  * and idle listening.
00012  *
00013  */
00014 
00015 /*
00016  * Copyright (c) 2009, Swedish Institute of Computer Science.
00017  * All rights reserved.
00018  *
00019  * Redistribution and use in source and binary forms, with or without
00020  * modification, are permitted provided that the following conditions
00021  * are met:
00022  * 1. Redistributions of source code must retain the above copyright
00023  *    notice, this list of conditions and the following disclaimer.
00024  * 2. Redistributions in binary form must reproduce the above copyright
00025  *    notice, this list of conditions and the following disclaimer in the
00026  *    documentation and/or other materials provided with the distribution.
00027  * 3. Neither the name of the Institute nor the names of its contributors
00028  *    may be used to endorse or promote products derived from this software
00029  *    without specific prior written permission.
00030  *
00031  * THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
00032  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
00033  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
00034  * ARE DISCLAIMED.  IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
00035  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
00036  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
00037  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
00038  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
00039  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
00040  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
00041  * SUCH DAMAGE.
00042  *
00043  * This file is part of the Contiki operating system.
00044  *
00045  * $Id: compower.h,v 1.2 2009/03/12 21:58:21 adamdunkels Exp $
00046  */
00047 
00048 /**
00049  * \file
00050  *         Header file for the communication power accounting module
00051  * \author
00052  *         Adam Dunkels <adam@sics.se>
00053  */
00054 
00055 #ifndef __COMPOWER_H__
00056 #define __COMPOWER_H__
00057 
00058 /**
00059  * \brief      An activity record that contains power consumption information for a specific communication activity.
00060  *
00061  *             This is a structure that holds power information about
00062  *             a communication activity. It is an opaque structure
00063  *             with no user-visible elements.
00064  */
00065 struct compower_activity {
00066   uint32_t listen, transmit;
00067 };
00068 
00069 /**
00070  * \brief      The default idle communication activity.
00071  *
00072  *             This is the idle communication activity, to which all
00073  *             energy that is not possible to attribute to individual
00074  *             packets, is attributed. Examples include idle listening
00075  *             for incoming packets and MAC-level beacon
00076  *             transmissions.
00077  */
00078 extern struct compower_activity compower_idle_activity;
00079 
00080 /**
00081  * \brief      Initialize the communication power accounting module.
00082  *
00083  *             This function initializes the communication power
00084  *             accounting module. The function is called by the system
00085  *             during boot-up.
00086  */
00087 void compower_init(void);
00088 
00089 /**
00090  * \brief      Accumulate power contumption for a communication activity
00091  * \param a    A pointer to an activity structure.
00092  *
00093  *             This function accumulates power consumption information
00094  *             for a communication activity. The function typically is
00095  *             called by a power-saving MAC protocol when the radio is
00096  *             switched off, or when a packet is received or
00097  *             transmitted.
00098  *
00099  */
00100 void compower_accumulate(struct compower_activity *a);
00101 
00102 /**
00103  * \brief      Clear power consumption information for a communication activity
00104  * \param a    A pointer to an activity structure.
00105  *
00106  *             This function clears any power contumption information
00107  *             that has previously been accumulated in an activity
00108  *             structure.
00109  *
00110  */
00111 void compower_clear(struct compower_activity *a);
00112 
00113 /**
00114  * \brief      Convert power contumption information to packet attributes
00115  * \param a    A pointer to an activity structure.
00116  *
00117  *             This function converts accumulated power consumption
00118  *             information for a communication activity to packet
00119  *             attributes (see \ref packetbufattr "packet attributes").
00120  */
00121 void compower_attrconv(struct compower_activity *a);
00122 
00123 /**
00124  * \brief      Accumulate power contumption for a communication activity based on energy data in packet attributes
00125  * \param a    A pointer to an activity structure.
00126  *
00127  *             This function accumulates power consumption information
00128  *             for a communication activity from packet attributes
00129  *             (see \ref packetbufattr "packet attributes").
00130  */
00131 void compower_accumulate_attrs(struct compower_activity *a);
00132 
00133 #endif /* __COMPOWER_H__ */
00134 
00135 /** @} */
00136 /** @} */