// -----------------------------------------------------------------------
-// Copyright (C) 2005 Mälardalen University, SWEDEN
+// Copyright (C) 2006 - 2007 FRESCOR consortium partners:
+//
+// Universidad de Cantabria, SPAIN
+// University of York, UK
+// Scuola Superiore Sant'Anna, ITALY
+// Kaiserslautern University, GERMANY
+// Univ. Politécnica Valencia, SPAIN
+// Czech Technical University in Prague, CZECH REPUBLIC
+// ENEA SWEDEN
+// Thales Communication S.A. FRANCE
+// Visual Tools S.A. SPAIN
+// Rapita Systems Ltd UK
+// Evidence ITALY
+//
+// See http://www.frescor.org for a link to partners' websites
+//
+// FRESCOR project (FP6/2005/IST/5-034026) is funded
+// in part by the European Union Sixth Framework Programme
+// The European Union is not liable of any use that may be
+// made of this code.
+//
+//
+// based on previous work (FSF) done in the FIRST project
+//
+// Copyright (C) 2005 Mälardalen University, SWEDEN
// Scuola Superiore S.Anna, ITALY
// Universidad de Cantabria, SPAIN
// University of York, UK
//
-// FRSH API web pages: http://marte.unican.es/frsh/docs/
+// FSF API web pages: http://marte.unican.es/fsf/docs
// http://shark.sssup.it/contrib/first/docs/
//
// This file is part of FRSH API
// -----------------------------------------------------------------------
//frsh_spare_capacity.h
//==============================================
-// ******** ******* ******** ** **
-// **///// /**////** **////// /** /**
-// ** /** /** /** /** /**
-// ******* /******* /*********/**********
-// **//// /**///** ////////**/**//////**
-// ** /** //** /**/** /**
-// ** /** //** ******** /** /**
-// // // // //////// // //
+// ******** ******* ******** ** **
+// **///// /**////** **////// /** /**
+// ** /** /** /** /** /**
+// ******* /******* /********* /**********
+// **//// /**///** ////////** /**//////**
+// ** /** //** /** /** /**
+// ** /** //** ******** /** /**
+// // // // //////// // //
//
// FRSH(FRescor ScHeduler), pronounced "fresh"
//==============================================
#include "frsh_core.h"
+/**
+ * @file frsh_spare_capacity.h
+ **/
+
#define FRSH_SPARE_CAPACITY_MODULE_SUPPORTED 1
* @defgroup sparecapacity Spare Capacity module
*
* This module manages the partition of exceeding capacity at
- * negotiation time between the servers that express their desire of
+ * negotiation time between the vres that express their desire of
* optional requirements.
*
* It works by:
- * * Allowing to define a range of budget and period instead of
+ *
+ * - Allowing to define a range of budget and period instead of
* giving WCET values only. This range can be continuous or
* discrete.
*
- * * Specify a fairness measurement to compete with other servers in the
+ * - Specifying a fairness measurement to compete with other vres in the
* division of the share.
*
+ * - Specifying a stability_time time for vres that need to have
+ * a assigned capacity remain const during time (they would be
+ * annoyed if their budget or period would change).
+ *
* There are no specific negotiation calls because the algorithms used
* in the core module take already these min-max ranges into account.
*
- * NOTE: When we talk here about "spare capacity" we mean extra
- * capacity at NEGOTIATION TIME. Whatever budget and period
- * limits we assign after negotiation will remain permanent
- * until a new (re)negotiation takes place (which may be
- * enlarged with stability_time).
+ * NOTE: When we talk here about "spare capacity" we mean STATIC extra
+ * capacity at NEGOTIATION TIME. This is the minimum capacity
+ * that the vres will get based on contract negotiation.
+ * This capacity is distributed based on the importance and
+ * weight values and is known before-hand at the beginning of
+ * a period.
+ *
+ * Besides this extra capacity, there is the DYNAMIC extra
+ * capacity that results at RUN TIME from earlier job endings of
+ * bounded-workload vres. This extra capacity can vary
+ * between each execution period and is not known beforehand.
+ *
+ * This extra run-time capacity is assigned if the following 2
+ * conditions are met:
*
- * FRSH manages as well another extra capacity that results in
- * the early job ending of bounded workload servers. We may
- * call this extra capacity at RUN TIME and it varies from
- * period to period.
+ * - FRSH_DYNAMIC_RECLAIMING_MODULE_SUPPORTED is defined to 1
+ * (in frsh_dynamic_reclaiming.h).
+ *
+ * - There is at least one vres willing to accept this extra
+ * capacity:
+ * - A FRSH_BOUNDED workload vres with a range of Budget
+ * and Period that can absorb the extra capacity and
+ * whose static_time period is not active.
+ * - An INDETERMINATE workload vres with an active
+ * static_time period.
+ * @{
**/
+
/**
- * frsh_set_contract_reclamation_parameters()
+ * frsh_contract_set_reclamation_params()
*
* 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
+ * utilization set, weight, and importance to the specified input
* parameters.
*
- * @param[inout] contract Contract object
+ * @param contract Contract object
* @param stability_time Time in which FRSH guarantees that the
* assigned budget and period will remain permanent
* even across renegotiations.
- * @param budget_max The maximum budget that the server aspires to
+ * @param budget_max The maximum budget that the vres aspires to
* get allocated.
* @param period_min The minimum period (therefore minimal
- * interarrival time) that the server may get for
+ * interarrival time) that the vres may get for
* awakening and replenishment periods.
* @param granularity FRSH_CONTINUOUS: Use min-max values,
* FRSH_DISCRETE: Use utilization_set.
* @param utilization_set A structure of discrete pairs (budget,period)
- * @param importance non-cooperative urgency indicator. Server with
+ * @param importance non-cooperative urgency indicator. Vres with
* higher importance will get all spare capacity des
- * @param quality cooperative urgency indicator. At equal
+ * @param weight cooperative urgency indicator. At equal
* importance, spare capacity will be distributed
- * proportionally to quality levels.
+ * proportionally to weight levels.
*
- * @return 0 if successful
- * FRSH_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 FRSH_CONTINUOUS nor FRSH_DISCRETE) or
+ * @return 0 if successful \n
+ * FRSH_ERR_BAD_ARGUMENT : if contract is NULL \b or \n
+ * (budget_max value is grater than period_max or smaller than budget_min) \b or \n
+ * (period_min is smaller than budget_mint or larger than period_max) \b or \n
+ * (granularity is neither FRSH_CONTINUOUS nor FRSH_DISCRETE) \b or \n
* (granularity is FRSH_CONTINUOUS and
- * utilization_set is not FRSH_NULL_UTILIZATION_SET) or
+ * utilization_set is not FRSH_NULL_UTILIZATION_SET) \b or \n
* (granularity is FRSH_DISCRETE and
- * utilization_set is FRSH_NULL_UTILIZATION_SET) or
+ * utilization_set is FRSH_NULL_UTILIZATION_SET \b or \n
* (utilization_set is not FRSH_NULL_UTILIZATION_SET and
* (size of utilization_set less than 2 or greater
- * than FRSH_MAX_N_UTILIZATION_VALUES) ) or
- * (quality < 0) or
- * (importance is less than 1 or greater than FRSH_N_IMPORTANCE_LEVELS) or
- * (the utilization_set elements are not in increasing utilization order) or
+ * than FRSH_MAX_N_UTILIZATION_VALUES) ) \b or \n
+ * (weight < 0) \b or \n
+ * (importance is less than 1 or greater than FRSH_N_IMPORTANCE_LEVELS) \b or \n
+ * (the utilization_set elements are not in increasing utilization order) \b or \n
* (the first utilization value in the utilization_set does not match
- * the pair (budget_min, period_max) of the contract) or
+ * the pair (budget_min, period_max) of the contract) \b or \n
* (the last utilization value in the utilization_set does not match
* the pair (budget_max, period_min) of the contract)
*
**/
-int frsh_set_contract_reclamation_parameters(frsh_contract_parameters_t *contract,
- const struct timespec *stability_time,
- const struct timespec *budget_max,
- const struct timespec *period_min,
- frsh_granularity_t granularity,
- const frsh_utilization_set_t *utilization_set,
- int importance,
- int quality);
+int frsh_contract_set_reclamation_params(frsh_contract_t *contract,
+ const struct timespec *stability_time,
+ const struct timespec *budget_max,
+ const struct timespec *period_min,
+ frsh_granularity_t granularity,
+ const frsh_utilization_set_t *utilization_set,
+ int importance,
+ int weight);
/**
- * frsh_get_contract_reclamation_parameters()
+ * frsh_contract_get_reclamation_params()
*
* The operation obtains the sparecapacity contract parameters from
* the contract object.
* that are in use, are copied (according to its size field).
*
*
- * @return 0 if successful
+ * @return 0 if successful \n
* FRSH_ERR_BAD_ARGUMENT : if contract is NULL
*
**/
-int frsh_get_contract_reclamation_parameters
- (const frsh_contract_parameters_t *contract,
+int frsh_contract_get_reclamation_params
+ (const frsh_contract_t *contract,
struct timespec *stability_time,
struct timespec *budget_max,
struct timespec *period_min,
frsh_granularity_t *granularity,
frsh_utilization_set_t *utilization_set,
- int *importance,,
- int *quality);
+ int *importance,
+ int *weight);
+/**
+ * frsh_vres_get_remaining_stability_time()
+ *
+ * This operation returns the stability_time for the vres.
+ *
+ * @return 0 if successful \n
+ * FRSH_ERR_BAD_ARGUMENT : if the value of the vres argument is not in range or
+ * capacity is NULL \n
+ * FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
+ * scheduled under FRSH \n
+ * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not
+ * running \n
+ * FRSH_ERR_NOT_CONTRACTED_VRES : if the vres has been cancelled or it
+ * is not valid \n
+ *
+ **/
+int frsh_vres_get_remaining_stability_time(frsh_vres_id_t vres,
+ struct timespec *stability_time);
/**
- * frsh_get_available_capacity()
+ * frsh_resource_get_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
+ * This operation gets the spare capacity currently assigned to an
+ * importance level. The capacity is the number obtained divided by
* UINT32_MAX, and it represents the processor or network
* utilization.
*
- * @return 0 if successful
- * FRSH_ERR_BAD_ARGUMENT : if the value of the server argument is not in range or
- * capacity is NULL
+ * @return 0 if successful \n
+ * FRSH_ERR_BAD_ARGUMENT : if the value of the vres argument is not in range or
+ * capacity is NULL \n
* FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
- * scheduled under the FRSH
- * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running
- * FRSH_ERR_NOT_CONTRACTED_SERVER : if the server has been cancelled or it
- * is not valid
+ * scheduled under the FRSH \n
+ * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not
+ * running \n
+ * FRSH_ERR_NOT_CONTRACTED_VRES : if the vres has been cancelled or it
+ * is not valid \n
*
**/
-int frsh_get_available_capacity(frsh_server_id_t server, uint32_t *capacity);
+int frsh_resource_get_capacity(const frsh_resource_type_t resource_type,
+ const frsh_resource_id_t resource_id,
+ const int importance,
+ uint32_t *capacity);
+
/**
- * frsh_get_total_quality()
+ * frsh_resource_get_total_weight()
*
- * 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.
+ * This operation calculates the sum of the weight parameters for all
+ * vres in the system for a certain importance level at a specific
+ * resource_id.
*
- * @return 0 if successful
- * FRSH_ERR_BAD_ARGUMENT : if the value of the server argument is not in range or
- * total_quality is NULL
+ * @return 0 if successful \n
+ * FRSH_ERR_BAD_ARGUMENT : if the value of the vres argument is not in range or
+ * total_weight is NULL \n
* FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
- * scheduled under the FRSH
- * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running
- * FRSH_ERR_NOT_CONTRACTED_SERVER : if the server has been cancelled or it
- * is not valid
- * ]
+ * scheduled under FRSH \n
+ * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not
+ * running \n
+ * FRSH_ERR_NOT_CONTRACTED_VRES : if the vres has been cancelled or it
+ * is not valid \n
+ **/
+int frsh_resource_get_total_weight
+ (const frsh_resource_type_t resource_type,
+ const frsh_resource_id_t resource_id,
+ const int importance,
+ uint32_t *total_weight);
+
+
+/**
+ * frsh_vres_decrease_capacity()
+ *
+ * This operation is mainly intended for distributed systems but may
+ * also be useful for control application in uniprocessor systems.
+ *
+ * It allows the vres to ask for less budget and period that what he
+ * has actually received. The request must be compatible with the
+ * rest of contract parameters.
+ *
**/
-int frsh_get_total_quality
- (frsh_server_id_t server, int *total_quality);
+int frsh_vres_decrease_capacity(frsh_vres_id_t vres,
+ struct timespec new_budget,
+ struct timespec new_period);
+
/*@}*/
projects / frescor / frsh-include.git / blobdiff