1 // -----------------------------------------------------------------------
2 // Copyright (C) 2006 - 2007 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 API
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)
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.
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
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
57 // -----------------------------------------------------------------------
58 //frsh_energy_management.h
60 //==============================================
61 // ******** ******* ******** ** **
62 // **///// /**////** **////// /** /**
63 // ** /** /** /** /** /**
64 // ******* /******* /********* /**********
65 // **//// /**///** ////////** /**//////**
66 // ** /** //** /** /** /**
67 // ** /** //** ******** /** /**
68 // // // // //////// // //
70 // FRSH(FRescor ScHeduler), pronounced "fresh"
71 //==============================================
73 #ifndef _FRSH_ENERGY_MANAGEMENT_H_
74 #define _FRSH_ENERGY_MANAGEMENT_H_
78 #include "frsh_fosa.h"
79 #include "frsh_energy_management_types.h"
80 #include "frsh_core_types.h"
83 #define FRSH_ENERGY_MANAGEMENT_MODULE_SUPPORTED 1
86 * @file frsh_energy_management.h
90 * @defgroup energymgmnt Energy Management Module
92 * This module provides the ability to specify different budgets for
93 * different CPU power levels.
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.
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.
109 //////////////////////////////////////////////////////////////////////
111 //////////////////////////////////////////////////////////////////////
115 * frsh_contract_set_min_duration()
117 * This function sets the minimum duration that the application must
118 * be able to run without finishing battery power. 0 would mean no
120 int frsh_contract_set_min_duration(struct timespec min_duration,
121 frsh_contract_t *contract);
124 * frsh_contract_get_min_duration()
126 * Get version of the previous function.
128 int frsh_contract_get_min_duration(const frsh_contract_t *contract,
129 struct timespec *min_duration);
132 * frsh_contract_set_min_budget_pow()
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.
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.
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.
147 int frsh_contract_set_min_budget_pow(const struct timespec pow_min_budget[],
148 frsh_contract_t *contract);
151 * frsh_contract_get_min_budget_pow()
153 * Get version of the previous function.
155 int frsh_contract_get_min_budget_pow(const frsh_contract_t *contract,
156 struct timespec pow_min_budget[]);
159 * frsh_contract_set_max_budget_pow()
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.
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.
170 * @param contract (in/out) Contract
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.
177 int frsh_contract_set_max_budget_pow(const struct timespec pow_max_budget[],
178 frsh_contract_t *contract);
181 * frsh_contract_get_max_budget_pow()
183 * Get version of the previous function.
185 int frsh_contract_get_max_budget_pow(const frsh_contract_t *contract,
186 struct timespec pow_max_budget[]);
190 * frsh_contract_set_utilizations_pow()
192 * Here we specify pairs of
193 * [ (budget_pmax, budget_pmedium, budget_plow) , Period ]
195 * for contracts of discrete granularity.
197 * param[in] utilization_set Discrete series of utilization values.
198 * param contract (in/out) Contract object.
200 int frsh_contract_set_utilizations_pow(const frsh_utilization_set_pow_t *utilization_set_pow,
201 frsh_contract_t *contract);
204 * frsh_contract_get_utilizations_pow()
206 * Get version of the previous function.
208 int frsh_contract_get_utilizations_pow(const frsh_utilization_set_pow_t *utilization_set_pow,
209 frsh_contract_t *contract);
212 //////////////////////////////////////////////////////////////////////
213 // MANAGING THE POWER LEVEL
214 //////////////////////////////////////////////////////////////////////
217 * frsh_resource_set_power_level()
219 * Set the powerlevel of the CPU given by resource_id. We assume
220 * resource_type = FRSH_RT_PROCESSOR.
222 int frsh_resource_set_power_level(frsh_resource_id_t resource_id,
227 //////////////////////////////////////////////////////////////////////
228 // BATTERY DURATION AND MANAGING POWER LEVELS
229 //////////////////////////////////////////////////////////////////////
232 * frsh_resource_get_battery_duration()
234 * Get the remaining battery duration of the CPU given by resource_id.
235 * We assume resource_type = FRSH_RT_PROCESSOR.
237 int frsh_resource_get_battery_duration(frsh_resource_id_t resource_id,
238 struct timespec *duration);
242 #endif /* _FRSH_ENERGY_MANAGEMENT_H_ */