Subversion Repositories shark

Rev

Rev 993 | Details | Compare with Previous | Last modification | View Log | RSS feed

Rev Author Line No. Line
1063 tullio 1
 
2
/*
3
 * This program is free software; you can redistribute it and/or modify
4
 * it under the terms of the GNU General Public License as published by
5
 * the Free Software Foundation; either version 2 of the License, or
6
 * (at your option) any later version.
7
 *
8
 * This program is distributed in the hope that it will be useful,
9
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
10
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
11
 * GNU General Public License for more details.
12
 *
13
 * You should have received a copy of the GNU General Public License
14
 * along with this program; if not, write to the Free Software
15
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
16
 *
17
 */
18
 
929 lipari 19
/**
20
   @file Spare capacity file.
21
 */
881 trimarchi 22
//fsf_spare_capacity.h
23
//===================================================
24
//       FFFFFFIII   RRRRR      SSTTTTTTT
25
//      FF         IIR   RR    SS
26
//     FF           IR        SS
27
//    FFFFFF         RRRR    SSSSST
28
//   FF       FI       RRR  SS
29
//  FF         II     RRR  SS
30
// FF           IIIIIR    RS
31
//
32
// FSF(FIRST Scheduling Framework) 
33
// spare capacity sharing functionality
34
//===================================================
35
 
36
#include <time.h>
37
#include <stdint.h>
38
#include "fsf_basic_types.h"
39
#include "fsf_core.h"
40
 
41
#ifndef _FSF_SPARE_CAPACITY_H_
42
#define _FSF_SPARE_CAPACITY_H_
43
 
44
#define FSF_SPARE_CAPACITY_MODULE_SUPPORTED       1
45
 
928 trimarchi 46
 
881 trimarchi 47
//// The definition of this types is in fsf_basic_types.h
48
//
49
//// Granularity of spare capacity requirements
50
//typedef enum {FSF_CONTINUOUS, FSF_DISCRETE} fsf_granularity_t;
51
//
52
//// Utilization (budget and period) value
53
//typedef struct {
54
//  struct timespec    budget;    // Execution time
55
//  struct timespec    period;    // Period
56
//} fsf_utilization_value_t;
57
//
58
////List of utilization values
59
//typedef struct {
60
//  int                         size; // = 0
61
//  fsf_utilization_value_t     
62
//      value[FSF_MAX_N_UTILIZATION_VALUES]; 
63
//      //unit change to value.....
64
//} fsf_utilization_set_t;
65
//
66
//
67
//// Constants for assigning default values
68
//#define FSF_DEFAULT_GRANULARITY         FSF_CONTINUOUS
69
//#define FSF_DEFAULT_QUALITY             0
70
//#define FSF_DEFAULT_IMPORTANCE          1
71
//
72
//
73
//// Constants for omitting the assignment of values to specific
74
//// arguments in calls to initialization functions
75
//
76
//#define FSF_NULL_UTILIZATION_SET     (fsf_utilization_set_t *)NULL
77
//
78
 
928 trimarchi 79
/**
80
   \ingroup sparemodule
881 trimarchi 81
 
928 trimarchi 82
   The operation updates the specified contract parameters object by
83
   setting its maximum usable budget, minimum period, granularity,
84
   utilization set, quality, and importance to the specified input
85
   parameters.
86
 
87
   @param [in] contract pointer ot the contract
88
   @param [in] budget_max  maximum budget this contract can obtain
89
   @param [in] period_min  minimum period this contract can obtain
90
   @param [in] granularity can be either FSF_CONTINUOUS or FSF_DISCRETE
91
   @param [in] utilization_set in case the granularity is set to
92
      FSF_DISCRETE it contains a list possible pairs (budget,period)
93
   @param [in] quality a number between FSF_MIN_QUALITY and FSF_MAX_QUALITY,
94
               to control how the spare capacity is shared between
95
               contracts with the same importance. The higher
993 lipari 96
               this number is , the more likely we get a large increase
928 trimarchi 97
               in the capacity
98
   @param [in] importance a numer between FSF_MIN_IMPORTANCE and
99
               FSF_MAX_IMPORTANCE, used to control how the spare capacity
100
               is shared. The higher the number, the more likely we get
101
               some spare capacity.
102
 
103
   @retval 0 if the call is succesful
104
   @retval FSF_ERR_BAD_ARGUMENT if contract is NULL or one of the
105
       following conditions is true:
106
       - (budget_max value is grater than period_max or smaller than
107
         budget_min);
108
       - (period_min is smaller than budget_mint or larger than period_max);
109
       - (granularity is neither FSF_CONTINUOUS nor FSF_DISCRETE);
110
       - (granularity is FSF_CONTINUOUS and
111
        utilization_set is not FSF_NULL_UTILIZATION_SET)
112
       - (granularity is FSF_DISCRETE and utilization_set is
113
          FSF_NULL_UTILIZATION_SET)
114
       - (utilization_set is not FSF_NULL_UTILIZATION_SET and
115
         (size of utilization_set less than 2 or greater
116
          than FSF_MAX_N_UTILIZATION_VALUES)
117
       - (quality < 0)
118
       - (importance is less than 1 or greater than FSF_N_IMPORTANCE_LEVELS)
119
       - (the utilization_set elements are not in increasing utilization order)
120
       - (the first utilization value in the utilization_set does not match
121
        the pair (budget_min, period_max) of the contract);
122
       - (the last utilization value in the utilization_set does not match
123
        the pair (budget_max, period_min) of the contract).
881 trimarchi 124
*/
125
int
126
fsf_set_contract_reclamation_parameters
127
  (fsf_contract_parameters_t   *contract,
128
   const struct timespec       *budget_max,
129
   const struct timespec       *period_min,
130
   fsf_granularity_t            granularity,
131
   const fsf_utilization_set_t *utilization_set,
132
   int                          quality,
133
   int                          importance);
134
 
135
 
928 trimarchi 136
/**
137
   \ingroup sparemodule
138
 
139
    The operation obtains from the specified contract parameters
140
    object its granularity, utilization set, quality, and
141
    importance. Then copies them to the variables pointed to by the
142
    specified input parameters.  Only the utilization_values of the
143
    utilization_set that are in use, are copied (according to its size
144
    field).
145
 
146
    @retval 0 if the operation is succesful
147
    @retval FSF_ERR_BAD_ARGUMENT :  if contract is NULL
148
 
149
    @see fsf_set_contract_reclamation_parameters
881 trimarchi 150
*/
151
int
152
fsf_get_contract_reclamation_parameters
153
  (const fsf_contract_parameters_t *contract,
154
   struct timespec                 *budget_max,
155
   struct timespec                 *period_min,
156
   fsf_granularity_t               *granularity,
157
   fsf_utilization_set_t           *utilization_set,
158
   int                             *quality,
159
   int                             *importance);
160
 
161
 
928 trimarchi 162
/**
163
   \ingroup sparemodule
164
 
165
   The operation enqueues a request to change the quality and
166
   importance parameters of the specified server, and returns
167
   immediately. The change operation is performed as soon as it is
168
   practical; meanwhile the system operation will continue normally.
169
 
170
   @param server server id
171
   @param new_importance  the new importance
172
   @param new_quality   the new requested quality
173
 
174
   @retval FSF_ERR_BAD_ARGUMENT if
175
       - the value of the server argument is not in range or
176
       - (quality < 0)
177
       - (importance is less than 1 or greater than FSF_N_IMPORTANCE_LEVELS).
178
 
179
   @retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD if the calling thread is not
881 trimarchi 180
       scheduled under the FSF
928 trimarchi 181
   @retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or
182
       not running
183
   @retval FSF_ERR_NOT_CONTRACTED_SERVER if the server has been cancelled
184
       or it is not valid
881 trimarchi 185
*/
186
int
187
fsf_request_change_quality_and_importance
188
  (fsf_server_id_t server,
189
   int new_importance,
190
   int new_quality);
191
 
192
 
928 trimarchi 193
/**
194
   \ingroup sparemodule
195
 
196
   This operation calculates the sum of the quality parameters for all
197
   servers in the system of importance level equal to that of the
198
   specified server, and stores it in the variable pointed to by
199
   total_quality.
200
 
201
   @param [in] server server id
202
   @param [out] total_quality the total quality in the system
203
 
204
   @retval FSF_ERR_BAD_ARGUMENT if the value of the server argument
205
           is not in range or total_quality is NULL
206
   @retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD if the calling thread is not
881 trimarchi 207
       scheduled under the FSF
928 trimarchi 208
   @retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or
209
       not running
210
   @retval FSF_ERR_NOT_CONTRACTED_SERVER if the server has been
211
       cancelled or it is not valid
881 trimarchi 212
*/
213
int
214
fsf_get_total_quality
215
   (fsf_server_id_t server, int *total_quality);
216
 
217
 
928 trimarchi 218
/**
219
   \ingroup sparemodule
220
 
221
    This operation stores in the variable pointed to by capacity the
222
    spare capacity currently available for the importance level of the
223
    specified server. The capacity is the utilization (of the
224
    processor or of the network) and it is represented by an integer
225
    number between 0 (no utilization) and UINT32_MAX (all
226
    utilization).
227
 
228
    @retval FSF_ERR_BAD_ARGUMENT if the value of the server argument is
229
            not in range or capacity is NULL
230
    @retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD if the calling thread is not
231
            scheduled under the FSF
232
    @retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or
233
            not running
234
    @retval FSF_ERR_NOT_CONTRACTED_SERVER if the server has been cancelled
235
            or it is not valid
889 trimarchi 236
*/
881 trimarchi 237
int
238
fsf_get_available_capacity (
239
    fsf_server_id_t server, uint32_t *capacity);
240
 
928 trimarchi 241
/* @} */
881 trimarchi 242
 
243
#endif // _FSF_SPARE_CAPACITY_H_