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
  81 /**
  82  * @file frsh_spare_capacity.h
  83  **/
  84
  85 #define FRSH_SPARE_CAPACITY_MODULE_SUPPORTED       1
  86
  87
  88 /**
  89  * @file frsh_spare_capacity.h
  90  *
  91  * This file contains the function prototypes for the usage of
  92  * spare capacity and dynamic reclamation.
  93  **/
  94
  95 /**
  96  * @defgroup sparecapacity Spare Capacity module
  97  *
  98  * This module manages the partition of exceeding capacity at
  99  * negotiation time between the vres that express their desire of
 100  * optional requirements.
 101  *
 102  * It works by:
 103  *
 104  * -  Allowing to define a range of budget and period instead of
 105  *    giving WCET values only.  This range can be continuous or
 106  *    discrete.
 107  *
 108  * -  Specifying a fairness measurement to compete with other vres in the
 109  *    division of the share.
 110  *
 111  * -  Specifying a stability_time time for vres that need to have
 112  *    a assigned capacity remain const during time (they would be
 113  *    annoyed if their budget or period would change).
 114  *
 115  * There are no specific negotiation calls because the algorithms used
 116  * in the core module take already these min-max ranges into account.
 117  *
 118  * NOTE:  When we talk here about "spare capacity" we mean STATIC extra
 119  *        capacity at NEGOTIATION TIME.  This is the minimum capacity
 120  *        that the vres will get based on contract negotiation.
 121  *        This capacity is distributed based on the importance and
 122  *        weight values and is known before-hand at the beginning of
 123  *        a period.
 124  *
 125  *        Besides this extra capacity, there is the DYNAMIC extra
 126  *        capacity that results at RUN TIME from earlier job endings of
 127  *        bounded-workload vres.  This extra capacity can vary
 128  *        between each execution period and is not known beforehand.
 129  *
 130  *        This extra run-time capacity is assigned if the following 2
 131  *        conditions are met:
 132  *
 133  *        -  FRSH_DYNAMIC_RECLAIMING_MODULE_SUPPORTED is defined to 1
 134  *            (in frsh_dynamic_reclaiming.h).
 135  *
 136  *        -  There is at least one vres willing to accept this extra
 137  *           capacity:
 138  *           -  A FRSH_BOUNDED workload vres with a range of Budget
 139  *              and Period that can absorb the extra capacity and
 140  *              whose static_time period is not active.
 141  *           -  An INDETERMINATE workload vres with an active
 142  *              static_time period.
 143  * @{
 144  **/
 145
 146
 147
 148 /**
 149  * frsh_contract_set_reclamation_params()
 150  *
 151  * The operation updates the specified contract parameters object by
 152  * setting its maximum usable budget, minimum period, granularity,
 153  * utilization set, weight, and importance to the specified input
 154  * parameters.
 155  *
 156  * @param contract  Contract object
 157  * @param stability_time Time in which FRSH guarantees that the
 158  *                   assigned budget and period will remain permanent
 159  *                   even across renegotiations.
 160  * @param budget_max The maximum budget that the vres aspires to
 161  *                   get allocated.
 162  * @param period_min The minimum period (therefore minimal
 163  *                   interarrival time) that the vres may get for
 164  *                   awakening and replenishment periods.
 165  * @param granularity FRSH_CONTINUOUS:  Use  min-max values,
 166  *                    FRSH_DISCRETE: Use utilization_set.
 167  * @param utilization_set A structure of discrete pairs (budget,period)
 168  * @param importance non-cooperative urgency indicator.  Vres with
 169  *                   higher importance will get all spare capacity des
 170  * @param weight    cooperative urgency indicator.  At equal
 171  *                   importance, spare capacity will be distributed
 172  *                   proportionally to weight levels.
 173  *
 174  * @return 0 if successful \n
 175  *   FRSH_ERR_BAD_ARGUMENT :  if contract is NULL  \b or \n
 176  *     (budget_max value is grater than period_max or smaller than budget_min) \b or \n
 177  *      (period_min is smaller than budget_mint or larger than period_max)     \b or \n
 178  *      (granularity is neither FRSH_CONTINUOUS nor FRSH_DISCRETE)     \b or \n
 179  *      (granularity is FRSH_CONTINUOUS and
 180  *       utilization_set is not FRSH_NULL_UTILIZATION_SET)            \b or \n
 181  *      (granularity is FRSH_DISCRETE and
 182  *       utilization_set is FRSH_NULL_UTILIZATION_SET                 \b or \n
 183  *      (utilization_set is not FRSH_NULL_UTILIZATION_SET and
 184  *       (size of utilization_set less than 2 or greater
 185  *        than FRSH_MAX_N_UTILIZATION_VALUES)                )        \b or \n
 186  *      (weight < 0)                                                  \b or \n
 187  *      (importance is less than 1 or greater than FRSH_N_IMPORTANCE_LEVELS) \b or \n
 188  *      (the utilization_set elements are not in increasing utilization order) \b or \n
 189  *      (the first utilization value in the utilization_set does not match
 190  *       the pair (budget_min, period_max) of the contract)           \b or \n
 191  *      (the last utilization value in the utilization_set does not match
 192  *       the pair (budget_max, period_min) of the contract)
 193  *
 194  **/
 195 int frsh_contract_set_reclamation_params(frsh_contract_t   *contract,
 196                                          const struct timespec       *stability_time,
 197                                          const struct timespec       *budget_max,
 198                                          const struct timespec       *period_min,
 199                                          frsh_granularity_t            granularity,
 200                                          const frsh_utilization_set_t *utilization_set,
 201                                          int                          importance,
 202                                          int                          weight);
 203
 204 /**
 205  * frsh_contract_get_reclamation_params()
 206  *
 207  * The operation obtains the sparecapacity contract parameters from
 208  * the contract object.
 209  *
 210  * @see frsh_set_contract_reclamation_parameters() for the meaning of
 211  * each parameter.
 212  *
 213  * Only the utilization_values of the utilization_set
 214  * that are in use, are copied (according to its size field).
 215  *
 216  *
 217  * @return 0 if successful \n
 218  *   FRSH_ERR_BAD_ARGUMENT :  if contract is NULL
 219  *
 220  **/
 221 int frsh_contract_get_reclamation_params
 222   (const frsh_contract_t *contract,
 223    struct timespec                 *stability_time,
 224    struct timespec                 *budget_max,
 225    struct timespec                 *period_min,
 226    frsh_granularity_t               *granularity,
 227    frsh_utilization_set_t           *utilization_set,
 228    int                             *importance,
 229    int                             *weight);
 230
 231
 232 /**
 233  * frsh_vres_get_remaining_stability_time()
 234  *
 235  * This operation returns the stability_time for the vres.
 236  *
 237  * @return 0 if successful \n
 238  *   FRSH_ERR_BAD_ARGUMENT : if the value of the vres argument is not in range or
 239  *       capacity is NULL \n
 240  *   FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
 241  *       scheduled under FRSH \n
 242  *   FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not
 243  *       running \n
 244  *   FRSH_ERR_NOT_CONTRACTED_VRES : if the vres has been cancelled or it
 245  *       is not valid \n
 246  *
 247  **/
 248 int frsh_vres_get_remaining_stability_time(frsh_vres_id_t vres,
 249                                       struct timespec *stability_time);
 250
 251 /**
 252  * frsh_resource_get_capacity()
 253  *
 254  * This operation gets the spare capacity currently assigned to an
 255  * importance level.  The capacity is the number obtained divided by
 256  * UINT32_MAX, and it represents the processor or network
 257  * utilization.
 258  *
 259  * @return 0 if successful \n
 260  *   FRSH_ERR_BAD_ARGUMENT : if the value of the vres argument is not in range or
 261  *       capacity is NULL \n
 262  *   FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
 263  *       scheduled under the FRSH \n
 264  *   FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not
 265  *       running \n
 266  *   FRSH_ERR_NOT_CONTRACTED_VRES : if the vres has been cancelled or it
 267  *       is not valid \n
 268  *
 269  **/
 270 int frsh_resource_get_capacity(const frsh_resource_type_t resource_type,
 271                                const frsh_resource_id_t resource_id,
 272                                const int importance,
 273                                uint32_t *capacity);
 274
 275
 276 /**
 277  * frsh_resource_get_total_weight()
 278  *
 279  * This operation calculates the sum of the weight parameters for all
 280  * vres in the system for a certain importance level at a specific
 281  * resource_id.
 282  *
 283  * @return 0 if successful \n
 284  *    FRSH_ERR_BAD_ARGUMENT : if the value of the vres argument is not in range or
 285  *       total_weight is NULL \n
 286  *    FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
 287  *       scheduled under FRSH \n
 288  *    FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not
 289  *                    running \n
 290  *    FRSH_ERR_NOT_CONTRACTED_VRES : if the vres has been cancelled or it
 291  *       is not valid \n
 292  **/
 293 int frsh_resource_get_total_weight
 294    (const frsh_resource_type_t resource_type,
 295     const frsh_resource_id_t resource_id,
 296     const int importance,
 297     uint32_t *total_weight);
 298
 299
 300 /**
 301  * frsh_vres_decrease_capacity()
 302  *
 303  * This operation is mainly intended for distributed systems but may
 304  * also be useful for control application in uniprocessor systems.
 305  *
 306  * It allows the vres to ask for less budget and period that what he
 307  * has actually received.  The request must be compatible with the
 308  * rest of contract parameters.
 309  *
 310  **/
 311 int frsh_vres_decrease_capacity(frsh_vres_id_t vres,
 312                            struct timespec new_budget,
 313                            struct timespec new_period);
 314
 315
 316 /*@}*/
 317
 318 #endif // _FRSH_SPARE_CAPACITY_H_