1 // -----------------------------------------------------------------------
2 // Copyright (C) 2006 - 2008 FRESCOR consortium partners:
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
11 // Thales Communication S.A. FRANCE
12 // Visual Tools S.A. SPAIN
13 // Rapita Systems Ltd UK
16 // See http://www.frescor.org for a link to partners' websites
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
24 // based on previous work (FSF) done in the FIRST project
26 // Copyright (C) 2005 Mälardalen University, SWEDEN
27 // Scuola Superiore S.Anna, ITALY
28 // Universidad de Cantabria, SPAIN
29 // University of York, UK
31 // FSF API web pages: http://marte.unican.es/fsf/docs
32 // http://shark.sssup.it/contrib/first/docs/
34 // This file is part of FRSH (FRescor ScHeduler)
36 // FRSH is free software; you can redistribute it and/or modify it
37 // under terms of the GNU General Public License as published by the
38 // Free Software Foundation; either version 2, or (at your option) any
39 // later version. FRSH is distributed in the hope that it will be
40 // useful, but WITHOUT ANY WARRANTY; without even the implied warranty
41 // of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
42 // General Public License for more details. You should have received a
43 // copy of the GNU General Public License along with FRSH; see file
44 // COPYING. If not, write to the Free Software Foundation, 675 Mass Ave,
45 // Cambridge, MA 02139, USA.
47 // As a special exception, including FRSH header files in a file,
48 // instantiating FRSH generics or templates, or linking other files
49 // with FRSH objects to produce an executable application, does not
50 // by itself cause the resulting executable application to be covered
51 // by the GNU General Public License. This exception does not
52 // however invalidate any other reasons why the executable file might be
53 // covered by the GNU Public License.
54 // -----------------------------------------------------------------------
55 //frsh_energy_management.h
57 //==============================================
58 // ******** ******* ******** ** **
59 // **///// /**////** **////// /** /**
60 // ** /** /** /** /** /**
61 // ******* /******* /********* /**********
62 // **//// /**///** ////////** /**//////**
63 // ** /** //** /** /** /**
64 // ** /** //** ******** /** /**
65 // // // // //////// // //
67 // FRSH(FRescor ScHeduler), pronounced "fresh"
68 //==============================================
70 #ifndef _FRSH_ENERGY_MANAGEMENT_H_
71 #define _FRSH_ENERGY_MANAGEMENT_H_
75 #include "frsh_energy_management_types.h"
76 #include "frsh_core_types.h"
80 #define FRSH_ENERGY_MANAGEMENT_MODULE_SUPPORTED 1
83 * @file frsh_energy_management.h
87 * @defgroup energymgmnt Energy Management Module
89 * This module provides the ability to specify different budgets for
90 * different power levels.
92 * We model the situation by specifying budget values per power
93 * level. Thus switching in the power-level would be done by changing
94 * the budget of the vres. In all cases the period remains the same.
96 * All global FRSH contract operations (those done with the core
97 * module without specifying the power level) are considered to be
98 * applied to the higest power level, corresponding to a power_level_t
102 * For all functions that operate on a contract, the resource is
103 * implicitly identified by the contract core parameters resource_type
104 * and resource_id that are either set through the
105 * frsh_contract_set_resource_and_label() function, or implicitly
106 * defined if no such call is made.
109 * For the power level management operations, only
110 * implementation for resource_type = FRSH_RT_PROCESSOR is mandatory,
111 * if the energy management module is present.
119 //////////////////////////////////////////////////////////////////////
121 //////////////////////////////////////////////////////////////////////
125 * frsh_contract_set_min_expiration()
127 * This function sets the minimum battery expiration time that the
128 * system must be able to sustain without finishing battery power. A
129 * value of (0,0) would mean that the application does not have such
130 * requirement (this is the default if this parameter is not explicitly
133 int frsh_contract_set_min_expiration(frsh_contract_t *contract,
134 frsh_rel_time_t min_expiration);
137 * frsh_contract_get_min_expiration()
139 * Get version of the previous function.
141 int frsh_contract_get_min_expiration(const frsh_contract_t *contract,
142 frsh_rel_time_t *min_expiration);
145 * frsh_contract_set_min_budget_pow()
147 * Here we specify the minimum budget value corresponding to a single
150 * @param contract The affected contract.
151 * @param power_level The power level for which we are specifying the minimum budget.
152 * @param pow_min_budget The minimum budget requested for the power level.
154 * @return 0 if no error \n
155 * FRSH_ERR_BAD_ARGUMENT if power_level is greater than or equal to the value
156 * returned by frsh_get_power_levels budget value is not correct.
159 * If the minimum budget relative to one or more power levels has not been specified, then
160 * the framework may attempt to perform interpolation of the supplied values in
161 * order to infer them, if an accurate model for such operation is available.
162 * Otherwise, the contract is rejected at frsh_negotiate() time.
164 int frsh_contract_set_min_budget_pow(frsh_contract_t *contract,
165 frsh_power_level_t power_level,
166 const frsh_rel_time_t *pow_min_budget);
169 * frsh_contract_get_min_budget_pow()
171 * Get version of the previous function.
173 int frsh_contract_get_min_budget_pow(const frsh_contract_t *contract,
174 frsh_power_level_t power_level,
175 frsh_rel_time_t *pow_min_budget);
178 * frsh_contract_set_max_budget_pow()
180 * Here we specify the maximum budget for a single power level.
182 * @param contract The affected contract object.
183 * @param power_level The power level for which we are specifying the maximum budget.
184 * @param pow_max_budget The maximum budget requested for the power level.
186 * @return 0 if no error \n
187 * FRSH_ERR_BAD_ARGUMENT if any of the pointers is NULL or the
188 * budget values don't go in ascending order.
191 int frsh_contract_set_max_budget_pow(frsh_contract_t *contract,
192 frsh_power_level_t power_level,
193 const frsh_rel_time_t *pow_max_budget);
196 * frsh_contract_get_max_budget_pow()
198 * Get version of the previous function.
200 int frsh_contract_get_max_budget_pow(const frsh_contract_t *contract,
201 frsh_power_level_t power_level,
202 frsh_rel_time_t *pow_max_budget);
206 * frsh_contract_set_utilization_pow()
208 * This function should be used for contracts with a period of
209 * discrete granularity. Here we specify, for each allowed period,
210 * the budget to be used for each power level.
212 * @param contract The affected contract object.
213 * @param power_level The power level for which we specify budget and period.
214 * @param budget The budget to be used for the supplied power level and period.
215 * @param period One of the allowed periods (from the discrete set).
216 * @param period The deadline used with the associated period (from the discrete set).
218 int frsh_contract_set_utilization_pow(frsh_contract_t *contract,
219 frsh_power_level_t power_level,
220 const frsh_rel_time_t *budget,
221 const frsh_rel_time_t *period,
222 const frsh_rel_time_t *deadline);
225 * frsh_contract_get_utilization_pow()
227 * Get version of the previous function.
229 int frsh_contract_get_utilization_pow(const frsh_contract_t *contract,
230 frsh_power_level_t power_level,
231 frsh_rel_time_t *budget,
232 frsh_rel_time_t *period,
233 frsh_rel_time_t *deadline);
236 //////////////////////////////////////////////////////////////////////
237 // MANAGING THE POWER LEVEL
238 //////////////////////////////////////////////////////////////////////
241 * frsh_resource_set_power_level()
243 * Set the power level of the resource identified by the supplied type and id.
246 * Only implementation for resource_type = FRSH_RT_PROCESSOR is mandatory,
247 * if the energy management module is present.
249 int frsh_resource_set_power_level(frsh_resource_type_t resource_type,
250 frsh_resource_id_t resource_id,
251 frsh_power_level_t power_level);
254 * frsh_resource_get_power_level()
256 * Get version of the previous function.
258 int frsh_resource_get_power_level(frsh_resource_type_t resource_type,
259 frsh_resource_id_t resource_id,
260 frsh_power_level_t *power_level);
263 * frsh_resource_get_num_power_levels()
265 * Get the number of power levels available for the resource identified
266 * by the supplied type and id.
269 * The power levels that may be used, for the identified resource,
270 * in other functions through a power_level_t type, range from 0
271 * to the value returned by this function minus 1.
274 * The power level 0 identifies the configuration with the maximum
275 * performance (and energy consumption) for the resource.
278 * Only implementation for resource_type = FRSH_RT_PROCESSOR is mandatory,
279 * if the energy management module is present.
281 int frsh_resource_get_num_power_levels(frsh_resource_type_t resource_type,
282 frsh_resource_id_t resource_id,
283 frsh_power_level_t *num_power_levels);
285 //////////////////////////////////////////////////////////////////////
286 // BATTERY EXPIRATION AND MANAGING POWER LEVELS
287 //////////////////////////////////////////////////////////////////////
289 /* /\** IS THIS NEEDED AT ALL ? I GUESS NOT - COMMENTED */
290 /* * frsh_resource_get_battery_expiration() */
292 /* * Get the foreseen expiration time of the battery for the resource */
293 /* * identified by the supplied type and id. */
295 /* int frsh_battery_get_expiration(frsh_resource_type_t resource_type, */
296 /* frsh_resource_id_t resource_id, */
297 /* frsh_rel_time_t *expiration); */
300 * frsh_battery_get_expiration()
302 * Get the foreseen expiration time of the system battery(ies).
304 int frsh_battery_get_expiration(frsh_abs_time_t *expiration);
310 #endif /* _FRSH_ENERGY_MANAGEMENT_H_ */