frsh_spare_capacity.h

   1 // -----------------------------------------------------------------------
   2 //   Copyright (C) 2005  Mälardalen University, SWEDEN
   3 //                       Scuola Superiore S.Anna, ITALY
   4 //                       Universidad de Cantabria, SPAIN
   5 //                       University of York, UK
   6 //
   7 //   FRSH API web pages: http://marte.unican.es/frsh/docs/
   8 //                      http://shark.sssup.it/contrib/first/docs/
   9 //
  10 //  This file is part of FRSH API
  11 //
  12 //  FRSH API is free software; you can  redistribute it and/or  modify
  13 //  it under the terms of  the GNU General Public License as published by
  14 //  the Free Software Foundation;  either  version 2, or (at  your option)
  15 //  any later version.
  16 //
  17 //  FRSH API  is distributed  in  the hope  that  it  will  be useful,  but
  18 //  WITHOUT  ANY  WARRANTY;     without  even the   implied   warranty  of
  19 //  MERCHANTABILITY  or  FITNESS FOR  A  PARTICULAR PURPOSE. See  the  GNU
  20 //  General Public License for more details.
  21 //
  22 //  You should have  received a  copy of  the  GNU  General Public License
  23 //  distributed  with  FRSH API;  see file COPYING.   If not,  write to the
  24 //  Free Software  Foundation,  59 Temple Place  -  Suite 330,  Boston, MA
  25 //  02111-1307, USA.
  26 //
  27 //  As a special exception, if you include this header file into source
  28 //  files to be compiled, this header file does not by itself cause
  29 //  the resulting executable to be covered by the GNU General Public
  30 //  License.  This exception does not however invalidate any other
  31 //  reasons why the executable file might be covered by the GNU General
  32 //  Public License.
  33 // -----------------------------------------------------------------------
  34 //frsh_spare_capacity.h
  35 //==============================================
  36 //  ******** *******    ******** **      **
  37 //  **///// /**////**  **////// /**     /**
  38 //  **      /**   /** /**       /**     /**
  39 //  ******* /*******  /*********/**********
  40 //  **////  /**///**  ////////**/**//////**
  41 //  **      /**  //**        /**/**     /**
  42 //  **      /**   //** ******** /**     /**
  43 //  //       //     // ////////  //      //
  44 //
  45 // FRSH(FRescor ScHeduler), pronounced "fresh"
  46 //==============================================
  47 #ifndef _FRSH_SPARE_CAPACITY_H_
  48 #define _FRSH_SPARE_CAPACITY_H_
  49
  50 #include <time.h>
  51 #include <stdint.h>
  52 #include "frsh_spare_capacity_types.h"
  53 #include "frsh_core_types.h"
  54 #include "frsh_core.h"
  55
  56
  57 #define FRSH_SPARE_CAPACITY_MODULE_SUPPORTED       1
  58
  59
  60 /**
  61  * @file frsh_spare_capacity.h
  62  *
  63  * This file contains the function prototypes for the usage of
  64  * spare capacity and dynamic reclamation.
  65  **/
  66
  67 /**
  68  * @defgroup sparecapacity Spare Capacity module
  69  *
  70  * This module manages the partition of exceeding capacity at
  71  * negotiation time between the servers that express their desire of
  72  * optional requirements.
  73  *
  74  * It works by:
  75  * *  Allowing to define a range of budget and period instead of
  76  *    giving WCET values only.  This range can be continuous or
  77  *    discrete.
  78  *
  79  * *  Specify a fairness measurement to compete with other servers in the
  80  *    division of the share.
  81  *
  82  * There are no specific negotiation calls because the algorithms used
  83  * in the core module take already these min-max ranges into account.
  84  *
  85  * NOTE:  When we talk here about "spare capacity" we mean extra
  86  *        capacity at NEGOTIATION TIME.  Whatever budget and period
  87  *        limits we assign after negotiation will remain permanent
  88  *        until a new (re)negotiation takes place (which may be
  89  *        enlarged with stability_time).
  90  *
  91  *        FRSH manages as well another extra capacity that results in
  92  *        the early job ending of bounded workload servers.  We may
  93  *        call this extra capacity at RUN TIME and it varies from
  94  *        period to period.
  95  **/
  96
  97
  98 /**
  99  * frsh_set_contract_reclamation_parameters()
 100  *
 101  * The operation updates the specified contract parameters object by
 102  * setting its maximum usable budget, minimum period, granularity,
 103  * utilization set, quality, and importance to the specified input
 104  * parameters.
 105  *
 106  * @param[inout] contract  Contract object
 107  * @param stability_time Time in which FRSH guarantees that the
 108  *                   assigned budget and period will remain permanent
 109  *                   even across renegotiations.
 110  * @param budget_max The maximum budget that the server aspires to
 111  *                   get allocated.
 112  * @param period_min The minimum period (therefore minimal
 113  *                   interarrival time) that the server may get for
 114  *                   awakening and replenishment periods.
 115  * @param granularity FRSH_CONTINUOUS:  Use  min-max values,
 116  *                    FRSH_DISCRETE: Use utilization_set.
 117  * @param utilization_set A structure of discrete pairs (budget,period)
 118  * @param importance non-cooperative urgency indicator.  Server with
 119  *                   higher importance will get all spare capacity des
 120  * @param quality    cooperative urgency indicator.  At equal
 121  *                   importance, spare capacity will be distributed
 122  *                   proportionally to quality levels.
 123  *
 124  * @return 0 if successful
 125  *   FRSH_ERR_BAD_ARGUMENT :  if contract is NULL or
 126  *     (budget_max value is grater than period_max or smaller than budget_min)  or
 127  *      (period_min is smaller than budget_mint or larger than period_max)      or
 128  *      (granularity is neither FRSH_CONTINUOUS nor FRSH_DISCRETE)              or
 129  *      (granularity is FRSH_CONTINUOUS and
 130  *       utilization_set is not FRSH_NULL_UTILIZATION_SET)                      or
 131  *      (granularity is FRSH_DISCRETE and
 132  *       utilization_set is FRSH_NULL_UTILIZATION_SET)                          or
 133  *      (utilization_set is not FRSH_NULL_UTILIZATION_SET and
 134  *       (size of utilization_set less than 2 or greater
 135  *        than FRSH_MAX_N_UTILIZATION_VALUES)                )                  or
 136  *      (quality < 0)                                                           or
 137  *      (importance is less than 1 or greater than FRSH_N_IMPORTANCE_LEVELS)    or
 138  *      (the utilization_set elements are not in increasing utilization order)  or
 139  *      (the first utilization value in the utilization_set does not match
 140  *       the pair (budget_min, period_max) of the contract)                     or
 141  *      (the last utilization value in the utilization_set does not match
 142  *       the pair (budget_max, period_min) of the contract)
 143  *
 144  **/
 145 int frsh_set_contract_reclamation_parameters(frsh_contract_parameters_t   *contract,
 146                                              const struct timespec       *stability_time,
 147                                              const struct timespec       *budget_max,
 148                                              const struct timespec       *period_min,
 149                                              frsh_granularity_t            granularity,
 150                                              const frsh_utilization_set_t *utilization_set,
 151                                              int                          importance,
 152                                              int                          quality);
 153
 154 /**
 155  * frsh_get_contract_reclamation_parameters()
 156  *
 157  * The operation obtains the sparecapacity contract parameters from
 158  * the contract object.
 159  *
 160  * @see frsh_set_contract_reclamation_parameters() for the meaning of
 161  * each parameter.
 162  *
 163  * Only the utilization_values of the utilization_set
 164  * that are in use, are copied (according to its size field).
 165  *
 166  *
 167  * @return 0 if successful
 168  *   FRSH_ERR_BAD_ARGUMENT :  if contract is NULL
 169  *
 170  **/
 171 int frsh_get_contract_reclamation_parameters
 172   (const frsh_contract_parameters_t *contract,
 173    struct timespec                 *stability_time,
 174    struct timespec                 *budget_max,
 175    struct timespec                 *period_min,
 176    frsh_granularity_t               *granularity,
 177    frsh_utilization_set_t           *utilization_set,
 178    int                             *importance,,
 179    int                             *quality);
 180
 181
 182
 183 /**
 184  * frsh_get_available_capacity()
 185  *
 186  * This operation stores in the variable pointed to by capacity the
 187  * spare capacity currently assigned to the importance level of the
 188  * specified server. The capacity is the number obtained divided by
 189  * UINT32_MAX, and it represents the processor or network
 190  * utilization.
 191  *
 192  * @return 0 if successful
 193  *   FRSH_ERR_BAD_ARGUMENT : if the value of the server argument is not in range or
 194  *       capacity is NULL
 195  *   FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
 196  *       scheduled under the FRSH
 197  *   FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running
 198  *   FRSH_ERR_NOT_CONTRACTED_SERVER : if the server has been cancelled or it
 199  *       is not valid
 200  *
 201  **/
 202 int frsh_get_available_capacity(frsh_server_id_t server, uint32_t *capacity);
 203
 204 /**
 205  * frsh_get_total_quality()
 206  *
 207  * This operation calculates the sum of the quality parameters for all
 208  * servers in the system of importance level equal to that of the
 209  * specified server, and stores it in the variable pointed to by
 210  * total_quality.
 211  *
 212  * @return 0 if successful
 213  *    FRSH_ERR_BAD_ARGUMENT : if the value of the server argument is not in range or
 214  *       total_quality is NULL
 215  *    FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
 216  *       scheduled under the FRSH
 217  *    FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running
 218  *    FRSH_ERR_NOT_CONTRACTED_SERVER : if the server has been cancelled or it
 219  *       is not valid
 220  * ]
 221  **/
 222 int frsh_get_total_quality
 223    (frsh_server_id_t server, int *total_quality);
 224
 225 /*@}*/
 226
 227 #endif // _FRSH_SPARE_CAPACITY_H_