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"
81 #define FRSH_SPARE_CAPACITY_MODULE_SUPPORTED 1
85 * @file frsh_spare_capacity.h
87 * This file contains the function prototypes for the usage of
88 * spare capacity and dynamic reclamation.
92 * @defgroup sparecapacity Spare Capacity module
94 * This module manages the partition of exceeding capacity at
95 * negotiation time between the servers that express their desire of
96 * optional requirements.
100 * - Allowing to define a range of budget and period instead of
101 * giving WCET values only. This range can be continuous or
104 * - Specifying a fairness measurement to compete with other servers in the
105 * division of the share.
107 * - Specifying a stability_time period for servers that need to have
108 * a assigned capacity remain const during time (they would be
109 * annoyed if their budget or period would change).
111 * There are no specific negotiation calls because the algorithms used
112 * in the core module take already these min-max ranges into account.
114 * NOTE: When we talk here about "spare capacity" we mean STATIC extra
115 * capacity at NEGOTIATION TIME. This is the minimum capacity
116 * that the server will get based on contract negotiation.
117 * This capacity is distributed based on the importance and
118 * quality values and is known before-hand at the beginning of
121 * Besides this extra capacity, there is the DYNAMIC extra
122 * capacity that results at RUN TIME from earlier job endings of
123 * bounded-workload servers. This extra capacity can vary
124 * between each execution period and is not known beforehand.
126 * This extra run-time capacity is assigned if the following 2
127 * conditions are met:
129 * - FRSH_DYNAMIC_RECLAIMING_MODULE_SUPPORTED is defined to 1
130 * (in frsh_dynamic_reclaiming.h).
132 * - There is at least one server willing to accept this extra
134 * - A FRSH_BOUNDED workload server with a range of Budget
135 * and Period that can absorb the extra capacity and
136 * whose static_time period is not active.
137 * - An INDETERMINATE workload server with an active
138 * static_time period.
145 * frsh_set_contract_reclamation_parameters()
147 * The operation updates the specified contract parameters object by
148 * setting its maximum usable budget, minimum period, granularity,
149 * utilization set, quality, and importance to the specified input
152 * @param contract Contract object
153 * @param stability_time Time in which FRSH guarantees that the
154 * assigned budget and period will remain permanent
155 * even across renegotiations.
156 * @param budget_max The maximum budget that the server aspires to
158 * @param period_min The minimum period (therefore minimal
159 * interarrival time) that the server may get for
160 * awakening and replenishment periods.
161 * @param granularity FRSH_CONTINUOUS: Use min-max values,
162 * FRSH_DISCRETE: Use utilization_set.
163 * @param utilization_set A structure of discrete pairs (budget,period)
164 * @param importance non-cooperative urgency indicator. Server with
165 * higher importance will get all spare capacity des
166 * @param quality cooperative urgency indicator. At equal
167 * importance, spare capacity will be distributed
168 * proportionally to quality levels.
170 * @return 0 if successful
171 * FRSH_ERR_BAD_ARGUMENT : if contract is NULL or
172 * (budget_max value is grater than period_max or smaller than budget_min) or
173 * (period_min is smaller than budget_mint or larger than period_max) or
174 * (granularity is neither FRSH_CONTINUOUS nor FRSH_DISCRETE) or
175 * (granularity is FRSH_CONTINUOUS and
176 * utilization_set is not FRSH_NULL_UTILIZATION_SET) or
177 * (granularity is FRSH_DISCRETE and
178 * utilization_set is FRSH_NULL_UTILIZATION_SET) or
179 * (utilization_set is not FRSH_NULL_UTILIZATION_SET and
180 * (size of utilization_set less than 2 or greater
181 * than FRSH_MAX_N_UTILIZATION_VALUES) ) or
183 * (importance is less than 1 or greater than FRSH_N_IMPORTANCE_LEVELS) or
184 * (the utilization_set elements are not in increasing utilization order) or
185 * (the first utilization value in the utilization_set does not match
186 * the pair (budget_min, period_max) of the contract) or
187 * (the last utilization value in the utilization_set does not match
188 * the pair (budget_max, period_min) of the contract)
191 int frsh_set_contract_reclamation_parameters(frsh_contract_parameters_t *contract,
192 const struct timespec *stability_time,
193 const struct timespec *budget_max,
194 const struct timespec *period_min,
195 frsh_granularity_t granularity,
196 const frsh_utilization_set_t *utilization_set,
201 * frsh_get_contract_reclamation_parameters()
203 * The operation obtains the sparecapacity contract parameters from
204 * the contract object.
206 * @see frsh_set_contract_reclamation_parameters() for the meaning of
209 * Only the utilization_values of the utilization_set
210 * that are in use, are copied (according to its size field).
213 * @return 0 if successful
214 * FRSH_ERR_BAD_ARGUMENT : if contract is NULL
217 int frsh_get_contract_reclamation_parameters
218 (const frsh_contract_parameters_t *contract,
219 struct timespec *stability_time,
220 struct timespec *budget_max,
221 struct timespec *period_min,
222 frsh_granularity_t *granularity,
223 frsh_utilization_set_t *utilization_set,
230 * frsh_get_available_capacity()
232 * This operation stores in the variable pointed to by capacity the
233 * spare capacity currently assigned to the importance level of the
234 * specified server. The capacity is the number obtained divided by
235 * UINT32_MAX, and it represents the processor or network
238 * @return 0 if successful
239 * FRSH_ERR_BAD_ARGUMENT : if the value of the server argument is not in range or
241 * FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
242 * scheduled under the FRSH
243 * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running
244 * FRSH_ERR_NOT_CONTRACTED_SERVER : if the server has been cancelled or it
248 int frsh_get_available_capacity(frsh_server_id_t server, uint32_t *capacity);
251 * frsh_get_total_quality()
253 * This operation calculates the sum of the quality parameters for all
254 * servers in the system of importance level equal to that of the
255 * specified server, and stores it in the variable pointed to by
258 * @return 0 if successful
259 * FRSH_ERR_BAD_ARGUMENT : if the value of the server argument is not in range or
260 * total_quality is NULL
261 * FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
262 * scheduled under the FRSH
263 * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running
264 * FRSH_ERR_NOT_CONTRACTED_SERVER : if the server has been cancelled or it
268 int frsh_get_total_quality
269 (frsh_server_id_t server, int *total_quality);
273 #endif // _FRSH_SPARE_CAPACITY_H_