Subversion Repositories shark

//fsf_spare_capacity.h
//===================================================
//       FFFFFFIII   RRRRR      SSTTTTTTT
//      FF         IIR   RR    SS
//     FF           IR        SS
//    FFFFFF         RRRR    SSSSST
//   FF       FI       RRR  SS
//  FF         II     RRR  SS
// FF           IIIIIR    RS
//
// FSF(FIRST Scheduling Framework)
// spare capacity sharing functionality
//===================================================

#include <time.h>
#include <stdint.h>
#include "fsf_basic_types.h"
#include "fsf_core.h"

#ifndef _FSF_SPARE_CAPACITY_H_
#define _FSF_SPARE_CAPACITY_H_

#define FSF_SPARE_CAPACITY_MODULE_SUPPORTED       1

//// The definition of this types is in fsf_basic_types.h
//
//// Granularity of spare capacity requirements
//typedef enum {FSF_CONTINUOUS, FSF_DISCRETE} fsf_granularity_t;
//
//// Utilization (budget and period) value
//typedef struct {
//  struct timespec    budget;    // Execution time
//  struct timespec    period;    // Period
//} fsf_utilization_value_t;
//
////List of utilization values
//typedef struct {
//  int                         size; // = 0
//  fsf_utilization_value_t    
//      value[FSF_MAX_N_UTILIZATION_VALUES];
//      //unit change to value.....
//} fsf_utilization_set_t;
//
//
//// Constants for assigning default values
//#define FSF_DEFAULT_GRANULARITY         FSF_CONTINUOUS
//#define FSF_DEFAULT_QUALITY             0
//#define FSF_DEFAULT_IMPORTANCE          1
//
//
//// Constants for omitting the assignment of values to specific
//// arguments in calls to initialization functions
//
//#define FSF_NULL_UTILIZATION_SET     (fsf_utilization_set_t *)NULL
//

//fsf_set_contract_reclamation_parameters: The operation updates the
//specified contract parameters object by setting its maximum usable
//budget, minimum period, granularity, utilization set, quality, and
//importance to the specified input parameters.
/*
    [ERR@RETURNED:
     FSF_ERR_BAD_ARGUMENT :  if contract is NULL or  
       (budget_max value is grater than period_max or smaller than budget_min)  or
       (period_min is smaller than budget_mint or larger than period_max)       or
       (granularity is neither FSF_CONTINUOUS nor FSF_DISCRETE)                 or
       (granularity is FSF_CONTINUOUS and
        utilization_set is not FSF_NULL_UTILIZATION_SET)                        or
       (granularity is FSF_DISCRETE and
        utilization_set is FSF_NULL_UTILIZATION_SET)                            or
       (utilization_set is not FSF_NULL_UTILIZATION_SET and
        (size of utilization_set less than 2 or greater
         than FSF_MAX_N_UTILIZATION_VALUES)                )                    or
       (quality < 0)                                                            or
       (importance is less than 1 or greater than FSF_N_IMPORTANCE_LEVELS)      or
       (the utilization_set elements are not in increasing utilization order)   or
       (the first utilization value in the utilization_set does not match
        the pair (budget_min, period_max) of the contract)                      or
       (the last utilization value in the utilization_set does not match
        the pair (budget_max, period_min) of the contract)
    ]

*/
int
fsf_set_contract_reclamation_parameters
  (fsf_contract_parameters_t   *contract,
   const struct timespec       *budget_max,
   const struct timespec       *period_min,
   fsf_granularity_t            granularity,
   const fsf_utilization_set_t *utilization_set,
   int                          quality,
   int                          importance);


//fsf_get_contract_reclamation_parameters: The operation obtains from
//the specified contract parameters object its granularity,
//utilization set, quality, and importance. Then copies them to the
//variables pointed to by the specified input parameters.  Only the
//utilization_values of the utilization_set that are in use, are
//copied (according to its size field).
/*
    [ERR@RETURNED:
     FSF_ERR_BAD_ARGUMENT :  if contract is NULL
    ]
*/
int
fsf_get_contract_reclamation_parameters
  (const fsf_contract_parameters_t *contract,
   struct timespec                 *budget_max,
   struct timespec                 *period_min,
   fsf_granularity_t               *granularity,
   fsf_utilization_set_t           *utilization_set,
   int                             *quality,
   int                             *importance);


//fsf_request_change_quality_and_importance: The operation enqueues a
//request to change the quality and importance parameters of the
//specified server, and returns immediately.  The change operation is
//performed as soon as it is practical; meanwhile the system operation
//will continue normally.
/*
    [ERR@RETURNED:
     FSF_ERR_BAD_ARGUMENT : if the value of the server argument is not in range or
       (quality < 0)                                                            or
       (importance is less than 1 or greater than FSF_N_IMPORTANCE_LEVELS)
     FSF_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
       scheduled under the FSF
     FSF_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running
     FSF_ERR_NOT_CONTRACTED_SERVER : if the server has been cancelled or it
       is not valid
    ]
*/
int
fsf_request_change_quality_and_importance
  (fsf_server_id_t server,
   int new_importance,
   int new_quality);


//fsf_get_total_quality: This operation calculates the sum of the
//quality parameters for all servers in the system of importance level
//equal to that of the specified server, and stores it in the variable
//pointed to by total_quality.
/*
    [ERR@RETURNED:
     FSF_ERR_BAD_ARGUMENT : if the value of the server argument is not in range or
       total_quality is NULL
     FSF_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
       scheduled under the FSF
     FSF_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running
     FSF_ERR_NOT_CONTRACTED_SERVER : if the server has been cancelled or it
       is not valid
    ]
*/

int
fsf_get_total_quality
   (fsf_server_id_t server, int *total_quality);


//fsf_get_available_capacity: This operation stores in the variable
//pointed to by capacity the spare capacity currently assigned to the
//importance level of the specified server. The capacity is the number
//obtained divided by UINT32_MAX, and it represents the processor or
//network utilization.
/*
    [ERR@RETURNED:
     FSF_ERR_BAD_ARGUMENT : if the value of the server argument is not in range or
       capacity is NULL
     FSF_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
       scheduled under the FSF
     FSF_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running
     FSF_ERR_NOT_CONTRACTED_SERVER : if the server has been cancelled or it
       is not valid
    ]
*/

int
fsf_get_available_capacity (
    fsf_server_id_t server, uint32_t *capacity);


#endif // _FSF_SPARE_CAPACITY_H_