// -----------------------------------------------------------------------
-// Copyright (C) 2005 Mälardalen University, SWEDEN
+// Copyright (C) 2006 - 2008 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 API 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, or (at your option)
-// any later version.
-//
-// FRSH API 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.
+// This file is part of FRSH (FRescor ScHeduler)
//
-// You should have received a copy of the GNU General Public License
-// distributed with FRSH API; see file COPYING. If not, write to the
-// Free Software Foundation, 59 Temple Place - Suite 330, Boston, MA
-// 02111-1307, USA.
+// FRSH is free software; you can redistribute it and/or modify it
+// under terms of the GNU General Public License as published by the
+// Free Software Foundation; either version 2, or (at your option) any
+// later version. FRSH 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 FRSH; see file
+// COPYING. If not, write to the Free Software Foundation, 675 Mass Ave,
+// Cambridge, MA 02139, USA.
//
-// As a special exception, if you include this header file into source
-// files to be compiled, this header file does not by itself cause
-// the resulting executable to be covered by the GNU General Public
-// License. This exception does not however invalidate any other
-// reasons why the executable file might be covered by the GNU General
-// Public License.
+// As a special exception, including FRSH header files in a file,
+// instantiating FRSH generics or templates, or linking other files
+// with FRSH objects to produce an executable application, does not
+// by itself cause the resulting executable application to be covered
+// by the GNU General Public License. This exception does not
+// however invalidate any other reasons why the executable file might be
+// covered by the GNU Public License.
// -----------------------------------------------------------------------
//frsh_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
+//==============================================
+// ******** ******* ******** ** **
+// **///// /**////** **////// /** /**
+// ** /** /** /** /** /**
+// ******* /******* /********* /**********
+// **//// /**///** ////////** /**//////**
+// ** /** //** /** /** /**
+// ** /** //** ******** /** /**
+// // // // //////// // //
//
-// FRSH(FIRST Scheduling Framework)
-// spare capacity sharing functionality
-//===================================================
+// FRSH(FRescor ScHeduler), pronounced "fresh"
+//==============================================
+#ifndef _FRSH_SPARE_CAPACITY_H_
+#define _FRSH_SPARE_CAPACITY_H_
#include <time.h>
#include <stdint.h>
-#include "frsh_basic_types.h"
+#include "frsh_spare_capacity_types.h"
+#include "frsh_core_types.h"
#include "frsh_core.h"
-#ifndef _FRSH_SPARE_CAPACITY_H_
-#define _FRSH_SPARE_CAPACITY_H_
+FRSH_CPP_BEGIN_DECLS
+
+/**
+ * @file frsh_spare_capacity.h
+ **/
#define FRSH_SPARE_CAPACITY_MODULE_SUPPORTED 1
-//// The definition of this types is in frsh_basic_types.h
-//
-//// Granularity of spare capacity requirements
-//typedef enum {FRSH_CONTINUOUS, FRSH_DISCRETE} frsh_granularity_t;
-//
-//// Utilization (budget and period) value
-//typedef struct {
-// struct timespec budget; // Execution time
-// struct timespec period; // Period
-//} frsh_utilization_value_t;
-//
-////List of utilization values
-//typedef struct {
-// int size; // = 0
-// frsh_utilization_value_t
-// value[FRSH_MAX_N_UTILIZATION_VALUES];
-// //unit change to value.....
-//} frsh_utilization_set_t;
-//
-//
-//// Constants for assigning default values
-//#define FRSH_DEFAULT_GRANULARITY FRSH_CONTINUOUS
-//#define FRSH_DEFAULT_QUALITY 0
-//#define FRSH_DEFAULT_IMPORTANCE 1
-//
-//
-//// Constants for omitting the assignment of values to specific
-//// arguments in calls to initialization functions
-//
-//#define FRSH_NULL_UTILIZATION_SET (frsh_utilization_set_t *)NULL
-//
-//frsh_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:
- 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
- (granularity is FRSH_CONTINUOUS and
- utilization_set is not FRSH_NULL_UTILIZATION_SET) or
- (granularity is FRSH_DISCRETE and
- utilization_set is FRSH_NULL_UTILIZATION_SET) or
- (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
- (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
-frsh_set_contract_reclamation_parameters
- (frsh_contract_parameters_t *contract,
- const struct timespec *budget_max,
- const struct timespec *period_min,
- frsh_granularity_t granularity,
- const frsh_utilization_set_t *utilization_set,
- int quality,
- int importance);
-
-
-//frsh_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:
- FRSH_ERR_BAD_ARGUMENT : if contract is NULL
- ]
-*/
-int
-frsh_get_contract_reclamation_parameters
- (const frsh_contract_parameters_t *contract,
- struct timespec *budget_max,
- struct timespec *period_min,
+/**
+ * @file frsh_spare_capacity.h
+ *
+ * This file contains the function prototypes for the usage of
+ * spare capacity and dynamic reclamation.
+ **/
+
+/**
+ * @defgroup sparecapacity Spare Capacity module
+ *
+ * This module manages the partition of exceeding capacity at
+ * 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
+ * giving WCET values only. This range can be continuous or
+ * discrete.
+ *
+ * - 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.
+ *
+ * An operation is available for applications to ask for a stability
+ * period of a specified length. The framework will then return the
+ * total capacity (execution time budget and virtual resource period)
+ * that the application is guaranteed to receive in this stability
+ * period. The rationale for this service is that jobs may span a
+ * number of virtual resource periods, and need to have a guaranteed
+ * amount of capacity before they can choose a higher quality (longer
+ * execution time) method, when multiple methods are available. Also
+ * applications may require that the capacity provided to them and
+ * hence the quality of results produced remains consistent for a
+ * period of time, so that consistent behaviour is provided for the
+ * user (e.g. multimedia applications).
+ *
+ * Requesting a new stability period has the effect of cancelling any
+ * previous one. So a subsequent request for stability up to the same
+ * point in time could return a lower total capacity, if spare capacity
+ * re-allocation is in progress due to the admission of a new
+ * application. If a stability period expires without having explicitly
+ * set a new one, the system may decide to perform a reallocation of
+ * spare resources at that point, or may defer this decision to some
+ * future point in time when it is appropriate. In both cases, a new
+ * stability period will start when the new spare capacity assignment
+ * is in effect.
+ *
+ *
+ * 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_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_contract_set_reclamation_params()
+ *
+ * The operation updates the specified contract parameters object by
+ * setting its maximum usable budget, minimum period, granularity,
+ * utilization set, weight, and importance to the specified input
+ * parameters.
+ *
+ * @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 vres aspires to
+ * get allocated.
+ * @param period_min The minimum period (therefore minimal
+ * 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 triples (budget,
+ * period, deadline)
+ * @param importance non-cooperative urgency indicator. Vres with
+ * higher importance will get all spare capacity des
+ * @param weight cooperative urgency indicator. At equal
+ * importance, spare capacity will be distributed
+ * proportionally to weight levels.
+ *
+ *
+ * @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) \b or \n
+ * (granularity is FRSH_DISCRETE and
+ * 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) ) \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) \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_contract_set_reclamation_params(frsh_contract_t *contract,
+ const frsh_rel_time_t *stability_time,
+ const frsh_rel_time_t *budget_max,
+ const frsh_rel_time_t *period_min,
+ frsh_granularity_t granularity,
+ const frsh_utilization_set_t *utilization_set,
+ int importance,
+ int weight);
+
+/**
+ * frsh_contract_get_reclamation_params()
+ *
+ * The operation obtains the sparecapacity contract parameters from
+ * the contract object.
+ *
+ * @see frsh_set_contract_reclamation_parameters() for the meaning of
+ * each parameter.
+ *
+ * Only the utilization_values of the utilization_set
+ * that are in use, are copied (according to its size field).
+ *
+ *
+ * @return 0 if successful \n
+ * FRSH_ERR_BAD_ARGUMENT : if contract is NULL
+ *
+ **/
+int frsh_contract_get_reclamation_params
+ (const frsh_contract_t *contract,
+ frsh_rel_time_t *stability_time,
+ frsh_rel_time_t *budget_max,
+ frsh_rel_time_t *period_min,
frsh_granularity_t *granularity,
frsh_utilization_set_t *utilization_set,
- int *quality,
- int *importance);
-
-
-//frsh_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:
- FRSH_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 FRSH_N_IMPORTANCE_LEVELS)
- 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
- ]
-*/
-int
-frsh_request_change_quality_and_importance
- (frsh_server_id_t server,
- int new_importance,
- int new_quality);
-
-
-//frsh_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:
- FRSH_ERR_BAD_ARGUMENT : if the value of the server argument is not in range or
- total_quality is NULL
- 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
- ]
-*/
-
-int
-frsh_get_total_quality
- (frsh_server_id_t server, int *total_quality);
-
-
-//frsh_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:
- FRSH_ERR_BAD_ARGUMENT : if the value of the server argument is not in range or
- capacity is NULL
- 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
- ]
-*/
-
-int
-frsh_get_available_capacity (
- frsh_server_id_t server, uint32_t *capacity);
+ 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,
+ frsh_rel_time_t *stability_time);
+
+
+/**
+ * frsh_vres_set_stability_time:
+ *
+ * Dynamically set the stability time for a given virtual resource to
+ * the specified interval. This operation sets a new value for the
+ * stability time associated with the virtual resource. As a result of
+ * this call the system may change the allocation of resources to the
+ * current virtual resource. Regardless of whether the resources are
+ * reallocated or not, the call resets the stability period so that
+ * the level of resources allocated to the virtual resource is kept
+ * stable for at least the duration of the requested interval. The
+ * possibly new values of budget and period are returned in the
+ * corresponding parameters
+ */
+
+int frsh_vres_set_stability_time
+ (frsh_vres_id_t vres,
+ const frsh_rel_time_t *stability_time,
+ frsh_rel_time_t *budget,
+ frsh_rel_time_t *period);
+
+
+/**
+ * frsh_resource_get_capacity()
+ *
+ * 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 \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 \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_capacity(const frsh_resource_type_t resource_type,
+ const frsh_resource_id_t resource_id,
+ const int importance,
+ uint32_t *capacity);
+
+
+/**
+ * frsh_resource_get_total_weight()
+ *
+ * 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 \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 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_vres_decrease_capacity(frsh_vres_id_t vres,
+ frsh_rel_time_t new_budget,
+ frsh_rel_time_t new_period);
+
+
+/*@}*/
+FRSH_CPP_END_DECLS
#endif // _FRSH_SPARE_CAPACITY_H_
projects / frescor / frsh-include.git / blobdiff