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