frsh_spare_capacity.h

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