frsh_energy_management.h

   1 // -----------------------------------------------------------------------
   2 //  Copyright (C) 2006 - 2007 FRESCOR consortium partners:
   3 //
   4 //    Universidad de Cantabria,              SPAIN
   5 //    University of York,                    UK
   6 //    Scuola Superiore Sant'Anna,            ITALY
   7 //    Kaiserslautern University,             GERMANY
   8 //    Univ. Politécnica  Valencia,           SPAIN
   9 //    Czech Technical University in Prague,  CZECH REPUBLIC
  10 //    ENEA                                   SWEDEN
  11 //    Thales Communication S.A.              FRANCE
  12 //    Visual Tools S.A.                      SPAIN
  13 //    Rapita Systems Ltd                     UK
  14 //    Evidence                               ITALY
  15 //
  16 //    See http://www.frescor.org for a link to partners' websites
  17 //
  18 //           FRESCOR project (FP6/2005/IST/5-034026) is funded
  19 //        in part by the European Union Sixth Framework Programme
  20 //        The European Union is not liable of any use that may be
  21 //        made of this code.
  22 //
  23 //
  24 //  based on previous work (FSF) done in the FIRST project
  25 //
  26 //   Copyright (C) 2005  Mälardalen University, SWEDEN
  27 //                       Scuola Superiore S.Anna, ITALY
  28 //                       Universidad de Cantabria, SPAIN
  29 //                       University of York, UK
  30 //
  31 //   FSF API web pages: http://marte.unican.es/fsf/docs
  32 //                      http://shark.sssup.it/contrib/first/docs/
  33 //
  34 //  This file is part of FRSH API
  35 //
  36 //  FRSH API is free software; you can  redistribute it and/or  modify
  37 //  it under the terms of  the GNU General Public License as published by
  38 //  the Free Software Foundation;  either  version 2, or (at  your option)
  39 //  any later version.
  40 //
  41 //  FRSH API  is distributed  in  the hope  that  it  will  be useful,  but
  42 //  WITHOUT  ANY  WARRANTY;     without  even the   implied   warranty  of
  43 //  MERCHANTABILITY  or  FITNESS FOR  A  PARTICULAR PURPOSE. See  the  GNU
  44 //  General Public License for more details.
  45 //
  46 //  You should have  received a  copy of  the  GNU  General Public License
  47 //  distributed  with  FRSH API;  see file COPYING.   If not,  write to the
  48 //  Free Software  Foundation,  59 Temple Place  -  Suite 330,  Boston, MA
  49 //  02111-1307, USA.
  50 //
  51 //  As a special exception, if you include this header file into source
  52 //  files to be compiled, this header file does not by itself cause
  53 //  the resulting executable to be covered by the GNU General Public
  54 //  License.  This exception does not however invalidate any other
  55 //  reasons why the executable file might be covered by the GNU General
  56 //  Public License.
  57 // -----------------------------------------------------------------------
  58 //frsh_energy_management.h
  59
  60 //==============================================
  61 //  ******** *******    ********  **      **
  62 //  **///// /**////**  **//////  /**     /**
  63 //  **      /**   /** /**        /**     /**
  64 //  ******* /*******  /********* /**********
  65 //  **////  /**///**  ////////** /**//////**
  66 //  **      /**  //**        /** /**     /**
  67 //  **      /**   //** ********  /**     /**
  68 //  //       //     // ////////   //      //
  69 //
  70 // FRSH(FRescor ScHeduler), pronounced "fresh"
  71 //==============================================
  72
  73 #ifndef  _FRSH_ENERGY_MANAGEMENT_H_
  74 #define  _FRSH_ENERGY_MANAGEMENT_H_
  75
  76 #include <time.h>
  77
  78 #include "frsh_energy_management_types.h"
  79 #include "frsh_core_types.h"
  80
  81 FRSH_CPP_BEGIN_DECLS
  82
  83 #define FRSH_ENERGY_MANAGEMENT_MODULE_SUPPORTED       1
  84
  85 /**
  86  * @file frsh_energy_management.h
  87  **/
  88
  89 /**
  90  * @defgroup energymgmnt Energy Management Module
  91  *
  92  * This module provides the ability to specify different budgets for
  93  * different CPU power levels.
  94  *
  95  * We model the situation by specifying budget values per power
  96  * level.  Thus switching in the power-level would be done by changing
  97  * the budget of the vres.  In all cases the period remains the same.
  98  *
  99  * All global FRSH contract operations (those done with the core
 100  * module without specifying the power level) are considered to be
 101  * applies to the higest power level.
 102  *
 103  * @{
 104  *
 105  **/
 106
 107
 108
 109 //////////////////////////////////////////////////////////////////////
 110 //           CONTRACT SERVICES
 111 //////////////////////////////////////////////////////////////////////
 112
 113
 114 /**
 115  * frsh_contract_set_min_duration()
 116  *
 117  * This function sets the minimum duration that the application must
 118  * be able to run without finishing battery power.  0 would mean no
 119  **/
 120 int frsh_contract_set_min_duration(struct timespec min_duration,
 121                                    frsh_contract_t *contract);
 122
 123 /**
 124  * frsh_contract_get_min_duration()
 125  *
 126  * Get version of the previous function.
 127  **/
 128 int frsh_contract_get_min_duration(const frsh_contract_t *contract,
 129                                    struct timespec *min_duration);
 130
 131 /**
 132  * frsh_contract_set_min_budget_pow()
 133  *
 134  * Here we specify the minimum budget values corresponding to the
 135  * 3 power levels.  The element order of the array goes from highest
 136  * power level to the lowest.
 137  *
 138  * @param[in] pow_min_budget Pointer to the first element of the
 139  *                           minimum budget array.  Elements
 140  *                           correspond to [0]->Highest PW,
 141  *                           [1]->Medium PW, [2]->Lowest PW.
 142  *
 143  * @return 0 if no error \n
 144  *        FRSH_ERR_BAD_ARGUMENT if any of the pointers is NULL or the
 145  *            budget values don't go in descending order.
 146  **/
 147 int frsh_contract_set_min_budget_pow(const struct timespec pow_min_budget[],
 148                                         frsh_contract_t *contract);
 149
 150 /**
 151  * frsh_contract_get_min_budget_pow()
 152  *
 153  * Get version of the previous function.
 154  **/
 155 int frsh_contract_get_min_budget_pow(const frsh_contract_t *contract,
 156                                        struct timespec pow_min_budget[]);
 157
 158 /**
 159  * frsh_contract_set_max_budget_pow()
 160  *
 161  * Here we specify the maximum budget values corresponding to the 3
 162  * power levels.  The element order of the array goes from highest
 163  * power level to the lowest.
 164  *
 165  * @param[in] pow_max_budget  Pointer to the first element of the
 166  *                            maximum budget array.  Elements
 167  *                            correspond to [0]->Highest PW,
 168  *                            [1]->Medium PW, [2]->Lowest PW.
 169  *
 170  * @param     contract        (in/out) Contract
 171  *
 172  * @return 0 if no error \n
 173  *        FRSH_ERR_BAD_ARGUMENT if any of the pointers is NULL or the
 174  *             budget values don't go in ascending order.
 175  *
 176  **/
 177 int frsh_contract_set_max_budget_pow(const struct timespec pow_max_budget[],
 178                                        frsh_contract_t *contract);
 179
 180 /**
 181  * frsh_contract_get_max_budget_pow()
 182  *
 183  * Get version of the previous function.
 184  **/
 185 int frsh_contract_get_max_budget_pow(const frsh_contract_t *contract,
 186                                        struct timespec pow_max_budget[]);
 187
 188
 189 /**
 190  * frsh_contract_set_utilizations_pow()
 191  *
 192  * Here we specify pairs of
 193  *    [ (budget_pmax, budget_pmedium, budget_plow) ,  Period ]
 194  *
 195  *    for contracts of discrete granularity.
 196  *
 197  * param[in] utilization_set  Discrete series of utilization values.
 198  * param contract (in/out) Contract object.
 199  **/
 200 int frsh_contract_set_utilizations_pow(const frsh_utilization_set_pow_t *utilization_set_pow,
 201                                        frsh_contract_t *contract);
 202
 203 /**
 204  * frsh_contract_get_utilizations_pow()
 205  *
 206  * Get version of the previous function.
 207  **/
 208 int frsh_contract_get_utilizations_pow(const frsh_utilization_set_pow_t *utilization_set_pow,
 209                                        frsh_contract_t *contract);
 210
 211
 212 //////////////////////////////////////////////////////////////////////
 213 //           MANAGING THE POWER LEVEL
 214 //////////////////////////////////////////////////////////////////////
 215
 216 /**
 217  * frsh_resource_set_power_level()
 218  *
 219  * Set the power level of the resource identified by the supplied type and id.
 220  *
 221  * @note
 222  * Only implementation for resource_type = FRSH_RT_PROCESSOR is mandatory,
 223  * if the energy management module is present.
 224  **/
 225 int frsh_resource_set_power_level(frsh_resource_type_t resource_type,
 226                                   frsh_resource_id_t resource_id,
 227                                   frsh_power_level_t power_level);
 228
 229 /**
 230  * frsh_resource_get_power_level()
 231  *
 232  * Get version of the previous function.
 233  **/
 234 int frsh_resource_get_power_level(frsh_resource_type_t resource_type,
 235                                   frsh_resource_id_t resource_id,
 236                                   frsh_power_level_t *power_level);
 237
 238 /**
 239  * frsh_resource_get_num_power_levels()
 240  *
 241  * Get the number of power levels available for the resource identified
 242  * by the supplied type and id.
 243  *
 244  * @note
 245  * The power levels that may be used, for the identified resource,
 246  * in other functions through a power_level_t type, range from 0
 247  * to the value returned by this function minus 1.
 248  *
 249  * @note
 250  * The power level 0 identifies the configuration with the maximum
 251  * performance (and energy consumption) for the resource.
 252  *
 253  * @note
 254  * Only implementation for resource_type = FRSH_RT_PROCESSOR is mandatory,
 255  * if the energy management module is present.
 256  */
 257 int frsh_resource_get_num_power_levels(frsh_resource_type_t resource_type,
 258                                        frsh_resource_id_t resource_id,
 259                                        frsh_power_level_t *num_power_levels);
 260
 261 //////////////////////////////////////////////////////////////////////
 262 //           BATTERY EXPIRATION AND MANAGING POWER LEVELS
 263 //////////////////////////////////////////////////////////////////////
 264
 265 /* /\** IS THIS NEEDED AT ALL ? I GUESS NOT - COMMENTED */
 266 /*  * frsh_resource_get_battery_expiration() */
 267 /*  * */
 268 /*  * Get the foreseen expiration time of the battery for the resource */
 269 /*  * identified by the supplied type and id. */
 270 /*  * */
 271 /* int frsh_battery_get_expiration(frsh_resource_type_t resource_type, */
 272 /*                               frsh_resource_id_t resource_id, */
 273 /*                               frsh_rel_time_t *expiration); */
 274
 275 /**
 276  * frsh_battery_get_expiration()
 277  *
 278  * Get the foreseen expiration time of the system battery(ies).
 279  **/
 280 int frsh_battery_get_expiration(struct timespec *expiration);
 281
 282 /*@}*/
 283
 284 FRSH_CPP_END_DECLS
 285
 286 #endif      /* _FRSH_ENERGY_MANAGEMENT_H_ */