Subversion Repositories shark

Rev

Rev 929 | Rev 993 | Go to most recent revision | Details | Compare with Previous | Last modification | View Log | RSS feed

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