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_spare_capacity.h
59 //==============================================
60 // ******** ******* ******** ** **
61 // **///// /**////** **////// /** /**
62 // ** /** /** /** /** /**
63 // ******* /******* /********* /**********
64 // **//// /**///** ////////** /**//////**
65 // ** /** //** /** /** /**
66 // ** /** //** ******** /** /**
67 // // // // //////// // //
69 // FRSH(FRescor ScHeduler), pronounced "fresh"
70 //==============================================
71 #ifndef _FRSH_SPARE_CAPACITY_H_
72 #define _FRSH_SPARE_CAPACITY_H_
76 #include "frsh_spare_capacity_types.h"
77 #include "frsh_core_types.h"
78 #include "frsh_core.h"
82 * @file frsh_spare_capacity.h
85 #define FRSH_SPARE_CAPACITY_MODULE_SUPPORTED 1
89 * @file frsh_spare_capacity.h
91 * This file contains the function prototypes for the usage of
92 * spare capacity and dynamic reclamation.
96 * @defgroup sparecapacity Spare Capacity module
98 * This module manages the partition of exceeding capacity at
99 * negotiation time between the vres that express their desire of
100 * optional requirements.
104 * - Allowing to define a range of budget and period instead of
105 * giving WCET values only. This range can be continuous or
108 * - Specifying a fairness measurement to compete with other vres in the
109 * division of the share.
111 * - Specifying a stability_time time for vres that need to have
112 * a assigned capacity remain const during time (they would be
113 * annoyed if their budget or period would change).
115 * There are no specific negotiation calls because the algorithms used
116 * in the core module take already these min-max ranges into account.
118 * NOTE: When we talk here about "spare capacity" we mean STATIC extra
119 * capacity at NEGOTIATION TIME. This is the minimum capacity
120 * that the vres will get based on contract negotiation.
121 * This capacity is distributed based on the importance and
122 * weight values and is known before-hand at the beginning of
125 * Besides this extra capacity, there is the DYNAMIC extra
126 * capacity that results at RUN TIME from earlier job endings of
127 * bounded-workload vres. This extra capacity can vary
128 * between each execution period and is not known beforehand.
130 * This extra run-time capacity is assigned if the following 2
131 * conditions are met:
133 * - FRSH_DYNAMIC_RECLAIMING_MODULE_SUPPORTED is defined to 1
134 * (in frsh_dynamic_reclaiming.h).
136 * - There is at least one vres willing to accept this extra
138 * - A FRSH_BOUNDED workload vres with a range of Budget
139 * and Period that can absorb the extra capacity and
140 * whose static_time period is not active.
141 * - An INDETERMINATE workload vres with an active
142 * static_time period.
149 * frsh_contract_set_reclamation_params()
151 * The operation updates the specified contract parameters object by
152 * setting its maximum usable budget, minimum period, granularity,
153 * utilization set, weight, and importance to the specified input
156 * @param contract Contract object
157 * @param stability_time Time in which FRSH guarantees that the
158 * assigned budget and period will remain permanent
159 * even across renegotiations.
160 * @param budget_max The maximum budget that the vres aspires to
162 * @param period_min The minimum period (therefore minimal
163 * interarrival time) that the vres may get for
164 * awakening and replenishment periods.
165 * @param granularity FRSH_CONTINUOUS: Use min-max values,
166 * FRSH_DISCRETE: Use utilization_set.
167 * @param utilization_set A structure of discrete pairs (budget,period)
168 * @param importance non-cooperative urgency indicator. Vres with
169 * higher importance will get all spare capacity des
170 * @param weight cooperative urgency indicator. At equal
171 * importance, spare capacity will be distributed
172 * proportionally to weight levels.
174 * @return 0 if successful \n
175 * FRSH_ERR_BAD_ARGUMENT : if contract is NULL \b or \n
176 * (budget_max value is grater than period_max or smaller than budget_min) \b or \n
177 * (period_min is smaller than budget_mint or larger than period_max) \b or \n
178 * (granularity is neither FRSH_CONTINUOUS nor FRSH_DISCRETE) \b or \n
179 * (granularity is FRSH_CONTINUOUS and
180 * utilization_set is not FRSH_NULL_UTILIZATION_SET) \b or \n
181 * (granularity is FRSH_DISCRETE and
182 * utilization_set is FRSH_NULL_UTILIZATION_SET \b or \n
183 * (utilization_set is not FRSH_NULL_UTILIZATION_SET and
184 * (size of utilization_set less than 2 or greater
185 * than FRSH_MAX_N_UTILIZATION_VALUES) ) \b or \n
186 * (weight < 0) \b or \n
187 * (importance is less than 1 or greater than FRSH_N_IMPORTANCE_LEVELS) \b or \n
188 * (the utilization_set elements are not in increasing utilization order) \b or \n
189 * (the first utilization value in the utilization_set does not match
190 * the pair (budget_min, period_max) of the contract) \b or \n
191 * (the last utilization value in the utilization_set does not match
192 * the pair (budget_max, period_min) of the contract)
195 int frsh_contract_set_reclamation_params(frsh_contract_t *contract,
196 const struct timespec *stability_time,
197 const struct timespec *budget_max,
198 const struct timespec *period_min,
199 frsh_granularity_t granularity,
200 const frsh_utilization_set_t *utilization_set,
205 * frsh_contract_get_reclamation_params()
207 * The operation obtains the sparecapacity contract parameters from
208 * the contract object.
210 * @see frsh_set_contract_reclamation_parameters() for the meaning of
213 * Only the utilization_values of the utilization_set
214 * that are in use, are copied (according to its size field).
217 * @return 0 if successful \n
218 * FRSH_ERR_BAD_ARGUMENT : if contract is NULL
221 int frsh_contract_get_reclamation_params
222 (const frsh_contract_t *contract,
223 struct timespec *stability_time,
224 struct timespec *budget_max,
225 struct timespec *period_min,
226 frsh_granularity_t *granularity,
227 frsh_utilization_set_t *utilization_set,
233 * frsh_vres_get_remaining_stability_time()
235 * This operation returns the stability_time for the vres.
237 * @return 0 if successful \n
238 * FRSH_ERR_BAD_ARGUMENT : if the value of the vres argument is not in range or
239 * capacity is NULL \n
240 * FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
241 * scheduled under FRSH \n
242 * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not
244 * FRSH_ERR_NOT_CONTRACTED_VRES : if the vres has been cancelled or it
248 int frsh_vres_get_remaining_stability_time(frsh_vres_id_t vres,
249 struct timespec *stability_time);
252 * frsh_resource_get_capacity()
254 * This operation gets the spare capacity currently assigned to an
255 * importance level. The capacity is the number obtained divided by
256 * UINT32_MAX, and it represents the processor or network
259 * @return 0 if successful \n
260 * FRSH_ERR_BAD_ARGUMENT : if the value of the vres argument is not in range or
261 * capacity is NULL \n
262 * FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
263 * scheduled under the FRSH \n
264 * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not
266 * FRSH_ERR_NOT_CONTRACTED_VRES : if the vres has been cancelled or it
270 int frsh_resource_get_capacity(const frsh_resource_type_t resource_type,
271 const frsh_resource_id_t resource_id,
272 const int importance,
277 * frsh_resource_get_total_weight()
279 * This operation calculates the sum of the weight parameters for all
280 * vres in the system for a certain importance level at a specific
283 * @return 0 if successful \n
284 * FRSH_ERR_BAD_ARGUMENT : if the value of the vres argument is not in range or
285 * total_weight is NULL \n
286 * FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
287 * scheduled under FRSH \n
288 * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not
290 * FRSH_ERR_NOT_CONTRACTED_VRES : if the vres has been cancelled or it
293 int frsh_resource_get_total_weight
294 (const frsh_resource_type_t resource_type,
295 const frsh_resource_id_t resource_id,
296 const int importance,
297 uint32_t *total_weight);
301 * frsh_vres_decrease_capacity()
303 * This operation is mainly intended for distributed systems but may
304 * also be useful for control application in uniprocessor systems.
306 * It allows the vres to ask for less budget and period that what he
307 * has actually received. The request must be compatible with the
308 * rest of contract parameters.
311 int frsh_vres_decrease_capacity(frsh_vres_id_t vres,
312 struct timespec new_budget,
313 struct timespec new_period);
318 #endif // _FRSH_SPARE_CAPACITY_H_