Rev 1063 |
Blame |
Compare with Previous |
Last modification |
View Log
| RSS feed
/*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*
*/
/**
@file Spare capacity file.
*/
//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
//
/**
\ingroup sparemodule
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.
@param [in] contract pointer ot the contract
@param [in] budget_max maximum budget this contract can obtain
@param [in] period_min minimum period this contract can obtain
@param [in] granularity can be either FSF_CONTINUOUS or FSF_DISCRETE
@param [in] utilization_set in case the granularity is set to
FSF_DISCRETE it contains a list possible pairs (budget,period)
@param [in] quality a number between FSF_MIN_QUALITY and FSF_MAX_QUALITY,
to control how the spare capacity is shared between
contracts with the same importance. The higher
this number is , the more likely we get a large increase
in the capacity
@param [in] importance a numer between FSF_MIN_IMPORTANCE and
FSF_MAX_IMPORTANCE, used to control how the spare capacity
is shared. The higher the number, the more likely we get
some spare capacity.
@retval 0 if the call is succesful
@retval FSF_ERR_BAD_ARGUMENT if contract is NULL or one of the
following conditions is true:
- (budget_max value is grater than period_max or smaller than
budget_min);
- (period_min is smaller than budget_mint or larger than period_max);
- (granularity is neither FSF_CONTINUOUS nor FSF_DISCRETE);
- (granularity is FSF_CONTINUOUS and
utilization_set is not FSF_NULL_UTILIZATION_SET)
- (granularity is FSF_DISCRETE and utilization_set is
FSF_NULL_UTILIZATION_SET)
- (utilization_set is not FSF_NULL_UTILIZATION_SET and
(size of utilization_set less than 2 or greater
than FSF_MAX_N_UTILIZATION_VALUES)
- (quality < 0)
- (importance is less than 1 or greater than FSF_N_IMPORTANCE_LEVELS)
- (the utilization_set elements are not in increasing utilization order)
- (the first utilization value in the utilization_set does not match
the pair (budget_min, period_max) of the contract);
- (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);
/**
\ingroup sparemodule
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).
@retval 0 if the operation is succesful
@retval FSF_ERR_BAD_ARGUMENT : if contract is NULL
@see fsf_set_contract_reclamation_parameters
*/
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);
/**
\ingroup sparemodule
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.
@param server server id
@param new_importance the new importance
@param new_quality the new requested quality
@retval FSF_ERR_BAD_ARGUMENT if
- the value of the server argument is not in range or
- (quality < 0)
- (importance is less than 1 or greater than FSF_N_IMPORTANCE_LEVELS).
@retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD if the calling thread is not
scheduled under the FSF
@retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or
not running
@retval 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);
/**
\ingroup sparemodule
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.
@param [in] server server id
@param [out] total_quality the total quality in the system
@retval FSF_ERR_BAD_ARGUMENT if the value of the server argument
is not in range or total_quality is NULL
@retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD if the calling thread is not
scheduled under the FSF
@retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or
not running
@retval 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);
/**
\ingroup sparemodule
This operation stores in the variable pointed to by capacity the
spare capacity currently available for the importance level of the
specified server. The capacity is the utilization (of the
processor or of the network) and it is represented by an integer
number between 0 (no utilization) and UINT32_MAX (all
utilization).
@retval FSF_ERR_BAD_ARGUMENT if the value of the server argument is
not in range or capacity is NULL
@retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD if the calling thread is not
scheduled under the FSF
@retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or
not running
@retval 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_