--- /dev/null
+ include_HEADERS := $(notdir $(wildcard $(SOURCES_DIR)/*.h))
+
+ ifeq ($(CONFIG_FRSH_FORB),y)
+ UNWANTED_HEADERS += frsh_opaque_types.h
+ endif
+ UNWANTED_HEADERS += frsh_configuration_parameters.h
+ include_HEADERS := $(filter-out $(UNWANTED_HEADERS),$(include_HEADERS))
+
+ default_CONFIG := $(shell grep '^\#define FRSH' $(SOURCES_DIR)/frsh_configuration_parameters.h|sed -e 's/\#define \([^ ]*\) *\(.*\)/\1=\2/' -e 's/ //g' -e 's|//.*||' -e 's|/\*.*\*/||g')
+
+ config_include_HEADERS = frsh_configuration_parameters.h
+ frsh_configuration_parameters_DEFINES := $(shell echo '$(default_CONFIG)' | sed -e 's/\([^=]*\)=[^ ]*/\1/g')
--- /dev/null
+ //----------------------------------------------------------------------
+ // Copyright (C) 2006 - 2009 by the FRESCOR consortium:
+ //
+ // Universidad de Cantabria, SPAIN
+ // University of York, UK
+ // Scuola Superiore Sant'Anna, ITALY
+ // Kaiserslautern University, GERMANY
+ // Univ. Politecnica 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
+ //
+ // The 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
+ //
+ // This file is part of DTM (Distributed Transaction Manager)
+ //
+ // DTM 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. DTM 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 DTM; see file
+ // COPYING. If not, write to the Free Software Foundation, 675 Mass Ave,
+ // Cambridge, MA 02139, USA.
+ //
+ // As a special exception, including DTM header files in a file,
+ // instantiating DTM generics or templates, or linking other files
+ // with DTM 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.
+ // -----------------------------------------------------------------------
+
+ /*!
+ * @file dtm.h
+ *
+ * @brief DTM API services
+ *
+ * This module contains the functions defined in the DTM API.
+ *
+ * @version 0.01
+ *
+ * @date 7-Sept-2007
+ *
+ * @author Michael Gonzalez Harbour <mgh@unican.es>
+ * @author Michal Sojka <sojkam1@fel.cvut.cz>
+ * @author Daniel Sangorrin <daniel.sangorrin@unican.es>
+ *
+ */
+
+ #ifndef _DTM_H_
+ #define _DTM_H_
+
+ #include "frsh.h"
+
+ typedef unsigned int trans_id_t; /* 0 .. MX_TRANS-1 */
+
+ typedef enum {
+ TRANS_UNKNOWN = 0,
+ TRANS_IN_PROGRESS = 1,
+ TRANS_ACTIVE = 2,
+ TRANS_CANCELLED = 3,
+ } trans_status_t;
+
+ /**
+ * dtm_resources_set_processor_vres()
+ *
+ * Set the virtual resource that will be used in the local processor by the
+ * manager thread of the agent of the DTM. This must be a valid virtual
+ * resource obtained form the negotiation of a contract.
+ *
+ **/
+
+ extern int dtm_resources_set_processor_vres(const frsh_vres_id_t vres);
+
+ /**
+ * dtm_resources_set_network_vres()
+ *
+ * Set the virtual resource that will be used by the local DTM agent to send
+ * messages to the specified destination address. This must be a valid virtual
+ * resource obtained from the negotiation of a network contract, and must be
+ * compatible with the current system topology. Multiple calls to this
+ * operation may be needed, one for each processing node that is connected
+ * directly.
+ *
+ **/
+
+ extern int dtm_resources_set_network_vres(const frsh_resource_id_t network,
+ const frsh_resource_id_t dest,
+ const frsh_vres_id_t vres);
+
+ /**
+ * dtm_trans_init()
+ *
+ * Initialize a new transaction with the given name and maximum number of
+ * contracts. The newly created transaction will be initialized to contain
+ * no contracts.
+ *
+ **/
+
+ extern int dtm_trans_init(const char *name,
+ const unsigned char num_contracts,
+ trans_id_t *trans);
+
+ /**
+ * dtm_trans_add_contract()
+ *
+ * Add a reference to a contract to the given transaction together with
+ * the node in which that contract needs to be negotiated, and a boolean
+ * indicating whether or not the period needs to be synchronous with
+ * respect to other synchronous-period contracts in the transaction. Just
+ * the reference to the contract is copied, not the full contract information,
+ * and thus future changes to the contract may affect future negotiations
+ * or renegotiations.
+ *
+ **/
+
+ extern int dtm_trans_add_contract(trans_id_t trans,
+ frsh_contract_t *contract,
+ frsh_resource_id_t node,
+ bool is_synch_period);
+
+ /**
+ * dtm_trans_remove_contract()
+ *
+ * Remove a contract, identified by its label, from the transaction.
+ *
+ **/
+
+ extern int dtm_trans_remove_contract(trans_id_t trans,
+ const char *contract_label);
+
+ /**
+ * dtm_trans_destroy()
+ *
+ * Destroy a transaction freeing any memory that was allocated to it at
+ * its creation.
+ *
+ **/
+
+ extern int dtm_trans_destroy(trans_id_t trans);
+
+ /**
+ * dtm_trans_num_contracts()
+ *
+ * Return the current number of contracts in a transaction.
+ *
+ **/
+
+ extern int dtm_trans_num_contracts(trans_id_t trans, unsigned char *num);
+
+ /**
+ * dtm_trans_get_contract()
+ *
+ * Given an index, return a reference to the contract stored in that index.
+ * This operation is used to iterate over the contracts of a transaction.
+ *
+ **/
+
+ extern int dtm_trans_get_contract(trans_id_t trans,
+ unsigned char index,
+ frsh_contract_t **contract);
+
+ /**
+ * dtm_trans_negotiate()
+ *
+ * Negotiate a transaction. This is a blocking call that will not return
+ * until the negotiation has been completed.
+ *
+ **/
+
+ extern int dtm_trans_negotiate(trans_id_t trans);
+
+ /**
+ * dtm_trans_cancel()
+ *
+ * Cancel a transaction, by cancelling all the virtual resources that were
+ * associated with it. Cancellation has to be invoked from the same node
+ * where the transaction was negotiated.
+ *
+ **/
+
+ extern int dtm_trans_cancel(trans_id_t trans);
+
+ /**
+ * dtm_trans_renegotiate()
+ *
+ * Renegotiate a transaction. This is a blocking call that will not return
+ * until the negotiation has been completed.
+ *
+ **/
+
+ extern int dtm_trans_renegotiate(trans_id_t trans);
+
+ /**
+ * dtm_priv_trans_search()
+ *
+ * Internal function that searches a transaction by its name. It returns
+ * true if the transaction exists and sets the parameter to the transaction
+ * handle.
+ *
+ * When allocate_if_miss equals true, it tries to allocate a new transaction
+ * if the transaction was not found with 0 contracts.
+ *
+ **/
+
+ extern bool dtm_priv_trans_search(const char *name,
+ trans_id_t *trans,
+ const bool allocate_if_miss);
+
+ /**
+ * dtm_trans_get_status()
+ *
+ * Given a transaction name, get its status. This operation can be created
+ * in any node in the system. The status is an enumeration:
+ *
+ * - unknown: the current node has not yet been involved in the transaction
+ * - in_progress: the negotiation is in progress
+ * - active: the transaction was successfully negotiated and is active
+ * - cancelled: the transaction was cancelled
+ *
+ **/
+
+ extern int dtm_trans_get_status(const char *name,
+ trans_status_t *status);
+
+ /**
+ * dtm_trans_wait_active()
+ *
+ * Given a transaction name, wait until it gets active. A handle to the
+ * transaction is obtained. A timeout may be specified.
+ *
+ **/
+
+ extern int dtm_trans_wait_active(const char *name,
+ const struct timespec *timeout,
+ trans_id_t *trans);
+
+ /**
+ * dtm_trans_get_vres()
+ *
+ * Given a transaction handle and a contract label, get the virtual resource
+ * associated with that contract in the local processor.
+ *
+ **/
+
+ extern int dtm_trans_get_vres(trans_id_t trans,
+ const char *contract_label,
+ frsh_vres_id_t *vres);
+
+ /**
+ * dtm_trans_get_period()
+ *
+ * Get the current synchronous period of an active transaction, if any.
+ *
+ **/
+
+ extern int dtm_trans_get_period(trans_id_t trans,
+ struct timespec *period);
+
+ /**
+ * dtm_init()
+ *
+ * Initialize the distributed transaction manager in the local node.
+ * The stream Id to be used for DTM messages is specified as an argument.
+ * In first place, the operation creates all the necessary system resources
+ * (threads and communication endpoints) and binds them to the resources that
+ * were previously assigned locally to the DTM. Then, it performs the
+ * initialization process that synchronizes all the nodes, waiting until all
+ * of them are ready to work.
+ *
+ * TODO: The wait can be specified with a timeout,
+ * after which the operation would deallocate the allocated resources
+ * and return an error indication.
+ *
+ **/
+
+ extern int dtm_init(frsh_stream_id_t stream);
+
+ /**
+ * dtm_init_isdone()
+ *
+ * Query about whether the DTM has been initialized or not.
+ *
+ **/
+
+ extern bool dtm_init_isdone(void);
+
+ #endif // _DTM_H_
--- /dev/null
+ // -----------------------------------------------------------------------
+ // Copyright (C) 2006 - 2009 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
+ //
+ // FSF API web pages: http://marte.unican.es/fsf/docs
+ // http://shark.sssup.it/contrib/first/docs/
+ //
+ // This file is part of FRSH (FRescor ScHeduler)
+ //
+ // 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, 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(FRescor ScHeduler), pronounced "fresh"
+ //==============================================
+ #ifndef _FRSH_H_
+ #define _FRSH_H_
+
+ /**
+ * @file frsh.h
+ *
+ * Intended to be used by API clients to get the interface
+ * requirements.
+ *
+ * It is also used by the library files to enforce the interface
+ * headings.
+ *
+ * However it is NOT used by any of the FRSH include files to avoid
+ * having include deadlocks.
+ **/
+
+ #include "fosa.h"
+
+ #include "frsh_cpp_macros.h"
+
+ #include "frsh_configuration_parameters.h"
+
+ /* We include all the types because they are needed for the
+ frsh_contract_parameters_t */
+
+ #include "frsh_core_types.h"
+ #include "frsh_shared_objects_types.h"
+ #include "frsh_spare_capacity_types.h"
+ #include "frsh_hierarchical_types.h"
+ #include "frsh_distributed_types.h"
+ #include "frsh_implementation_specific_types.h"
+
+ #include "frsh_core.h"
+ #include "frsh_thread_attrs.h"
+ #include "frsh_time.h"
+ #include "frsh_implementation_specific.h"
+
+ // Configure these modules by commenting out the appropiate lines
+
+ #include "frsh_hierarchical.h" //
+ #include "frsh_shared_objects.h"
+ #include "frsh_dynamic_reclaiming.h" //
+ #include "frsh_spare_capacity.h"
+ #include "frsh_distributed.h" //
+ #include "frsh_feedback_control.h"
+ #include "frsh_memory_management.h"
+ #include "frsh_energy_management.h"
+
+ #include "frsh_debug_and_trace.h"
+
+ #ifndef FRSH_HIERARCHICAL_MODULE_SUPPORTED
+ #define FRSH_HIERARCHICAL_MODULE_SUPPORTED 0
+
+ #endif //FRSH_HIERARCHICAL_MODULE_SUPPORTED
+
+ #ifndef FRSH_SHARED_OBJECTS_MODULE_SUPPORTED
+ #define FRSH_SHARED_OBJECTS_MODULE_SUPPORTED 0
+ #endif //FRSH_SHARED_OBJECTS_MODULE_SUPPORTED
+
+ #ifndef FRSH_DYNAMIC_RECLAIMING_MODULE_SUPPORTED
+ #define FRSH_DYNAMIC_RECLAIMING_MODULE_SUPPORTED 0
+ #endif //FRSH_DYNAMIC_RECLAIMING_MODULE_SUPPORTED
+
+ #ifndef FRSH_SPARE_CAPACITY_MODULE_SUPPORTED
+ #define FRSH_SPARE_CAPACITY_MODULE_SUPPORTED 0
+
+ //Return warnings if spare_capacity module is not included:
+
+ #define frsh_set_contract_reclamation_parameters \
+ (contract, budget_max, period_min, granularity,\
+ utilization_set, quality, importance) \
+ ( FRSH_WRN_MODULE_NOT SUPPORTED )
+
+ #define frsh_get_contract_reclamation_parameters \
+ (contract, budget_max, period_min, granularity,\
+ utilization_set, quality, importance) \
+ ( FRSH_WRN_MODULE_NOT SUPPORTED )
+
+ #define frsh_request_change_quality_and_importance\
+ (server, new_importance, new_quality) \
+ ( FRSH_WRN_MODULE_NOT SUPPORTED )
+
+ #define frsh_get_total_quality (server,total_quality)\
+ ( FRSH_WRN_MODULE_NOT SUPPORTED )
+
+ #endif //FRSH_SPARE_CAPACITY_MODULE_SUPPORTED
+
+ #include <frsh_transaction.h>
+
+ #endif // _FRSH_H_
--- /dev/null
+ // -----------------------------------------------------------------------
+ // Copyright (C) 2006 - 2009 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
+ //
+ // FSF API web pages: http://marte.unican.es/fsf/docs
+ // http://shark.sssup.it/contrib/first/docs/
+ //
+ // This file is part of FRSH (FRescor ScHeduler)
+ //
+ // 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, 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_configuration_parameters.h
+ //==============================================
+ // ******** ******* ******** ** **
+ // **///// /**////** **////// /** /**
+ // ** /** /** /** /** /**
+ // ******* /******* /********* /**********
+ // **//// /**///** ////////** /**//////**
+ // ** /** //** /** /** /**
+ // ** /** //** ******** /** /**
+ // // // // //////// // //
+ //
+ // FRSH(FRescor ScHeduler), pronounced "fresh"
+ //==============================================
+ #ifndef _FRSH_CONFIGURATION_PARAMETERS_H_
+ #define _FRSH_CONFIGURATION_PARAMETERS_H_
+
+ #include <unistd.h>
+ #include <limits.h>
+ #include <frsh_cpp_macros.h>
+
+ FRSH_CPP_BEGIN_DECLS
+
+ /**
+ * @file frsh_configuration_parameters.h
+ *
+ * This file contains parameters that govern the capabilities of the
+ * FRescor ScHeduler. They must be in concordance with the respective
+ * OS configuration.
+ **/
+
+
+ /**
+ * @defgroup config Configuration Parameters
+ *
+ * Here we define global parameters that will have an important
+ * influence on FRSH behaviour. They must also be coherent with the
+ * respective values in the underlaying OS.
+ *
+ * @{
+ **/
+
+
+ /**
+ * This symbol specifies whether the scheduler will make a
+ * schedulability test of the requested contract or not
+ **/
+ #define FRSH_ADMISSION_TEST_IS_ENABLED true
+
+ /**
+ * This symbol specifies whether the service thread will try to
+ * assign automatically the priorities of each vres
+ **/
+ #define FRSH_AUTOMATIC_PRIO_ASSIGN_ENABLE true
+
+ #ifdef ENABLE_FRSH_DISTRIBUTED_MODULE
+ #define FRSH_DISTRIBUTED_MODULE_SUPPORTED true
+ #else
+ #define FRSH_DISTRIBUTED_MODULE_SUPPORTED false
+ #endif
+
+ /** This defines 1 resource_id value for systems that have only one
+ resource of a kind. **/
+ #define FRSH_RESOURCE_ID_DEFAULT 0
+ #define FRSH_CPU_ID_DEFAULT 0
+ #define FRSH_NETWORK_ID_DEFAULT 0
+
+ /**
+ * @defgroup internal Array size for memory optimization
+ * @ingroup config
+ *
+ * Tune these values for optimizing the amount of memory used by the
+ * implementation
+ *
+ * @{
+ **/
+
+ /** Maximum number of accepted contracts (vres) **/
+ #define FRSH_MAX_N_VRES 25
+
+ /** Maximum number of threads that may be scheduled by the framework **/
+ #define FRSH_MAX_N_THREADS 25
+
+ /**
+ * Maximum number of critical sections that can be stored in a
+ * contract parameters object
+ **/
+ #define FRSH_MAX_N_CRITICAL_SECTIONS 10
+
+ /**
+ * Maximum number of memory areas that can be specified for a
+ * wite operation in a critical section
+ **/
+ #define FRSH_MAX_N_MEMORY_AREAS 4
+
+ /**
+ * Maximum number of utilization values (pairs of budget and period)
+ * that can be stored in a contract parameters object
+ **/
+ #define FRSH_MAX_N_UTILIZATION_VALUES 5
+
+ /** Number of importance levels for spare capacity allocation **/
+ #define FRSH_N_IMPORTANCE_LEVELS 5
+
+ /**
+ * Maximum number of synchronization objects
+ **/
+ #define FRSH_MAX_N_SYNCH_OBJECTS 5
+
+ /** Maximum number of shared objects **/
+ #define FRSH_MAX_N_SHARED_OBJECTS 100
+
+ /** Maximum number of send and receive endpoints in a single node **/
+ #define FRSH_MAX_N_ENDPOINTS 10
+
+ /** Maximum number of chars for a contract label **/
+ #define FRSH_CONTRACT_LABEL_MAXLENGTH 15
+
+ /*@}*/
+
+ /**
+ * @defgroup schedandservice Scheduler and Service thread parameters
+ * @ingroup config
+ *
+ * The current implementation in MaRTE OS uses the Application-Defined
+ * Scheduling Interface (proposed to the POSIX standardization
+ * committee), to create a fixed-priority-based scheduler that
+ * operates under the rules of the FIRST scheduling framework.
+ *
+ * In this implementation there are two special threads:
+ * - The application scheduler thread, that
+ * implements the scheduler
+ *
+ * - The service thread, that is in charge of
+ * negotiating and renegotiating contracts
+ * concurrently with the application
+ *
+ * The following symbols are necessary to adapt the application to the
+ * underlying fixed priority scheduler
+ *
+ * @{
+ **/
+
+ /**
+ * Priority assigned to the application scheduler; it should be above
+ * the priorities of the application threads and of the service
+ * thread, and it should be at least 1 level below the maximum of the
+ * system
+ **/
+ #define FRSH_SCHEDULER_PRIORITY (fosa_get_priority_max() - FOSA_ADS_SCHEDULER_PRIO_DIFF)
+
+ /**
+ * Real-time signal number reserved for the application scheduler to
+ * manage its timers.
+ **/
+ #define FRSH_SCHEDULER_SIGNAL FRSH_SIGNAL_MIN
+
+
+
+ /**
+ * The highest priority that can be assigned to an application thread,
+ * it should be defined as one level less than the
+ * FRSH_SCHEDULER_PRIORITY
+ **/
+ #define FRSH_HIGHEST_THREAD_PRIORITY (FRSH_SCHEDULER_PRIORITY-1)
+
+
+ /**
+ * The lowest priority that can be assigned to an application thread,
+ * it should be at least 1 level above the minimum of the system
+ **/
+ #define FRSH_LOWEST_THREAD_PRIORITY ( fosa_get_priority_min() + 4)
+
+ /**
+ * Each call to the functions that negotiate or renegotiate a contract
+ * or that change the quality and importance generates a request for
+ * the service thread that we call a service job. This job will be
+ * pending in a queue until executed by the service thread. The
+ * following symbol represents the maximum number of requests that can
+ * be simultaneously queued.
+ **/
+ #define FRSH_MAX_N_SERVICE_JOBS (FRSH_MAX_N_VRES * 2)
+
+
+ /**
+ * In order to bound the background activity of the scheduler (i.e.,
+ * the admission tests necessary for the negotiation and
+ * re-negotiation of contracts), a service thread has been defined. It
+ * runs at a given priority level and has a budget and period
+ * assigned.
+ *
+ **/
+
+ /** Initial period of the service thread (timespec) **/
+ #define FRSH_SERVICE_THREAD_PERIOD_USECS 500000 /* 500 msecs */
+
+ /** Initial budget of the service thread (timespec) **/
+ #define FRSH_SERVICE_THREAD_BUDGET_USECS 1000 /* 1 msec */
+
+ /**
+ * Initial priority of the service thread, it has to be lower than the
+ * FRSH_SCHEDULER_PRIORITY, and is set according to its period and the
+ * expected response times for reconfiguration or tunning of the
+ * system.
+ *
+ * If set to zero and FRSH_ADMISSSION_TEST_ENABLE is set to true then
+ * the priority will be assigned according to DMA rules.
+ **/
+ //#define FRSH_SERVICE_THREAD_PRIORITY (FRSH_LOWEST_THREAD_PRIORITY+1)
+ #define FRSH_SERVICE_THREAD_PRIORITY 0
+
+
+ /*@}*/
+
+
+ /**
+ * @defgroup miscconfig Miscellaneous Config parameters
+ * @ingroup config
+ *
+ * @{
+ **/
+
+ /**
+ * Maximum number of vres that can be simultaneusly waiting for
+ * being signaled in a synchronization object
+ **/
+ #define FRSH_MAX_N_VRES_IN_SYNCH_OBJECT 4
+
+
+ /**
+ * Maximum number of events that can be pending to be signaled in a
+ * synchronization object
+ **/
+ #define FRSH_MAX_N_EVENTS_IN_SYNCH_OBJECT 100
+
+ /**
+ * Maximum number of pending replenishments in each sporadic server
+ **/
+ #define FRSH_MAX_N_PENDING_REPLENISHMENTS 25 //250
+
+
+ /**
+ * Maximum number of target windows in a table driven schedule
+ **/
+ #define FRSH_MAX_N_TARGET_WINDOWS 100
+
+ /**
+ * The cpu time given by the round robin scheduler
+ * to the threads in the background (timespec)
+ **/
+ #define FRSH_RR_SLICE_CPU_TIME_USECS 100000 // 0.1 sec
+
+ /**
+ * This function must be supplied by the user to map the preemption
+ * level values given in the contracts for the vres, to priority
+ * values in the range that is allowed by the present implementation
+ * for application threads. The value returned by the function must
+ * fit in the interval defined by the constants:
+ * [FRSH_LOWEST_THREAD_PRIORITY, FRSH_HIGHEST_THREAD_PRIORITY]
+ **/
+ int frsh_priority_map (unsigned long plevel);
+
+ /**
+ * This symbol specifies the maximum number of chars that are stored
+ * of a given shared_object_id, so this is the maximum length used
+ * in comparisons
+ **/
+ #define FRSH_MAX_SIZE_SHARED_OBJ_LABEL 15
+
+
+ /** Maximum number of networks accesible from a node **/
+ #define FRSH_MAX_N_NETWORK_IDS 1
+
+ /**
+ * Maximum number of groups allocated at the same time
+ **/
+ #define FRSH_MAX_N_GROUPS 3
+
+ /**
+ * Maximum number of groups operations (neg, reneg, cancel) per group
+ **/
+ #define FRSH_MAX_GROUP_OPS 25
+
+ /**
+ * Default overheads of shared object protection mechanisms
+ * These values should be calibrated on each specific execution platform
+ */
+
+ // fixed overhead for saving the environment and subsequently
+ // aborting a critical section; units in nanoseconds
+
+ #define FRSH_SO_FIXED_ABORT_OVHD 0
+
+
+ // fixed overhead for copying a memory area, in nanoseconds
+
+ #define FRSH_SO_FIXED_AREA_OVHD 0
+
+
+ // variable overhead for copying a memory area; units in nanoseconds per kbyte
+
+ #define FRSH_SO_NANOS_PER_KB 0
+
+
+ /* Default memory pool's size in Kbytes */
+ #define FRSH_DYNAMIC_MEMORY_POOL_SIZE 6670
+
+ /**
+ * Maximum synchronized workload period number. After this value any
+ * increments will be set to zero.
+ **/
+ #define FRSH_MAX_SYNCHRONIZED_PERIOD_NUMBER LONG_MAX
+
+
+ /*@}*/
+
+ /*@}*/
+
+ FRSH_CPP_END_DECLS
+
+ #endif /* _FRSH_CONFIGURATION_PARAMETERS_H_ */
+
--- /dev/null
+ // -----------------------------------------------------------------------
+ // Copyright (C) 2006 - 2009 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
+ //
+ // FSF API web pages: http://marte.unican.es/fsf/docs
+ // http://shark.sssup.it/contrib/first/docs/
+ //
+ // This file is part of FRSH (FRescor ScHeduler)
+ //
+ // 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, 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(FRescor ScHeduler), pronounced "fresh"
+ //==============================================
+
+ #ifndef _FRSH_CORE_H_
+ #define _FRSH_CORE_H_
+
+
+ /**
+ * @file frsh_core.h
+ **/
+
+
+ #include <time.h>
+ #include <sys/types.h>
+
+ #include "frsh_core_types.h"
+ #include "frsh_spare_capacity.h"
+
+
+ FRSH_CPP_BEGIN_DECLS
+
+ /**
+ * @defgroup core Core module
+ *
+ * This module includes the basic functions and services that are
+ * provided by any FRSH implementation. This module includes basic type
+ * definitions, and functions to
+ *
+ * - create a contract and initialize it
+ * - set/get the basic parameters of a contract
+ * - negotiate a service contract, obtaining a vres id
+ * - create and bind threads to vres
+ * - create/destroy a synchronization object
+ * - manage bounded workloads
+ *
+ **/
+
+
+ //////////////////////////////////////////////////////////////////////
+ // INITIALIZATION SERVICES
+ //////////////////////////////////////////////////////////////////////
+
+ /**
+ * @defgroup initialization Initialization services
+ * @ingroup core
+ *
+ * These functions need to be called before doing any FRSH operation
+ * (including contract initialization).
+ *
+ * @{
+ **/
+
+
+ /**
+ * frsh_init()
+ *
+ * We cannot call any frsh functions before frsh_init. After calling
+ * frsh_init, the main will be executing in the background. Then, it
+ * can do the negotiations and create new threads if needed. The
+ * second time this function is called it fails.
+ *
+ * @return 0 if no error. \n
+ * FRSH_ERR_SYSTEM_ALREADY_INITIALIZED : if the function has already
+ * been called before\n
+ * .
+ * It may also return any of the errors that may be returned by the
+ * underlying operating system primitives required to perform the
+ * FRSH system start up
+ *
+ **/
+ int frsh_init();
+
+ /**
+ * frsh_destroy()
+ *
+ * Reverts the efect of frsh_init().
+ */
+ void frsh_destroy();
+
+ /*@}*/
+
+
+ /////////////////////////////////////////////////////////////
+ // CONTRACT PARAMETERS
+ /////////////////////////////////////////////////////////////
+ /**
+ * @defgroup contract Contract Creation and Initialization.
+ * @ingroup core
+ *
+ * These functions are used to create and initialize a contract, and
+ * set its parameters.
+ *
+ * @{
+ **/
+
+
+ /**
+ * frsh_contract_init()
+ *
+ * The operation receives a pointer to a contract object
+ * and initializes it, setting it to the default values.
+ *
+ * The default values are:
+ *
+ * - resource_id => 0
+ * - ressource_type => FRSH_CRT_PROCESSOR
+ * - contract_label => ""
+ * - budget_min => {0,0};
+ * - period_max => {0,0};
+ * - budget_max => {0,0};
+ * - period_min => {0,0};
+ * - workload => FRSH_WT_INDETERMINATE
+ * - d_equals_t => true
+ * - contract_type => FRSH_CT_REGULAR;
+ * - deadline => {0,0};
+ * - budget_overrun_signal => 0; (signal number)
+ * - budget_overrun_siginfo => {0, NULL};
+ * - deadline_miss_signal => 0; (signal number)
+ * - deadline_miss_siginfo => {0, NULL};
+ *
+ * - granularity => DEFAULT_GRANULARITY;
+ * - utilization_set; => size = 0
+ * - quality => DEFAULT_QUALITY; (range 0..100)
+ * - importance => DEFAULT_IMPORTANCE; (range 1..5)
+ * - preemption_level => 0; (range 1..2**32-1)
+ * - critical_sections; => size = 0
+ *
+ * - sched_policy => DEFAULT_SCHED_POLICY (FRSH_NONE)
+ *
+ * @param contract the pointer to the contract variable.
+ *
+ * @return 0 if no error \n
+ * FRSH_ERR_BAD_ARGUMENT : contract is NULL
+ *
+ **/
+ int frsh_contract_init(frsh_contract_t *contract);
+
+
+ /**
+ * frsh_contract_destroy()
+ *
+ * The operation deallocates all memory which might be allocated for
+ * the contract.
+ *
+ * @param contract the pointer to the contract variable.
+ **/
+ void frsh_contract_destroy(frsh_contract_t *contract);
+
+
+ /**
+ * frsh_contract_set_basic_params()
+ *
+ * The operation updates the specified contract parameters object by
+ * setting its budget, period, workload and type to the specified
+ * input parameters. (Note: the workload is a basic parameter because
+ * bounded tasks are triggered by the scheduler (see the
+ * frsh_timed_wait() and frsh_synchobj_wait* operations), while
+ * indeterminate tasks are not; therefore, their programming model is
+ * quite different).
+ *
+ * @param contract the pointer to the contract object
+ * @param[in] budget_min the minimum budget for the contract
+ * @param[in] period_max the maximum period for the contract
+ * @param[in] workload the kind of workload (can be FRSH_WT_BOUNDED,
+ * FRSH_WT_INDETERMINATE or FRSH_OVERHEAD)
+ * @param[in] contract_type can be FRSH_CT_REGULAR,
+ * FRSH_CT_BACKGROUND, FRSH_CT_DUMMY.
+ *
+ * @return 0 if no error \n
+ * FRSH_ERR_BAD_ARGUMENT : if any of the pointers is NULL
+ * or if only one of the time values is 0, and also if the
+ * workload or the contract type values are unknown in the
+ * enumerations.
+ **/
+ int frsh_contract_set_basic_params
+ (frsh_contract_t *contract,
+ const frsh_rel_time_t *budget_min,
+ const frsh_rel_time_t *period_max,
+ const frsh_workload_t workload,
+ const frsh_contract_type_t contract_type);
+
+ /**
+ * frsh_contract_get_basic_params()
+ *
+ * This operation obtains from the specified contract object its
+ * budget, period, and workload, and copies them to the places pointed
+ * to by the corresponding output parameters.
+ *
+ * @param[in] contract the pointer to the contract object
+ * @param[out] budget_min pointer to preallocated space
+ * @param[out] period_max pointer to preallocated space
+ * @param[out] workload pointer to preallocated space
+ * @param[out] contract_type pointer to preallocated space
+ *
+ * @return 0 if no error \n
+ * FRSH_ERR_BAD_ARGUMENT : if one of the contract or
+ * pointers is NULL.
+ *
+ **/
+ int frsh_contract_get_basic_params
+ (const frsh_contract_t *contract,
+ frsh_rel_time_t *budget_min,
+ frsh_rel_time_t *period_max,
+ frsh_workload_t *workload,
+ frsh_contract_type_t *contract_type);
+
+ /**
+ * frsh_contract_set_resource_and_label()
+ *
+ * Specify resource_id and type, and the contract label. Otherwise
+ * default values will apply. If the contract label is too long it is truncated
+ *
+ * @return 0 if no error \n
+ * FRSH_ERR_BAD_ARGUMENT : if the contract pointer is NULL.
+ **/
+ int frsh_contract_set_resource_and_label
+ (frsh_contract_t *contract,
+ const frsh_resource_type_t resource_type,
+ const frsh_resource_id_t resource_id,
+ const char *contract_label);
+
+
+ /**
+ * frsh_contract_get_resource_and_label()
+ *
+ * Obtain the resource_id and type, and the contract label.
+ *
+ * @return 0 if no error \n
+ * FRSH_ERR_BAD_ARGUMENT : if the contract or the contract_label
+ * pointer is NULL.
+ **/
+ int frsh_contract_get_resource_and_label
+ (const frsh_contract_t *contract,
+ frsh_resource_type_t *resource_type,
+ frsh_resource_id_t *resource_id,
+ char *contract_label);
+
+
+ /**
+ * frsh_contract_set_timing_reqs()
+ *
+ * The operation updates the specified contract object, specifying
+ * additional time-related requirements.
+ *
+ * @param contract The pointer to the contract object
+ *
+ * @param [in] d_equals_t It is a boolean value, set to true (1) if
+ * we want to specify a deadline different from
+ * the period for the contract.
+ * @param [in] deadline If the previous parameter is set to true,
+ * this parameter is ignored (the contract value
+ * will be NULL_DEADLINE internally). Otherwise, it
+ * contains the desired deadline value.
+ *
+ * @return 0 if successful\n
+ * FRSH_ERR_BAD_ARGUMENT : if contract is NULL \b or \n
+ * (d_equals_t is true and deadline is not FRSH_NULL_DEADLINE) \b or \n
+ * (budget_overrun_signal is not a valid signal) \b or \n
+ * (deadline_miss_signal is not a valid signal) \b or \n
+ * (d_equals_t is false but (deadline is FRSH_NULL_DEADLINE or its value
+ * is grater than the contract's maximum period))
+ *
+ **/
+ int frsh_contract_set_timing_reqs
+ (frsh_contract_t *contract,
+ const bool d_equals_t,
+ const frsh_rel_time_t *deadline);
+
+ /**
+ * frsh_contract_get_timing_reqs()
+ *
+ * The operation obtains the corresponding input parameters from the
+ * specified contract object. If d_equals_t is true, the deadline will
+ * be set to FRSH_NULL_DEADLINE.
+ *
+ * @return 0 if no error \n
+ * FRSH_ERR_BAD_ARGUMENT : if contract is NULL
+ *
+ **/
+ int frsh_contract_get_timing_reqs
+ (const frsh_contract_t *contract,
+ bool *d_equals_t,
+ frsh_rel_time_t *deadline);
+
+
+ /*@}*/
+
+ //////////////////////////////////////////////////////////////////
+ // SYNCHRONIZATION OBJECTS
+ //////////////////////////////////////////////////////////////////
+ /**
+ * @defgroup synch Synchronization objects
+ * @ingroup core
+ *
+ * Synchronisation objects provide an alternative to timers for
+ * bounded-workload vres to signal the end of their current job and
+ * return their remaining budget to FRSH.
+ *
+ * Instead of asking to be reactivated based on an absolute time, they
+ * queue themselves in a synchronisation object and will wait there
+ * until another vres (bounded-workload or indeterminate-workload)
+ * wakes them up with a signal call the earliest at the beginning of
+ * the next period.
+ *
+ * Indeterminate-workload vres cannot queue themselves here because
+ * they don't have any budget to return. However they can signal on
+ * the objects to activate a waiting workload vres.
+ *
+ * For classical signal/wait synchronisation paradigms the application
+ * must use whatever mechanism the underlying OS provides.
+ *
+ * In the future we may add a broadcast operation that would signal a
+ * group of synchronization objects. We have not included a broadcast
+ * service in this version because it can be easily created by the
+ * user by signalling individual synchronization objects inside a
+ * loop.
+ *
+ * Notice that for synchronization objects there is no naming service
+ * like in shared objects because tasks that use synchronization are
+ * not developed independently, as they are closely coupled.
+ *
+ * @{
+ **/
+
+
+ /**
+ * frsh_synchobj_create()
+ *
+ * This operation creates and initializes a synchronization object
+ * variable managed by the scheduler, and returns a handle to it in
+ * the variable pointed to by synch_handle.
+ *
+ * @param[out] synch_handle pointer to the variable that will contain
+ * the handle to the newly created synchronization object
+ *
+ * @return 0 if the operation is succesful
+ * FRSH_ERR_TOO_MANY_SYNCH_OBJS if the number of synchronization
+ * objects in the system has already exceeded the maximum
+ *
+ * FRSH_ERR_TOO_MANY_SYNCH_OBJS : if the number of synchronization
+ * objects in the system has already exceeded the maximum\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
+ *
+ **/
+ int frsh_synchobj_create
+ (frsh_synchobj_handle_t *synch_handle);
+
+
+ /**
+ * frsh_synchobj_destroy()
+ *
+ * This operation destroys the synchronization object (created by a
+ * previous call to frsh_synchobj_create) that is referenced by the
+ * synch_handle variable. After calling this operation, the
+ * synch_handle variable can not be used until it is initialized again
+ * by a call to frsh_synchobj_create.
+ *
+ * @param synch_handle the handle to the synchronization object
+ * to be destroyed
+ *
+ * @return 0 if no error \n
+ * FRSH_ERR_BAD_ARGUMENT : if synch_handle is 0\n
+ * FRSH_ERR_INVALID_SYNCH_OBJ_HANDLE if the handle is not valid\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
+ *
+ * @sa frsh_synchobj_create
+ **/
+ int frsh_synchobj_destroy
+ (const frsh_synchobj_handle_t synchobj_handle);
+
+ /**
+ * frsh_synchobj_wait()
+ *
+ * This operation is invoked by threads associated with bounded
+ * workload vres to indicate that a job has been completed (and
+ * that the scheduler may reassign the unused capacity of the current
+ * job to other vres).
+ *
+ * As a difference with frsh_timed_wait(), here the vres
+ * specifies to be awakened by the arrival of a signal operation
+ * instead of at a precise point of time.
+ *
+ * This function can also be called to schedule the first job of a
+ * recently created vres and make it start when a signal operation
+ * has been sent from another thread.
+ *
+ * The vres' budget will be made zero for the remainder of the vres'
+ * period, and FRSH will not replenish it until an event has been
+ * notified to the synchronisation object by another vres.
+ *
+ * It can happen that the synchronisation object has notification
+ * events queued from the past, in this case one of the events is
+ * dequeued immediately and the vres won't have to wait for another
+ * one.
+ *
+ * At the time of reception of a notification event (wether in the
+ * future or in the past), all pending budget replenishments (if any)
+ * are made effective. Once the vres has a positive budget and the
+ * scheduler schedules the calling thread again, the call returns and
+ * the vres continues executing.
+ *
+ * If the synchronisation object is destroyed while the vres was
+ * waiting on it, the vres will be awaken and the function will
+ * return with a code FRSH_ERR_INVALID_SYNCH_OBJ_HANDLE
+ *
+ * Except for those parameters equal to NULL pointers, the system
+ * reports the current period and budget for the current job, it informs
+ * if the deadline of the previous job was missed or not, and whether the
+ * budget of the previous job was overrun or not.
+ *
+ * In a system with hierarchical scheduling, since this call makes the
+ * budget of the current period zero, the other threads in the same
+ * vres are not run. As mentioned above, only when the call finishes
+ * the budget may be replenished.
+ *
+ * @param synch_handle Synchronisation object upon which the vres
+ * will be waiting.
+ * @param next_budget[out] Upon return of this function, the variable
+ * pointed by this function will be equal to
+ * the current vres budget. If this parameter is
+ * set to NULL, no action is taken
+ * @param next_period[out] The vres period upon return (ignored if NULL).
+ * @param was_deadline_missed Upon return whether the deadline was
+ * missed in the previous period.
+ * @param was_budget_overran
+ *
+ *
+ * @return 0 if success \n
+ * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not
+ * running \n
+ * FRSH_ERR_INTERNAL_ERROR : erroneous binding or malfunction of the FRSH
+ * main scheduler \n
+ * FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not scheduled
+ * under FRSH \n
+ * FRSH_ERR_NOT_BOUND : if the calling thread does not have a valid
+ * vres bound to it \n
+ * FRSH_ERR_BAD_ARGUMENT : if synch_handle is 0 \n
+ * FRSH_ERR_INVALID_SYNCH_OBJ_HANDLE if the synch_handle is not
+ * valid or was destroyed while the vres was waiting on it. \n
+ * FRSH_ERR_VRES_WORKLOAD_NOT_COMPATIBLE: if the kind of workload of the vres
+ * is not FRSH_BOUNDED
+ *
+ **/
+ int frsh_synchobj_wait
+ (const frsh_synchobj_handle_t synch_handle,
+ frsh_rel_time_t *next_budget,
+ frsh_rel_time_t *next_period,
+ bool *was_deadline_missed,
+ bool *was_budget_overran);
+
+
+ /**
+ * frsh_synchobj_wait_with_timeout()
+ *
+ * This call is the same as frsh_synchobj_wait() but with an extra
+ * absolute timeout. The timed_out argument, indicates whether the
+ * function returned because of the expiration of the timeout or not.
+ *
+ * @return 0 if no error \n
+ * FRSH_ERR_INVALID_SYNCH_OBJ_HANDLE if the synch_handle is not
+ * valid \n
+ * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not
+ * running \n
+ * FRSH_ERR_INTERNAL_ERROR : erroneous binding or malfunction of the FRSH
+ * main scheduler \n
+ * FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not scheduled
+ * under FRSH \n
+ * FRSH_ERR_NOT_BOUND : if the calling thread does not have a valid
+ * vres bound to it \n
+ * FRSH_ERR_BAD_ARGUMENT : if the synch_handle given is not valid or the
+ * abs_timeout argument is NULL or its value is in the past\n
+ * FRSH_ERR_VRES_WORKLOAD_NOT_COMPATIBLE: if the kind of workload of the vres
+ * is not FRSH_BOUNDED
+ *
+ **/
+ int frsh_synchobj_wait_with_timeout
+ (const frsh_synchobj_handle_t synch_handle,
+ const frsh_abs_time_t *abs_timeout,
+ bool *timed_out,
+ frsh_rel_time_t *next_budget,
+ frsh_rel_time_t *next_period,
+ bool *was_deadline_missed,
+ bool *was_budget_overran);
+
+ /**
+ * frsh_synchobj_signal()
+ *
+ * This function sends a notification event to the synchronization object
+ * specified as parameter. If there is at least one vres waiting on
+ * the synchronization object, it is awaken. If more than one vres
+ * are waiting, just one of them is awaken. However, which one is
+ * awaken is implementation dependent. If no vres is waiting on the
+ * synchronization object, the notification event is queued.
+ *
+ * @param [in] synch_handle the handle of the synchronization object to
+ * notify.
+ *
+ * @return 0 if no error \n
+ * FRSH_ERR_BAD_ARGUMENT : if synch_handle is 0 \n
+ * FRSH_ERR_INVALID_SYNCH_OBJ_HANDLE if the handle is not valid \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_TOO_MANY_EVENTS_IN_SYNCH_OBJ : if the number of events stored
+ * in the synchronization object reaches the maximum defined in the
+ * configuration parameter header file
+ *
+ * @sa frsh_synchobj_wait, frsh_synchobj_wait_with_timeout
+ **/
+ int frsh_synchobj_signal
+ (const frsh_synchobj_handle_t synch_handle);
+
+ /**
+ * frsh_timed_wait()
+ *
+ * This operation is invoked by threads associated with bounded
+ * workload vres to indicate that a job has been completed (and
+ * that the scheduler may reassign the unused capacity of the current
+ * job to other vres). It is also invoked when the first job of
+ * such threads has to be scheduled.
+ *
+ * As an effect, the system will make the current vres's budget zero
+ * for the remainder of the vres's period, and will not replenish
+ * the budget until the specified absolute time. At that time, all
+ * pending budget replenishments (if any) are made effective. Once the
+ * vres has a positive budget and the scheduler schedules the
+ * calling thread again, the call returns and at that time, except for
+ * those parameters equal to NULL pointers, the system reports the
+ * current period and budget for the current job, whether the deadline
+ * of the previous job was missed or not, and whether the budget of
+ * the previous job was overrun or not.
+ *
+ * In a system with hierarchical scheduling, since this call makes the
+ * budget zero, the other threads in the same vres are not run. As
+ * mentioned abobe, only when the call finishes the budget may be
+ * replenished.
+ *
+ * @param [in] abs_time absolute time at which the budget will be
+ * replenished
+ *
+ * @param [out] next_budget upon return of this function, the variable
+ * pointed by this function will be equal to
+ * the current vres budget. If this parameter is
+ * set to NULL, no action is taken.
+ *
+ * @param [out] next_period upon return of this function, the variable
+ * pointed by this function will be equal to
+ * the current vres period. If this parameter is
+ * set to NULL, no action is taken.
+ *
+ * @param [out] was_deadline_missed upon return of this function, the
+ * variable pointed by this function will be
+ * equal to true if the previous vres deadline
+ * was missed, to false otherwise. If this
+ * parameter is set to NULL, no action is
+ * taken.
+ *
+ * @param [out] was_budget_overrun upon return of this function, the
+ * variable pointed by this function will be
+ * equal to true if the previous vres budget was
+ * overrun, to false otherwise. If this
+ * parameter is set to NULL, no action is
+ * taken.
+ *
+ * @return 0 if the operation is successful \n
+ * FRSH_ERR_TIME_SPEC_IN_THE_PAST if the absolute time specification
+ * is in the past. \n
+ * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong
+ * or not running \n
+ * FRSH_ERR_INTERNAL_ERROR : erroneous binding or malfunction of the FRSH
+ * main scheduler \n
+ * FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling
+ * thread is not scheduled under FRSH \n
+ * FRSH_ERR_NOT_BOUND : if the calling thread does not have a valid
+ * vres bound to it \n
+ * FRSH_ERR_BAD_ARGUMENT : if abs_time is NULL \n
+ * FRSH_ERR_VRES_WORKLOAD_NOT_COMPATIBLE: if the kind of workload of the vres
+ * is not FRSH_BOUNDED
+ *
+ *
+ * @sa frsh_synchobj_wait, frsh_synchobj_wait_with_timeout
+ **/
+ int frsh_timed_wait
+ (const frsh_abs_time_t *abs_time,
+ frsh_rel_time_t *next_budget,
+ frsh_rel_time_t *next_period,
+ bool *was_deadline_missed,
+ bool *was_budget_overran);
+
+
+
+ /**
+ * frsh_vresperiod_wait()
+ *
+ * Suspend the calling thread until the start of the specified virtual
+ * resource period of a vres_id, for a synchronized workload.
+ *
+ * Virtual resource periods are numbered. The number of the current
+ * period can be obtained through the frsh_vres_get_period_number()
+ * operation.
+ **/
+ int frsh_vresperiod_wait(unsigned long period_num,
+ frsh_rel_time_t *next_budget,
+ frsh_rel_time_t *next_period,
+ bool *was_deadline_missed,
+ bool *was_budget_overran);
+
+
+ /**
+ * frsh_vres_get_period()
+ *
+ * Return the current period number, for a virtual resource of
+ * synchronized workload.
+ **/
+ int frsh_vres_get_period_number
+ (const frsh_vres_id_t vres,
+ long *period_num);
+
+
+
+
+ /*@}*/
+
+ ///////////////////////////////////////////////////////////////////
+ // CONTRACT NEGOCIATION OPERATIONS
+ ///////////////////////////////////////////////////////////////////
+
+ /**
+ * @defgroup negotiate Negotiate contract functions
+ * @ingroup core
+ *
+ * The following functions are used to negotiate contracts and thus
+ * creating vres which are the execution image of a contract.
+ * Besides, these functions allow to assign and unassign threads to
+ * vres.
+ *
+ * In the case of more than one thread per vres please refer to the
+ * hierarchical module.
+ *
+ * @{
+ **/
+
+
+
+ /**
+ * frsh_contract_negotiate()
+ *
+ * The operation negotiates a contract and if accepted it will return
+ * a vres_id. It will also check that the given contract_label is unique
+ * within the node.
+ *
+ * If the on-line admission test is enabled, it determines whether the
+ * contract can be admitted or not based on the current contracts
+ * established in the system. Then it creates the vres and
+ * recalculates all necessary parameters for the contracts already
+ * present in the system.
+ *
+ * This is a potentially blocking operation, it returns when the
+ * system has either rejected the contract, or admitted it and made it
+ * effective. No thread is bound to the newly created vres, which
+ * will be idle until a thread is bound to it via frsh_thread_bind()
+ * or frsh_thread_create_and_bind().
+ *
+ * This operation can only be executed by threads that are already
+ * bound to an active vres and therefore are being scheduled by the
+ * frsh scheduler.
+ *
+ * @return 0 if successful \n
+ * FRSH_ERR_CONTRACT_REJECTED: The contract is not accepted.\n
+ * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not
+ * running \n
+ * FRSH_ERR_INTERNAL_ERROR : erroneous binding or malfunction of the FRSH
+ * main scheduler \n
+ * FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not scheduled
+ * under FRSH scheduler \n
+ * FRSH_ERR_BAD_ARGUMENT : if the contract or vres arguments are NULL \n
+ * FRSH_ERR_TOO_MANY_VRES : if there is no space for more vres
+ * (the maximum number of them is already reached) \n
+ * FRSH_ERR_CONTRACT_LABEL_ALREADY_EXISTS : contract_label is not unique.
+ *
+ **/
+ int frsh_contract_negotiate
+ (const frsh_contract_t *contract,
+ frsh_vres_id_t *vres);
+
+ /**
+ * frsh_thread_create_and_bind()
+ *
+ * This operation creates a thread and binds it to an existing vres.
+ *
+ * This is the preferred way to add threads to the application because
+ * we make sure that the thread won't become unbound.
+ *
+ * The vres must not have any thread binded to it. If you want to
+ * bind more than one thread to the vres you must use the
+ * hierarchical module.
+ *
+ * The frsh_thread_attr_t parameter is overwritten as necessary to
+ * introduce the adequate scheduling policy and priority, according
+ * to the preemption level given in the contract and the
+ * frsh_priority_map() function defined by the user.
+ *
+ * @param[in] vres_id vres with which the thread will be bound.
+ * @param[out] thread frsh_thread_id returned by the system.
+ * @param attr pthread_attr taken and maybe corrected
+ * by the system. Ignored if NULL
+ * @param[in] thread_code Thread function (void func(void *) )
+ * that will constitute the main of the
+ * thread.
+ * @param[in] arg Argument for data to be passed at the
+ * thread. Set to NUL if you don't want
+ * to do anything like this.
+ *
+ * @return 0 if successful \n
+ * FRSH_ERR_BAD_ARGUMENT : if the contract or vres arguments are
+ * NULL \n
+ * FRSH_ERR_CONTRACT_REJECTED : if the contract is rejected. \n
+ * .
+ * It may also return all the errors that may be returned by the
+ * fosa_thread_create() function call
+ *
+ **/
+ int frsh_thread_create_and_bind
+ (const frsh_vres_id_t vres,
+ frsh_thread_id_t *thread,
+ frsh_thread_attr_t *attr,
+ frsh_thread_code_t thread_code,
+ void *arg);
+
+
+ /**
+ * frsh_thread_create_in_background()
+ *
+ * This function creates a "background contract" that does not need to
+ * be negotiated, creates a threads and binds to the new vres.
+ *
+ * This method is suggested as a way to initate components and
+ * plugins. The event that triggers the component activation should
+ * arrive to an application thread that could use this function to
+ * create a thread used in its initialisation.
+ *
+ * The attribute parameter is overwritten as necessary to introduce
+ * the adequate scheduling policy and priority.
+ *
+ * @param[in] thread_code Function to be executed by the new
+ * thread.
+ * @param[in] thread_arg General pointer that will be passed to
+ * the new thread as initialisation data.
+ * @param attr Pthread attribute with thread params
+ * @param[in] contract_label Contract label for the new vres.
+ * @param[out] thread_id Id of the new thread.
+ * @param[out] vres_id vres_id of the new vres.
+ *
+ * @return 0 if successful \n
+ * FRSH_ERR_BAD_ARGUMENT : Any problems with the argument \n
+ * FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is
+ * not scheduled under FRSH \n
+ * FRSH_ERR_CONTRACT_LABEL_ALREADY_EXISTS : contract_label is not unique \n
+ * FRSH_ERR_TOO_MANY_VRES : if there is no space for more vres
+ * (the maximum number of them is already reached)
+ *
+ **/
+ int frsh_thread_create_in_background
+ (frsh_thread_code_t thread_code,
+ const void *thread_arg,
+ const char *contract_label,
+ frsh_thread_attr_t *attr,
+ frsh_thread_id_t *thread_id,
+ frsh_vres_id_t *vres_id);
+
+
+
+ /**
+ * frsh_thread_join_in_background()
+ *
+ * This function is aimed for external threads to join FRSH in the
+ * least disturbing possible mode.
+ *
+ * Upon calling this function by a thread which has been created
+ * natively in the OS, it joins the framework and gets inmediately
+ * bound to an on-the-fly generated background contract.
+ *
+ * In order to gain a higher priority then it can renegotiate a
+ * contract for its vres with the needed parameters.
+ *
+ * @param[in] resource_id: Resource (CPU) in which the vres will
+ * be associated.
+ *
+ * @param[in] resource_type: Resource type (should be CPU) for the
+ * contract.
+ *
+ * @param[in] label: Label to be added to the contract.
+ *
+ * @param[out] vres_id: Resulting vres_id from the on-the-fly
+ * generated background contract.
+ *
+ * @return 0 if successful\n
+ * FRSH_ERR_NOT_CONTRACTED_VRES if the thread is already
+ * bound to a vres.
+ **/
+ int frsh_thread_join_in_background(frsh_resource_id_t resource_id,
+ frsh_resource_type_t resource_type,
+ const char *label,
+ frsh_vres_id_t *vres_id);
+
+
+
+ /**
+ * frsh_thread_bind()
+ *
+ * This operation associates a thread with a vres, which means that
+ * it starts consuming the vres's budget and is executed according
+ * to the contract established for that vres. If the thread is
+ * already bound to another vres, it is effectively unbound from it
+ * and bound to the specified one.
+ *
+ * It fails if the vres's policy is different than FRSH_NONE, or if
+ * there is already a thread bound to this vres. In order to bind
+ * more than one vres to the same thread you must use the
+ * hierarchical module.
+ *
+ * Implementation dependent issue: In order to allow the usage of
+ * application defined schedulers, the given thread must not have the
+ * scheduling policy SCHED_APP and at the same time be attached to an
+ * application scheduler different than the frsh scheduler.
+ *
+ * @return 0 if successful \n
+ * FRSH_ERR_INTERNAL_ERROR : erroneous binding or malfunction of the FRSH
+ * main scheduler \n
+ * FRSH_ERR_UNKNOWN_APPSCHEDULED_THREAD : if the thread is attached to
+ * an application defined scheduler different than the frsh
+ * scheduler \n
+ * FRSH_ERR_BAD_ARGUMENT : if the vres value does not complain with the
+ * expected format or valid range or the given thread does not
+ * exist \n
+ * FRSH_ERR_NOT_CONTRACTED_VRES : if the referenced vres is not
+ * valid \n
+ * FRSH_ERR_VRES_WORKLOAD_NOT_COMPATIBLE: if the kind of workload
+ * of the vres is FRSH_OVERHEAD \n
+ * FRSH_ERR_ALREADY_BOUND : if the given vres has a thread already
+ * bound
+ *
+ **/
+ int frsh_thread_bind
+ (const frsh_vres_id_t vres,
+ const frsh_thread_id_t thread);
+
+
+ /**
+ * frsh_thread_unbind()
+ *
+ * This operation unbinds a thread from a vres. Since threads with
+ * no vres associated are not allowed to execute, they remain in a
+ * dormant state until they are either eliminated or bound again.
+ *
+ * If the thread is inside a critical section the effects of this call
+ * are deferred until the critical section is ended
+ *
+ * Implementation dependent issue: in the implementation with an
+ * application scheduler, the thread is still attached to the frsh
+ * scheduler, but suspended.
+ *
+ * @return 0 if successful \n
+ * FRSH_ERR_INTERNAL_ERROR : erroneous binding or malfunction of the FRSH
+ * main scheduler \n
+ * FRSH_ERR_BAD_ARGUMENT : if the given thread does not exist \n
+ * FRSH_ERR_NOT_SCHEDULED_THREAD : if the given thread is not scheduled
+ * under FRSH \n
+ * FRSH_ERR_UNKNOWN_APPSCHEDULED_THREAD : if the thread is attached to
+ * an application defined scheduler different than the frsh
+ * scheduler \n
+ * FRSH_ERR_NOT_BOUND : if the given thread does not have a valid
+ * vres bound to it
+ **/
+ int frsh_thread_unbind(const frsh_thread_id_t thread);
+
+ /**
+ * frsh_vres_set_notification()
+ *
+ * This function setups notification signals for CPU vres. It is
+ * necessary to call this function before bounding the thread to the
+ * vres.
+ *
+ * @param [in] budget_overrun_signal contains the number of the signal
+ * that must be raised if the budget of the vres is
+ * overrun by the thread.
+ * If the value of this parameter is FRSH_NULL_SIGNAL, no signal will
+ * be raised.
+ * @param [in] budget_overrun_siginfo contains the value that will be
+ * passed to the signal "catcher" when the signal is raised.
+ * This parameters is not used if the budget_overrun_signal
+ * parameter is set to FRSH_NULL_SIGNAL.
+ * @param [in] deadline_miss_signal contains the number of the
+ * signal that must be raised if the deadline of the
+ * vres is missed. If the value of this parameter is
+ * FRSH_NULL_SIGNAL, no signal is raised.
+ * @param [in] deadline_miss_siginfo contains the value that will be
+ * passed to the signal "catcher" when the signal is
+ * raised. This parameter is not used if the
+ * deadline_signal parameter is set to NULL_SIGNAL
+ **/
+ int frsh_vres_set_notification(
+ frsh_vres_id_t vres,
+ const frsh_signal_t budget_overrun_signal,
+ const frsh_signal_info_t budget_overrun_siginfo,
+ const frsh_signal_t deadline_miss_signal,
+ const frsh_signal_info_t deadline_miss_siginfo);
+
+ /**
+ * frsh_thread_get_vres_id()
+ *
+ * This operation stores the Id of the vres associated with the
+ * specified thread in the variable pointed to by vres. It returns
+ * an error if the thread does not exist, it is not under the control
+ * of the scheduling framework, or is not bound.
+ *
+ * @return 0 if no error \n
+ * FRSH_ERR_NOT_SCHEDULED_THREAD : if the given thread is not scheduled
+ * under FRSH \n
+ * FRSH_ERR_NOT_BOUND : if the given thread does not have a valid
+ * vres bound to it \n
+ * FRSH_ERR_BAD_ARGUMENT : if the given thread does not exist or the
+ * vres argument is NULL
+ *
+ **/
+ int frsh_thread_get_vres_id(const frsh_thread_id_t thread,
+ frsh_vres_id_t *vres_id);
+
+ /**
+ * frsh_vres_get_priority()
+ *
+ * This operation stores the priority currently associated
+ * with the specified vres in the variable pointed to by
+ * priority. It returns an error if the vres_id is not recognised.
+ *
+ * @return 0 if no error \n
+ * FRSH_ERR_BAD_ARGUMENT : if the contract argument is NULL or the value
+ * of the vres argument is not in range \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 of the calling thread
+ * has been cancelled or it is not valid
+ *
+ **/
+ int frsh_vres_get_priority
+ (frsh_vres_id_t vres_id,
+ int *priority);
+
+ /**
+ * frsh_vres_get_contract()
+ *
+ * This operation stores the contract parameters currently associated
+ * with the specified vres in the variable pointed to by
+ * contract. It returns an error if the vres_id is not recognised.
+ *
+ * @return 0 if no error \n
+ * FRSH_ERR_BAD_ARGUMENT : if the contract argument is NULL or the value
+ * of the vres argument is not in range \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 of the calling thread
+ * has been cancelled or it is not valid
+ *
+ **/
+ int frsh_vres_get_contract
+ (const frsh_vres_id_t vres,
+ frsh_contract_t *contract);
+
+ /**
+ * frsh_resource_get_vres_from_label()
+ *
+ * This operation retrieves the vres_id whose contract_label
+ * corresponds to the parameter in the resource_id and resource_type
+ * specified.
+ *
+ * The contract label must refer to a contract negotiated
+ * in the same processing node in which the call is being
+ * made. Otherwise an error is returned.
+ *
+ * @return 0 if no error \n
+ * FRSH_ERR_BAD_ARGUMENT : if the contract argument is NULL or the
+ * contract_label 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_CONTRACT_LABEL_UNKNOWN: if the contract_label is not known
+ **/
+ int frsh_resource_get_vres_from_label
+ (const char *contract_label,
+ const frsh_resource_type_t resource_type,
+ const frsh_resource_id_t resource_id,
+ frsh_vres_id_t *vres);
+
+
+
+ /**
+ * frsh_contract_cancel()
+ *
+ * The operation eliminates the specified vres
+ * and recalculates all necessary parameters for the contracts
+ * remaining in the system. This is a potentially blocking operation;
+ * it returns when the system has made the changes effective.
+ *
+ * Note that the thread is not eliminated. We leave the application
+ * the option to either freeze it for a later use or bind it to
+ * another vres.
+ *
+ * @return 0 if successful \n
+ * FRSH_ERR_BAD_ARGUMENT : if the value of vres is not in range \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 of the calling thread
+ * has been cancelled or it is not valid
+ *
+ **/
+ int frsh_contract_cancel (const frsh_vres_id_t vres);
+
+
+ /**
+ * frsh_contract_renegotiate_sync()
+ *
+ * The operation renegotiates a contract for an existing vres. If
+ * the on-line admission test is enabled it determines whether the
+ * contract can be admitted or not based on the current contracts
+ * established in the system. If it cannot be admitted, the old
+ * contract remains in effect and an error is returned. If it can be
+ * admitted, it recalculates all necessary parameters for the
+ * contracts already present in the system and returns zero. This is a
+ * potentially blocking operation; it returns when the system has
+ * either rejected the new contract, or admitted it and made it
+ * effective.
+ *
+ * @return 0 if successful \n
+ * FRSH_ERR_BAD_ARGUMENT : if the new_contract argument is NULL or the
+ * value of the vres argument is not in range \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 of the calling thread
+ * has been cancelled or it is not valid \n
+ * FRSH_ERR_CONTRACT_REJECTED : if the renegotiation fails
+ *
+ **/
+ int frsh_contract_renegotiate_sync
+ (const frsh_contract_t *new_contract,
+ const frsh_vres_id_t vres);
+
+
+ /**
+ * frsh_contract_renegotiate_async()
+ *
+ * The operation enqueues a renegotiate operation for an existing
+ * vres, and returns immediately. The renegotiate operation is
+ * performed asynchronously, as soon as it is practical; meanwhile the
+ * system operation will continue normally. When the renegotiation is
+ * made, if the on-line admission test is enabled it determines
+ * whether the contract can be admitted or not based on the current
+ * contracts established in the system. If it cannot be admitted, the
+ * old contract remains in effect. If it can be admitted, it
+ * recalculates all necessary parameters for the contracts already
+ * present in the system.
+ *
+ * When the operation is completed, notification is made to the
+ * caller, if requested, via a signal. The status of the operation (in
+ * progress, admitted, rejected) can be checked with the
+ * frsh_vres_get_renegotiation_status() operation. The argument
+ * sig_notify can be FRSH_NULL_SIGNAL (no notification), or any FRSH
+ * signal value and in this case signal_info is to be sent with the signal.
+ *
+ * @param[in] new_contract New contract parameters for the new
+ * situation if approved.
+ * @param[in] vres vres_id on which to do the renegotiation.
+ * @param[in] signal_to_notify Signal number to use to notify vres of
+ * the negotiation result. If
+ * FRSH_NULL_SIGNAL, no signal will be raised.
+ * @param[in] signal_info: Associated info that will come with the
+ * signal. This parameter will be ignored
+ * if signal_to_notify == FRSH_NULL_SIGNAL.
+ *
+ * @return 0 if no error \n
+ * FRSH_ERR_BAD_ARGUMENT : if the new_contract argument is NULL, the
+ * value of the vres argument is not in range or sig_notify is
+ * neither NULL nor a valid POSIX signal \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 of the calling thread
+ * has been cancelled or it is not valid
+ *
+ **/
+ int frsh_contract_renegotiate_async
+ (const frsh_contract_t *new_contract,
+ const frsh_vres_id_t vres,
+ const frsh_signal_t signal_to_notify,
+ const frsh_signal_info_t signal_info);
+
+
+ /**
+ * frsh_vres_get_renegotiation_status()
+ *
+ * The operation reports on the status of the last renegotiation
+ * operation enqueued for the specified vres. It is callable even
+ * after notification of the completion of such operation, if
+ * requested.
+ *
+ * If the vres is not and has not been involved in any of the
+ * frsh_contract_renegotiate_async() or frsh_group_change_mode_async()
+ * operations, the status returned is FRSH_RS_NOT_REQUESTED
+ *
+ * @return 0 if no error \n
+ * FRSH_ERR_BAD_ARGUMENT : if the renegotiation_status argument is
+ * NULL or the value of the vres argument is not in range \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 of the calling thread
+ * has been cancelled or it is not valid
+ *
+ **/
+ int frsh_vres_get_renegotiation_status
+ (const frsh_vres_id_t vres,
+ frsh_renegotiation_status_t *renegotiation_status);
+
+ /*@}*/
+
+ ////////////////////////////////////////////////////////////////////////
+ // CHANGE OF MODE: GROUPS OF CONTRACTS
+ ////////////////////////////////////////////////////////////////////////
+ /**
+ * @defgroup groupofcontracts Group of contracts
+ * @ingroup core
+ *
+ * The following functions are used to negotiate atomically more than
+ * one contract. This allows to build complex applications by
+ * splitting them in individual contracts that are negotiated
+ * simultaneously and atomically.
+ *
+ * @{
+ **/
+
+ /**
+ * frsh_group_change_mode_sync()
+ *
+ * This function performs a set of negotiation operations which can
+ * include: adding new contracts (neg), modifying existing vres (reneg)
+ * or cancelling existing vres (cancel).
+ *
+ * If one of the group operations has a NULL value, unless it causes an
+ * inconsistency the system will suppose that no operation of that
+ * type (neg, reneg or cancel) should be done.
+ *
+ * The virtual resources resulting from negotiations of new contracts are
+ * returned in the parameter 'new_vres' which must be provided by the user.
+ *
+ * If the on-line admission test is enabled, FRSH analizes the
+ * schedulability of the context that would result in the new
+ * contract situation with removed, changed and added contracts.
+ *
+ * A successful return code will mean that all contracts have been
+ * accepted and all required operations (creation, cancellation or
+ * update of vres) have been carried out to reach the new running
+ * context.
+ *
+ * If any of the contracts is not accepted a corresponding error shall be
+ * returned and no changes will be made to the previously running context.
+ *
+ * This call is a synchronous, potentially blocking operation. It
+ * returns when the system has rejected the contracts or accepted
+ * and made them effective.
+ *
+ * @param[in] contracts_to_neg List of new contracts to negotiate
+ * @param[in] contracts_to_reneg List of contracts to renegotiate
+ * @param[in] vres_to_reneg List of vres to renegotiate
+ * @param[in] vres_to_cancel List of vres to cancel
+ * @param[out] new_vres List of vres of new contracts.
+ *
+ * @return 0 if no error \n
+ * FRSH_ERR_BAD_ARGUMENT Invalid pointer or group identifier. \n
+ * FRSH_ERR_CONTRACT_LABEL_ALREADY_EXISTS contract_label not unique. \n
+ * FRSH_ERR_NOT_CONTRACTED_VRES: One of the provided vres_ids
+ * is not recognised. \n
+ * FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD The calling thread
+ * is not scheduled under FRSH. \n
+ * FRSH_ERR_INVALID_SCHEDULER_REPLY: The scheduler is wrong or
+ * not running. \n
+ * FRSH_ERR_INTERNAL_ERROR: Erroneous binding or malfunction of
+ * FRSH main scheduler. \n
+ * FRSH_ERR_REJECTED_CONTRACT: The negotiation of one of the
+ * proposed contracts has failed.
+ **/
+ int frsh_group_change_mode_sync
+ (const frsh_contracts_group_t *contracts_to_neg,
+ const frsh_contracts_group_t *contracts_to_reneg,
+ const frsh_vres_group_t *vres_to_reneg,
+ const frsh_vres_group_t *vres_to_cancel,
+ frsh_vres_group_t *new_vres);
+
+ /**
+ * frsh_group_change_mode_async()
+ *
+ * This is an asynchronous (non-blocking) version of the previous function,
+ * frsh_group_change_mode_sync() and thus, it returns inmediately.
+ *
+ * The status of the change of mode and the identifiers for new virtual
+ * resources must be requested with the function 'frsh_group_get_status'
+ * by using the return parameter 'group'.
+ *
+ * As in the asynchronous renegotiations, when the operation is completed,
+ * the user is notified with a signal so he can check the final result with
+ * 'frsh_group_get_status'. In case that FRSH_NULL_SIGNAL is used, no
+ * signal will be sent to the user.
+ *
+ * @param[in] contracts_to_neg List of new contracts to negotiate
+ * @param[in] contracts_to_reneg List of contracts to renegotiate
+ * @param[in] vres_to_reneg List of vres to renegotiate
+ * @param[in] vres_to_cancel List of vres to cancel
+ * @param[in] signal Signal number to notify completion of
+ * the change of mode. If FRSH_NULL_SIGNAL,
+ * no signal will be raised.
+ * @param[in] signal_info Data associated to the signal
+ * @param[out] group The group identifier to get the status
+ *
+ * @return 0 if no error \n
+ * FRSH_ERR_BAD_ARGUMENT Invalid pointer, signal or group identifier. \n
+ * FRSH_ERR_CONTRACT_LABEL_ALREADY_EXISTS contract_label not unique. \n
+ * FRSH_ERR_NOT_CONTRACTED_VRES: One of the provided vres_ids
+ * is not recognised. \n
+ * FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD The calling thread
+ * is not scheduled under FRSH. \n
+ * FRSH_ERR_INVALID_SCHEDULER_REPLY: The scheduler is wrong or
+ * not running. \n
+ * FRSH_ERR_INTERNAL_ERROR: Erroneous binding or malfunction of
+ * FRSH main scheduler.
+ **/
+ int frsh_group_change_mode_async
+ (const frsh_contracts_group_t *contracts_to_neg,
+ const frsh_contracts_group_t *contracts_to_reneg,
+ const frsh_vres_group_t *vres_to_reneg,
+ const frsh_vres_group_t *vres_to_cancel,
+ const frsh_signal_t signal,
+ const frsh_signal_info_t signal_info,
+ frsh_group_id_t *group);
+
+ /**
+ * frsh_group_get_status()
+ *
+ * This function is similar to 'frsh_vres_get_renegotiation_status' but it
+ * is intented for group negotiations (changes of mode).
+ *
+ * The operation reports on the status of the last negotiation
+ * operation enqueued for the specified group identifier.
+ *
+ * The status value can be one of the following values:
+ *
+ * - FRSH_RS_IN_PROGRESS: the change of mode is in progress
+ * - FRSH_RS_REJECTED: the change of mode was not accepted
+ * - FRSH_RS_ADMITTED: the change of mode was accepted
+ * - FRSH_RS_NOT_REQUESTED: no change of mode has been requested yet
+ *
+ * When status returns 'FRSH_RS_ADMITTED', the array 'new_vres' contains
+ * the values for the new virtual resources (if there was any).
+ *
+ * This function frees the group identifier when status returns something
+ * different than FRSH_RS_IN_PROGRESS so further calls to this function may
+ * return inconsistent values.
+ *
+ * @param[in] group The group identifier
+ * @param[out] status The status of the change of mode
+ * @param[out] new_vres List of vres for the negotiation of new contracts.
+ *
+ * @return 0 if no error \n
+ * FRSH_ERR_BAD_ARGUMENT Invalid pointer, signal or group identifier. \n
+ * FRSH_ERR_CONTRACT_LABEL_ALREADY_EXISTS contract_label not unique. \n
+ * FRSH_ERR_NOT_CONTRACTED_VRES: One of the provided vres_ids
+ * is not recognised. \n
+ * FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD The calling thread
+ * is not scheduled under FRSH. \n
+ * FRSH_ERR_INVALID_SCHEDULER_REPLY: The scheduler is wrong or
+ * not running. \n
+ * FRSH_ERR_INTERNAL_ERROR: Erroneous binding or malfunction of
+ * FRSH main scheduler.
+ **/
+ int frsh_group_get_status(const frsh_group_id_t group,
+ frsh_renegotiation_status_t *status,
+ frsh_vres_group_t *new_vres);
+
+
+ /*@}*/
+
+
+ ////////////////////////////////////////////////////
+ // OBTAINING INFORMATION FROM THE SCHEDULER
+ ////////////////////////////////////////////////////
+
+ /**
+ * @defgroup getschedinfo Obtaining information from the scheduler
+ *
+ * @ingroup core
+ *
+ * The following functions are used to obtain available budget and
+ * resource usage in the system. They can be used to adapt the
+ * execution of threads according to the load of the system.
+ *
+ * @{
+ **/
+
+
+ /**
+ * frsh_config_is_admission_test_enabled()
+ *
+ * Returns true if the system is
+ * configured with the on-line admission test enabled, or false
+ * otherwise. This situation can only be changed at compile time.
+ **/
+ bool frsh_config_is_admission_test_enabled();
+
+ /**
+ * frsh_vres_get_usage()
+ *
+ * This function stores the current execution time spent by the
+ * threads bound to the specified vres in the variable pointed to by
+ * cpu_time.
+ *
+ * @return 0 if successful \n
+ * FRSH_ERR_BAD_ARGUMENT : if the value of the vres argument is not in range or
+ * cpu_time 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_VRESR : if the vres of the calling thread
+ * has been cancelled or it is not valid
+ *
+ **/
+ int frsh_vres_get_usage
+ (const frsh_vres_id_t vres,
+ frsh_rel_time_t *spent);
+
+
+ /**
+ * frsh_vres_get_job_usage()
+ *
+ * Get the execution time of the current job of the specified virtual
+ * resource for a bounded or synchronized workload.
+ **/
+ int frsh_vres_get_job_usage
+ (const frsh_vres_id_t vres,
+ frsh_rel_time_t *spent);
+
+
+ /**
+ * frsh_vres_get_remaining_budget()
+ *
+ * This function stores in the variable pointed to by budget the
+ * remaining execution-time budget associated with the specified
+ * vres.
+ *
+ * @return 0 if successful \n
+ * FRSH_ERR_BAD_ARGUMENT : if the value of the vres argument is not in range or
+ * budget 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 of the calling thread
+ * has been cancelled or it is not valid
+ *
+ **/
+ int frsh_vres_get_remaining_budget
+ (const frsh_vres_id_t vres,
+ frsh_rel_time_t *budget);
+
+
+ /**
+ * frsh_vres_get_budget_and_period()
+ *
+ * This function stores in the variables
+ * pointed to by budget and period, the execution-time budget and the
+ * period respectively associated with the specified vres. If any of
+ * these pointers is NULL, the corresponding information is not stored.
+ *
+ * @return 0 if successful \n
+ * FRSH_ERR_BAD_ARGUMENT : if the value of the vres argument is not in range,
+ * or budget and period are both 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 of the calling thread
+ * has been cancelled or it is not valid
+ *
+ **/
+ int frsh_vres_get_budget_and_period
+ (const frsh_vres_id_t vres,
+ frsh_rel_time_t *budget,
+ frsh_rel_time_t *period);
+
+ /*@}*/
+
+ /////////////////////////////////////////////////////////////////////
+ // SERVICE THREAD TUNING
+ /////////////////////////////////////////////////////////////////////
+ /**
+ * @defgroup servthtuning Service thread tuning
+ *
+ * @ingroup core
+ *
+ * The following functions are used to obtain available budget and
+ * resource usage in the system. They can be used to adapt the
+ * execution of threads to the load of the system.
+ *
+ * @{
+ **/
+
+ /**
+ * frsh_service_thread_set_data()
+ *
+ * This function allows the application to change the period and
+ * budget of the service thread that makes the
+ * negotiations. Increasing the utilization of this thread makes the
+ * negotiations faster, but introduces additional load in the system
+ * that may decrease the bandwidth available for the vres. For this
+ * call, the system will make a schedulability analysis to determine
+ * if the new situation is acceptable or not. This is reported back in
+ * the variable pointed to by accepted. If the new service thread data
+ * is accepted, the system will reassign budgets and periods to the
+ * vres according to the new bandwidth available, in the same way
+ * as it does for a regular contract negotiation.
+ *
+ * When its budget is exhausted, the service thread may run in the
+ * background
+ *
+ * The service thread starts with a default budget and period that are
+ * configurable
+ *
+ * Implementation dependency: in the fixed priority implementtaion of
+ * frsh, the default priority is lower than the priority of any vres,
+ * but higher than the background. According to the
+ * implementation-dependent module the priority is adjustable by means
+ * of a function that changes its preemption level
+ *
+ * @return 0 if successful \n
+ * FRSH_ERR_BAD_ARGUMENT : if any of the pointer arguments is NULL or
+ * the budget value is greater than the period value \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 of the calling thread
+ * has been cancelled or it is not valid
+ *
+ **/
+ int frsh_service_thread_set_data (const frsh_rel_time_t *budget,
+ const frsh_rel_time_t *period,
+ bool *accepted);
+
+ /**
+ * frsh_service_thread_get_data()
+ *
+ * this function returns in the variables pointed by budget and
+ * period, respectively, the current budget and period of the service
+ * thread.
+ *
+ * @return 0 if successful \n
+ * FRSH_ERR_BAD_ARGUMENT : if any of the pointer arguments 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 of the calling thread
+ * has been cancelled or it is not valid
+ *
+ **/
+ int frsh_service_thread_get_data
+ (frsh_rel_time_t *budget,
+ frsh_rel_time_t *period);
+
+
+ /*@}*/
+
+
+ ////////////////////////////////////////////////////////////////////////
+ // BACKGROUND MANAGEMENT
+ ////////////////////////////////////////////////////////////////////////
+
+ //A round-robin background scheduling policy is available for those
+ //threads that do not have real-time requirements. Because some of
+ //these threads may require sharing information with other threads run
+ //by regular vres. Special background contracts may be created for
+ //specifying the synchronization requirements.
+
+ //The way of specifying a background contract is by setting
+ //contract_type to FRSH_CT_BACKGROUND. Negotiation may fail if the contract uses
+ //shared_objects. If the contract has no shared_objects the returned
+ //vres id represents the background and may be used to bind more
+ //than one thread. If the contract has shared objects a vres is
+ //created to keep track of them, but the associated threads are
+ //executed in the background, together with the other background
+ //threads
+
+
+ ////////////////////////////////////////////////////////////////////////
+ // OTHER
+ ////////////////////////////////////////////////////////////////////////
+
+ /**
+ * Returns resource id of local CPU.
+ *
+ * The ID is determined from environment variable FRSH_CPU_ID or, if
+ * that is not defined, the compile time default (defined in
+ * config.target/omk).
+ */
+ frsh_resource_id_t frsh_get_local_cpu_id(void);
+
+ FRSH_CPP_END_DECLS
+
+ #endif // _FRSH_CORE_H_
--- /dev/null
+ // -----------------------------------------------------------------------
+ // Copyright (C) 2006 - 2009 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
+ //
+ // FSF API web pages: http://marte.unican.es/fsf/docs
+ // http://shark.sssup.it/contrib/first/docs/
+ //
+ // This file is part of FRSH (FRescor ScHeduler)
+ //
+ // 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, 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_core_types.h
+ //==============================================
+ // ******** ******* ******** ** **
+ // **///// /**////** **////// /** /**
+ // ** /** /** /** /** /**
+ // ******* /******* /********* /**********
+ // **//// /**///** ////////** /**//////**
+ // ** /** //** /** /** /**
+ // ** /** //** ******** /** /**
+ // // // // //////// // //
+ //
+ // FRSH(FRescor ScHeduler), pronounced "fresh"
+ //==============================================
+
+
+ #ifndef FRSH_CORE_TYPES_H_
+ #define FRSH_CORE_TYPES_H_
+
+ #include <stdbool.h>
+ #include "frsh_time_types.h"
+ #include "frsh_configuration_parameters.h"
+ #include "frsh_opaque_types.h"
+ #include "frsh_shared_objects_types.h"
+ #include "frsh_spare_capacity_types.h"
+
+ #include "frsh_implementation_specific_types.h"
+ #include "frsh_hierarchical_types.h"
+ #include "frsh_distributed_types.h"
+ #include "frsh_error.h"
+
+ #include "fosa.h"
+
+ FRSH_CPP_BEGIN_DECLS
+
+ /**
+ * @file frsh_core_types.h
+ **/
+
+
+ /**
+ * \addtogroup core
+ **/
+ /*@{*/
+
+
+ /** identifier of a frsh thread **/
+ typedef fosa_thread_id_t frsh_thread_id_t;
+
+
+ /** thread attributes object **/
+ typedef fosa_thread_attr_t frsh_thread_attr_t;
+
+ /**
+ * The type references a function that may become a thread's
+ * code
+ **/
+ typedef fosa_thread_code_t frsh_thread_code_t;
+
+
+ /** signal number; it is an integer type **/
+ typedef fosa_signal_t frsh_signal_t;
+
+ #define FRSH_NULL_SIGNAL FOSA_NULL_SIGNAL
+
+
+ #define FRSH_SIGNAL_MIN FOSA_SIGNAL_MIN
+ #define FRSH_SIGNAL_MAX FOSA_SIGNAL_MAX
+
+
+ typedef fosa_signal_info_t frsh_signal_info_t;
+
+
+ /** Kind of workload expected in vres: bounded or indeterminate **/
+ typedef enum {
+ FRSH_WT_BOUNDED = 0,
+ FRSH_WT_INDETERMINATE = 1,
+ FRSH_WT_SYNCHRONIZED = 2
+ } frsh_workload_t;
+ /**
+ * In the synchronized workload the virtual resource hosts one or more
+ * threads that synchronize the execution of their jobs with the start
+ * of the virtual resource's period. In this kind of workload, once
+ * the threads that were activated at the beginning of the period
+ * finish their current job, the virtual resource may return any
+ * unused capacity to the system. This kind of workload can be
+ * scheduled using a regular periodic server that has the properties
+ * of being simple, having less overhead, and being able to increase
+ * the schedulability of periodic synchronized threads
+ **/
+
+ #define FRSH_NULL_DEADLINE (frsh_rel_time_t *)NULL
+ // #define FRSH_NULL_SIGNAL 0 /* Defined at frsh_adaption.h */
+
+ /** Negotiation status: In_progress, rejected, admitted, not_requested **/
+ typedef enum {FRSH_RS_IN_PROGRESS,
+ FRSH_RS_REJECTED,
+ FRSH_RS_ADMITTED,
+ FRSH_RS_NOT_REQUESTED} frsh_renegotiation_status_t;
+
+ /**
+ * Vres Id type, that identifies a vres created to manage a given
+ * contract
+ **/
+ typedef FRSH_VRES_ID_T_OPAQUE frsh_vres_id_t; // => 0
+
+ /** Contract ressource type: processor, network, memory **/
+ typedef enum {
+ FRSH_RT_PROCESSOR = 0,
+ FRSH_RT_NETWORK = 1,
+ FRSH_RT_MEMORY = 2,
+ FRSH_RT_DISK = 3,
+ FRSH_RT_FPGA = 4,
+ FRSH_RT_LCD = 5
+ } frsh_resource_type_t;
+
+ /** Ressource Id: processor_id or network_id **/
+ /**********************************************/
+ typedef fosa_resource_id_t frsh_resource_id_t;
+
+ /** Kind of contract: regular, background or dummy **/
+ typedef enum {
+ FRSH_CT_REGULAR = 0,
+ FRSH_CT_BACKGROUND = 1,
+ FRSH_CT_DUMMY = 2
+ } frsh_contract_type_t;
+
+ // The name of this constant has been updated to have the FRSH_ prefix
+ typedef char frsh_contract_label_t[FRSH_CONTRACT_LABEL_MAXLENGTH + 1];
+
+ /**
+ * Contract parameters type; it is an opaque type (i.e. the internal
+ * structure of this data type is implementation dependent). The user
+ * can access and modify the parameters of a contract only with the
+ * proper functions, and should never access the data directly.
+ **/
+ typedef FRSH_CONTRACT_T_OPAQUE frsh_contract_t;
+
+
+ /** List of vres **/
+ typedef struct {
+ int size;
+ frsh_vres_id_t vres[FRSH_MAX_GROUP_OPS];
+ } frsh_vres_group_t;
+
+ /** List of contracts to negotiate **/
+ typedef struct {
+ int size;
+ frsh_contract_t contracts[FRSH_MAX_GROUP_OPS];
+ } frsh_contracts_group_t;
+
+ typedef FRSH_GROUP_ID_T_OPAQUE frsh_group_id_t;
+
+ /**
+ * An abstract synchronization object is defined by the application.
+ * This object can be used by an application to wait for an event to
+ * arrive by invoking the frsh_sychobj_wait() operation. It
+ * can also be used to signal the event either causing a waiting
+ * vres to wake up, or the event to be queued if no vres is
+ * waiting for it.
+ **/
+ typedef FRSH_SYNCHOBJ_HANDLE_T_OPAQUE frsh_synchobj_handle_t;
+
+
+ /*@}*/
+
+ FRSH_CPP_END_DECLS
+
+ #endif /* !FRSH_CORE_TYPES_H_ */
--- /dev/null
+ // -----------------------------------------------------------------------
+ // Copyright (C) 2006 - 2009 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
+ //
+ // FSF API web pages: http://marte.unican.es/fsf/docs
+ // http://shark.sssup.it/contrib/first/docs/
+ //
+ // This file is part of FRSH (FRescor ScHeduler)
+ //
+ // 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, 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.
+ // -----------------------------------------------------------------------
+
+ #ifndef _FRSH_CPP_MACROS_H_
+ #define _FRSH_CPP_MACROS_H_
+
+ #if defined(__cplusplus)
+ #define FRSH_CPP_BEGIN_DECLS extern "C" {
+ #else
+ #define FRSH_CPP_BEGIN_DECLS
+ #endif
+
+ #if defined(__cplusplus)
+ #define FRSH_CPP_END_DECLS }
+ #else
+ #define FRSH_CPP_END_DECLS
+ #endif
+
+ #endif // _FRSH_CPP_MACROS_H_
+
--- /dev/null
+ // -----------------------------------------------------------------------
+ // Copyright (C) 2006 - 2009 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
+ //
+ // FSF API web pages: http://marte.unican.es/fsf/docs
+ // http://shark.sssup.it/contrib/first/docs/
+ //
+ // This file is part of FRSH (FRescor ScHeduler)
+ //
+ // 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, 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(FRescor ScHeduler), pronounced "fresh"
+ //==============================================
+ //
+ // 23-Jul-2007 SANGORRIN: create this file for debugging functions
+ // 31-Jul-2007 TELLERIA: Change "debug" for "trace"
+ // -----------------------------------------------------------------------
+ #ifndef FRSH_DEBUG_H
+ #define FRSH_DEBUG_H
+
+ #include <stdio.h> // for vprintf
+ #include <stdbool.h> // for bool
+ #include <stdarg.h> // for va_list, va_start and va_end
+ #include "fosa.h"
+ #include "frsh_debug_and_trace_types.h"
+ #include "fosa_configuration_parameters.h" /* FOSA_CLOCK_REALTIME */
+ #include "fosa_clocks_and_timers.h"
+
+ FRSH_CPP_BEGIN_DECLS
+
+ // Tune the following FLAGS to select the debugging messages to be generated
+ #define FRSH_TRACE_CALLBACKS false
+ #define FRSH_TRACE_SERVICE_TH false
+ #define FRSH_TRACE_WATCHDOG false
+ #define FRSH_TRACE_SPORADIC_SERVER false
+ #define FRSH_TRACE_REPLENISHMENTS false
+ #define FRSH_TRACE_ROUND_ROBIN false
+ #define FRSH_TRACE_BOUNDED_JOB false
+ #define FRSH_TRACE_SYNCHRONIZE_WORKLOAD false
+ #define FRSH_TRACE_ADMISSION_TEST false
+ #define FRSH_TRACE_ADMISSION_RESULT false
+
+ #define FRSH_TRACE_THREAD_INDEX false
+ #define FRSH_TRACE_VRES_INDEX false
+
+ #define FRSH_TRACE_DISTRIBUTED false
+
+ #define QUICK_AND_DIRTY_FIX_JLDEMO true
+
+
+ /**
+ * frsh_trace_point_insert()
+ *
+ * Insert an application-defined trace-point identifier together with
+ * a timestamp into the trace log, if tracing is enabled; the
+ * identifier is an integer that must be between two configurable
+ * values defined in the FRSH API as constants; if tracing is not
+ * enabled, this function has no effect.
+ */
+ int frsh_trace_point_insert(frsh_trace_point_id_t ipoint);
+
+ /** If FRSH_TRACE_TS_MSECS is defined, each trace line is prefixed
+ with a msec counter **/
+ #define FRSH_TRACE_TS_MSECS
+
+ /* These variables live defined in frsh_error.c */
+ /************************************************/
+ extern fosa_abs_time_t frsh_trace_init_timespec;
+ extern long frsh_trace_init_timemsec;
+
+ extern int global_error_condition; /* Used to propagate error
+ * conditions in debugging */
+
+ static inline long int FRSH_GET_TIMESTAMP_MSECS()
+ {
+ int terror = -1;
+ fosa_abs_time_t current_time;
+ long int current_time_msec = -1;
+ long int result = -1;
+
+ PRW( fosa_clock_get_time(FOSA_CLOCK_REALTIME, ¤t_time) );
+ current_time_msec = fosa_abs_time_to_msec(current_time);
+
+ result = current_time_msec - frsh_trace_init_timemsec;
+
+ return result;
+ }
+
+ static inline long int FRSH_TIMESTAMP_TO_RELATIVE_MSECS(const fosa_abs_time_t *timestamp)
+ {
+ long int time_msecs = -1;
+
+ time_msecs = fosa_abs_time_to_msec(*timestamp);
+
+ return time_msecs - frsh_trace_init_timemsec;
+ }
+
+ /**
+ * FRSH_TRACE()
+ *
+ * If the boolean value is true, print the format line optionally
+ * preceded by a timestamp in ms relative to the start of the
+ * program.
+ *
+ * Due to the "..." argument passing, this function cannot be
+ * inlined.
+ **/
+ void FRSH_TRACE(bool is_active, const char *format, ...);
+
+ FRSH_CPP_END_DECLS
+
+ #endif
--- /dev/null
+ // -----------------------------------------------------------------------
+ // Copyright (C) 2006 - 2009 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
+ //
+ // FSF API web pages: http://marte.unican.es/fsf/docs
+ // http://shark.sssup.it/contrib/first/docs/
+ //
+ // This file is part of FRSH (FRescor ScHeduler)
+ //
+ // 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, 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(FRescor ScHeduler), pronounced "fresh"
+ //==============================================
+ //
+ // 23-Jul-2007 SANGORRIN: create this file for debugging functions
+ // 31-Jul-2007 TELLERIA: Change "debug" for "trace"
+ // -----------------------------------------------------------------------
+ #ifndef FRSH_DEBUG_AND_TRACE_TYPES_H_
+ #define FRSH_DEBUG_AND_TRACE_TYPES_H_
+
+ FRSH_CPP_BEGIN_DECLS
+
+ /** identifier of a trace point **/
+ typedef int frsh_trace_point_id_t;
+
+ /** constants that describe the valid range of trace point identifiers **/
+ #define FRSH_TRACE_POINT_ID_MIN 0
+ #define FRSH_TRACE_POINT_ID_MAX 10
+
+ FRSH_CPP_END_DECLS
+
+ #endif /* !FRSH_DEBUG_AND_TRACE_TYPES_H_ */
--- /dev/null
+ // -----------------------------------------------------------------------
+ // Copyright (C) 2006 - 2009 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
+ //
+ // FSF API web pages: http://marte.unican.es/fsf/docs
+ // http://shark.sssup.it/contrib/first/docs/
+ //
+ // This file is part of FRSH (FRescor ScHeduler)
+ //
+ // 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, 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_distributed.h
+ //==============================================
+ // ******** ******* ******** ** **
+ // **///// /**////** **////// /** /**
+ // ** /** /** /** /** /**
+ // ******* /******* /********* /**********
+ // **//// /**///** ////////** /**//////**
+ // ** /** //** /** /** /**
+ // ** /** //** ******** /** /**
+ // // // // //////// // //
+ //
+ // FRSH(FRescor ScHeduler), pronounced "fresh"
+ //==============================================
+ #ifndef _FRSH_DISTRIBUTED_H_
+ #define _FRSH_DISTRIBUTED_H_
+
+
+ /**
+ * @file frsh_distributed.h
+ **/
+
+
+ #include "frsh_distributed_types.h"
+ #include "frsh_core_types.h"
+
+ FRSH_CPP_BEGIN_DECLS
+
+ // this global variable is assigned by frsh_distributed_init()
+ extern frsh_resource_id_t THE_FRSH_CPU_ID;
+
+ typedef enum {
+ FRSH_NETPF_FRESCAN = 0,
+ FRSH_NETPF_RTEP = 1,
+ FRSH_NETPF_UNIX = 2,
+ FRSH_NETPF_FWP = 3,
+ FRSH_NETPF_CLUSTER_TREE = 4,
+ FRSH_NETPF_ITEM = 5,
+ } frsh_netpf_t;
+
+ /**
+ * @defgroup distributed Distributed module
+ *
+ * This module defines the functions and typedefs for use in
+ * distributed applications.
+ *
+ * Each network is identified by its resource_id and FRSH hides its
+ * characteristics completely. The type of network is implied with
+ * its ID via a configuration table defined at compile time.
+ *
+ * FRSH uses the "message" as the atomic unit for every exchange.
+ * Queue sizes are measured in number of pending messages.
+ *
+ * FRSH provides a function to calculate the transmision time needed
+ * for a certain message size in a network as well as the maximum
+ * message size that can admit.
+ *
+ * Note also that package delivery guarantee is protocol dependent.
+ * For protocols in which the order is no guaranteed, the application
+ * needs to add extra info to detect possible package disorder.
+ *
+ * Summary of typical steps.
+ *
+ * 1. Map (internally in FRSH implementation)
+ * - node--> network_addresses
+ * - network --> resource_id's
+ * - unidirectional communication channel --> stream_id
+ * - other config --> protocol_info.
+ *
+ * 2. In a sending node:
+ * 2.1. Negotiates a "network contract" per communication channel
+ * that is used in the application. In the contract it is
+ * specified:
+ * - frsh_resource_type = FRSH_RT_NETWORK.
+ * - frsh_resource_id = <network id #>
+ * - budget: Time needed to send the required data per period.
+ * (you can use frsh_netinfo_*() functions for this).
+ * - period: Period of sendings.
+ * - Queueing info: How will sends be queued at sendEndpoint.
+ * - Other protocol dependent function in protocol_contract_info.
+ * 2.2. Create a send_endpoint per any unidirectional stream that will
+ * be used in sending
+ * resource_id --> the network through which the stream will
+ * flow (this is extra info needed for coherency
+ * with the bind).
+ * destinator --> network_address of the destination.
+ * stream_id --> the unidirectional communication channel.
+ * 2.3. Bind the send_endpoint to the network contract negotiated
+ * above.
+ * 2.4. The (processor) sending vres invokes frsh_send_(a)sync() to
+ * send the data through the corresponding stream.
+ *
+ * 3. In a receiving node:
+ * 3.1. Create a receive_endpoint per any unidirectional stream
+ * that will be used in receiving.
+ * 3.2. The processor expecting a reception of message invokes
+ * frsh_receive_(a)sync() to read the incoming data.
+ *
+ * 4. When all comunication is finished and the channel is no longer
+ * needed the nodes will destroy the send and receive endpoints
+ * and the network contract will be canceled.
+ **/
+
+ /**
+ * frsh_distributed_init(void)
+ *
+ * This operation initializes all the installed networks and the structures
+ * that are necessary for the distributed module. Currently it is called by
+ * frsh_init so it is not necessary that the user calls it again.
+ *
+ * 0: No error \n
+ * FRSH_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
+ *
+ **/
+ int frsh_distributed_init(void);
+
+ //////////////////////////////////////////////////////////////////////
+ // CONTRACT ASPECTS
+ //////////////////////////////////////////////////////////////////////
+
+ /**
+ * @defgroup distcontract Contract Info for Distributed Systems
+ * @ingroup distributed
+ *
+ * These functions help you calculate the needed budget for network
+ * contracts and also to include protocol dependent info in contract
+ * parameters.
+ *
+ * @{
+ **/
+
+ /**
+ * frsh_network_get_max_message_size()
+ *
+ * This operation gives the maximum number of bytes that can be sent
+ * at a time through the send function when using the network designated by
+ * 'resource_id' and sending it to 'destination'.
+ *
+ * If the application needs to send bigger messages it will have to
+ * split them.
+ *
+ * Some protocols, like IP, are capable of sending large messages
+ * (and use fragmentation internally) but other protocols don't.
+ *
+ * @param[in] resource_id The network we want the tx time from.
+ * @param[in] destination The destination address
+ * @param[out] max_size The maximum number of bytes for each message
+ *
+ * @return
+ * FRSH_NO_ERROR \n
+ * FRSH_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
+ * FRSH_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
+ * FRSH_ERR_RESOURCE_ID_INVALID: if resource id does not represent
+ * a network accessible from the current processing node \n
+ * FRSH_ERR_BAD_ARGUMENT: if pointers are NULL or destination is
+ * invalid \n
+ *
+ **/
+ int frsh_network_get_max_message_size
+ (const frsh_resource_id_t resource_id,
+ const frsh_network_address_t destination,
+ size_t *max_size);
+
+ /**
+ * frsh_network_bytes_to_budget()
+ *
+ * This operation converts a number of bytes into a temporal budget for
+ * a specific network. Network overheads are not included here but are
+ * considered internally when negotiating a specific contract.
+ *
+ * @param[in] resource_id The network
+ * @param[in] nbytes Number of bytes
+ * @param[out] budget The network budget for nbytes
+ *
+ * @return
+ * FRSH_NO_ERROR \n
+ * FRSH_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
+ * FRSH_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
+ * FRSH_ERR_RESOURCE_ID_INVALID: if resource id does not represent
+ * a network accessible from the current processing node \n
+ * FRSH_ERR_BAD_ARGUMENT: if pointers are NULL or nbytes is less
+ * than zero \n
+ *
+ **/
+ int frsh_network_bytes_to_budget
+ (const frsh_resource_id_t resource_id,
+ const size_t nbytes,
+ frsh_rel_time_t *budget);
+
+ /**
+ * frsh_network_budget_to_bytes()
+ *
+ * This operation converts a temporal budget into a number of bytes for
+ * a specific network. Network overheads are not included.
+ *
+ * @param[in] resource_id The network
+ * @param[in] budget The network budget for nbytes
+ * @param[out] nbytes Number of bytes
+ *
+ * @return
+ * FRSH_NO_ERROR \n
+ * FRSH_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
+ * FRSH_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
+ * FRSH_ERR_RESOURCE_ID_INVALID: if resource id does not represent
+ * a network accessible from the current processing node \n
+ * FRSH_ERR_BAD_ARGUMENT: if pointers are NULL or budget refers to
+ * an invalid time value \n
+ *
+ **/
+ int frsh_network_budget_to_bytes
+ (const frsh_resource_id_t resource_id,
+ const frsh_rel_time_t *budget,
+ size_t *nbytes);
+
+ /**
+ * frsh_network_get_min_effective_budget()
+ *
+ * This operation gets the minimum effective budget for a network. Each message
+ * consumes a contracted budget in "chunks" (i.e: packets) that we call
+ * minimum effective budget.
+ *
+ * A negotiated contract, for N bytes in a period T, means that there is a
+ * virtual resource that reserves for the user:
+ *
+ * Ceiling ((N bytes) / budget_to_bytes (min_effective_budget)) "CHUNKS"
+ *
+ * Note that if the user decides not to send these N bytes at once but, say,
+ * one byte at a time, it will consume one "CHUNK" at a time and the reserved
+ * budget will become exhausted before sending all the bytes.
+ *
+ * @param[in] resource_id The network
+ * @param[out] budget The network budget
+ *
+ * @return
+ * FRSH_NO_ERROR \n
+ * FRSH_ERR_INTERNAL_ERROR: protocol dependent internal errors \n
+ * FRSH_ERR_NOT_INITIALIZED: if the protocol is not initialized \n
+ * FRSH_ERR_RESOURCE_ID_INVALID: if resource id does not represent
+ * a network accessible from the current processing node \n
+ * FRSH_ERR_BAD_ARGUMENT: if pointers are NULL \n
+ *
+ **/
+ int frsh_network_get_min_effective_budget
+ (const frsh_resource_id_t resource_id,
+ frsh_rel_time_t *budget);
+
+ /**
+ * frsh_contract_set_queueing_info()
+ *
+ * This function adds queueing parameters that will be used in the
+ * sendEndpoint when the sendEndpoint is bound to the vres.
+ **/
+ int frsh_contract_set_queueing_info(frsh_endpoint_queueing_info_t queueing_info,
+ frsh_contract_t *contract);
+
+ /**
+ * frsh_contract_get_queueing_info()
+ *
+ * This function gets the queueing parameters that were specified in
+ * the network contract.
+ **/
+ int frsh_contract_get_queueing_info(const frsh_contract_t *contract,
+ frsh_endpoint_queueing_info_t *queueing_info);
+
+ /**
+ * frsh_contract_set_protocol_info
+ *
+ * We add protocol info to the contract
+ **/
+ int frsh_contract_set_protocol_info(frsh_protocol_info_t protocol_info,
+ frsh_contract_t *contract);
+
+ /**
+ * frsh_contract_get_protocol_info
+ *
+ * We get protocol info from the contract
+ **/
+ int frsh_contract_get_protocol_info(frsh_contract_t *contract,
+ frsh_protocol_info_t *protocol_info);
+
+ /**
+ * frsh_contract_marshal
+ *
+ * Convert a contract to a sequence of bytes of minimum size so it can
+ * be sent through the network with the minimum amount of bytes.
+ *
+ **/
+
+ int frsh_contract_marshal(const frsh_contract_t *contract,
+ unsigned char *buffer,
+ const size_t buffer_size,
+ size_t *size);
+
+ /**
+ * frsh_contract_unmarshal
+ *
+ * Convert a sequence of bytes generated by frsh_contract_marshal to a contract
+ *
+ **/
+
+ int frsh_contract_unmarshal(frsh_contract_t *contract,
+ const unsigned char *marshal_bytes,
+ const size_t size);
+
+ /*@}*/
+ //////////////////////////////////////////////////////////////////////
+ // TWO STEP NEGOTIATION
+ //////////////////////////////////////////////////////////////////////
+
+ /**
+ * @defgroup twostepnego Two Step Negotiation
+ * @ingroup distributed
+ *
+ * Using the core services of FRSH, contracts may be negotiated in a
+ * single step.
+ *
+ * An alternative two-step negotiation process is introduced in the
+ * distribution module: the first step involves the reservation of the
+ * resources, but without the right to use them, and the second step
+ * is the commitment to use those resources.
+ *
+ * The rationale behind this approach is that in distributed systems,
+ * when a distributed transaction is being negotiated the system
+ * should only commit the virtual resources that were negotiated with
+ * various nodes in the system if the results of all negotiations
+ * match together. This approach enhances the efficiency since the
+ * actual temporal values of the virtual resources on distributed
+ * nodes are only changed if the initiator of the distributed
+ * transaction is satisfied with the results of the negotiations.
+ *
+ * After the reservation, it is not necessary to change the actual
+ * virtual resource attributes (and modifying the schedule) on each
+ * node before the initiator of the distributed transaction knows the
+ * amount of available virtual resources. A renegotiation of a
+ * reserved virtual resource is possible, to harmonize for the
+ * available virtual resources in other parts of the system, before a
+ * final commitment is made.
+ *
+ * @{
+ **/
+
+
+ /**
+ * frsh_contract_negotiate_reservation()
+ *
+ * Negotiate a service contract, obtaining a virtual resource id that
+ * represents a reservation of resources, but without the right to use
+ * those resources until the reservation is committed via
+ * frsh_vres_commit_reservation. In particular, this virtual resource
+ * cannot be bound until committed, but renegotiations are allowed for
+ * it.
+ */
+ int frsh_contract_negotiate_reservation
+ (const frsh_contract_t *contract,
+ frsh_vres_id_t *vres);
+
+ /**
+ * frsh_vres_commit_reservation()
+ *
+ * Commit the resources reserved for a virtual resource through a
+ * frsh_contract_negotiate_reservation operation. The effects of
+ * subsequent calls to frsh_contract_negotiate_reservation and
+ * frsh_vres_commit_reservation are equivalent to a single call to
+ * frsh_contract_negotiate.
+ */
+ int frsh_vres_commit_reservation
+ (const frsh_vres_id_t vres);
+
+ /* @} */
+
+
+
+ //////////////////////////////////////////////////////////////////////
+ // TRANSMISSION SERVICES
+ //////////////////////////////////////////////////////////////////////
+
+ /**
+ * @defgroup txservices Transmission services
+ * @ingroup distributed
+ *
+ * These functions allow to create and manage endpoints for sending
+ * and receiving and to perform send and receive operations both
+ * synchronously (blocking) and asynchronously (non-blocking).
+ *
+ * @{
+ **/
+
+
+ /**
+ * frsh_send_endpoint_create()
+ *
+ * This operation creates a unidirectional stream input endpoint
+ * through which, after the corresponding binding, it is possible to
+ * send data to a unicast or multicast destination.
+ *
+ * @param[in] resource_id Identifier of the network referred in the
+ * network contract as a resource_id.
+ * @param[in] destination FRSH abstraction of the protocol address for the
+ * destinator node.
+ * @param[in] stream_id Identifier of the communication channel between
+ * the nodes. Multiplexing is achieved by using
+ * different streams between the same nodes and the
+ * same network.
+ * @param[in] queueing_info Queueing params of the endpoint (size and
+ * policy).
+ * @param[in] protocol_info Optional protocol-dependent info.
+ * @param[out] endpoint Placeholder for the endpoint object.
+ **/
+ int frsh_send_endpoint_create
+ (frsh_resource_id_t resource_id,
+ frsh_network_address_t destination,
+ frsh_stream_id_t stream_id,
+ frsh_send_endpoint_protocol_info_t protocol_info,
+ frsh_send_endpoint_t *endpoint);
+
+ /**
+ * frsh_send_endpoint_get_params()
+ *
+ * This operation returns in the variables associated to the
+ * endpoint at creation time.
+ **/
+ int frsh_send_endpoint_get_params
+ (const frsh_send_endpoint_t endpoint,
+ frsh_resource_id_t *resource_id,
+ frsh_network_address_t *destination,
+ frsh_stream_id_t *stream,
+ frsh_send_endpoint_protocol_info_t *protocol_info);
+
+ /**
+ * frsh_send_endpoint_destroy()
+ *
+ * This operation eliminates any resources reserved for the referenced
+ * endpoint. Pending messages will be discarded and processor-vres
+ * waiting in a synchronous operation will be awoken with an error
+ * code.
+ **/
+ int frsh_send_endpoint_destroy
+ (frsh_send_endpoint_t endpoint);
+
+ /**
+ * frsh_send_endpoint_bind()
+ *
+ * This operation associates a send endpoint with a network vres,
+ * which means that messages sent through this endpoint will consume
+ * the vres's reserved bandwidth and its packets will be sent
+ * according to the contract established for that vres.
+ *
+ * If the endpoint is already bound to another vres, it is effectively
+ * unbound from it and bound to the specified one. However if a vres
+ * is already bound to another endpoint an error is returned.
+ *
+ * A consistency check is done in which the resource_id specified at
+ * endpoint creation must correspond to the resource_id of the vres
+ * contract.
+ *
+ * @return 0 if successful \n
+ * FRSH_ERR_BAD_ARGUMENT if the endpoint or the vres are not
+ * valid \n
+ * FRSH_ERR_ALREADY_BOUND if the vres is already bound to some
+ * other send endpoint \n
+ * FRSH_ERR_WRONG_NETWORK if the vres network id is not the same
+ * as the one in the endpoint \n
+ **/
+ int frsh_send_endpoint_bind
+ (frsh_vres_id_t vres,
+ frsh_send_endpoint_t endpoint);
+
+ /**
+ * frsh_send_endpoint_unbind()
+ *
+ * This operation unbinds a send endpoint from a vres. Endpoints with
+ * no vres associated cannot be used to send data, and they stay in
+ * that state until they are either eliminated or bound again.
+ *
+ * @return 0 if successful \n
+ * FRSH_ERR_NOT_BOUND if the endpoint was not bound \n
+ **/
+ int frsh_send_endpoint_unbind
+ (frsh_send_endpoint_t endpoint);
+
+ /**
+ * frsh_send_endpoint_get_vres_id()
+ *
+ * This operation copies the id of the vres that is bound to the
+ * specified send endpoint into the variable pointed to by vres.
+ *
+ * @return 0 if successful \n
+ * FRSH_ERR_NOT_BOUND if the endpoint was not bound \n
+ * FRSH_ERR_BAD_ARGUMENT if the endpoint is not valid or vres
+ * is NULL \n
+ **/
+ int frsh_send_endpoint_get_vres_id
+ (const frsh_send_endpoint_t endpoint,
+ frsh_vres_id_t *vres);
+
+ /**
+ * frsh_send_async()
+ *
+ * This operation sends a message stored in msg and of length size
+ * through the given endpoint. The operation is non-blocking and
+ * returns immediately.
+ *
+ * An internal frsh service will schedule the sending of messages and
+ * implement the communications sporadic vres corresponding to the
+ * network vres bound to the given endpoint.
+ *
+ * @returns 0 if successful \n
+ * FRSH_ERR_BAD_ARGUMENT if endpoint is not valid \n
+ * FRSH_ERR_NOT_BOUND if endpoint is not bound to a valid vres \n
+ * FRSH_ERR_TOO_LARGE if the message is too large for the
+ * network protocol \n
+ * FRSH_ERR_BUFFER_FULL if the message has been discarded
+ * because the queue is full (and does not
+ * have the policy FRSH_QP_OLDEST \n
+ **/
+ int frsh_send_async
+ (const frsh_send_endpoint_t endpoint,
+ const void *msg,
+ const size_t size);
+
+ /**
+ * frsh_send_sync()
+ *
+ * Similar to previous function but now the sending vres gets blocked
+ * until the message is processed.
+ **/
+ int frsh_send_sync
+ (const frsh_send_endpoint_t endpoint,
+ const void *msg,
+ size_t size);
+
+ /**
+ * frsh_send_endpoint_get_status()
+ *
+ * This function tells the number of messages still pending in the
+ * endpoint queue, whether the network is up or down with some
+ * optional information which is protocol_dependent.
+ **/
+ int frsh_send_endpoint_get_status
+ (const frsh_send_endpoint_t endpoint,
+ int *number_pending_msg,
+ frsh_endpoint_network_status_t *network_status,
+ frsh_protocol_status_t *protocol_status);
+
+ /**
+ * frsh_receive_endpoint_create()
+ *
+ * This operation creates a receive endpoint associated with a
+ * undirectional stream within a network interface of the node.
+ *
+ * Receiving endpoints are not bound to any network vres, this is
+ * because don't originate any traffic.
+ *
+ * Note that the protocol address is not needed for reception because
+ * it can be determined internally by FRSH based on the resource_id.
+ *
+ * Note also that messages may come from diferent originators.
+ *
+ * @param[in] resource_id Id of the network from which we listen.
+ * @param[in] stream_id Id of the stream within the network.
+ * @param[in] queueing_info Buffering information(queue size and
+ * policy).
+ * @param[in] protocol_info Extra protocol info opaque for the
+ * application.
+ * @param[in] endpoin Placeholder for the endpoint object.
+ *
+ * @return 0 if successful \n
+ * FRSH_ERR_BAD_ARGUMENT if the stream or the network id are not
+ * valid \n
+ **/
+ int frsh_receive_endpoint_create
+ (frsh_resource_id_t resource_id,
+ frsh_stream_id_t stream_id,
+ frsh_endpoint_queueing_info_t queueing_info,
+ frsh_receive_endpoint_protocol_info_t protocol_info,
+ frsh_receive_endpoint_t *endpoint);
+
+ /**
+ * frsh_receive_endpoint_get_params()
+ *
+ * This operation returns in the variables associated to the
+ * endpoint at creation time.
+ **/
+ int frsh_receive_endpoint_get_params
+ (const frsh_receive_endpoint_t endpoint,
+ frsh_resource_id_t *resource_id,
+ frsh_stream_id_t *stream,
+ frsh_endpoint_queueing_info_t *queueing_info,
+ frsh_receive_endpoint_protocol_info_t *protocol_info);
+
+ /**
+ * frsh_receive_endpoint_destroy()
+ *
+ * This operation eliminates any resources reserved for the referenced
+ * endpoint. Pending messages will be discarded and processor-vres
+ * waiting in a synchronous operation will be awoken with an error
+ * code.
+ **/
+ int frsh_receive_endpoint_destroy
+ (frsh_receive_endpoint_t endpoint);
+
+
+ /**
+ * frsh_receive_sync()
+ *
+ * If there are no messages available in the specified receive endpoint
+ * this operation blocks the calling thread waiting for a message to be
+ * received.
+ *
+ * When a message is available, if its size is less than or
+ * equal to the buffer_size, the function stores it in the variable
+ * pointed to by buffer and puts the number of bytes received in the
+ * variable pointed to by message size.
+ *
+ * The function fails with FRSH_ERR_NO_SPACE if the buffersize is
+ * too small for the message received. In this case the message is
+ * lost.
+ *
+ * Messages arriving at a destination buffer that is full will be
+ * silently discarded (details in the queueing policy of the
+ * endpoint). The application is responsible of reading the receive
+ * endpoints with appropriate regularity, or of using a sequence
+ * number or some other mechanism to detect any lost messages.
+ *
+ * @return 0 if successful \n
+ * FRSH_ERR_BAD_ARGUMENT if the endpoint is not valid, or if
+ * buffer or message_size are NULL.\n
+ * FRSH_ERR_NO_SPACE if the message size is bigger than the
+ * provided buffer \n
+ **/
+ int frsh_receive_sync
+ (const frsh_receive_endpoint_t endpoint,
+ void *buffer,
+ size_t buffer_size,
+ size_t *message_size,
+ frsh_network_address_t *from);
+
+ /**
+ * frsh_receive_async()
+ *
+ * This operation is similar to the previous one but it works in a non
+ * blocking (asynchronous) fashion. If no message is available it
+ * returns with error FRSH_NO_MESSAGE.
+ *
+ * @return 0 if successful \n
+ * FRSH_ERR_BAD_ARGUMENT if the endpoint is not valid, or if
+ * buffer or message_size are NULL \n
+ * FRSH_NO_MESSAGE if no messages are available in the queue \n
+ * FRSH_ERR_NO_SPACE if the message size is bigger than the
+ * provided buffer \n
+ **/
+ int frsh_receive_async
+ (const frsh_receive_endpoint_t endpoint,
+ void *buffer,
+ size_t buffer_size,
+ size_t *message_size,
+ frsh_network_address_t *from);
+
+
+ /**
+ * frsh_receive_endpoint_get_status
+ *
+ * This function tells the number of messages still pending in the
+ * endpoint queue, whether the network is up or down and some optional
+ * information which is protocol dependent.
+ **/
+ int frsh_receive_endpoint_get_status
+ (const frsh_receive_endpoint_t endpoint,
+ int *number_pending_messages,
+ frsh_endpoint_network_status_t *network_status,
+ frsh_protocol_status_t *protocol_status);
+
+ /*@}*/
+
+ FRSH_CPP_END_DECLS
+
+ #endif // _FRSH_DISTRIBUTED_H_
--- /dev/null
+ // -----------------------------------------------------------------------
+ // Copyright (C) 2006 - 2009 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
+ //
+ // FSF API web pages: http://marte.unican.es/fsf/docs
+ // http://shark.sssup.it/contrib/first/docs/
+ //
+ // This file is part of FRSH (FRescor ScHeduler)
+ //
+ // 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, 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(FRescor ScHeduler), pronounced "fresh"
+ //==============================================
+
+ #ifndef FRSH_DISTRIBUTED_TYPES_H_
+ #define FRSH_DISTRIBUTED_TYPES_H_
+
+ /**
+ * @file frsh_distributed_types.h
+ **/
+
+ #include "frsh_opaque_types.h"
+
+ FRSH_CPP_BEGIN_DECLS
+
+ /**
+ * @addtogroup distributed
+ *
+ * @{
+ **/
+
+ //opaque types for frsh endpoints
+ typedef FRSH_SEND_ENDPOINT_T_OPAQUE frsh_send_endpoint_t;
+ typedef FRSH_RECEIVE_ENDPOINT_T_OPAQUE frsh_receive_endpoint_t;
+
+ /**
+ * The network_address type specifies the node or multicast address in
+ * a communication-protocol-independent way. The actual address is
+ * obtained via a configuration dependent mapping function
+ **/
+ typedef unsigned int frsh_network_address_t;
+
+ /**
+ * The port type specifies the information that is
+ * necessary to get in contact with the thread in the
+ * receiving node, in a protocol-independent way.
+ * The actual port number is obtained via a configuration
+ * dependent mapping function
+ **/
+ typedef unsigned int frsh_stream_id_t;
+
+ /**
+ * Extra information protocol dependent opaque for the application.
+ * It can be used in different places: contract negotiation, extra
+ * endpoint info, extra status info...
+ **/
+ typedef struct {
+ void *body;
+ int size;
+ } frsh_protocol_info_t;
+
+ /**
+ * Protocol dependent information about the status of an endpoint
+ **/
+ typedef struct {
+ void *body;
+ int size;
+ } frsh_protocol_status_t;
+
+ /**
+ * Protocol dependent information about extra parameters for
+ * send_endpoint definition.
+ **/
+ typedef struct {
+ void *body;
+ int size;
+ } frsh_send_endpoint_protocol_info_t;
+
+ /**
+ * Protocol dependent information about extra parameters for
+ * receive_endpoint definition.
+ **/
+ typedef struct {
+ void *body;
+ int size;
+ } frsh_receive_endpoint_protocol_info_t;
+
+ /**
+ * Algorithm used when the queue is full to choose the message to reject
+ **/
+ typedef enum {
+ /** A new message is admitted rejecting the oldest message in the
+ queue to make room for the newcomer **/
+ FRSH_QRP_OLDEST,
+
+ /** Incoming messages are rejected if the queue is full **/
+ FRSH_QRP_NEWCOMER
+ } frsh_queue_rejection_policy_t;
+
+ /**
+ * Queing information for endpoints
+ **/
+ typedef struct {
+ int queue_size; /** Size 0 means that there is no queue **/
+ frsh_queue_rejection_policy_t queue_policy;
+ } frsh_endpoint_queueing_info_t;
+
+
+ typedef enum {
+ /** Network works OK **/
+ FRSH_ENS_UP,
+
+ /** Network is down **/
+ FRSH_ENS_DOWN
+ } frsh_endpoint_network_status_t;
+
+ /*@}*/
+
+ FRSH_CPP_END_DECLS
+
+ #endif /* !FRSH_DISTRIBUTED_TYPES_H_ */
--- /dev/null
+ // -----------------------------------------------------------------------
+ // Copyright (C) 2006 - 2009 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
+ //
+ // FSF API web pages: http://marte.unican.es/fsf/docs
+ // http://shark.sssup.it/contrib/first/docs/
+ //
+ // This file is part of FRSH (FRescor ScHeduler)
+ //
+ // 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, 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_dynamic_reclaiming.h
+ //==============================================
+ // ******** ******* ******** ** **
+ // **///// /**////** **////// /** /**
+ // ** /** /** /** /** /**
+ // ******* /******* /********* /**********
+ // **//// /**///** ////////** /**//////**
+ // ** /** //** /** /** /**
+ // ** /** //** ******** /** /**
+ // // // // //////// // //
+ //
+ // FRSH(FRescor ScHeduler), pronounced "fresh"
+ //==============================================
+ #ifndef _FRSH_DYNAMIC_RECLAIMING_H_
+ #define _FRSH_DYNAMIC_RECLAIMING_H_
+
+ #include "frsh_core.h"
+
+ /**
+ * @file frsh_dynamic_reclaiming.h
+ *
+ * If this define is activated, dynamic reclaimation will be used
+ * after spare capacity allocation.
+ **/
+
+
+ #define FRSH_DYNAMIC_RECLAIMING_MODULE_SUPPORTED 1
+
+
+ #endif // _FRSH_DYNAMIC_RECLAIMING_H_
--- /dev/null
+ // -----------------------------------------------------------------------
+ // Copyright (C) 2006 - 2009 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
+ //
+ // FSF API web pages: http://marte.unican.es/fsf/docs
+ // http://shark.sssup.it/contrib/first/docs/
+ //
+ // This file is part of FRSH (FRescor ScHeduler)
+ //
+ // 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, 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_energy_management.h
+
+ //==============================================
+ // ******** ******* ******** ** **
+ // **///// /**////** **////// /** /**
+ // ** /** /** /** /** /**
+ // ******* /******* /********* /**********
+ // **//// /**///** ////////** /**//////**
+ // ** /** //** /** /** /**
+ // ** /** //** ******** /** /**
+ // // // // //////// // //
+ //
+ // FRSH(FRescor ScHeduler), pronounced "fresh"
+ //==============================================
+
+ #ifndef _FRSH_ENERGY_MANAGEMENT_H_
+ #define _FRSH_ENERGY_MANAGEMENT_H_
+
+ #include <time.h>
+
+ #include "frsh_energy_management_types.h"
+ #include "frsh_core_types.h"
+
+ FRSH_CPP_BEGIN_DECLS
+
+ #define FRSH_ENERGY_MANAGEMENT_MODULE_SUPPORTED 1
+
+ /**
+ * @file frsh_energy_management.h
+ **/
+
+ /**
+ * @defgroup energymgmnt Energy Management Module
+ *
+ * This module provides the ability to specify different budgets for
+ * different power levels.
+ *
+ * We model the situation by specifying budget values per power
+ * level. Thus switching in the power-level would be done by changing
+ * the budget of the vres. In all cases the period remains the same.
+ *
+ * All global FRSH contract operations (those done with the core
+ * module without specifying the power level) are considered to be
+ * applied to the higest power level, corresponding to a power_level_t
+ * value of 0.
+ *
+ * @note
+ * For all functions that operate on a contract, the resource is
+ * implicitly identified by the contract core parameters resource_type
+ * and resource_id that are either set through the
+ * frsh_contract_set_resource_and_label() function, or implicitly
+ * defined if no such call is made.
+ *
+ * @note
+ * For the power level management operations, only
+ * implementation for resource_type = FRSH_RT_PROCESSOR is mandatory,
+ * if the energy management module is present.
+ *
+ * @{
+ *
+ **/
+
+
+
+ //////////////////////////////////////////////////////////////////////
+ // CONTRACT SERVICES
+ //////////////////////////////////////////////////////////////////////
+
+
+ /**
+ * frsh_contract_set_min_expiration()
+ *
+ * This function sets the minimum battery expiration time that the
+ * system must be able to sustain without finishing battery power. A
+ * value of (0,0) would mean that the application does not have such
+ * requirement (this is the default if this parameter is not explicitly
+ * set).
+ **/
+ int frsh_contract_set_min_expiration(frsh_contract_t *contract,
+ frsh_rel_time_t min_expiration);
+
+ /**
+ * frsh_contract_get_min_expiration()
+ *
+ * Get version of the previous function.
+ **/
+ int frsh_contract_get_min_expiration(const frsh_contract_t *contract,
+ frsh_rel_time_t *min_expiration);
+
+ /**
+ * frsh_contract_set_min_budget_pow()
+ *
+ * Here we specify the minimum budget value corresponding to a single
+ * power level.
+ *
+ * @param contract The affected contract.
+ * @param power_level The power level for which we are specifying the minimum budget.
+ * @param pow_min_budget The minimum budget requested for the power level.
+ *
+ * @return 0 if no error \n
+ * FRSH_ERR_BAD_ARGUMENT if power_level is greater than or equal to the value
+ * returned by frsh_get_power_levels budget value is not correct.
+ *
+ * @note
+ * If the minimum budget relative to one or more power levels has not been specified, then
+ * the framework may attempt to perform interpolation of the supplied values in
+ * order to infer them, if an accurate model for such operation is available.
+ * Otherwise, the contract is rejected at frsh_negotiate() time.
+ **/
+ int frsh_contract_set_min_budget_pow(frsh_contract_t *contract,
+ frsh_power_level_t power_level,
+ const frsh_rel_time_t *pow_min_budget);
+
+ /**
+ * frsh_contract_get_min_budget_pow()
+ *
+ * Get version of the previous function.
+ **/
+ int frsh_contract_get_min_budget_pow(const frsh_contract_t *contract,
+ frsh_power_level_t power_level,
+ frsh_rel_time_t *pow_min_budget);
+
+ /**
+ * frsh_contract_set_max_budget_pow()
+ *
+ * Here we specify the maximum budget for a single power level.
+ *
+ * @param contract The affected contract object.
+ * @param power_level The power level for which we are specifying the maximum budget.
+ * @param pow_max_budget The maximum budget requested for the power level.
+ *
+ * @return 0 if no error \n
+ * FRSH_ERR_BAD_ARGUMENT if any of the pointers is NULL or the
+ * budget values don't go in ascending order.
+ *
+ **/
+ int frsh_contract_set_max_budget_pow(frsh_contract_t *contract,
+ frsh_power_level_t power_level,
+ const frsh_rel_time_t *pow_max_budget);
+
+ /**
+ * frsh_contract_get_max_budget_pow()
+ *
+ * Get version of the previous function.
+ **/
+ int frsh_contract_get_max_budget_pow(const frsh_contract_t *contract,
+ frsh_power_level_t power_level,
+ frsh_rel_time_t *pow_max_budget);
+
+
+ /**
+ * frsh_contract_set_utilization_pow()
+ *
+ * This function should be used for contracts with a period of
+ * discrete granularity. Here we specify, for each allowed period,
+ * the budget to be used for each power level.
+ *
+ * @param contract The affected contract object.
+ * @param power_level The power level for which we specify budget and period.
+ * @param budget The budget to be used for the supplied power level and period.
+ * @param period One of the allowed periods (from the discrete set).
+ * @param period The deadline used with the associated period (from the discrete set).
+ **/
+ int frsh_contract_set_utilization_pow(frsh_contract_t *contract,
+ frsh_power_level_t power_level,
+ const frsh_rel_time_t *budget,
+ const frsh_rel_time_t *period,
+ const frsh_rel_time_t *deadline);
+
+ /**
+ * frsh_contract_get_utilization_pow()
+ *
+ * Get version of the previous function.
+ **/
+ int frsh_contract_get_utilization_pow(const frsh_contract_t *contract,
+ frsh_power_level_t power_level,
+ frsh_rel_time_t *budget,
+ frsh_rel_time_t *period,
+ frsh_rel_time_t *deadline);
+
+
+ //////////////////////////////////////////////////////////////////////
+ // MANAGING THE POWER LEVEL
+ //////////////////////////////////////////////////////////////////////
+
+ /**
+ * frsh_resource_set_power_level()
+ *
+ * Set the power level of the resource identified by the supplied type and id.
+ *
+ * @note
+ * Only implementation for resource_type = FRSH_RT_PROCESSOR is mandatory,
+ * if the energy management module is present.
+ **/
+ int frsh_resource_set_power_level(frsh_resource_type_t resource_type,
+ frsh_resource_id_t resource_id,
+ frsh_power_level_t power_level);
+
+ /**
+ * frsh_resource_get_power_level()
+ *
+ * Get version of the previous function.
+ **/
+ int frsh_resource_get_power_level(frsh_resource_type_t resource_type,
+ frsh_resource_id_t resource_id,
+ frsh_power_level_t *power_level);
+
+ /**
+ * frsh_resource_get_speed()
+ *
+ * Get in speed_ratio representative value for the speed of the specified
+ * resource, with respect to the maximum possible speed for such resource.
+ *
+ * @note
+ * Only implementation for resource_type = FRSH_RT_PROCESSOR is mandatory,
+ * if the energy management module is present.
+ **/
+ int frsh_resource_get_speed(frsh_resource_type_t resource_type,
+ frsh_resource_id_t resource_id,
+ frsh_power_level_t power_level,
+ double *speed_ratio);
+
+ /**
+ * frsh_resource_get_num_power_levels()
+ *
+ * Get the number of power levels available for the resource identified
+ * by the supplied type and id.
+ *
+ * @note
+ * The power levels that may be used, for the identified resource,
+ * in other functions through a power_level_t type, range from 0
+ * to the value returned by this function minus 1.
+ *
+ * @note
+ * The power level 0 identifies the configuration with the maximum
+ * performance (and energy consumption) for the resource.
+ *
+ * @note
+ * Only implementation for resource_type = FRSH_RT_PROCESSOR is mandatory,
+ * if the energy management module is present.
+ */
+ int frsh_resource_get_num_power_levels(frsh_resource_type_t resource_type,
+ frsh_resource_id_t resource_id,
+ int *num_power_levels);
+
+ //////////////////////////////////////////////////////////////////////
+ // BATTERY EXPIRATION AND MANAGING POWER LEVELS
+ //////////////////////////////////////////////////////////////////////
+
+ /* /\** IS THIS NEEDED AT ALL ? I GUESS NOT - COMMENTED */
+ /* * frsh_resource_get_battery_expiration() */
+ /* * */
+ /* * Get the foreseen expiration time of the battery for the resource */
+ /* * identified by the supplied type and id. */
+ /* * */
+ /* int frsh_battery_get_expiration(frsh_resource_type_t resource_type, */
+ /* frsh_resource_id_t resource_id, */
+ /* frsh_rel_time_t *expiration); */
+
+ /**
+ * frsh_battery_get_expiration()
+ *
+ * Get the foreseen expiration time of the system battery(ies).
+ **/
+ int frsh_battery_get_expiration(frsh_abs_time_t *expiration);
+
+ /*@}*/
+
+ FRSH_CPP_END_DECLS
+
+ #endif /* _FRSH_ENERGY_MANAGEMENT_H_ */
--- /dev/null
+ // -----------------------------------------------------------------------
+ // Copyright (C) 2006 - 2009 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
+ //
+ // FSF API web pages: http://marte.unican.es/fsf/docs
+ // http://shark.sssup.it/contrib/first/docs/
+ //
+ // This file is part of FRSH (FRescor ScHeduler)
+ //
+ // 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, 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_energy_management_types.h
+ //==============================================
+ // ******** ******* ******** ** **
+ // **///// /**////** **////// /** /**
+ // ** /** /** /** /** /**
+ // ******* /******* /********* /**********
+ // **//// /**///** ////////** /**//////**
+ // ** /** //** /** /** /**
+ // ** /** //** ******** /** /**
+ // // // // //////// // //
+ //
+ // FRSH(FRescor ScHeduler), pronounced "fresh"
+ //==============================================
+ #ifndef FRSH_ENERGY_MANAGEMENT_TYPES_H_
+ #define FRSH_ENERGY_MANAGEMENT_TYPES_H_
+
+ #include <time.h>
+ #include "frsh_core_types.h"
+
+ FRSH_CPP_BEGIN_DECLS
+
+ /**
+ * @file frsh_energy_management_types.h
+ **/
+
+ /**
+ * @addtogroup energymgmnt
+ *
+ * @{
+ **/
+
+
+
+
+ /**
+ * Here we define the different power levels. They will be
+ * used as index to the budget arrays in energy management.
+ **/
+ typedef enum {
+ FRSH_PLT_HIGH = 0,
+ FRSH_PLT_MEDIUM = 1,
+ FRSH_PLT_LOW = 2
+ } frsh_power_level_t;
+
+
+ /**
+ * Here we define a capacity specification for all power levels.
+ **/
+ typedef struct {
+ frsh_rel_time_t budget[3];
+ frsh_rel_time_t period;
+ } frsh_utilization_line_pow_t;
+
+ /**
+ * Here we define the utilization set for different power levels
+ **/
+ typedef struct {
+ int size;
+ frsh_utilization_line_pow_t utilizations[FRSH_MAX_N_UTILIZATION_VALUES];
+ } frsh_utilization_set_pow_t;
+
+ FRSH_CPP_END_DECLS
+
+ #endif /* !FRSH_ENERGY_MANAGEMENT_TYPES_H_ */
--- /dev/null
+ // -----------------------------------------------------------------------
+ // Copyright (C) 2006 - 2009 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
+ //
+ // FSF API web pages: http://marte.unican.es/fsf/docs
+ // http://shark.sssup.it/contrib/first/docs/
+ //
+ // This file is part of FRSH (FRescor ScHeduler)
+ //
+ // 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, 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_error.h
+ //==============================================
+ // ******** ******* ******** ** **
+ // **///// /**////** **////// /** /**
+ // ** /** /** /** /** /**
+ // ******* /******* /********* /**********
+ // **//// /**///** ////////** /**//////**
+ // ** /** //** /** /** /**
+ // ** /** //** ******** /** /**
+ // // // // //////// // //
+ //
+ // FRSH(FRescor ScHeduler), pronounced "fresh"
+ //==============================================
+
+ #ifndef FRSH_ERROR_H_
+ #define FRSH_ERROR_H_
+
+ #ifdef __cplusplus
+ extern "C" {
+ #endif
+
+ /**
+ * @file frsh_error.h
+ **/
+
+ /**
+ * addtogroup core
+ *
+ * @{
+ **/
+
+ /* Error codes */
+ #define FRSH_NO_ERROR 0
+
+ #define FRSH_ERR_BASE_VALUE 0x02004000
+
+ #define FRSH_ERR_TOO_MANY_TASKS 0x02004001
+ #define FRSH_ERR_BAD_ARGUMENT 0x02004002
+ #define FRSH_ERR_INVALID_SYNCH_OBJ_HANDLE 0x02004003
+ #define FRSH_ERR_NO_RENEGOTIATION_REQUESTED 0x02004004
+ #define FRSH_ERR_CONTRACT_REJECTED 0x02004005
+ #define FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD 0x02004006
+ #define FRSH_ERR_NOT_BOUND 0x02004007
+ #define FRSH_ERR_UNKNOWN_SCHEDULED_THREAD 0x02004008
+ #define FRSH_ERR_NOT_CONTRACTED_VRES 0x02004009
+ #define FRSH_ERR_NOT_SCHEDULED_THREAD 0x0200400A
+ #define FRSH_ERR_TOO_MANY_SERVICE_JOBS 0x0200400B
+ #define FRSH_ERR_TOO_MANY_SYNCH_OBJS 0x0200400C
+ #define FRSH_ERR_TOO_MANY_VRES_IN_SYNCH_OBJ 0x0200400D
+ #define FRSH_ERR_TOO_MANY_EVENTS_IN_SYNCH_OBJ 0x0200400E
+ #define FRSH_ERR_INTERNAL_ERROR 0x0200400F
+ #define FRSH_ERR_TOO_MANY_VRES 0x02004010
+ #define FRSH_ERR_INVALID_SCHEDULER_REPLY 0x02004011
+ #define FRSH_ERR_TOO_MANY_PENDING_REPLENISHMENTS 0x02004012
+ #define FRSH_ERR_SYSTEM_ALREADY_INITIALIZED 0x02004013
+ #define FRSH_ERR_SHARED_OBJ_ALREADY_INITIALIZED 0x02004014
+ #define FRSH_ERR_SHARED_OBJ_NOT_INITIALIZED 0x02004015
+ #define FRSH_ERR_SCHED_POLICY_NOT_COMPATIBLE 0x02004016
+ #define FRSH_ERR_VRES_WORKLOAD_NOT_COMPATIBLE 0x02004017
+ #define FRSH_ERR_ALREADY_BOUND 0x02004018
+ #define FRSH_ERR_RESOURCE_ID_INVALID 0x02004019
+ #define FRSH_ERR_TOO_LARGE 0x0200401A
+ #define FRSH_ERR_BUFFER_FULL 0x0200401B
+ #define FRSH_ERR_NO_SPACE 0x0200401C
+ #define FRSH_ERR_NO_MESSAGES 0x0200401D
+ #define FRSH_WRN_MODULE_NOT_SUPPORTED 0x0200401E
+ #define FRSH_ERR_NOT_INITIALIZED 0x0200401F
+ #define FRSH_ERR_TOO_MANY_SHARED_OBJS 0x02004020
+ #define FRSH_ERR_CONTRACT_LABEL_ALREADY_EXISTS 0x02004021
+ #define FRSH_ERR_BUDGET_EXPIRED 0x02004022
+ #define FRSH_ERR_SHARED_OBJECT_NOT_PROTECTED 0x02004023
+ #define FRSH_ERR_NOT_IMPLEMENTED 0x02004024
+ #define FRSH_ERR_CONTRACT_TYPE_NOT_COMPATIBLE 0x02004025
+ #define FRSH_ERR_CAPACITY_NOT_DECREASING 0x02004026
+ #define FRSH_ERR_CONTRACT_LABEL_UNKNOWN 0x02004027
+ #define FRSH_ERR_OUT_OF_BUDGET 0x02004028
+ #define FRSH_ERR_ALREADY_IN_FRSH 0x02004029
+
+ #define FRSH_ERR_LAST_VALUE 0x02004030
+
+
+
+ #ifdef AQuoSA
+ #define my_frsh_perror(nn,ss) do { errno = nn; perror(ss); } while(0)
+ #else
+ #define my_frsh_perror(nn,ss) do { perror(ss); } while(0)
+ #endif
+
+ #define ERROR(nn,ss) do {if(nn>FRSH_ERR_BASE_VALUE) my_frsh_strerror(nn, ss); else { my_frsh_perror(nn, ss); } exit (nn);} while (0)
+
+
+ int frsh_strerror (int error, char *message, size_t size);
+ void my_frsh_strerror(int error, char *sss);
+
+ /**
+ * This str_helper is needed to ensure argument expansion,
+ * see http://www.iar.com/p180591/p180591_eng.php
+ **/
+ #define STR_HELPER(x) #x
+
+ /**
+ * PERROR_FRESCOR
+ *
+ * This macro checks the given error number and composes a messages accordingly.
+ *
+ * @param nn Error number
+ * @param ss Error string (to be appended to FRSH or system error string)
+ **/
+ #define PERROR_FRESCOR(_nn_,_ss_) do { \
+ \
+ char error_string[1024]; \
+ \
+ sprintf(error_string, "File: %s, in function %s at line %d, error %d: %s\n", __FILE__, __FUNCTION__, __LINE__, (_nn_), _ss_); \
+ \
+ if( (_nn_)>FRSH_ERR_BASE_VALUE ) { \
+ my_frsh_strerror( (_nn_), error_string); \
+ } else { \
+ my_frsh_perror(_nn_, error_string); \
+ } \
+ } while(0)
+
+
+
+ /**
+ * PERROR_AND_RETURN
+ *
+ * Macro that displays an error code and message and then returns from
+ * the current function
+ *
+ * @param nn Error number
+ * @param ss Error string (to be appended to FRSH or system error string)
+ **/
+ #define PERROR_AND_RETURN(nn,ss) do { \
+ PERROR_FRESCOR(nn, ss); \
+ return (nn); \
+ } while (0)
+
+
+
+
+ /**
+ * PERROR_AND_EXIT
+ *
+ * Macro that displays an error code and message and then aborts the
+ * program.
+ *
+ * @param nn Error number
+ * @param ss Error string (to be appended to FRSH or system error string)
+ **/
+ #define PERROR_AND_EXIT(nn,ss) do { \
+ PERROR_FRESCOR(nn,ss); \
+ exit(nn); \
+ } while (0)
+
+
+ /**
+ * PRW: Perror and Return Wrapper
+ *
+ * Function that calls funccall and checks the result != 0.
+ * In case of error it displays the error code with the function call
+ * as extra error string and returns from the function.
+ *
+ * terror (int) needs to be visible in the point of call.
+ *
+ * @param funccall Code to execute that should return 0 in a non error
+ * case.
+ **/
+ #define PRW(funccall) do { \
+ if ( (terror = funccall ) != 0) \
+ { \
+ PERROR_AND_RETURN( terror, STR_HELPER(funccall) ); \
+ } \
+ } while(0)
+
+
+
+ /**
+ * PXW: Perror and eXit Wrapper
+ *
+ * Function that calls funccall and checks the result != 0.
+ * In case of error it displays the error code with the function call
+ * as extra error string and ABORTS the program.
+ *
+ * terror (int) needs to be visible in the point of call.
+ *
+ * @param funccall Code to execute that should return 0 in a non error
+ * case.
+ **/
+ #define PXW(funccall) do { \
+ if ( (terror = funccall ) != 0) \
+ { \
+ PERROR_AND_EXIT( terror, STR_HELPER(funccall) ); \
+ } \
+ } while(0)
+
+
+
+ /**
+ * PERROR_KERN_AND_EXIT
+ *
+ * Function that displays an error code and message and then aborts the
+ * program.
+ *
+ * @param nn Error number
+ * @param ss Error string (to be appended to FRSH or system error string)
+ **/
+ #define PERROR_KERN_AND_EXIT(nn, ss) do { \
+ errno = errno ? errno : (nn); \
+ kern_printf(ss); \
+ exit(nn); \
+ } while (0)
+
+
+
+
+ /*}*/
+
+ #ifdef __cplusplus
+ }
+ #endif
+
+
+ #endif /* !FRSH_ERROR_H_ */
--- /dev/null
+ // -----------------------------------------------------------------------
+ // Copyright (C) 2006 - 2009 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
+ //
+ // FSF API web pages: http://marte.unican.es/fsf/docs
+ // http://shark.sssup.it/contrib/first/docs/
+ //
+ // This file is part of FRSH (FRescor ScHeduler)
+ //
+ // 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, 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_feedback_control.h
+
+ //==============================================
+ // ******** ******* ******** ** **
+ // **///// /**////** **////// /** /**
+ // ** /** /** /** /** /**
+ // ******* /******* /********* /**********
+ // **//// /**///** ////////** /**//////**
+ // ** /** //** /** /** /**
+ // ** /** //** ******** /** /**
+ // // // // //////// // //
+ //
+ // FRSH(FRescor ScHeduler), pronounced "fresh"
+ //==============================================
+
+ #ifndef _FRSH_FEEDBACK_CONTROL_H_
+ #define _FRSH_FEEDBACK_CONTROL_H_
+
+ #include <time.h>
+
+ //#include "frsh_feedback_control_types.h"
+ #include "frsh_core_types.h"
+
+ FRSH_CPP_BEGIN_DECLS
+
+ #define FRSH_FEEDBACKCTRL_MODULE_SUPPORTED 1
+
+ /**
+ * @file frsh_feedback_control.h
+ **/
+
+ /**
+ * @defgroup feedbackctrl Feedback Control Module
+ *
+ * This module provides a way to implement a QoS manager at the
+ * application level.
+ *
+ * @note
+ * Please, note that, in order to exploit the feedback-scheduling
+ * functionality of FRESCOR, an application needs to use a set of
+ * different functions:
+ * <ul>
+ * <li>the frsh_contract_set_basic_params() and the
+ * frsh_contract_set_reclamation_params() functions are used
+ * to set the dynamic variability range (or options) for the budget;
+ * <li>the frsh_feedback_set_spare() function is used to communicate to
+ * the FMGR module what is the spare virtual resource that is used
+ * to reserve a fraction of resource availability by FMGR-enabled
+ * applications, so to avoid a complete occupation of the system
+ * (this is needed in common cases if one wants to keep a good
+ * performance of the QoS control loops);
+ * such spare vres needs to have been previously negotiated through
+ * the usual functions in the FRSH Core module;
+ * <li>the frsh_feedback_set_desired_budget() function is used to
+ * dynamically fine-tune the budget request for the application,
+ * leaving to the FMGR module the freedom to fulfill the requests
+ * made by all the applications in the system according to global
+ * QoS control goals, as well as to the importance and weight
+ * parameters that may be specified by the applications for individual
+ * virtual resources.
+ * </ul>
+ *
+ * @{
+ *
+ **/
+
+ /**
+ * frsh_feedback_set_spare()
+ *
+ * This function is used to tell the FRSH FEEDBACKCTRL module what is
+ * the spare contract that is used as a "reserve" of computation
+ * resources that may be used by other contracts making use of adaptive
+ * reservations.
+ *
+ * @note
+ * No threads must be ever attached to the contract identified by
+ * spare_id. If this happens, behaviour is unspecified.
+ *
+ * @note
+ * This function must be called only once. If it is called more than
+ * once, then the behaviour is unspecified.
+ **/
+ int frsh_feedback_set_spare(const frsh_contract_t *spare_contract);
+
+ /**
+ * frsh_feedback_get_spare()
+ *
+ * Get version of the frsh_feedback_set_spare() function.
+ **/
+ int frsh_feedback_get_spare(frsh_contract_t *spare_contract);
+
+ /**
+ * frsh_feedback_set_desired_budget()
+ *
+ * This function sets the budget request that would best suite the
+ * needs of the application for the very next server periods. The
+ * budget actually used for the vres instances (application jobs),
+ * that may be retrieved through a frsh_feedback_get_actual_budget() call,
+ * is dynamically changed by the FMGR Module, and may be less than
+ * the required value, as due to the following rules:
+ *
+ * <ul>
+ * <li>if the required budget is less than the minimum guaranteed
+ * negotiated for the vres, then it is always granted;
+ * <li>if the set of requested budgets is schedulable, then all the
+ * requests are granted, except for what stated in the note below;
+ * <li>if the set of requested budgets overcomes the resource capacity
+ * and the required budget is higher than the minimum guaranteed
+ * negotiated for the vres, then the FMGR module makes an attempt to
+ * fulfill the application request by using also the spare computation
+ * resources that have been reserved through the
+ * frsh_feedback_set_spare() call.
+ * </ul>
+ *
+ * Before any frsh_feedback_set_desired_budget() call, the desired budget
+ * is assumed to be equal to the maximum budget value set during contract
+ * negotiation.
+ *
+ * @note
+ * If the requested budget is higher than the maximum value negotiated
+ * for the vres, then an error is returned.
+ *
+ * @note
+ * The actual budget that is used for a vres may change dynamically
+ * and asynchronously with respect to the threads attached to the vres,
+ * due to other contracts being negotiated, renegotiated or terminated,
+ * or due the call of the frsh_feedback_set_desired_budget() function
+ * for other virtual resources.
+ *
+ * @param[in] p_budget_in
+ * The new budget to set as desired.
+ **/
+ int frsh_feedback_set_desired_budget(frsh_vres_id_t vres_id, frsh_rel_time_t *p_budget_in);
+
+ /**
+ * frsh_feedback_get_desired_budget()
+ *
+ * Get version of the frsh_feedback_set_desired_budget() function.
+ *
+ * @param[out] p_budget_out
+ * The last budget set as desired through a frsh_feedback_set_desired_budget()
+ * call, or the maximum budget set during contract negotiation, if no such
+ * call ever occurred.
+ **/
+ int frsh_feedback_get_desired_budget(frsh_vres_id_t vres_id, frsh_rel_time_t *p_budget_out);
+
+ /**
+ * frsh_feedback_get_actual_budget()
+ *
+ * Retrieve the actual budget that is being dynamically used by the FMGR module for
+ * the specified vres. The value returned by this function (in the budget parameter)
+ * for a given vres may change dynamically as a result of a call to the
+ * frsh_feedback_set_desired_budget() function for the same or other virtual resources.
+ **/
+ int frsh_feedback_get_actual_budget(frsh_vres_id_t vres_id, frsh_rel_time_t *budget);
+
+ /*@}*/
+
+
+ FRSH_CPP_END_DECLS
+
+ #endif
--- /dev/null
+ // -----------------------------------------------------------------------
+ // Copyright (C) 2006 - 2009 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
+ //
+ // FSF API web pages: http://marte.unican.es/fsf/docs
+ // http://shark.sssup.it/contrib/first/docs/
+ //
+ // This file is part of FRSH (FRescor ScHeduler)
+ //
+ // 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, 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(FRescor ScHeduler), pronounced "fresh"
+ //==============================================
+
+ #ifndef FRSH_FEEDBACK_CONTROL_TYPES_H_
+ #define FRSH_FEEDBACK_CONTROL_TYPES_H__
+
+ #include <time.h>
+ #include "frsh_opaque_types.h"
+ #include "frsh_configuration_parameters.h"
+
+ FRSH_CPP_BEGIN_DECLS
+ /**
+ * @file frsh_feedback_control_types.h
+ **/
+
+ /**
+ * @addtogroup feedbackctrl
+ *
+ * @{
+ **/
+
+ /**
+ * Integer type from 0 to 100 representing the percentage of spare
+ * capacity that will be allocated for feedbackctrl
+ **/
+ typedef int frsh_spare_subset_t;
+
+ /*@}*/
+
+ FRSH_CPP_END_DECLS
+
+ #endif /* !FRSH_FEEDBACK_CONTROL_TYPES_H_ */
--- /dev/null
+ // -----------------------------------------------------------------------
+ // Copyright (C) 2006 - 2009 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
+ //
+ // FSF API web pages: http://marte.unican.es/fsf/docs
+ // http://shark.sssup.it/contrib/first/docs/
+ //
+ // This file is part of FRSH (FRescor ScHeduler)
+ //
+ // 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, 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_hierarchical.h
+
+ //==============================================
+ // ******** ******* ******** ** **
+ // **///// /**////** **////// /** /**
+ // ** /** /** /** /** /**
+ // ******* /******* /********* /**********
+ // **//// /**///** ////////** /**//////**
+ // ** /** //** /** /** /**
+ // ** /** //** ******** /** /**
+ // // // // //////// // //
+ //
+ // FRSH(FRescor ScHeduler), pronounced "fresh"
+ //==============================================
+ #ifndef _FRSH_HIERARCHICAL_H_
+ #define _FRSH_HIERARCHICAL_H_
+
+ #include <time.h>
+ #include "frsh_hierarchical_types.h"
+ #include "frsh_core.h"
+
+ FRSH_CPP_BEGIN_DECLS
+
+ #define FRSH_HIERARCHICAL_MODULE_SUPPORTED 1
+
+ /**
+ * @file frsh_hierarchical.h
+ **/
+
+ /**
+ * @defgroup hierarchical Hierarchical Scheduling Module
+ *
+ * This module includes the types and functions to use local
+ * schedulers within vres allowing to attach more than one thread
+ * to a vres and define an scheduling policy within.
+ *
+ * @{
+ **/
+
+ /**
+ * frsh_local_scheduler_init()
+ *
+ * This call has the following effects:
+ * FP: none \n
+ * EDF: none \n
+ * TABLE_DRIVEN :
+ * Records the schedule duration, and starts the
+ * schedule at the time of the call. After the
+ * schedule duration has elapsed, the schedule in
+ * the table is repeated.
+ *
+ * @return 0 if no error \n
+ * FRSH_ERR_BAD_ARGUMENT : if the value of the vres argument is not in range,
+ * or info 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 of the calling thread
+ * has been cancelled or it is not valid
+ **/
+ int frsh_local_scheduler_init(
+ frsh_vres_id_t vres,
+ frsh_sched_init_info_t info);
+
+
+ /**
+ * frsh_contract_set_sched_policy()
+ *
+ * The operation updates the specified contract parameters object by
+ * setting its scheduling policy to the specified input parameter.
+ * The default policy is FRSH_NONE, which means that only one thread
+ * may be bound to the vres
+ *
+ * @return 0 if no error \n
+ * FRSH_ERR_BAD_ARGUMENT : if sched_policy is not in range,
+ * or contract is NULL
+ **/
+ int frsh_contract_set_sched_policy
+ (frsh_contract_t *contract,
+ frsh_sched_policy_t sched_policy);
+
+
+ /**
+ * frsh_contract_get_sched_policy()
+ *
+ * This operation obtains from the specified contract parameters
+ * object its scheduling policy, and copies it to the place pointed to
+ * by the corresponding input parameter.
+ *
+ * @return 0 if no error \n
+ * FRSH_ERR_BAD_ARGUMENT : if sched_policy or contract are NULL
+ **/
+ int frsh_contract_get_sched_policy
+ (const frsh_contract_t *contract,
+ frsh_sched_policy_t *sched_policy);
+
+
+ /**
+ * frsh_thread_create_local()
+ *
+ * This operation creates a thread and binds it to the specified
+ * vres, which must have a policy different than FRSH_NONE. The new
+ * thread is created with the arguments thread, attr, thread_code and
+ * arg as they are defined for the pthread_create() POSIX function
+ * call, and its local scheduling parameters are set to the value
+ * stored in the variable pointed to by sched_params, which must be
+ * compatible with the vres's scheduling policy. Then, the function
+ * binds the created thread to the new vres. The attr /parameter is
+ * overwritten as necessary to introduce the adequate scheduling
+ * policy and priority, according to the preemption level given in the
+ * contract and the frsh_priority_map() function defined by the user.
+ *
+ * @return 0 if no error \n
+ * FRSH_ERR_BAD_ARGUMENT : if the value of the vres argument is not in range,
+ * or sched_params is NULL \n
+ * FRSH_ERR_SCHED_POLICY_NOT_COMPATIBLE : if the scheduling policy
+ * in sched_params is not compatible to the vres's one \n
+ * FRSH_ERR_INTERNAL_ERROR : erroneous binding or malfunction of the FRSH
+ * main scheduler \n
+ * FRSH_ERR_NOT_CONTRACTED_VRES : if the referenced vres is not
+ * valid \n
+ * FRSH_ERR_VRES_WORKLOAD_NOT_COMPATIBLE: if the kind of workload
+ * of the vres is FRSH_OVERHEAD \n
+ * .
+ * It may also return any of the errors that may be returned by the
+ * pthread_create()POSIX function call
+ **/
+ int frsh_thread_create_local(frsh_vres_id_t vres,
+ frsh_sched_params_t *sched_params,
+ frsh_thread_id_t *thread,
+ frsh_thread_attr_t *attr,
+ frsh_thread_code_t thread_code,
+ void *arg);
+
+ /**
+ * frsh_thread_bind_local()
+ *
+ * This operation associates a thread with a vres, which must have a
+ * policy different than FRSH_NONE. The thread's local scheduling
+ * parameters are set to the value stored in the variable pointed to
+ * by sched_params, which must be compatible with the vres's
+ * scheduling policy. After the call the thread starts consuming the
+ * vres's budget and is executed according to the contract
+ * established for that vres and to its scheduling policy. If the
+ * thread was already bound to another vres, it is effectively
+ * unbound from it and bound to the specified one.
+ *
+ * Implementation dependent issue: In order to allow the usage of
+ * application defined schedulers, the given thread must not have the
+ * scheduling policy SCHED_APP and at the same time be attached to an
+ * application scheduler different than the frsh scheduler.
+ *
+ * @return 0 if no error \n
+ * FRSH_ERR_BAD_ARGUMENT : if the vres argument does not complain with
+ * the expected format or valid range, the given thread does not exist,
+ * or sched_params is NULL \n
+ * FRSH_ERR_SCHED_POLICY_NOT_COMPATIBLE : if the scheduling policy
+ * in sched_params is not compatible to the vres's one. \n
+ * FRSH_ERR_INTERNAL_ERROR : erroneous binding or malfunction of the FRSH
+ * main scheduler \n
+ * FRSH_ERR_UNKNOWN_APPSCHEDULED_THREAD : if the thread is attached to
+ * an application defined scheduler different than the frsh
+ * scheduler \n
+ * FRSH_ERR_NOT_CONTRACTED_VRES : if the referenced vres is not
+ * valid \n
+ * FRSH_ERR_VRES_WORKLOAD_NOT_COMPATIBLE: if the kind of workload
+ * of the vres is FRSH_OVERHEAD
+ **/
+ int frsh_thread_bind_local(frsh_vres_id_t vres,
+ frsh_thread_id_t thread,
+ frsh_sched_params_t *sched_params);
+
+
+ /**
+ * frsh_thread_set_local_sched_params()
+ *
+ * This function changes the local scheduling parameters of the thread
+ * to the value pointed to by sched_params. This value must be
+ * compatible with the scheduling policy of the vres to which the
+ * thread is bound.
+ *
+ * @return 0 if no error \n
+ * FRSH_ERR_BAD_ARGUMENT : if the given thread does not exist,
+ * or sched_params is NULL \n
+ * FRSH_ERR_SCHED_POLICY_NOT_COMPATIBLE : if the thread is already bound
+ * and the scheduling policy in sched_params is not compatible to the
+ * one of the thread's vres. \n
+ * FRSH_ERR_NOT_SCHEDULED_THREAD : if the given thread is not scheduled
+ * under FRSH \n
+ * FRSH_ERR_INTERNAL_ERROR : erroneous binding or malfunction of the FRSH
+ * main scheduler \n
+ * FRSH_ERR_UNKNOWN_APPSCHEDULED_THREAD : if the thread is attached to
+ * an application defined scheduler different than the frsh
+ * scheduler \n
+ * FRSH_ERR_NOT_CONTRACTED_VRES : if the thread is bound and its vres
+ * is not valid
+ **/
+ int frsh_thread_set_local_sched_params (frsh_thread_id_t thread,
+ const frsh_sched_params_t *sched_params);
+
+ /**
+ * frsh_thread_get_local_sched_params()
+ *
+ * This function stores the local scheduling parameters of the
+ * specified thread in the variable pointed to by sched_params.
+ *
+ * @return 0 if no error \n
+ * FRSH_ERR_BAD_ARGUMENT : if sched_params is NULL or the thread does
+ * not exist \n
+ * FRSH_ERR_NOT_SCHEDULED_THREAD : if the given thread is not scheduled
+ * under FRSH
+ **/
+ int frsh_thread_get_local_sched_params(frsh_thread_id_t thread,
+ frsh_sched_params_t *sched_params);
+
+ /*}*/
+
+ FRSH_CPP_END_DECLS
+
+ #endif // _FRSH_HIERARCHICAL_H_
--- /dev/null
+ // -----------------------------------------------------------------------
+ // Copyright (C) 2006 - 2009 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
+ //
+ // FSF API web pages: http://marte.unican.es/fsf/docs
+ // http://shark.sssup.it/contrib/first/docs/
+ //
+ // This file is part of FRSH (FRescor ScHeduler)
+ //
+ // 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, 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(FRescor ScHeduler), pronounced "fresh"
+ //==============================================
+ #ifndef FRSH_HIERARCHICAL_TYPES_H_
+ #define FRSH_HIERARCHICAL_TYPES_H_
+
+ /**
+ * @file frsh_hierarchical_types.h
+ **/
+
+ #include <time.h>
+
+ FRSH_CPP_BEGIN_DECLS
+
+ /**
+ * @addtogroup hierarchical
+ *
+ * @{
+ **/
+
+ /** Scheduling policies **/
+ typedef enum {FRSH_FP, FRSH_EDF, FRSH_TABLE_DRIVEN, FRSH_RR, FRSH_NONE}
+ frsh_sched_policy_t;
+
+ #define FRSH_DEFAULT_SCHED_POLICY FRSH_NONE
+
+ /**
+ * Scheduling policy and parameters
+ *
+ * The params member is a pointer to one of the
+ * following:
+ * FP: int (priority)
+ * EDF: frsh_rel_time_t (deadline)
+ * RR: none
+ * TABLE_DRIVEN : struct frsh_table_driven_params_t
+ **/
+ typedef struct {
+ frsh_sched_policy_t policy;
+ void * params;
+ } frsh_sched_params_t;
+
+
+ /**
+ * Scheduling parameters for the table-driven policy
+ * list of target windows
+ **/
+ typedef struct {
+ frsh_rel_time_t start;
+ frsh_rel_time_t end;
+ frsh_rel_time_t comp_time;
+ } frsh_target_window_t;
+
+ /**
+ * Container for a frsh_target_window array
+ **/
+ typedef struct {
+ int size;
+ frsh_target_window_t table[FRSH_MAX_N_TARGET_WINDOWS];
+ } frsh_table_driven_params_t;
+
+
+ /**
+ * Initialization information for a scheduling policy
+ *
+ * It shall be one of the following:
+ * FP: none
+ * EDF: none
+ * RR: frsh_rel_time_t (slice duration)
+ * TABLE_DRIVEN : frsh_rel_time_t (schedule duration)
+ **/
+ typedef void * frsh_sched_init_info_t;
+
+ /*}*/
+
+ FRSH_CPP_END_DECLS
+
+ #endif /* !FRSH_HIERARCHICAL_TYPES_H_ */
--- /dev/null
+ // -----------------------------------------------------------------------
+ // Copyright (C) 2006 - 2009 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
+ //
+ // FSF API web pages: http://marte.unican.es/fsf/docs
+ // http://shark.sssup.it/contrib/first/docs/
+ //
+ // This file is part of FRSH (FRescor ScHeduler)
+ //
+ // 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, 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_implementation_specific.h
+ //==============================================
+ // ******** ******* ******** ** **
+ // **///// /**////** **////// /** /**
+ // ** /** /** /** /** /**
+ // ******* /******* /********* /**********
+ // **//// /**///** ////////** /**//////**
+ // ** /** //** /** /** /**
+ // ** /** //** ******** /** /**
+ // // // // //////// // //
+ //
+ // FRSH(FRescor ScHeduler), pronounced "fresh"
+ //==============================================
+ #ifndef _FRSH_IMPLEMENTATION_SPECIFIC_H_
+ #define _FRSH_IMPLEMENTATION_SPECIFIC_H_
+
+ #include "frsh_implementation_specific_types.h"
+ #include "frsh_core.h"
+
+ #define FRSH_IMPLEMENTATION_SPECIFIC_MODULE_SUPPORTED 1
+
+ FRSH_CPP_BEGIN_DECLS
+
+ /**
+ * @file frsh_implementation_specific.h
+ *
+ **/
+
+ /**
+ * @defgroup implementationspec Implementation Specific module
+ *
+ * The operations defined in this module are of optional use. The
+ * intention is to provide better tunning options taking advantage of
+ * specific characteristics of the underlaying OS.
+ *
+ *
+ * e.g. being able to manually assign priorities assuming that the OS
+ * uses a fixed priority paradigm).
+ *
+ * @{
+ **/
+
+ /**
+ * frsh_contract_set_preemption_level()
+ *
+ * The operation updates the specified contract parameters object by
+ * setting its preemption level to the specified input parameter.
+ *
+ * OBSERVATION: if this value is changed being any contract that
+ * uses the resource already accepted, the system's behavior and
+ * particularly the acceptance tests correctness are not garantee
+ * and probably wrong.
+ *
+ **/
+ int frsh_contract_set_preemption_level
+ (frsh_contract_t *contract,
+ frsh_preemption_level_t preemption_level);
+
+
+ /**
+ * frsh_contract_get_preemption_level()
+ *
+ * The operation obtains from the specified contract parameters object
+ * its preemption level and copies it to the place pointed to by the
+ * specified input parameter.
+ **/
+ int frsh_contract_get_preemption_level
+ (const frsh_contract_t *contract,
+ frsh_preemption_level_t *preemption_level);
+
+ /**
+ * frsh_service_thread_set_preemption_level()
+ *
+ * This function sets the preemption level of the service thread to
+ * the specified value. The initial preemption level is a configurable
+ * parameter. This value is stored in a temporary variable and it is
+ * used the next time the service thread data is updated with the
+ * frsh_service_thread_set_data() function.
+ **/
+ int frsh_service_thread_set_preemption_level
+ (frsh_preemption_level_t preemption_level);
+
+ /**
+ * frsh_service_thread_get_preemption_level()
+ *
+ * This function stores the current preemption level of the service
+ * thread in the variable pointed to by preemption_level
+ **/
+ int frsh_service_thread_get_preemption_level
+ (frsh_preemption_level_t *preemption_level);
+
+
+ /**
+ * frsh_thread_exit()
+ *
+ * This operation shall terminate the calling thread, make the value
+ * value_ptr available to any successful join with the terminating
+ * thread, and unbind the thread from its associated vres. After
+ * cleaning up the thread management data, it is unbound and the
+ * scheduling policy is changed to fixed priority before the posix
+ * pthread_exit() function is called.
+ *
+ * There is a limitation in the current version of the
+ * MaRTE implementation that causes the information of a terminated
+ * thread to continue to be stored in the frsh scheduler, and the thread
+ * to continue to be counted in the number of threads. The
+ * frsh_thread_exit operation allows the implementation to delete the
+ * thread's information, and then terminate the thread. Therefore, it
+ * is recommended to use this function to terminate a thread under frsh.
+ *
+ * Implementation dependent issue: in the implementation with an
+ * application scheduler, after cleaning up the thread management
+ * data, it is unbound and the scheduling policy changed to fixed
+ * priority before calling the posix pthread_exit() function.
+ *
+ * NOTE: This function, together with the internal function
+ * frsh_internal_remove_thread() has been removed from FRSH
+ * because it shouldn't be necessary.
+ *
+ * If there are some problems with MaRTE in thread termination
+ * it should be fixed in the OS and not here.
+ *
+ * The function does not do anything special that is not done in the
+ * terminate callback of the FRSH scheduler.
+ *
+ * If you want to be curious about what the function did, look at the
+ * SVN repository (revision 273) or one of the past branches.
+ **/
+ void frsh_thread_exit (void *value_ptr);
+
+
+ /**
+ * frsh_sharedobj_set_preemption_level()
+ *
+ * The operation updates the specified shared object by setting its
+ * preemption level to the specified input parameter.
+ *
+ * OBSERVATION: if this value is changed being any contract that
+ * uses the resource already accepted, the system's behavior and
+ * particularly the acceptance tests correctness are not garantee
+ * and probably wrong.
+ **/
+ int frsh_sharedobj_set_preemption_level(frsh_sharedobj_handle_t obj_handle,
+ frsh_preemption_level_t preemption_level);
+
+ /**
+ * frsh_sharedobj_get_preemption_level()
+ *
+ * The operation obtains from the specified shared object its
+ * preemption level and copies it to the place pointed to by the
+ * specified input parameter.
+ **/
+ int frsh_sharedobj_get_preemption_level(frsh_sharedobj_handle_t obj_handle,
+ frsh_preemption_level_t *preemption_level);
+
+ /*@}*/
+
+ FRSH_CPP_END_DECLS
+
+ #endif // _FRSH_IMPLEMENTATION_SPECIFIC_H_
--- /dev/null
+ // -----------------------------------------------------------------------
+ // Copyright (C) 2006 - 2009 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
+ //
+ // FSF API web pages: http://marte.unican.es/fsf/docs
+ // http://shark.sssup.it/contrib/first/docs/
+ //
+ // This file is part of FRSH (FRescor ScHeduler)
+ //
+ // 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, 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_implementation_specific_types.h
+ //==============================================
+ // ******** ******* ******** ** **
+ // **///// /**////** **////// /** /**
+ // ** /** /** /** /** /**
+ // ******* /******* /********* /**********
+ // **//// /**///** ////////** /**//////**
+ // ** /** //** /** /** /**
+ // ** /** //** ******** /** /**
+ // // // // //////// // //
+ //
+ // FRSH(FRescor ScHeduler), pronounced "fresh"
+ //==============================================
+
+ #ifndef FRSH_IMPLEMENTATION_SPECIFIC_TYPES_H_
+ #define FRSH_IMPLEMENTATION_SPECIFIC_TYPES_H_
+
+ FRSH_CPP_BEGIN_DECLS
+
+ /**
+ * @file frsh_implementation_specific_types.h
+ **/
+
+ /**
+ * @addtogroup implementationspec
+ *
+ * @{
+ **/
+
+ /** Implementation specific preemption level values **/
+ typedef unsigned long frsh_preemption_level_t; // range 1..2**32-1
+
+ /*@}*/
+
+ FRSH_CPP_END_DECLS
+
+
+ #endif /* !FRSH_IMPLEMENTATION_SPECIFIC_TYPES_H_ */
--- /dev/null
+ // -----------------------------------------------------------------------
+ // Copyright (C) 2006 - 2009 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
+ //
+ // FSF API web pages: http://marte.unican.es/fsf/docs
+ // http://shark.sssup.it/contrib/first/docs/
+ //
+ // This file is part of FRSH (FRescor ScHeduler)
+ //
+ // 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, 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_memory_management.h
+
+ //==============================================
+ // ******** ******* ******** ** **
+ // **///// /**////** **////// /** /**
+ // ** /** /** /** /** /**
+ // ******* /******* /********* /**********
+ // **//// /**///** ////////** /**//////**
+ // ** /** //** /** /** /**
+ // ** /** //** ******** /** /**
+ // // // // //////// // //
+ //
+ // FRSH(FRescor ScHeduler), pronounced "fresh"
+ //==============================================
+
+ #ifndef _FRSH_MEMORY_MANAGEMENT_H_
+ #define _FRSH_MEMORY_MANAGEMENT_H_
+
+ #include "frsh_core_types.h"
+
+
+ #define FRSH_MEMORY_MANAGEMENT_SUPPORTED 1
+
+ FRSH_CPP_BEGIN_DECLS
+
+ /**
+ * @file frsh_memory_management.h
+ **/
+
+ /**
+ * @defgroup memmanagement Memory Management
+ *
+ * This module provides the types and the functions to add memory
+ * management support to FRSH contracts.
+ *
+ * @{
+ *
+ **/
+
+ /**
+ * frsh_contract_set_min_memory()
+ *
+ * This function specifies in the contract the minimum
+ * memory needed by the application.
+ *
+ * @param[in] min_memory Minimum needed memory in bytes.
+ * @param[in] max_memory Maximum needed memory in bytes.
+ * @param contract Contract, in-out argument.
+ *
+ * @return 0 if no error \n
+ * FRSH_ERR_BAD_ARGUMENT if min_memory <0
+ *
+ **/
+ int frsh_contract_set_min_memory(size_t min_memory,
+ frsh_contract_t *contract);
+
+ /**
+ * frsh_contract_get_min_memory()
+ *
+ * This function gets the minimum memory parameter from the contract.
+ *
+ * @param[in] contract Contract object
+ * @param[out] min_memory Placeholder for the minimum required
+ * memory.
+ *
+ * @return 0 if no error \n
+ * FRSH_ERR_BAD_ARGUMENT if one of the pointers is NULL
+ **/
+ int frsh_contract_get_min_memory(const frsh_contract_t *contract,
+ size_t *min_memory);
+
+ // frsh_contract_set_max_memory() is new
+ // frsh_contract_get_max_memory() is new
+
+ /**
+ * frsh_contract_set_max_memory()
+ *
+ * This function specifies in the contract the minimum
+ * memory needed by the application.
+ *
+ * @param[in] max_memory Maximum needed memory in bytes.
+ * @param contract Contract, in-out argument.
+ *
+ * FRSH_ERR_BAD_ARGUMENT if min_memory > max_memory
+ *
+ **/
+ int frsh_contract_set_max_memory(size_t max_memory,
+ frsh_contract_t *contract);
+
+
+ /**
+ * frsh_contract_get_max_memory()
+ *
+ * This function gets the maximum memory parameter from the contract.
+ *
+ * @param[in] contract Contract object
+ * @param[out] max_memory Placeholder for the maximum required
+ * memory.
+ *
+ * @return 0 if no error \n
+ * FRSH_ERR_BAD_ARGUMENT if one of the pointers is NULL
+ **/
+ int frsh_contract_get_max_memory(const frsh_contract_t *contract,
+ size_t *max_memory);
+
+
+ /**
+ * frsh_vres_get_memory_info()
+ *
+ * This function gives us the runtime info of memory usage and
+ * reservation.
+ *
+ * @param[in] vres_id Identifier of vres
+ * @param[out] mem_allocated Memory currently allocated to the vres
+ * @param[out] mem_budget Total pool of memory reserved for the vres
+ * (until next renegotiation).
+ *
+ * @return 0 if no error \n
+ * FRSH_ERR_BAD_ARGUMENT if one of the pointers is NULL
+ **/
+ int frsh_vres_get_memory_info(frsh_vres_id_t vres_id,
+ size_t *mem_allocated,
+ size_t *mem_budget);
+
+
+ /**
+ * frsh_vres_memalloc()
+ *
+ * This function reserves some memory from the memory to this virtual
+ * resource.
+ *
+ * @param[in] vres_id Identifier of vres.
+ * @param[in] Number of bytes
+ * @param[out] Valid pointer for the allocation
+ *
+ * @return 0 if no error \n
+ * FRSH_ERR_BAD_ARGUMENT if the area pointer is NULL
+ * FRSH_ERR_OUT_OF_BUDGET if no budget is available
+ **/
+ int frsh_vres_malloc(frsh_vres_id_t vres_id,
+ size_t num_bytes,
+ void **area);
+
+ /**
+ * frsh_vres_memfree()
+ *
+ * This function returns the previously allocated memory area for this
+ * virtual_resource to the main memory.
+ *
+ * @param[in] vres_id Identifier of vres.
+ * @param[in] area Memory area to return
+ *
+ * @return 0 if no error \n
+ * FRSH_ERR_BAD_ARGUMENT if the area pointer is NULL
+ **/
+ int frsh_vres_memfree(frsh_vres_id_t vres_id,
+ void *area);
+
+
+
+
+ /*@}*/
+
+ FRSH_CPP_END_DECLS
+
+ #endif /* !FRSH_MEMORY_MANAGEMENT_H_ */
--- /dev/null
+ // -----------------------------------------------------------------------
+ // Copyright (C) 2006 - 2009 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
+ //
+ // FSF API web pages: http://marte.unican.es/fsf/docs
+ // http://shark.sssup.it/contrib/first/docs/
+ //
+ // This file is part of FRSH (FRescor ScHeduler)
+ //
+ // 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, 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_opaque_types.h
+ //==============================================
+ // ******** ******* ******** ** **
+ // **///// /**////** **////// /** /**
+ // ** /** /** /** /** /**
+ // ******* /******* /********* /**********
+ // **//// /**///** ////////** /**//////**
+ // ** /** //** /** /** /**
+ // ** /** //** ******** /** /**
+ // // // // //////// // //
+ //
+ // FRSH(FRescor ScHeduler), pronounced "fresh"
+ //==============================================
+
+ // Implementation dependent definitions
+ #ifndef _FRSH_OPAQUE_TYPES_H_
+ #define _FRSH_OPAQUE_TYPES_H_
+
+ FRSH_CPP_BEGIN_DECLS
+
+ /**
+ * @file frsh_opaque_types.h
+ **/
+
+ /**
+ * @defgroup opaque Opaque types
+ *
+ * This module specifies some #defines for privates types in the
+ * interface. In this way we warn the FRSH user never to access the internal
+ * members of the types directly allowing us to change their internal
+ * definitions to suit our needs.
+ *
+ * Note that in Ada the FRSH user would never be allowed to access the
+ * members directly, however in C the compiler does not prevent this.
+ * But this is the best we can do in this language.
+ *
+ * @{
+ **/
+
+ #define FRSH_VRES_ID_T_OPAQUE unsigned int
+
+ /** frsh_contract_parameters_t **/
+ #define FRSH_CONTRACT_T_OPAQUE struct { \
+ \
+ /** Processor Id or Network Id **/ \
+ frsh_resource_id_t resource_id; \
+ \
+ /** Whether processor or network **/ \
+ frsh_resource_type_t resource_type; \
+ \
+ /** Printable name for the contract
+ Unique within the local node **/ \
+ frsh_contract_label_t contract_label; \
+ \
+ /** Minimum budget needed to perform a job. With the energy
+ module this will be an array **/ \
+ frsh_rel_time_t budget_min; \
+ \
+ /** Maximum period that the system system can sustain **/ \
+ frsh_rel_time_t period_max; \
+ \
+ /** Maximum budget that the vres can use
+ (and would be happy to have). With the energy module
+ this will be an array **/ \
+ frsh_rel_time_t budget_max; \
+ \
+ /** Minimum period for that
+ the system can use (and would be happy to have) **/ \
+ frsh_rel_time_t period_min; \
+ \
+ /** Set of discrete values for budget and period. With the
+ energy module this will be an array **/ \
+ frsh_utilization_set_t utilization_set; \
+ \
+ /** Workload_type: bounded, indeterminate, overhead **/ \
+ frsh_workload_t workload; \
+ \
+ /** Scheduling type: Regular, background
+ (in round-robin) or dummy **/ \
+ frsh_contract_type_t contract_type; \
+ \
+ /** Whether delay equals period **/ \
+ bool d_equals_t; \
+ \
+ /** Deadline (will be ignored if d_equals_t is TRUE **/ \
+ frsh_rel_time_t deadline; \
+ \
+ /** Signal parameters for the case of
+ attempting to use too much budget **/ \
+ frsh_signal_t budget_overrun_signal; \
+ frsh_signal_info_t budget_overrun_siginfo; \
+ \
+ /** Signal parameters for the case a deadline
+ is missed **/ \
+ frsh_signal_t deadline_miss_signal; \
+ frsh_signal_info_t deadline_miss_siginfo; \
+ \
+ /** Wether the range of period and budget is specified
+ in a continuous way (max-min) or as a set of
+ discrete values **/ \
+ frsh_granularity_t granularity; \
+ \
+ /** Non-cooperative parameter for fair capacity
+ distribution **/ \
+ int importance; \
+ \
+ /** Cooperative parameter for fair capacity
+ distribution **/ \
+ int weight; \
+ \
+ /** If > 0 it describes a duration for which
+ the allocated budget and capacity will be
+ maintained across negotiations and will
+ not be affected for dynamic spare capacity **/ \
+ frsh_rel_time_t stability_time; \
+ \
+ /** Low level parameter related with the elegibility
+ preempt other threads **/ \
+ frsh_preemption_level_t preemption_level; \
+ \
+ /** Set of critical sections that the vres executes
+ besides the normal budget **/ \
+ frsh_csects_group_t critical_sections; \
+ \
+ /** Internal scheduling policy within the vres for
+ hierarchical scheduling systems **/ \
+ frsh_sched_policy_t policy; \
+ \
+ /** Protocol info for distributed systems. We store it
+ as a pointer+size. It's internal meaning is imple-
+ mentation dependent. **/ \
+ frsh_protocol_info_t protocol_info; \
+ frsh_endpoint_queueing_info_t queueing_info; \
+ \
+ /** Maximum loss rate
+ Percentage of packet loss in the network that is
+ tolerated by the application **/ \
+ int max_loss_rate; \
+ \
+ /** Minimum memory size to be reserved **/ \
+ size_t minimum_memory; \
+ \
+ /** Maximum memory size to be reserved **/ \
+ size_t maximum_memory; \
+ }
+
+
+ typedef int FRSH_SYNCHOBJ_HANDLE_T_OPAQUE;
+
+ typedef int FRSH_SHAREDOBJ_HANDLE_T_OPAQUE;
+
+ typedef unsigned int FRSH_GROUP_ID_T_OPAQUE;
+
+ /**
+ * Critical section data
+ * - comon parameters
+ * op_kind; // kind of operation (READ or WRITE)
+ * obj_handle; // handle to shared object
+ * wcet; // Execution time
+ * blocking; // Blocking time (execution time + protection overheads)
+ * - attributes used only for protected shared objects
+ * op; // pointer to the operation
+ * - attributes used only for protected write operations
+ * areas; // memory areas to be protected
+ *
+ **/
+ #define FRSH_CSECT_T_OPAQUE struct { \
+ frsh_csect_op_kind_t op_kind; \
+ frsh_sharedobj_handle_t obj_handle; \
+ frsh_rel_time_t wcet; \
+ frsh_rel_time_t blocking; \
+ frsh_csect_op_t op; \
+ frsh_memory_areas_t areas; \
+ frsh_memory_areas_t storage; \
+ }
+
+
+ //opaque types for frsh endpoints
+ typedef int FRSH_SEND_ENDPOINT_T_OPAQUE;
+
+ typedef int FRSH_RECEIVE_ENDPOINT_T_OPAQUE;
+
+ /*@}*/
+
+ FRSH_CPP_END_DECLS
+
+ #endif // _FRSH_OPAQUE_TYPES_H_
--- /dev/null
+ // -----------------------------------------------------------------------
+ // Copyright (C) 2006 - 2009 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
+ //
+ // FSF API web pages: http://marte.unican.es/fsf/docs
+ // http://shark.sssup.it/contrib/first/docs/
+ //
+ // This file is part of FRSH (FRescor ScHeduler)
+ //
+ // 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, 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_shared_objects.h
+
+ //==============================================
+ // ******** ******* ******** ** **
+ // **///// /**////** **////// /** /**
+ // ** /** /** /** /** /**
+ // ******* /******* /********* /**********
+ // **//// /**///** ////////** /**//////**
+ // ** /** //** /** /** /**
+ // ** /** //** ******** /** /**
+ // // // // //////// // //
+ //
+ // FRSH(FRescor ScHeduler), pronounced "fresh"
+ //==============================================
+
+ #ifndef _FRSH_SHARED_OBJECTS_H_
+ #define _FRSH_SHARED_OBJECTS_H_
+
+ #include "frsh_shared_objects_types.h"
+ #include "frsh_core_types.h"
+
+ FRSH_CPP_BEGIN_DECLS
+
+ #define FRSH_SHAREDOBJS_MODULE_SUPPORTED 1
+
+ /**
+ * @file frsh_shared_objects.h
+ **/
+
+ /**
+ * @defgroup sharedobj Shared Objects module
+ *
+ * This module includes the functions to declare and use shared
+ * objects in different critical sections.
+ *
+ * A shared object is an abstraction of a mutex giving it a name and a
+ * possible priority ceiling.
+ *
+ * A critical section represents a usage of a shared object with a wcet.
+ * One or more critical sections can be included in a contract.
+ *
+ * There are two types of shared_objects: protected and unprotected.
+ *
+ * - <b>UNPROTECTED shared objects</b>. These shared objects are always
+ * used in trusted critical sections for which the worst-case
+ * execution times can be guaranteed not to be exceeded by the
+ * application designer (eg because tools have been used to verify
+ * the schedulability off-line). Given these conditions, there is
+ * no need to have a mechanism to monitor their execution time, with
+ * the corresponding savings in overhead.
+ *
+ * - <b>PROTECTED shared objects</b>. For these shared objects a mechanism
+ * may be used in one or more of their critical sections to monitor
+ * and enforce their worst-case execution time. These shared
+ * objects are restricted to data in regular memory because a
+ * mechanism to save and restore the state is necessary in order to
+ * cleanly abort a misbehaving critical section.\n
+ *
+ * Critical sections are categorized depending on wcet monitoring and
+ * rollback capability.
+ *
+ * - <b>UNCHECKED critical sections</b>. These critical sections are
+ * not monitored by FRSH for wcet compliance. Their wcet value is
+ * used only for analysis purposes (calculation of blocking times).
+ *
+ * - <b>READ critical sections</b>. These critical sections have
+ * their wcet enforced but they don't have any rollback action
+ * applied when their wcet is exceeded.
+ *
+ * - <b>WRITE critical sections</b>. These critical sections have
+ * their wcet monitored and they have a rollback mechanism applied
+ * to their memory areas prior to being aborted for exceeding their
+ * declared wcet.
+ *
+ * READ and WRITE critical sections must use PROTECTED shared objects,
+ * but UNCHECKED critical sections may use PROTECTED or UNPROTECTED
+ * shared objects.
+ *
+ * The monitoring mechanism for READ and WRITE critical section works
+ * by executing them indirectly via a registered callback function.
+ * UNCHECKED critical sections are executed directly by the
+ * application.
+ *
+ * The rollback mechanism for WRITE critical sections requires an
+ * additional registration of the memory areas that the callback
+ * function may modify. With this data FRSH will do an initial saving
+ * of this areas that will used for restoration when there is a rollback
+ * operation.
+ *
+ * Note that extra time for the saving and the restoration must be
+ * included in the wcet specified for a WRITE critical section.
+ * Functions are provided to assist the developer in calculating this
+ * extra time.
+ *
+ * The reason for allowing the use of PROTECTED shared objects in
+ * UNCHECKED critical sections is to allow for legacy or trusted
+ * code that would use UNCHECKED critical sections to share a shared
+ * object with an untrusted code using READ or WRITE critical sections.
+ *
+ * This module makes use of the following constants defined in
+ * frsh_configuration_parameters.h. We list them with our proposed
+ * default values.
+ *
+ * FRSH_MAX_N_SHARED_OBJECTS 100 \n
+ * FRSH_MAX_N_CRITICAL_SECTIONS 20\n
+ * FRSH_MAX_N_MEMORY_AREAS 4\n
+ *
+ * @{
+ **/
+
+
+ /////////////////////////////////////////////////////
+ // SHARED OBJECTS & OPERATIONS MANAGEMENT
+ /////////////////////////////////////////////////////
+ /**
+ * @defgroup so_opp_mgmnt Shared Objects & Operations
+ * @ingroup sharedobj
+ *
+ * These functions are used to declare shared objects and link them
+ * with a mutex.
+ *
+ * @{
+ **/
+
+ /**
+ * frsh_sharedobj_init()
+ *
+ * Initialization of shared objects. If the object identified by
+ * obj_label does not yet exist, it is created, a handle to the object is
+ * returned in the variable pointed to by obj_handle, and the
+ * specified mutex is initialized with the appropriate attributes
+ * necessary for the current implementation. If the object already
+ * exists, the function fails. The object is created according to the
+ * kind of object (protected or unprotected) specified by obj_kind
+ *
+ * @param[in] obj_label Label defined by the application. Char * for
+ * a string of FRSH_MAX_SIZE_SHARED_OBJ_LABEL
+ * characters (+ null terminating \0).
+ *
+ * @param[in] obj_kind Whether it is protected or unprotected.
+ *
+ * @param[out] obj_handle Placeholder for the shared object handle.
+ *
+ * @param[out] mutex Placeholder for the mutex.
+ *
+ * @return 0 if no error \n
+ * FRSH_ERR_BAD_ARGUMENT : if obj_label, obj_handle, or mutex are NULL \n
+ * FRSH_ERR_SHARED_OBJ_ALREADY_INITIALIZED : if the object identified
+ * by label already exists \n
+ * FRSH_ERR_TOO_MANY_SHARED_OBJS : if the number of already
+ * initialized shared objects exceed the
+ * FRSH_MAX_N_SHARED_OBJECTS configuration parameter. \n
+ * .
+ * It may also return any of the error codes that are returned by
+ * fosa_mutex_init() and fosa_mutex_set_prioceiling().
+ *
+ **/
+ int frsh_sharedobj_init
+ (char *obj_label,
+ frsh_sharedobj_kind_t obj_kind,
+ frsh_sharedobj_handle_t *obj_handle,
+ frsh_mutex_t *mutex);
+
+
+
+ /**
+ * frsh_sharedobj_get_handle()
+ *
+ * Getting the handle of shared objects. If the object already exists
+ * a handle to the object is returned in the variable pointed to by
+ * obj_handle. Otherwise, an error code is returned.
+ *
+ * @param[in] obj_label Defined by the application at object creation
+ * time. Char * for a string of FRSH_MAX_SIZE_SHARED_OBJ_LABEL
+ * characters (+ null terminating \0).
+ *
+ * @param[out] obj_handle Placeholder for the object handle.
+ *
+ * @return 0 if no error \n
+ * FRSH_ERR_BAD_ARGUMENT : if label or obj_handle are NULL \n
+ * FRSH_ERR_SHARED_OBJ_NOT_INITIALIZED : if the shared object identified
+ * by obj_label does not exist \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 of the calling thread
+ * has been cancelled or it is not valid \n
+ * .
+ * It may also return any of the error codes that are returned by the
+ * fosa_mutex_init() function call
+ *
+ **/
+ int frsh_sharedobj_get_handle
+ (char *obj_label,
+ frsh_sharedobj_handle_t *obj_handle);
+
+
+ /**
+ * frsh_sharedobj_get_mutex()
+ *
+ * Getting the mutex of shared objects.
+ *
+ * @param[in] obj_handle Handle of the shared object
+ *
+ * @param[out] mutex Placeholder for A POINTER to a pointer of the
+ * mutex. We give the pointer to discourage the
+ * application of using a local copy of the mutex.
+ *
+ * @return 0 if no error \n
+ * FRSH_ERR_BAD_ARGUMENT : if obj_handle or mutex are NULL or obj_handle
+ * is not correct or reference a wrong shared object \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 of the calling thread
+ * has been cancelled or it is not valid
+ *
+ **/
+ int frsh_sharedobj_get_mutex
+ (frsh_sharedobj_handle_t obj_handle,
+ frsh_mutex_t **mutex);
+
+ /**
+ * frsh_sharedobj_get_obj_kind()
+ *
+ * Get the object kind (protected/unprotected) of the object handle.
+ *
+ * @param[in] obj_handle Handle of the shared object
+ *
+ * @param[out] obj_kind Placeholder for an enumeration variable of
+ * protected / unprotected.
+ *
+ * @return 0 if no error \n
+ * FRSH_ERR_BAD_ARGUMENT : if obj_handle or mutex are NULL or obj_handle
+ * is not correct or reference a wrong shared object \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 of the calling thread
+ * has been cancelled or it is not valid
+ *
+ **/
+ int frsh_sharedobj_get_obj_kind
+ (frsh_sharedobj_handle_t obj_handle,
+ frsh_sharedobj_kind_t *obj_kind);
+
+ /**
+ * frsh_sharedobj_remove()
+ *
+ * Allows the implementation to remove a shared object when the last
+ * vres referencing it is cancelled. This removes the object id and
+ * other internal data associated with the object, but does not remove
+ * the mutex; this is done by the application through the common POSIX
+ * API.
+ *
+ * @return 0 if no error \n
+ * FRSH_ERR_BAD_ARGUMENT : if obj_handle is NULL or obj_handle
+ * is not correct or references a wrong shared object \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 of the calling thread
+ * has been cancelled or it is not valid
+ *
+ **/
+ int frsh_sharedobj_remove
+ (frsh_sharedobj_handle_t obj_handle);
+
+
+
+ /*@}*/
+
+ /////////////////////////////////////////////////////
+ // CRITICAL SECTIONS
+ /////////////////////////////////////////////////////
+ /**
+ * @defgroup so_critical Critical Sections
+ * @ingroup sharedobj
+ *
+ * These functions are used to create and manage the parameters
+ * of critical sections. Critical sections are operations that
+ * make use of a shared object in a mutually exclusive way.
+ *
+ * @{
+ **/
+
+ /**
+ * frsh_csect_init()
+ *
+ * Initialize the critical section pointed to by csect
+ * with a handle to its shared object, and the worst-case execution
+ * time.
+ *
+ * The operation_kind is set to FRSH_CSOK_UNCHECKED.
+ *
+ * @param[in] obj_handle Shared object previously initialised.
+ *
+ * @param[in] wcet Execution time of the critical section. This
+ * budget is consumed in parallel with the vres budget.
+ *
+ * @param[out] csect Critical section memory placeholder.
+ *
+ * @return 0 if no error \n
+ * FRSH_ERR_BAD_ARGUMENT : if obj_handle is NULL \b or \n
+ * obj_handle is not correct or references a wrong shared object \b or \n
+ * if wcet is in the wrong format for specifying a time interval value \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 of the calling thread
+ * has been cancelled or it is not valid
+ *
+ **/
+ int frsh_csect_init
+ (frsh_sharedobj_handle_t obj_handle,
+ frsh_rel_time_t wcet,
+ frsh_csect_t *csect);
+
+
+ /**
+ * frsh_csect_get_sharedobj_handle()
+ *
+ * Get in the variable pointed to by obj_handle the handle to the
+ * shared object stored in the critical section referenced by csect
+ *
+ * @return 0 if no error \n
+ * FRSH_ERR_BAD_ARGUMENT : if csect or obj_handle are NULL or csect
+ * is not correct \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 of the calling thread
+ * has been cancelled or it is not valid
+ *
+ **/
+ int frsh_csect_get_sharedobj_handle
+ (const frsh_csect_t *csect,
+ frsh_sharedobj_handle_t * obj_handle);
+
+ /**
+ * frsh_csect_get_wcet()
+ *
+ * Get in the variable pointed to by wcet the worst-case execution time
+ * of the operation stored in the critical section referenced by csect.
+ *
+ * @return 0 if no error \n
+ * FRSH_ERR_BAD_ARGUMENT : if csect or wcet are NULL or csect
+ * is not correct \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 of the calling thread
+ * has been cancelled or it is not valid
+ *
+ **/
+ int frsh_csect_get_wcet
+ (const frsh_csect_t *csect,
+ frsh_rel_time_t *wcet);
+
+
+ /**
+ * frsh_csect_register_read_op()
+ *
+ * Register the given operation with the critical section and set
+ * op_kind to FRSH_CSOK_READ.
+ *
+ * The function returns an error if the shared_object is unprotected.
+ *
+ * @return 0 if no error \n
+ * FRSH_ERR_BAD_ARGUMENT : if csect or op are NULL or if csect points
+ * to a wrong critical section or if the shared_object is of type
+ * unprotected.
+ * 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 of the calling thread
+ * has been cancelled or it is not valid
+ *
+ **/
+ int frsh_csect_register_read_op
+ (frsh_csect_t *csect,
+ frsh_csect_op_t op);
+
+ /**
+ * frsh_csect_register_write_op()
+ *
+ * Register the given operation with the critical section, register
+ * the memory areas and set op_kind to FRSH_CSOK_WRITE.
+ *
+ * If the memory areas are empty the functions returns an error.
+ *
+ * The function returns an error if the shared_object is unprotected.
+ *
+ * @return 0 if no error \n
+ * FRSH_ERR_BAD_ARGUMENT : if op, csect or areas are NULL or csect points
+ * to a wrong critical section, or areas has a wrong size, or if the
+ * shared_object of csect is of type unprotected.
+ * 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 of the calling thread
+ * has been cancelled or it is not valid
+ *
+ **/
+ int frsh_csect_register_write_op
+ (frsh_csect_t *csect,
+ frsh_csect_op_t op,
+ const frsh_memory_areas_t *areas);
+
+
+ /**
+ * frsh_csect_get_op_kind()
+ *
+ * Returns the type of operation (read/write/unchecked) of the critical section.
+ *
+ * @return 0 if no error \n
+ * FRSH_ERR_BAD_ARGUMENT : if csect or op_kind are NULL or csect
+ * is not correct \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 of the calling thread
+ * has been cancelled or it is not valid
+ *
+ **/
+ int frsh_csect_get_op_kind
+ (const frsh_csect_t *csect,
+ frsh_csect_op_kind_t *op_kind);
+
+
+ /**
+ * frsh_csect_get_read_op()
+ *
+ * Get into the variable pointed to by op the operation pointer stored
+ * in the critical section referenced by csect.
+ *
+ * If the csect is of type write or unchecked it returns an error.
+ *
+ * @return 0 if no error \n
+ * FRSH_ERR_BAD_ARGUMENT : if csect is NULL or points to a wrong
+ * critical section, or to a critical section that is not of the
+ * FRSH_CSOK_READ kind \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 of the calling thread
+ * has been cancelled or it is not valid
+ *
+ **/
+ int frsh_csect_get_read_op
+ (const frsh_csect_t *csect,
+ frsh_csect_op_t *op);
+
+
+
+ /**
+ * frsh_csect_get_write_op()
+ *
+ * Get the operation pointer and the memory areas stored in the csect.
+ *
+ * If the csect is of type read or unchecked.
+ *
+ * @return 0 if no error \n
+ * FRSH_ERR_BAD_ARGUMENT : if csect is NULL or points to a wrong
+ * critical section, or to a critical section that is not of the
+ * FRSH_CSOK_WRITE kind \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 of the calling thread
+ * has been cancelled or it is not valid \n
+ *
+ **/
+ int frsh_csect_get_write_op
+ (const frsh_csect_t *csect,
+ frsh_csect_op_t *op,
+ frsh_memory_areas_t *areas);
+
+
+ /**
+ * frsh_csect_invoke()
+ *
+ * Invoke the registered operation in the critical section, with the pointers
+ * to the input and output parameters specified by input_arg and
+ * output arg.
+ *
+ * If the section is of type FRSH_CSOK_UNCHECKED, the function returns
+ * an error.
+ *
+ * For read operations, the mutex is locked, the csect budget is set equal
+ * to the wcet, the registered read operation is invoked, and then the
+ * mutex is unlocked; if the csect budget expires, the operation is
+ * interrupted, the mutex is unlocked, and the function returns with
+ * an error code.
+ *
+ * For write operations, the mutex is locked, the registered memory
+ * areas are backed up, the csect budget is set equal to the wcet, the
+ * registered write operation is called, and the mutex is unlocked. If
+ * the csect budget expires, the operation is interrupted, the backed-up
+ * memory areas are recovered, the mutex is unlocked, and the function
+ * returns with an error code. The blocking time suffered by higher
+ * priority tasks is at most the wcet of the operation plus the backup
+ * time plus the recovery time.
+ *
+ * If the shared object in the critical section is not protected it
+ * returns an error.
+ *
+ * @return 0 if no error \n
+ * FRSH_ERR_BAD_ARGUMENT : if csect is NULL or points to a wrong
+ * critical section, or to a critical section that is unprotected \n
+ * FRSH_ERR_BUDGET_EXPIRED : the csect budget expired and the protected
+ * operation was interrupted \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 of the calling thread
+ * has been cancelled or it is not valid
+ *
+ **/
+ int frsh_csect_invoke
+ (const frsh_csect_t *csect,
+ const void * input_arg,
+ void * output_arg);
+
+ /**
+ * frsh_csect_get_blocking_time()
+ *
+ * Get in the variable pointed to by blocking the maximum blocking
+ * time of the operation of the referenced protected critical section.
+ *
+ * For read or unchecked operations, the maximum blocking time is the wcet.
+ *
+ * For write operations, the maximum blocking time suffered by higher
+ * priority tasks is the wcet of the operation plus the backup time
+ * plus the recovery time.
+ *
+ * @return 0 if no error \n
+ * FRSH_ERR_BAD_ARGUMENT : if csect or blocking are NULL or if csect
+ * points to a wrong critical section, or to a critical section
+ * that is unprotected \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 of the calling thread
+ * has been cancelled or it is not valid
+ *
+ **/
+ int frsh_csect_get_blocking_time
+ (const frsh_csect_t *csect,
+ frsh_rel_time_t *blocking);
+
+
+ /**
+ * frsh_csect_destroy()
+ *
+ * Destroy a critical section, deallocating all the resources that may
+ * have been allocated to it.
+ **/
+ int frsh_csect_destroy
+ (frsh_csect_t *csect);
+
+ /**
+ * frsh_csect_register_thread()
+ *
+ * Register the calling thread for invoking time-protected critical
+ * sections via frsh_csect_invoke.
+ **/
+ int frsh_csect_register_thread();
+
+ /**
+ * frsh_csect_deregister_thread()
+ *
+ * Deregister the calling thread from being able to invoke
+ * time-protected critical sections. This operation releases system
+ * resources that may have been allocated for the thread.
+ **/
+ int frsh_csect_deregister_thread();
+
+
+
+ /*@}*/ /* For so_critical group */
+
+
+ /////////////////////////////////////////////////////
+ // CONTRACT PARAMETERS
+ /////////////////////////////////////////////////////
+ /**
+ * @defgroup so_contract Shared Objects & Contract Parameters
+ * @ingroup sharedobj
+ *
+ * These functions are used to link shared objects to contracts via
+ * critical sections.
+ *
+ * @{
+ **/
+
+
+ /**
+ * frsh_contract_set_csects()
+ *
+ * The operation updates the specified contract parameters object by
+ * setting its critical sections to the specified input parameter.
+ *
+ * @return 0 if no error \n
+ * FRSH_ERR_BAD_ARGUMENT : if any of the pointers is NULL or
+ * the size of the critical_sections structure is less than zero
+ * or greater than FRSH_MAX_N_CRITICAL_SECTIONS
+ *
+ **/
+ int frsh_contract_set_csects
+ (frsh_contract_t *contract,
+ const frsh_csects_group_t *critical_sections);
+
+ /**
+ * frsh_contract_get_csects()
+ *
+ * The operation obtains from the specified contract parameters object
+ * its critical sections, and copies them to the places pointed to by
+ * the specified input parameter. Only those critical_section_data
+ * records that are in use in the critical_sections structure are
+ * copied (according to its size field).
+ *
+ * @return 0 if no error \n
+ * FRSH_ERR_BAD_ARGUMENT : if any of the pointers is NULL
+ *
+ **/
+ int frsh_contract_get_csects
+ (const frsh_contract_t *contract,
+ frsh_csects_group_t *critical_sections);
+
+ /*@}*/ /* For so_contract group */
+
+ /*@}*/ /* For shared_objects group */
+
+ FRSH_CPP_END_DECLS
+
+ #endif // _FRSH_SHARED_OBJECTS_H_
--- /dev/null
+ // -----------------------------------------------------------------------
+ // Copyright (C) 2006 - 2009 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
+ //
+ // FSF API web pages: http://marte.unican.es/fsf/docs
+ // http://shark.sssup.it/contrib/first/docs/
+ //
+ // This file is part of FRSH (FRescor ScHeduler)
+ //
+ // 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, 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(FRescor ScHeduler), pronounced "fresh"
+ //==============================================
+
+ #ifndef FRSH_SHARED_OBJECTS_TYPES_H_
+ #define FRSH_SHARED_OBJECTS_TYPES_H_
+
+ #include <time.h>
+ #include "frsh_core_types.h"
+ #include "frsh_configuration_parameters.h"
+
+ FRSH_CPP_BEGIN_DECLS
+
+ /**
+ * @file frsh_shared_objects_types.h
+ **/
+
+ /**
+ * @addtogroup sharedobj
+ *
+ * @{
+ **/
+
+ /** Mutex object. Attributes are handled by FOSA **/
+ typedef fosa_mutex_t frsh_mutex_t;
+
+
+ /**
+ * Shared object handle: It is an opaque type (i.e. the internal
+ * structure of this data type is implementation dependent).
+ **/
+ typedef FRSH_SHAREDOBJ_HANDLE_T_OPAQUE frsh_sharedobj_handle_t;
+
+ /**
+ * Shared object textual label
+ **/
+ typedef char frsh_sharedobj_label_t[FRSH_MAX_SIZE_SHARED_OBJ_LABEL + 1];
+
+ /**
+ * Kind of shared object: protected or unprotected
+ */
+ typedef enum
+ {FRSH_SOK_UNPROTECTED, FRSH_SOK_PROTECTED}
+ frsh_sharedobj_kind_t;
+
+ /**
+ * Kind of protected operation: read, write or unchecked
+ **/
+ typedef enum
+ {FRSH_CSOK_UNCHECKED, FRSH_CSOK_READ, FRSH_CSOK_WRITE}
+ frsh_csect_op_kind_t;
+
+ /**
+ * Pointer to protected operation, which takes a pointer to
+ * the input parameters, and a pointer to the output
+ * parameters; the user is responsible for not exceeding the
+ * sizes of the respective input and output parameters data structures
+ */
+ typedef void (*frsh_csect_op_t)
+ (const void * input_arg, void * output_arg);
+
+ /**
+ * A memory area
+ */
+ typedef struct {
+ size_t size;
+ void * area;
+ } frsh_memory_area_data_t;
+
+ /**
+ * Memory areas container
+ **/
+ typedef struct {
+ int size; // = 0
+ frsh_memory_area_data_t memory_areas[FRSH_MAX_N_MEMORY_AREAS];
+ } frsh_memory_areas_t;
+
+
+ /**
+ * Critical section data (opaque type)
+ **/
+ typedef FRSH_CSECT_T_OPAQUE frsh_csect_t;
+
+
+ /**
+ * Container of a group of critical sections, up to a maximum size
+ **/
+ typedef struct {
+ int size; // size of the group; initially=0
+ frsh_csect_t csects[FRSH_MAX_N_CRITICAL_SECTIONS]; // array of csect
+ } frsh_csects_group_t;
+
+ /*@}*/
+
+
+ FRSH_CPP_END_DECLS
+
+ #endif /* !FRSH_SHARED_OBJECTS_TYPES_H_ */
--- /dev/null
+ // -----------------------------------------------------------------------
+ // Copyright (C) 2006 - 2009 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
+ //
+ // FSF API web pages: http://marte.unican.es/fsf/docs
+ // http://shark.sssup.it/contrib/first/docs/
+ //
+ // This file is part of FRSH (FRescor ScHeduler)
+ //
+ // 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, 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
+ //==============================================
+ // ******** ******* ******** ** **
+ // **///// /**////** **////// /** /**
+ // ** /** /** /** /** /**
+ // ******* /******* /********* /**********
+ // **//// /**///** ////////** /**//////**
+ // ** /** //** /** /** /**
+ // ** /** //** ******** /** /**
+ // // // // //////// // //
+ //
+ // FRSH(FRescor ScHeduler), pronounced "fresh"
+ //==============================================
+ #ifndef _FRSH_SPARE_CAPACITY_H_
+ #define _FRSH_SPARE_CAPACITY_H_
+
+ #include <time.h>
+ #include <stdint.h>
+ #include "frsh_spare_capacity_types.h"
+ #include "frsh_core_types.h"
+ #include "frsh_core.h"
+
+ FRSH_CPP_BEGIN_DECLS
+
+ /**
+ * @file frsh_spare_capacity.h
+ **/
+
+ #define FRSH_SPARE_CAPACITY_MODULE_SUPPORTED 1
+
+
+ /**
+ * @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 *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_
--- /dev/null
+ // -----------------------------------------------------------------------
+ // Copyright (C) 2006 - 2009 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
+ //
+ // FSF API web pages: http://marte.unican.es/fsf/docs
+ // http://shark.sssup.it/contrib/first/docs/
+ //
+ // This file is part of FRSH (FRescor ScHeduler)
+ //
+ // 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, 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_types.h
+ //==============================================
+ // ******** ******* ******** ** **
+ // **///// /**////** **////// /** /**
+ // ** /** /** /** /** /**
+ // ******* /******* /********* /**********
+ // **//// /**///** ////////** /**//////**
+ // ** /** //** /** /** /**
+ // ** /** //** ******** /** /**
+ // // // // //////// // //
+ //
+ // FRSH(FRescor ScHeduler), pronounced "fresh"
+ //==============================================
+
+ #ifndef FRSH_SPARE_CAPACITY_TYPES_H_
+ #define FRSH_SPARE_CAPACITY_TYPES_H_
+
+ #include <time.h>
+
+ FRSH_CPP_BEGIN_DECLS
+
+ /**
+ * @file frsh_spare_capacity_types.h
+ **/
+
+ /**
+ * @addtogroup sparecapacity
+ *
+ * @{
+ **/
+
+ /*************************/
+ /* D E F I N I T I O N S */
+ /*************************/
+
+ /** Granularity of spare capacity requirements: continuous or discrete **/
+ typedef enum {FRSH_GR_CONTINUOUS, FRSH_GR_DISCRETE} frsh_granularity_t;
+
+ /** Utilization (C, T, and D) **/
+ typedef struct {
+ frsh_rel_time_t budget; // Execution time
+ frsh_rel_time_t period; // Period
+ frsh_rel_time_t deadline; // Deadline
+ } frsh_utilization_t;
+
+ /** List of utilization values **/
+ typedef struct {
+ int size; // = 0
+ frsh_utilization_t utilizations[FRSH_MAX_N_UTILIZATION_VALUES];
+ } frsh_utilization_set_t;
+
+ // Constants for assigning default values
+ #define FRSH_DEFAULT_GRANULARITY FRSH_GR_CONTINUOUS
+ #define FRSH_DEFAULT_WEIGHT 1 // Cannot be zero with fsa_response_time
+ #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_CPP_END_DECLS
+
+
+ #endif /* !FRSH_SPARE_CAPACITY_TYPES_H_ */
--- /dev/null
+ // -----------------------------------------------------------------------
+ // Copyright (C) 2006 - 2009 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
+ //
+ // FSF API web pages: http://marte.unican.es/fsf/docs
+ // http://shark.sssup.it/contrib/first/docs/
+ //
+ // This file is part of FRSH (FRescor ScHeduler)
+ //
+ // 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, 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_thread.h
+ //==============================================
+ // ******** ******* ******** ** **
+ // **///// /**////** **////// /** /**
+ // ** /** /** /** /** /**
+ // ******* /******* /********* /**********
+ // **//// /**///** ////////** /**//////**
+ // ** /** //** /** /** /**
+ // ** /** //** ******** /** /**
+ // // // // //////// // //
+ //
+ // FRSH(FRescor ScHeduler), pronounced "fresh"
+ //==============================================
+ #ifndef _FRSH_THREADS_H_
+ #define _FRSH_THREADS_H_
+
+ #include "frsh_core_types.h"
+ #include "frsh_core.h"
+
+ FRSH_CPP_BEGIN_DECLS
+
+ /**
+ * @file frsh_thread_attrs.h
+ **/
+
+ /**
+ * @defgroup threadfunc FRSH thread functions.
+ * @ingroup core
+ *
+ * These functions are used to manage frsh_thread_t and
+ * frsh_thread_attr_t used in the public API of FRSH.
+ *
+ * @{
+ **/
+
+
+ /*************************
+ * Thread attributes
+ *************************/
+
+ /**
+ * frsh_thread_attr_init()
+ *
+ * Initialize a thread attributes object
+ *
+ * This function initializes the object pointed to by attr to all
+ * the default values defined by FRSH
+ *
+ * @return 0 if successful; otherwise it returns \n
+ * FOSA_ENOMEM: insufficient memory exists to initialize the thread
+ * attributes object
+ **/
+ static inline int frsh_thread_attr_init(frsh_thread_attr_t *attr)
+ {
+ return fosa_thread_attr_init(attr);
+ }
+
+ /**
+ * frsh_thread_attr_destroy()
+ *
+ * Destroy a thread attributes object
+ *
+ * This function is used to destroy the thread attributes object,
+ * pointed to by attr, and deallocate any system resources allocated for it
+ *
+ * Returns 0
+ */
+ static inline int frsh_thread_attr_destroy(frsh_thread_attr_t *attr)
+ {
+ return fosa_thread_attr_destroy(attr);
+ }
+
+ /**
+ * frsh_thread_attr_set_stacksize()
+ *
+ * Set the thread minimum stack size in a thread attributes object
+ *
+ * This function sets the minimum stack size of the thread attributes
+ * object attr to the value given by stacksize, in bytes. This
+ * function has no runtime effect on the stack size, except when the
+ * attributes object is used to create a thread, when it will be
+ * created with the specified minimum stack size
+ *
+ * @return 0 if successful, or the following error code:
+ * FOSA_EINVAL: the specified stacksize value is not supported in
+ * this implementation
+ */
+ static inline int frsh_thread_attr_set_stacksize(frsh_thread_attr_t *attr, size_t stacksize)
+ {
+ return fosa_thread_attr_set_stacksize(attr, stacksize);
+ }
+
+ /**
+ * frsh_thread_attr_get_stacksize()
+ *
+ * Get the thread minimum stack size from a thread attributes object
+ *
+ * This function sets the variable pointed to by stacksize to the
+ * minimum stack size stored in the thread attributes object attr.
+ *
+ * @return 0
+ */
+ static inline int frsh_thread_attr_get_stacksize
+ (const frsh_thread_attr_t *attr, size_t *stacksize)
+ {
+ return fosa_thread_attr_get_stacksize(attr, stacksize);
+ }
+
+
+ /*@}*/
+
+ FRSH_CPP_END_DECLS
+
+ #endif
+
--- /dev/null
+ // -----------------------------------------------------------------------
+ // Copyright (C) 2006 - 2009 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
+ //
+ // FSF API web pages: http://marte.unican.es/fsf/docs
+ // http://shark.sssup.it/contrib/first/docs/
+ //
+ // This file is part of FRSH (FRescor ScHeduler)
+ //
+ // 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, 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_types.h
+ //==============================================
+ // ******** ******* ******** ** **
+ // **///// /**////** **////// /** /**
+ // ** /** /** /** /** /**
+ // ******* /******* /********* /**********
+ // **//// /**///** ////////** /**//////**
+ // ** /** //** /** /** /**
+ // ** /** //** ******** /** /**
+ // // // // //////// // //
+ //
+ // FRSH(FRescor ScHeduler), pronounced "fresh"
+ //==============================================
+
+ #ifndef FRSH_TIME_H_
+ #define FRSH_TIME_H_
+
+ #include "frsh_core_types.h"
+ #include "frsh_core.h"
+
+ FRSH_CPP_BEGIN_DECLS
+
+ /**
+ * @file frsh_time.h
+ **/
+
+
+ /**
+ * \addtogroup core
+ **/
+ /*@{*/
+
+ /***********************
+ * Relational operations
+ ***********************/
+
+ /**
+ * frsh_abs_time_smaller()
+ *
+ * Check if an absolute time is smaller than another one.
+ **/
+ static inline bool frsh_abs_time_smaller(frsh_abs_time_t t1, frsh_abs_time_t t2)
+ {
+ return fosa_abs_time_smaller(t1, t2);
+ }
+
+ /**
+ * frsh_rel_time_smaller()
+ *
+ * Check if a relative interval is smaller than another one.
+ **/
+ static inline bool frsh_rel_time_smaller(frsh_rel_time_t t1, frsh_rel_time_t t2)
+ {
+ return fosa_rel_time_smaller(t1, t2);
+ }
+
+ /**
+ * frsh_abs_time_smaller_or_equal()
+ *
+ * Check if an absolute time is smaller than or equal to another one.
+ **/
+ static inline bool frsh_abs_time_smaller_or_equal(frsh_abs_time_t t1, frsh_abs_time_t t2)
+ {
+ return fosa_abs_time_smaller_or_equal(t1, t2);
+ }
+
+ /**
+ * frsh_rel_time_smaller_or_equal()
+ *
+ * Check if a relative interval is smaller than or equal to another one.
+ **/
+ static inline bool frsh_rel_time_smaller_or_equal(frsh_rel_time_t t1, frsh_rel_time_t t2)
+ {
+ return fosa_rel_time_smaller_or_equal(t1, t2);
+ }
+
+
+ /***********************
+ * Arithmetic operations
+ ***********************/
+
+ /**
+ * frsh_abs_time_incr()
+ *
+ * Add a relative interval to an absolute time.
+ */
+ static inline frsh_abs_time_t frsh_abs_time_incr(frsh_abs_time_t base, frsh_rel_time_t interval)
+ {
+ return fosa_abs_time_incr(base, interval);
+ }
+
+ /**
+ * frsh_rel_time_add()
+ *
+ * Add a relative interval to another one.
+ */
+ static inline frsh_rel_time_t frsh_rel_time_add(frsh_rel_time_t t1, frsh_rel_time_t t2)
+ {
+ return fosa_rel_time_add(t1, t2);
+ }
+
+ static inline frsh_rel_time_t frsh_rel_time_incr(frsh_rel_time_t t1, frsh_rel_time_t t2)
+ {
+ return fosa_rel_time_add(t1, t2);
+ }
+
+
+
+
+ /**
+ * frsh_abs_time_decr
+ *
+ * Subtract a relative interval from an absolute time.
+ */
+ static inline frsh_abs_time_t frsh_abs_time_decr(frsh_abs_time_t time, frsh_rel_time_t interval)
+ {
+ return fosa_abs_time_decr(time, interval);
+ }
+
+ /**
+ * frsh_rel_time_decr()
+ *
+ * Subtract a relative interval from another one.
+ */
+ static inline frsh_rel_time_t frsh_rel_time_decr(frsh_rel_time_t total, frsh_rel_time_t part)
+ {
+ return fosa_rel_time_decr(total, part);
+ }
+
+
+ /**
+ * frsh_abs_time_extract_interval()
+ *
+ * Subtract two absolute times to get a relative interval.
+ */
+ static inline frsh_rel_time_t frsh_abs_time_extract_interval(frsh_abs_time_t past, frsh_abs_time_t future)
+ {
+ return fosa_abs_time_extract_interval(past, future);
+ }
+
+
+ static inline frsh_rel_time_t frsh_abs_time_subtract(frsh_abs_time_t past, frsh_abs_time_t future)
+ {
+ return fosa_abs_time_extract_interval(past, future);
+ }
+
+
+
+
+ /**
+ * frsh_rel_time_times_integer()
+ *
+ * Multiplies a relative time by an integer
+ */
+ static inline frsh_rel_time_t frsh_rel_time_times_integer(frsh_rel_time_t time, long multiplier)
+ {
+ return fosa_rel_time_times_integer(time, multiplier);
+ }
+
+ /**
+ * frsh_rel_time_times_integer()
+ *
+ * Divides a relative time by an integer
+ **/
+ static inline frsh_rel_time_t frsh_rel_time_divided_by_integer(frsh_rel_time_t time, long divider)
+ {
+ return fosa_rel_time_divided_by_integer(time, divider);
+ }
+
+
+ /************************************
+ * Conversion to-from natural formats
+ * Note: Overflows may occur
+ ************************************/
+
+ /**
+ * frsh_msec_to_rel_time()
+ *
+ * Convert an integer value of milliseconds into a relative time interval.
+ */
+ static inline frsh_rel_time_t frsh_msec_to_rel_time(long msec)
+ {
+ return fosa_msec_to_rel_time(msec);
+ }
+
+ /**
+ * frsh_rel_time_to_msec()
+ *
+ * Convert a relative interval into an integer number of milliseconds.
+ */
+ static inline long frsh_rel_time_to_msec(frsh_rel_time_t interval)
+ {
+ return fosa_rel_time_to_msec(interval);
+ }
+
+ /**
+ * frsh_msec_to_abs_time()
+ *
+ * Convert an integer value of milliseconds into an absolute time instant
+ */
+ static inline frsh_abs_time_t frsh_msec_to_abs_time(long msec)
+ {
+ return fosa_msec_to_abs_time(msec);
+ }
+
+ /**
+ * frsh_abs_time_to_msec()
+ *
+ * Convert an absolute instant into an integer number of milliseconds.
+ */
+ static inline long frsh_abs_time_to_msec(frsh_abs_time_t instant)
+ {
+ return fosa_abs_time_to_msec(instant);
+ }
+
+ /**
+ * frsh_usec_to_rel_time()
+ *
+ * Convert an integer value of microseconds into an absolute instant.
+ */
+ static inline frsh_rel_time_t frsh_usec_to_rel_time(long usec)
+ {
+ return fosa_usec_to_rel_time(usec);
+ }
+
+
+ /**
+ * frsh_rel_time_to_usec()
+ *
+ * Convert a relative interval into an integer number of microseconds.
+ */
+ static inline long frsh_rel_time_to_usec(frsh_rel_time_t interval)
+ {
+ return fosa_rel_time_to_usec(interval);
+ }
+
+ /**
+ * frsh_usec_to_abs_time()
+ *
+ * Convert an integer value of microseconds into an absolute instant.
+ */
+ static inline frsh_abs_time_t frsh_usec_to_abs_time(long usec)
+ {
+ return fosa_usec_to_abs_time(usec);
+ }
+
+
+ /**
+ * frsh_abs_time_to_usec()
+ *
+ * Convert a relative interval into an integer number of microseconds.
+ */
+ static inline long frsh_abs_time_to_usec(frsh_abs_time_t interval)
+ {
+ return fosa_abs_time_to_usec(interval);
+ }
+
+ /**
+ * frsh_nsec_to_rel_time()
+ *
+ * Convert an integer value of microseconds into an absolute instant.
+ */
+ static inline frsh_rel_time_t frsh_nsec_to_rel_time(long nsec)
+ {
+ return fosa_nsec_to_rel_time(nsec);
+ }
+
+
+ /**
+ * frsh_rel_time_to_nsec()
+ *
+ * Convert a relative interval into an integer number of microseconds.
+ */
+ static inline long frsh_rel_time_to_nsec(frsh_rel_time_t interval)
+ {
+ return fosa_rel_time_to_nsec(interval);
+ }
+
+ /**
+ * frsh_nsec_to_abs_time()
+ *
+ * Convert an integer value of microseconds into an absolute instant.
+ */
+ static inline frsh_abs_time_t frsh_nsec_to_abs_time(long nsec)
+ {
+ return fosa_nsec_to_abs_time(nsec);
+ }
+
+
+ /**
+ * frsh_abs_time_to_nsec()
+ *
+ * Convert a relative interval into an integer number of microseconds.
+ */
+ static inline long frsh_abs_time_to_nsec(frsh_abs_time_t interval)
+ {
+ return fosa_abs_time_to_nsec(interval);
+ }
+
+ /******************************************
+ * Conversion to-from POSIX timespec format
+ ******************************************/
+
+ /**
+ * frsh_timespec_to_rel_time()
+ *
+ * Convert a POSIX timespec value into a relative time interval.
+ */
+ static inline frsh_rel_time_t frsh_timespec_to_rel_time(struct timespec interval)
+ {
+ return fosa_timespec_to_rel_time(interval);
+ }
+
+ /**
+ * frsh_rel_time_to_timespec()
+ *
+ * Convert a relative interval into a POSIX timespec value.
+ */
+ static inline struct timespec frsh_rel_time_to_timespec(frsh_rel_time_t interval)
+ {
+ return fosa_rel_time_to_timespec(interval);
+ }
+
+ /**
+ * frsh_timespec_to_abs_time()
+ *
+ * Convert a POSIX timespec value into an absolute time.
+ */
+ static inline frsh_abs_time_t frsh_timespec_to_abs_time(struct timespec time)
+ {
+ return fosa_timespec_to_abs_time(time);
+ }
+
+ /**
+ * frsh_abs_time_to_timespec()
+ *
+ * Convert an absolute time into a POSIX timespec value.
+ */
+ static inline struct timespec frsh_abs_time_to_timespec(frsh_abs_time_t time)
+ {
+ return fosa_abs_time_to_timespec(time);
+ }
+
+
+ /**
+ * frsh_eat()
+ *
+ * Keep the thread busy executing for a given period of time.
+ **/
+ static inline void frsh_eat(frsh_rel_time_t *cpu_time)
+ {
+ fosa_eat(cpu_time);
+ }
+
+ /*@}*/
+
+ FRSH_CPP_END_DECLS
+
+ #endif /* !FOSA_TIME_H_ */
--- /dev/null
+ // -----------------------------------------------------------------------
+ // Copyright (C) 2006 - 2009 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
+ //
+ // FSF API web pages: http://marte.unican.es/fsf/docs
+ // http://shark.sssup.it/contrib/first/docs/
+ //
+ // This file is part of FRSH (FRescor ScHeduler)
+ //
+ // 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, 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_types.h
+ //==============================================
+ // ******** ******* ******** ** **
+ // **///// /**////** **////// /** /**
+ // ** /** /** /** /** /**
+ // ******* /******* /********* /**********
+ // **//// /**///** ////////** /**//////**
+ // ** /** //** /** /** /**
+ // ** /** //** ******** /** /**
+ // // // // //////// // //
+ //
+ // FRSH(FRescor ScHeduler), pronounced "fresh"
+ //==============================================
+
+ #ifndef FRSH_TIME_TYPES_H_
+ #define FRSH_TIME_TYPES_H_
+
+ #include <fosa_types.h>
+
+ /**
+ * @file frsh_time_types.h
+ **/
+
+
+ /**
+ * \addtogroup core
+ **/
+ /*@{*/
+
+ /** the time types shall have assignment and equal operators **/
+ typedef fosa_abs_time_t frsh_abs_time_t;
+ typedef fosa_rel_time_t frsh_rel_time_t;
+
+
+ /*@}*/
+
+ #endif /* !FRSH_TIME_TYPES_H_ */
--- /dev/null
+ /**************************************************************************/
+ /* Copyright (C) 2010 Czech Technical University in Prague */
+ /* */
+ /* This file is part of FRSH (FRescor ScHeduler) */
+ /* */
+ /* 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, 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. */
+ /**************************************************************************/
+
+
+ #ifndef _FRSH_TRANSACTION_H_
+ #define _FRSH_TRANSACTION_H_
+
+ #include "frsh_cpp_macros.h"
+ #include "frsh_core_types.h"
+
+ FRSH_CPP_BEGIN_DECLS
+
+ struct fres_transaction_t_type;
+
+ /* frsh_transaction_t is a pointer to resemble how frsh_contract_t is
+ * defined. */
+ typedef struct fres_transaction_t_type *frsh_transaction_t;
+
+ /**
+ * Initialize a transaction.
+ *
+ * @param transaction
+ *
+ * @param name The name of the transaction which can be used in
+ * frsh_transaction_wait_for_name().
+ *
+ * @return Zero on success, non-zero error code on return.
+ */
+ int
+ frsh_transaction_init(frsh_transaction_t *transaction,
+ char *name);
+
+ /**
+ * Deallocates memory of the transaction object.
+ *
+ * @param transaction
+ */
+ void
+ frsh_transaction_destroy(frsh_transaction_t *transaction);
+
+ /**
+ * Add a contract to the transaction.
+ *
+ * @param transaction Transaction
+ * @param contract Contract to add
+ *
+ * @param index Index of the contract within the transaction. The
+ * index is used in frsh_transaction_alloc_vres(). The first added
+ * contract must have zero index, the second one, etc.
+ *
+ * @return Zero on success, non-zero error code on return.
+ */
+ int
+ frsh_transaction_add_contract(frsh_transaction_t *transaction,
+ frsh_contract_t *contract,
+ int index);
+
+ /**
+ * Negotiates a multi-resource transaction.
+ *
+ * No resource is allocated in this step of negotiation. Use
+ * frsh_transaction_alloc_vres() to allocate resource and use it in
+ * application.
+ *
+ * @param trans Transaction with added contracts.
+ *
+ * @return Zero on success, non-zero error code on return.
+ */
+ int
+ frsh_transaction_negotiate(frsh_transaction_t *trans);
+
+ /**
+ * Cancels a negotiated transaction.
+ *
+ * @param trans
+ *
+ * @return Zero on success, non-zero error code on return.
+ */
+ int
+ frsh_transaction_cancel(frsh_transaction_t *trans);
+
+ /**
+ * Retrieves a negotiated transaction by name.
+ *
+ * Applications that do not initiate transaction negotiation need a
+ * way to participate in the transaction. This function waits until
+ * the transaction with a given @a name is negotiated and then returns
+ * the @a transaction object.
+ *
+ * @param name
+ * @param transaction
+ *
+ * @return Zero on success, non-zero error code on return.
+ */
+ int
+ frsh_transaction_wait_for_name(frsh_transaction_t *transaction,
+ const char *name);
+ /**
+ * Allocates VRES from the negotiated transaction.
+ *
+ * Given the transaction object and an index (see
+ * frsh_transaction_add_contract()) this function requests allocation
+ * of the
+ *
+ * @param t
+ * @param vres
+ * @param index
+ *
+ * @return
+ */
+ int
+ frsh_transaction_alloc_vres(frsh_transaction_t *t,
+ int index,
+ frsh_vres_id_t *vres);
+
+ FRSH_CPP_END_DECLS
+
+ #endif // _FRSH_TRANSACTION_H_
projects / frescor / frsh-forb.git / commitdiff