frsh_spare_capacity.h

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