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 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  * applied to the higest power level, corresponding to a power_level_t
 102  * value of 0.
 103  *
 104  * @note
 105  * For all functions that operate on a contract, the resource is
 106  * implicitly identified by the contract core parameters resource_type
 107  * and resource_id that are either set through the
 108  * frsh_contract_set_resource_and_label() function, or implicitly
 109  * defined if no such call is made.
 110  *
 111  * @note
 112  * For the power level management operations, only
 113  * implementation for resource_type = FRSH_RT_PROCESSOR is mandatory,
 114  * if the energy management module is present.
 115  *
 116  * @{
 117  *
 118  **/
 119
 120
 121
 122 //////////////////////////////////////////////////////////////////////
 123 //           CONTRACT SERVICES
 124 //////////////////////////////////////////////////////////////////////
 125
 126
 127 /**
 128  * frsh_contract_set_min_expiration()
 129  *
 130  * This function sets the minimum battery expiration time that the
 131  * system must be able to sustain without finishing battery power. A
 132  * value of (0,0) would mean that the application does not have such
 133  * requirement (this is the default if this parameter is not explicitly
 134  * set).
 135  **/
 136 int frsh_contract_set_min_expiration(frsh_contract_t *contract,
 137                                      frsh_rel_time_t min_expiration);
 138
 139 /**
 140  * frsh_contract_get_min_expiration()
 141  *
 142  * Get version of the previous function.
 143  **/
 144 int frsh_contract_get_min_expiration(const frsh_contract_t *contract,
 145                                      frsh_rel_time_t *min_expiration);
 146
 147 /**
 148  * frsh_contract_set_min_budget_pow()
 149  *
 150  * Here we specify the minimum budget value corresponding to a single
 151  * power level.
 152  *
 153  * @param contract              The affected contract.
 154  * @param power_level           The power level for which we are specifying the minimum budget.
 155  * @param pow_min_budget        The minimum budget requested for the power level.
 156  *
 157  * @return 0 if no error \n
 158  *      FRSH_ERR_BAD_ARGUMENT if power_level is greater than or equal to the value
 159  *      returned by frsh_get_power_levels  budget value is not correct.
 160  *
 161  * @note
 162  * If the minimum budget relative to one or more power levels has not been specified, then
 163  * the framework may attempt to perform interpolation of the supplied values in
 164  * order to infer them, if an accurate model for such operation is available.
 165  * Otherwise, the contract is rejected at frsh_negotiate() time.
 166  **/
 167 int frsh_contract_set_min_budget_pow(frsh_contract_t *contract,
 168                                      frsh_power_level_t power_level,
 169                                      const frsh_rel_time_t *pow_min_budget);
 170
 171 /**
 172  * frsh_contract_get_min_budget_pow()
 173  *
 174  * Get version of the previous function.
 175  **/
 176 int frsh_contract_get_min_budget_pow(const frsh_contract_t *contract,
 177                                      frsh_power_level_t power_level,
 178                                      frsh_rel_time_t *pow_min_budget);
 179
 180 /**
 181  * frsh_contract_set_max_budget_pow()
 182  *
 183  * Here we specify the maximum budget for a single power level.
 184  *
 185  * @param contract              The affected contract object.
 186  * @param power_level           The power level for which we are specifying the maximum budget.
 187  * @param pow_max_budget        The maximum budget requested for the power level.
 188  *
 189  * @return 0 if no error \n
 190  *        FRSH_ERR_BAD_ARGUMENT if any of the pointers is NULL or the
 191  *             budget values don't go in ascending order.
 192  *
 193  **/
 194 int frsh_contract_set_max_budget_pow(frsh_contract_t *contract,
 195                                      frsh_power_level_t power_level,
 196                                      const frsh_rel_time_t *pow_max_budget);
 197
 198 /**
 199  * frsh_contract_get_max_budget_pow()
 200  *
 201  * Get version of the previous function.
 202  **/
 203 int frsh_contract_get_max_budget_pow(const frsh_contract_t *contract,
 204                                      frsh_power_level_t power_level,
 205                                      frsh_rel_time_t *pow_max_budget);
 206
 207
 208 /**
 209  * frsh_contract_set_utilization_pow()
 210  *
 211  * This function should be used for contracts with a period of
 212  * discrete granularity.  Here we specify, for each allowed period,
 213  * the budget to be used for each power level.
 214  *
 215  * @param contract      The affected contract object.
 216  * @param power_level   The power level for which we specify budget and period.
 217  * @param budget        The budget to be used for the supplied power level and period.
 218  * @param period        One of the allowed periods (from the discrete set).
 219  * @param period        The deadline used with the associated period (from the discrete set).
 220  **/
 221 int frsh_contract_set_utilization_pow(frsh_contract_t *contract,
 222                                       frsh_power_level_t power_level,
 223                                       const frsh_rel_time_t *budget,
 224                                       const frsh_rel_time_t *period,
 225                                       const frsh_rel_time_t *deadline);
 226
 227 /**
 228  * frsh_contract_get_utilization_pow()
 229  *
 230  * Get version of the previous function.
 231  **/
 232 int frsh_contract_get_utilization_pow(const frsh_contract_t *contract,
 233                                       frsh_power_level_t power_level,
 234                                       frsh_rel_time_t *budget,
 235                                       frsh_rel_time_t *period,
 236                                       frsh_rel_time_t *deadline);
 237
 238
 239 //////////////////////////////////////////////////////////////////////
 240 //           MANAGING THE POWER LEVEL
 241 //////////////////////////////////////////////////////////////////////
 242
 243 /**
 244  * frsh_resource_set_power_level()
 245  *
 246  * Set the power level of the resource identified by the supplied type and id.
 247  *
 248  * @note
 249  * Only implementation for resource_type = FRSH_RT_PROCESSOR is mandatory,
 250  * if the energy management module is present.
 251  **/
 252 int frsh_resource_set_power_level(frsh_resource_type_t resource_type,
 253                                   frsh_resource_id_t resource_id,
 254                                   frsh_power_level_t power_level);
 255
 256 /**
 257  * frsh_resource_get_power_level()
 258  *
 259  * Get version of the previous function.
 260  **/
 261 int frsh_resource_get_power_level(frsh_resource_type_t resource_type,
 262                                   frsh_resource_id_t resource_id,
 263                                   frsh_power_level_t *power_level);
 264
 265 /**
 266  * frsh_resource_get_num_power_levels()
 267  *
 268  * Get the number of power levels available for the resource identified
 269  * by the supplied type and id.
 270  *
 271  * @note
 272  * The power levels that may be used, for the identified resource,
 273  * in other functions through a power_level_t type, range from 0
 274  * to the value returned by this function minus 1.
 275  *
 276  * @note
 277  * The power level 0 identifies the configuration with the maximum
 278  * performance (and energy consumption) for the resource.
 279  *
 280  * @note
 281  * Only implementation for resource_type = FRSH_RT_PROCESSOR is mandatory,
 282  * if the energy management module is present.
 283  */
 284 int frsh_resource_get_num_power_levels(frsh_resource_type_t resource_type,
 285                                        frsh_resource_id_t resource_id,
 286                                        frsh_power_level_t *num_power_levels);
 287
 288 //////////////////////////////////////////////////////////////////////
 289 //           BATTERY EXPIRATION AND MANAGING POWER LEVELS
 290 //////////////////////////////////////////////////////////////////////
 291
 292 /* /\** IS THIS NEEDED AT ALL ? I GUESS NOT - COMMENTED */
 293 /*  * frsh_resource_get_battery_expiration() */
 294 /*  * */
 295 /*  * Get the foreseen expiration time of the battery for the resource */
 296 /*  * identified by the supplied type and id. */
 297 /*  * */
 298 /* int frsh_battery_get_expiration(frsh_resource_type_t resource_type, */
 299 /*                               frsh_resource_id_t resource_id, */
 300 /*                               frsh_rel_time_t *expiration); */
 301
 302 /**
 303  * frsh_battery_get_expiration()
 304  *
 305  * Get the foreseen expiration time of the system battery(ies).
 306  **/
 307 int frsh_battery_get_expiration(frsh_abs_time_t *expiration);
 308
 309 /*@}*/
 310
 311 FRSH_CPP_END_DECLS
 312
 313 #endif      /* _FRSH_ENERGY_MANAGEMENT_H_ */