// ----------------------------------------------------------------------- // Copyright (C) 2006 - 2009 FRESCOR consortium partners: // // Universidad de Cantabria, SPAIN // University of York, UK // Scuola Superiore Sant'Anna, ITALY // Kaiserslautern University, GERMANY // Univ. Politécnica Valencia, SPAIN // Czech Technical University in Prague, CZECH REPUBLIC // ENEA SWEDEN // Thales Communication S.A. FRANCE // Visual Tools S.A. SPAIN // Rapita Systems Ltd UK // Evidence ITALY // // See http://www.frescor.org for a link to partners' websites // // FRESCOR project (FP6/2005/IST/5-034026) is funded // in part by the European Union Sixth Framework Programme // The European Union is not liable of any use that may be // made of this code. // // // based on previous work (FSF) done in the FIRST project // // Copyright (C) 2005 Mälardalen University, SWEDEN // Scuola Superiore S.Anna, ITALY // Universidad de Cantabria, SPAIN // University of York, UK // // FSF API web pages: http://marte.unican.es/fsf/docs // http://shark.sssup.it/contrib/first/docs/ // // This file is part of FRSH (FRescor ScHeduler) // // FRSH is free software; you can redistribute it and/or modify it // under terms of the GNU General Public License as published by the // Free Software Foundation; either version 2, or (at your option) any // later version. FRSH is distributed in the hope that it will be // useful, but WITHOUT ANY WARRANTY; without even the implied warranty // of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU // General Public License for more details. You should have received a // copy of the GNU General Public License along with FRSH; see file // COPYING. If not, write to the Free Software Foundation, 675 Mass Ave, // Cambridge, MA 02139, USA. // // As a special exception, including FRSH header files in a file, // instantiating FRSH generics or templates, or linking other files // with FRSH objects to produce an executable application, does not // by itself cause the resulting executable application to be covered // by the GNU General Public License. This exception does not // however invalidate any other reasons why the executable file might be // covered by the GNU Public License. // ----------------------------------------------------------------------- //frsh_energy_management.h //============================================== // ******** ******* ******** ** ** // **///// /**////** **////// /** /** // ** /** /** /** /** /** // ******* /******* /********* /********** // **//// /**///** ////////** /**//////** // ** /** //** /** /** /** // ** /** //** ******** /** /** // // // // //////// // // // // FRSH(FRescor ScHeduler), pronounced "fresh" //============================================== #ifndef _FRSH_ENERGY_MANAGEMENT_H_ #define _FRSH_ENERGY_MANAGEMENT_H_ #include #include "frsh_energy_management_types.h" #include "frsh_core_types.h" FRSH_CPP_BEGIN_DECLS #define FRSH_ENERGY_MANAGEMENT_MODULE_SUPPORTED 1 /** * @file frsh_energy_management.h **/ /** * @defgroup energymgmnt Energy Management Module * * This module provides the ability to specify different budgets for * different power levels. * * We model the situation by specifying budget values per power * level. Thus switching in the power-level would be done by changing * the budget of the vres. In all cases the period remains the same. * * All global FRSH contract operations (those done with the core * module without specifying the power level) are considered to be * applied to the higest power level, corresponding to a power_level_t * value of 0. * * @note * For all functions that operate on a contract, the resource is * implicitly identified by the contract core parameters resource_type * and resource_id that are either set through the * frsh_contract_set_resource_and_label() function, or implicitly * defined if no such call is made. * * @note * For the power level management operations, only * implementation for resource_type = FRSH_RT_PROCESSOR is mandatory, * if the energy management module is present. * * @{ * **/ ////////////////////////////////////////////////////////////////////// // CONTRACT SERVICES ////////////////////////////////////////////////////////////////////// /** * frsh_contract_set_min_expiration() * * This function sets the minimum battery expiration time that the * system must be able to sustain without finishing battery power. A * value of (0,0) would mean that the application does not have such * requirement (this is the default if this parameter is not explicitly * set). **/ int frsh_contract_set_min_expiration(frsh_contract_t *contract, frsh_rel_time_t min_expiration); /** * frsh_contract_get_min_expiration() * * Get version of the previous function. **/ int frsh_contract_get_min_expiration(const frsh_contract_t *contract, frsh_rel_time_t *min_expiration); /** * frsh_contract_set_min_budget_pow() * * Here we specify the minimum budget value corresponding to a single * power level. * * @param contract The affected contract. * @param power_level The power level for which we are specifying the minimum budget. * @param pow_min_budget The minimum budget requested for the power level. * * @return 0 if no error \n * FRSH_ERR_BAD_ARGUMENT if power_level is greater than or equal to the value * returned by frsh_get_power_levels budget value is not correct. * * @note * If the minimum budget relative to one or more power levels has not been specified, then * the framework may attempt to perform interpolation of the supplied values in * order to infer them, if an accurate model for such operation is available. * Otherwise, the contract is rejected at frsh_negotiate() time. **/ int frsh_contract_set_min_budget_pow(frsh_contract_t *contract, frsh_power_level_t power_level, const frsh_rel_time_t *pow_min_budget); /** * frsh_contract_get_min_budget_pow() * * Get version of the previous function. **/ int frsh_contract_get_min_budget_pow(const frsh_contract_t *contract, frsh_power_level_t power_level, frsh_rel_time_t *pow_min_budget); /** * frsh_contract_set_max_budget_pow() * * Here we specify the maximum budget for a single power level. * * @param contract The affected contract object. * @param power_level The power level for which we are specifying the maximum budget. * @param pow_max_budget The maximum budget requested for the power level. * * @return 0 if no error \n * FRSH_ERR_BAD_ARGUMENT if any of the pointers is NULL or the * budget values don't go in ascending order. * **/ int frsh_contract_set_max_budget_pow(frsh_contract_t *contract, frsh_power_level_t power_level, const frsh_rel_time_t *pow_max_budget); /** * frsh_contract_get_max_budget_pow() * * Get version of the previous function. **/ int frsh_contract_get_max_budget_pow(const frsh_contract_t *contract, frsh_power_level_t power_level, frsh_rel_time_t *pow_max_budget); /** * frsh_contract_set_utilization_pow() * * This function should be used for contracts with a period of * discrete granularity. Here we specify, for each allowed period, * the budget to be used for each power level. * * @param contract The affected contract object. * @param power_level The power level for which we specify budget and period. * @param budget The budget to be used for the supplied power level and period. * @param period One of the allowed periods (from the discrete set). * @param period The deadline used with the associated period (from the discrete set). **/ int frsh_contract_set_utilization_pow(frsh_contract_t *contract, frsh_power_level_t power_level, const frsh_rel_time_t *budget, const frsh_rel_time_t *period, const frsh_rel_time_t *deadline); /** * frsh_contract_get_utilization_pow() * * Get version of the previous function. **/ int frsh_contract_get_utilization_pow(const frsh_contract_t *contract, frsh_power_level_t power_level, frsh_rel_time_t *budget, frsh_rel_time_t *period, frsh_rel_time_t *deadline); ////////////////////////////////////////////////////////////////////// // MANAGING THE POWER LEVEL ////////////////////////////////////////////////////////////////////// /** * frsh_resource_set_power_level() * * Set the power level of the resource identified by the supplied type and id. * * @note * Only implementation for resource_type = FRSH_RT_PROCESSOR is mandatory, * if the energy management module is present. **/ int frsh_resource_set_power_level(frsh_resource_type_t resource_type, frsh_resource_id_t resource_id, frsh_power_level_t power_level); /** * frsh_resource_get_power_level() * * Get version of the previous function. **/ int frsh_resource_get_power_level(frsh_resource_type_t resource_type, frsh_resource_id_t resource_id, frsh_power_level_t *power_level); /** * frsh_resource_get_speed() * * Get in speed_ratio representative value for the speed of the specified * resource, with respect to the maximum possible speed for such resource. * * @note * Only implementation for resource_type = FRSH_RT_PROCESSOR is mandatory, * if the energy management module is present. **/ int frsh_resource_get_speed(frsh_resource_type_t resource_type, frsh_resource_id_t resource_id, frsh_power_level_t power_level, double *speed_ratio); /** * frsh_resource_get_num_power_levels() * * Get the number of power levels available for the resource identified * by the supplied type and id. * * @note * The power levels that may be used, for the identified resource, * in other functions through a power_level_t type, range from 0 * to the value returned by this function minus 1. * * @note * The power level 0 identifies the configuration with the maximum * performance (and energy consumption) for the resource. * * @note * Only implementation for resource_type = FRSH_RT_PROCESSOR is mandatory, * if the energy management module is present. */ int frsh_resource_get_num_power_levels(frsh_resource_type_t resource_type, frsh_resource_id_t resource_id, int *num_power_levels); ////////////////////////////////////////////////////////////////////// // BATTERY EXPIRATION AND MANAGING POWER LEVELS ////////////////////////////////////////////////////////////////////// /* /\** IS THIS NEEDED AT ALL ? I GUESS NOT - COMMENTED */ /* * frsh_resource_get_battery_expiration() */ /* * */ /* * Get the foreseen expiration time of the battery for the resource */ /* * identified by the supplied type and id. */ /* * */ /* int frsh_battery_get_expiration(frsh_resource_type_t resource_type, */ /* frsh_resource_id_t resource_id, */ /* frsh_rel_time_t *expiration); */ /** * frsh_battery_get_expiration() * * Get the foreseen expiration time of the system battery(ies). **/ int frsh_battery_get_expiration(frsh_abs_time_t *expiration); /*@}*/ FRSH_CPP_END_DECLS #endif /* _FRSH_ENERGY_MANAGEMENT_H_ */