// -----------------------------------------------------------------------
-// Copyright (C) 2006 - 2007 FRESCOR consortium partners:
+// Copyright (C) 2006 - 2008 FRESCOR consortium partners:
//
// Universidad de Cantabria, SPAIN
// University of York, UK
// 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
//
//
// 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
// FSF API web pages: http://marte.unican.es/fsf/docs
// http://shark.sssup.it/contrib/first/docs/
//
-// This file is part of FRSH API
-//
-// FRSH API is free software; you can redistribute it and/or modify
-// it under the terms of the GNU General Public License as published by
-// the Free Software Foundation; either version 2, or (at your option)
-// any later version.
+// This file is part of FRSH (FRescor ScHeduler)
//
-// FRSH API 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.
+// 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.
//
-// You should have received a copy of the GNU General Public License
-// distributed with FRSH API; see file COPYING. If not, write to the
-// Free Software Foundation, 59 Temple Place - Suite 330, Boston, MA
-// 02111-1307, USA.
-//
-// As a special exception, if you include this header file into source
-// files to be compiled, this header file does not by itself cause
-// the resulting executable 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 General
-// Public License.
+// 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
#include <time.h>
-#include "frsh_fosa.h"
#include "frsh_energy_management_types.h"
#include "frsh_core_types.h"
+FRSH_CPP_BEGIN_DECLS
#define FRSH_ENERGY_MANAGEMENT_MODULE_SUPPORTED 1
* @defgroup energymgmnt Energy Management Module
*
* This module provides the ability to specify different budgets for
- * different CPU power levels.
+ * 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
*
* All global FRSH contract operations (those done with the core
* module without specifying the power level) are considered to be
- * applies to the higest power level.
+ * 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.
*
* @{
*
/**
- * frsh_contract_set_min_duration()
+ * frsh_contract_set_min_expiration()
*
- * This function sets the minimum duration that the application must
- * be able to run without finishing battery power. 0 would mean no
+ * 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_duration(struct timespec min_duration,
- frsh_contract_t *contract);
+int frsh_contract_set_min_expiration(frsh_contract_t *contract,
+ frsh_rel_time_t min_expiration);
/**
- * frsh_contract_get_min_duration()
+ * frsh_contract_get_min_expiration()
*
* Get version of the previous function.
**/
-int frsh_contract_get_min_duration(const frsh_contract_t *contract,
- struct timespec *min_duration);
+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 values corresponding to the
- * 3 power levels. The element order of the array goes from highest
- * power level to the lowest.
+ * Here we specify the minimum budget value corresponding to a single
+ * power level.
*
- * @param[in] pow_min_budget Pointer to the first element of the
- * minimum budget array. Elements
- * correspond to [0]->Highest PW,
- * [1]->Medium PW, [2]->Lowest PW.
+ * @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 any of the pointers is NULL or the
- * budget values don't go in descending order.
+ * 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(const struct timespec pow_min_budget[],
- frsh_contract_t *contract);
+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,
- struct timespec pow_min_budget[]);
+ 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 values corresponding to the 3
- * power levels. The element order of the array goes from highest
- * power level to the lowest.
+ * Here we specify the maximum budget for a single power level.
*
- * @param[in] pow_max_budget Pointer to the first element of the
- * maximum budget array. Elements
- * correspond to [0]->Highest PW,
- * [1]->Medium PW, [2]->Lowest PW.
- *
- * @param contract (in/out) Contract
+ * @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(const struct timespec pow_max_budget[],
- frsh_contract_t *contract);
+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,
- struct timespec pow_max_budget[]);
+ frsh_power_level_t power_level,
+ frsh_rel_time_t *pow_max_budget);
/**
- * frsh_contract_set_utilizations_pow()
- *
- * Here we specify pairs of
- * [ (budget_pmax, budget_pmedium, budget_plow) , Period ]
+ * frsh_contract_set_utilization_pow()
*
- * for contracts of discrete granularity.
+ * 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[in] utilization_set Discrete series of utilization values.
- * param contract (in/out) Contract object.
+ * @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_utilizations_pow(const frsh_utilization_set_pow_t *utilization_set_pow,
- frsh_contract_t *contract);
+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_utilizations_pow()
+ * frsh_contract_get_utilization_pow()
*
* Get version of the previous function.
**/
-int frsh_contract_get_utilizations_pow(const frsh_utilization_set_pow_t *utilization_set_pow,
- frsh_contract_t *contract);
+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);
//////////////////////////////////////////////////////////////////////
/**
* frsh_resource_set_power_level()
*
- * Set the powerlevel of the CPU given by resource_id. We assume
- * resource_type = FRSH_RT_PROCESSOR.
+ * 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_id_t resource_id,
- int power_level);
+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_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,
+ frsh_power_level_t *num_power_levels);
//////////////////////////////////////////////////////////////////////
-// BATTERY DURATION AND MANAGING 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_resource_get_battery_duration()
+ * frsh_battery_get_expiration()
*
- * Get the remaining battery duration of the CPU given by resource_id.
- * We assume resource_type = FRSH_RT_PROCESSOR.
+ * Get the foreseen expiration time of the system battery(ies).
**/
-int frsh_resource_get_battery_duration(frsh_resource_id_t resource_id,
- struct timespec *duration);
+int frsh_battery_get_expiration(frsh_abs_time_t *expiration);
/*@}*/
+FRSH_CPP_END_DECLS
+
#endif /* _FRSH_ENERGY_MANAGEMENT_H_ */
projects / frescor / frsh-include.git / blobdiff