frsh_spare_capacity.h

   1 // -----------------------------------------------------------------------
   2 //  Copyright (C) 2006 - 2009 FRESCOR consortium partners:
   3 //
   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
  10 //    ENEA                                   SWEDEN
  11 //    Thales Communication S.A.              FRANCE
  12 //    Visual Tools S.A.                      SPAIN
  13 //    Rapita Systems Ltd                     UK
  14 //    Evidence                               ITALY
  15 //
  16 //    See http://www.frescor.org for a link to partners' websites
  17 //
  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
  21 //        made of this code.
  22 //
  23 //
  24 //  based on previous work (FSF) done in the FIRST project
  25 //
  26 //   Copyright (C) 2005  Mälardalen University, SWEDEN
  27 //                       Scuola Superiore S.Anna, ITALY
  28 //                       Universidad de Cantabria, SPAIN
  29 //                       University of York, UK
  30 //
  31 //   FSF API web pages: http://marte.unican.es/fsf/docs
  32 //                      http://shark.sssup.it/contrib/first/docs/
  33 //
  34 //   This file is part of FRSH (FRescor ScHeduler)
  35 //
  36 //  FRSH is free software; you can redistribute it and/or modify it
  37 //  under terms of the GNU General Public License as published by the
  38 //  Free Software Foundation; either version 2, or (at your option) any
  39 //  later version.  FRSH is distributed in the hope that it will be
  40 //  useful, but WITHOUT ANY WARRANTY; without even the implied warranty
  41 //  of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  42 //  General Public License for more details. You should have received a
  43 //  copy of the GNU General Public License along with FRSH; see file
  44 //  COPYING. If not, write to the Free Software Foundation, 675 Mass Ave,
  45 //  Cambridge, MA 02139, USA.
  46 //
  47 //  As a special exception, including FRSH header files in a file,
  48 //  instantiating FRSH generics or templates, or linking other files
  49 //  with FRSH objects to produce an executable application, does not
  50 //  by itself cause the resulting executable application to be covered
  51 //  by the GNU General Public License. This exception does not
  52 //  however invalidate any other reasons why the executable file might be
  53 //  covered by the GNU Public License.
  54 // -----------------------------------------------------------------------
  55 //frsh_spare_capacity.h
  56 //==============================================
  57 //  ******** *******    ********  **      **
  58 //  **///// /**////**  **//////  /**     /**
  59 //  **      /**   /** /**        /**     /**
  60 //  ******* /*******  /********* /**********
  61 //  **////  /**///**  ////////** /**//////**
  62 //  **      /**  //**        /** /**     /**
  63 //  **      /**   //** ********  /**     /**
  64 //  //       //     // ////////   //      //
  65 //
  66 // FRSH(FRescor ScHeduler), pronounced "fresh"
  67 //==============================================
  68 #ifndef _FRSH_SPARE_CAPACITY_H_
  69 #define _FRSH_SPARE_CAPACITY_H_
  70
  71 #include <time.h>
  72 #include <stdint.h>
  73 #include "frsh_spare_capacity_types.h"
  74 #include "frsh_core_types.h"
  75 #include "frsh_core.h"
  76
  77 FRSH_CPP_BEGIN_DECLS
  78
  79 /**
  80  * @file frsh_spare_capacity.h
  81  **/
  82
  83 #define FRSH_SPARE_CAPACITY_MODULE_SUPPORTED       1
  84
  85
  86 /**
  87  * @file frsh_spare_capacity.h
  88  *
  89  * This file contains the function prototypes for the usage of
  90  * spare capacity and dynamic reclamation.
  91  **/
  92
  93 /**
  94  * @defgroup sparecapacity Spare Capacity module
  95  *
  96  * This module manages the partition of exceeding capacity at
  97  * negotiation time between the vres that express their desire of
  98  * optional requirements.
  99  *
 100  * It works by:
 101  *
 102  * -  Allowing to define a range of budget and period instead of
 103  *    giving WCET values only.  This range can be continuous or
 104  *    discrete.
 105  *
 106  * -  Specifying a fairness measurement to compete with other vres in the
 107  *    division of the share.
 108  *
 109  * -  Specifying a stability_time time for vres that need to have
 110  *    a assigned capacity remain const during time (they would be
 111  *    annoyed if their budget or period would change).
 112  *
 113  * There are no specific negotiation calls because the algorithms used
 114  * in the core module take already these min-max ranges into account.
 115  *
 116  * An operation is available for applications to ask for a stability
 117  * period of a specified length. The framework will then return the
 118  * total capacity (execution time budget and virtual resource period)
 119  * that the application is guaranteed to receive in this stability
 120  * period. The rationale for this service is that jobs may span a
 121  * number of virtual resource periods, and need to have a guaranteed
 122  * amount of capacity before they can choose a higher quality (longer
 123  * execution time) method, when multiple methods are available. Also
 124  * applications may require that the capacity provided to them and
 125  * hence the quality of results produced remains consistent for a
 126  * period of time, so that consistent behaviour is provided for the
 127  * user (e.g. multimedia applications).
 128  *
 129  * Requesting a new stability period has the effect of cancelling any
 130  * previous one. So a subsequent request for stability up to the same
 131  * point in time could return a lower total capacity, if spare capacity
 132  * re-allocation is in progress due to the admission of a new
 133  * application. If a stability period expires without having explicitly
 134  * set a new one, the system may decide to perform a reallocation of
 135  * spare resources at that point, or may defer this decision to some
 136  * future point in time when it is appropriate. In both cases, a new
 137  * stability period will start when the new spare capacity assignment
 138  * is in effect.
 139  *
 140  *
 141  * NOTE:  When we talk here about "spare capacity" we mean STATIC extra
 142  *        capacity at NEGOTIATION TIME.  This is the minimum capacity
 143  *        that the vres will get based on contract negotiation.
 144  *        This capacity is distributed based on the importance and
 145  *        weight values and is known before-hand at the beginning of
 146  *        a period.
 147  *
 148  *        Besides this extra capacity, there is the DYNAMIC extra
 149  *        capacity that results at RUN TIME from earlier job endings of
 150  *        bounded-workload vres.  This extra capacity can vary
 151  *        between each execution period and is not known beforehand.
 152  *
 153  *        This extra run-time capacity is assigned if the following 2
 154  *        conditions are met:
 155  *
 156  *        -  FRSH_DYNAMIC_RECLAIMING_MODULE_SUPPORTED is defined to 1
 157  *            (in frsh_dynamic_reclaiming.h).
 158  *
 159  *        -  There is at least one vres willing to accept this extra
 160  *           capacity:
 161  *           -  A FRSH_BOUNDED workload vres with a range of Budget
 162  *              and Period that can absorb the extra capacity and
 163  *              whose static_time period is not active.
 164  *           -  An INDETERMINATE workload vres with an active
 165  *              static_time period.
 166  * @{
 167  **/
 168
 169
 170
 171 /**
 172  * frsh_contract_set_reclamation_params()
 173  *
 174  * The operation updates the specified contract parameters object by
 175  * setting its maximum usable budget, minimum period, granularity,
 176  * utilization set, weight, and importance to the specified input
 177  * parameters.
 178  *
 179  * @param contract  Contract object
 180  * @param stability_time Time in which FRSH guarantees that the
 181  *                   assigned budget and period will remain permanent
 182  *                   even across renegotiations.
 183  * @param budget_max The maximum budget that the vres aspires to
 184  *                   get allocated.
 185  * @param period_min The minimum period (therefore minimal
 186  *                   interarrival time) that the vres may get for
 187  *                   awakening and replenishment periods.
 188  * @param granularity FRSH_CONTINUOUS:  Use  min-max values,
 189  *                    FRSH_DISCRETE: Use utilization_set.
 190  * @param utilization_set A structure of discrete triples (budget,
 191  *                          period, deadline)
 192  * @param importance non-cooperative urgency indicator.  Vres with
 193  *                   higher importance will get all spare capacity des
 194  * @param weight    cooperative urgency indicator.  At equal
 195  *                   importance, spare capacity will be distributed
 196  *                   proportionally to weight levels.
 197  *
 198  *
 199  * @return 0 if successful \n
 200  *   FRSH_ERR_BAD_ARGUMENT :  if contract is NULL  \b or \n
 201  *     (budget_max value is grater than period_max or smaller than budget_min) \b or \n
 202  *      (period_min is smaller than budget_mint or larger than period_max)     \b or \n
 203  *      (granularity is neither FRSH_CONTINUOUS nor FRSH_DISCRETE)     \b or \n
 204  *      (granularity is FRSH_CONTINUOUS and
 205  *       utilization_set is not FRSH_NULL_UTILIZATION_SET)            \b or \n
 206  *      (granularity is FRSH_DISCRETE and
 207  *       utilization_set is FRSH_NULL_UTILIZATION_SET                 \b or \n
 208  *      (utilization_set is not FRSH_NULL_UTILIZATION_SET and
 209  *       (size of utilization_set less than 2 or greater
 210  *        than FRSH_MAX_N_UTILIZATION_VALUES)                )        \b or \n
 211  *      (weight < 0)                                                  \b or \n
 212  *      (importance is less than 1 or greater than FRSH_N_IMPORTANCE_LEVELS) \b or \n
 213  *      (the utilization_set elements are not in increasing utilization order) \b or \n
 214  *      (the first utilization value in the utilization_set does not match
 215  *       the pair (budget_min, period_max) of the contract)           \b or \n
 216  *      (the last utilization value in the utilization_set does not match
 217  *       the pair (budget_max, period_min) of the contract)
 218  *
 219  **/
 220 int frsh_contract_set_reclamation_params(frsh_contract_t   *contract,
 221                                          const frsh_rel_time_t       *stability_time,
 222                                          const frsh_rel_time_t       *budget_max,
 223                                          const frsh_rel_time_t       *period_min,
 224                                          frsh_granularity_t            granularity,
 225                                          const frsh_utilization_set_t *utilization_set,
 226                                          int                          importance,
 227                                          int                          weight);
 228
 229 /**
 230  * frsh_contract_get_reclamation_params()
 231  *
 232  * The operation obtains the sparecapacity contract parameters from
 233  * the contract object.
 234  *
 235  * @see frsh_set_contract_reclamation_parameters() for the meaning of
 236  * each parameter.
 237  *
 238  * Only the utilization_values of the utilization_set
 239  * that are in use, are copied (according to its size field).
 240  *
 241  *
 242  * @return 0 if successful \n
 243  *   FRSH_ERR_BAD_ARGUMENT :  if contract is NULL
 244  *
 245  **/
 246 int frsh_contract_get_reclamation_params
 247   (const frsh_contract_t *contract,
 248    frsh_rel_time_t                 *stability_time,
 249    frsh_rel_time_t                 *budget_max,
 250    frsh_rel_time_t                 *period_min,
 251    frsh_granularity_t               *granularity,
 252    frsh_utilization_set_t           *utilization_set,
 253    int                             *importance,
 254    int                             *weight);
 255
 256
 257 /**
 258  * frsh_vres_get_remaining_stability_time()
 259  *
 260  * This operation returns the stability_time for the vres.
 261  *
 262  * @return 0 if successful \n
 263  *   FRSH_ERR_BAD_ARGUMENT : if the value of the vres argument is not in range or
 264  *       capacity is NULL \n
 265  *   FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
 266  *       scheduled under FRSH \n
 267  *   FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not
 268  *       running \n
 269  *   FRSH_ERR_NOT_CONTRACTED_VRES : if the vres has been cancelled or it
 270  *       is not valid \n
 271  *
 272  **/
 273 int frsh_vres_get_remaining_stability_time(frsh_vres_id_t vres,
 274                                       frsh_rel_time_t *stability_time);
 275
 276
 277 /**
 278  * frsh_vres_set_stability_time:
 279  *
 280  * Dynamically set the stability time for a given virtual resource to
 281  * the specified interval. This operation sets a new value for the
 282  * stability time associated with the virtual resource. As a result of
 283  * this call the system may change the allocation of resources to the
 284  * current virtual resource. Regardless of whether the resources are
 285  * reallocated or not, the call resets the stability period so that
 286  * the level of resources allocated to the virtual resource is kept
 287  * stable for at least the duration of the requested interval.  The
 288  * possibly new values of budget and period are returned in the
 289  * corresponding parameters
 290  */
 291
 292 int frsh_vres_set_stability_time
 293       (frsh_vres_id_t vres,
 294        const frsh_rel_time_t *stability_time,
 295        frsh_rel_time_t *budget,
 296        frsh_rel_time_t *period);
 297
 298
 299 /**
 300  * frsh_resource_get_capacity()
 301  *
 302  * This operation gets the spare capacity currently assigned to an
 303  * importance level.  The capacity is the number obtained divided by
 304  * UINT32_MAX, and it represents the processor or network
 305  * utilization.
 306  *
 307  * @return 0 if successful \n
 308  *   FRSH_ERR_BAD_ARGUMENT : if the value of the vres argument is not in range or
 309  *       capacity is NULL \n
 310  *   FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
 311  *       scheduled under the FRSH \n
 312  *   FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not
 313  *       running \n
 314  *   FRSH_ERR_NOT_CONTRACTED_VRES : if the vres has been cancelled or it
 315  *       is not valid \n
 316  *
 317  **/
 318 int frsh_resource_get_capacity(const frsh_resource_type_t resource_type,
 319                                const frsh_resource_id_t resource_id,
 320                                const int importance,
 321                                uint32_t *capacity);
 322
 323
 324 /**
 325  * frsh_resource_get_total_weight()
 326  *
 327  * This operation calculates the sum of the weight parameters for all
 328  * vres in the system for a certain importance level at a specific
 329  * resource_id.
 330  *
 331  * @return 0 if successful \n
 332  *    FRSH_ERR_BAD_ARGUMENT : if the value of the vres argument is not in range or
 333  *       total_weight is NULL \n
 334  *    FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
 335  *       scheduled under FRSH \n
 336  *    FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not
 337  *                    running \n
 338  *    FRSH_ERR_NOT_CONTRACTED_VRES : if the vres has been cancelled or it
 339  *       is not valid \n
 340  **/
 341 int frsh_resource_get_total_weight
 342    (const frsh_resource_type_t resource_type,
 343     const frsh_resource_id_t resource_id,
 344     const int importance,
 345     uint32_t *total_weight);
 346
 347
 348 /**
 349  * frsh_vres_decrease_capacity()
 350  *
 351  * This operation is mainly intended for distributed systems but may
 352  * also be useful for control application in uniprocessor systems.
 353  *
 354  * It allows the vres to ask for less budget and period that what he
 355  * has actually received.  The request must be compatible with the
 356  * rest of contract parameters.
 357  *
 358  **/
 359 int frsh_vres_decrease_capacity(frsh_vres_id_t vres,
 360                            frsh_rel_time_t new_budget,
 361                            frsh_rel_time_t new_period);
 362
 363
 364 /*@}*/
 365
 366 FRSH_CPP_END_DECLS
 367
 368 #endif // _FRSH_SPARE_CAPACITY_H_