// -----------------------------------------------------------------------
+// Copyright (C) 2006 - 2007 FRESCOR consortium partners:
+//
+// Universidad de Cantabria, SPAIN
+// University of York, UK
+// Scuola Superiore Sant'Anna, ITALY
+// Kaiserslautern University, GERMANY
+// Univ. Politécnica Valencia, SPAIN
+// Czech Technical University in Prague, CZECH REPUBLIC
+// ENEA SWEDEN
+// Thales Communication S.A. FRANCE
+// Visual Tools S.A. SPAIN
+// Rapita Systems Ltd UK
+// Evidence ITALY
+//
+// See http://www.frescor.org for a link to partners' websites
+//
+// FRESCOR project (FP6/2005/IST/5-034026) is funded
+// in part by the European Union Sixth Framework Programme
+// The European Union is not liable of any use that may be
+// made of this code.
+//
+//
+// based on previous work (FSF) done in the FIRST project
+//
// Copyright (C) 2005 Mälardalen University, SWEDEN
// Scuola Superiore S.Anna, ITALY
// Universidad de Cantabria, SPAIN
// University of York, UK
//
-// FRSH API web pages: http://marte.unican.es/frsh/docs/
+// FSF API web pages: http://marte.unican.es/fsf/docs
// http://shark.sssup.it/contrib/first/docs/
//
// This file is part of FRSH API
// Public License.
// -----------------------------------------------------------------------
//frsh_configuration_parameters.h
-//===============================================================
-// FFFFFFIII RRRRR SSTTTTTTT
-// FF IIR RR SS
-// FF IR SS
-// FFFFFF RRRR SSSSST
-// FF FI RRR SS
-// FF II RRR SS
-// FF IIIIIR RS
+//==============================================
+// ******** ******* ******** ** **
+// **///// /**////** **////// /** /**
+// ** /** /** /** /** /**
+// ******* /******* /********* /**********
+// **//// /**///** ////////** /**//////**
+// ** /** //** /** /** /**
+// ** /** //** ******** /** /**
+// // // // //////// // //
//
-// Basic FRSH(FIRST Scheduling Framework) configuration parameters
-//==============================================================
-
-//////////////////////////////////////////////////////
-// Definitions required to configure the frsh
-// scheduling algorithms.
-
-#include <unistd.h>
-#include "stdbool.h"
-
+// FRSH(FRescor ScHeduler), pronounced "fresh"
+//==============================================
#ifndef _FRSH_CONFIGURATION_PARAMETERS_H_
#define _FRSH_CONFIGURATION_PARAMETERS_H_
-// This symbol specifies whether the scheduler will make a
-// schedulability test of the requested contract or not
+#include <unistd.h>
+/**
+ * @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
-// Tune these values for optimizing the amount of memory used by the
-// implementation
+#define FRSH_DISTRIBUTED_MODULE_SUPPORTED false
-// Maximum number of accepted contracts (servers)
-#define FRSH_MAX_N_SERVERS 125
+/** 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 1
+#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 threads that may be scheduled by the framework
+/** Maximum number of accepted contracts (vres) **/
+#define FRSH_MAX_N_VRES 125
-#define FRSH_MAX_N_THREADS 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
+/**
+ * Maximum number of critical sections that can be stored in a
+ * contract parameters object
+ **/
#define FRSH_MAX_N_CRITICAL_SECTIONS 25
+/**
+ * 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
-
+/**
+ * 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
-// Maximum number of synchronization objects
-
+/**
+ * Maximum number of synchronization objects
+ **/
#define FRSH_MAX_N_SYNCH_OBJECTS 5
-// Maximum number of shared objects
-
+/** 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
+
+/*@}*/
+
+/**
+ * @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 {5,0}
+
+/** Initial budget of the service thread (timespec) **/
+#define FRSH_SERVICE_THREAD_BUDGET {0,1000000}
+
+/**
+ * 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.
+ **/
+#define FRSH_SERVICE_THREAD_PRIORITY (FRSH_LOWEST_THREAD_PRIORITY+1) //3 3 //3 1
+
+
+/*@}*/
+
+
+/**
+ * @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
-////////////////////////////////////////////
-// Other implementation dependent parameters
-
-// 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 29 //104
-
-
-// Real-time signal number reserved for the application scheduler to
-// manage its timers.
-
-#define FRSH_SCHEDULER_SIGNAL SIGRTMIN
-
-
-// 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 3
-
-// 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_SERVERS * 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 {0,10000000} // 0.01 seg
- // {0,100000000} //0.1 seg
- // {0,10000000} //3.1 0.01
-
-// Initial budget of the service thread (timespec)
-
-#define FRSH_SERVICE_THREAD_BUDGET {0,1000000} // 0.001 seg
- // {0,10000000} //0.01 seg
- // {0,1000000} //3.1 0.001
-
-
-// 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.
-
-#define FRSH_SERVICE_THREAD_PRIORITY FRSH_LOWEST_THREAD_PRIORITY+1 //3 3 //3 1
-
-
-
-//Maximum number of servers that can be simultaneusly waiting for
-//being signaled in a synchronization object
-
-#define FRSH_MAX_N_SERVERS_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 {0,100000000} //3 0.1 sec
-//Maximum number of target windows in a table driven schedule
+/**
+ * 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
-#define FRSH_MAX_N_TARGET_WINDOWS 100
+/**
+ * Maximum number of vres that can be given in a vres list
+ * to the group negotiation/cancellation primitive
+ **/
+#define FRSH_MAX_N_VRES_VALUES 10
-//The cpu time given by the round robin scheduler
-//to the threads in the background (timespec)
+/**
+ * Maximum number of contracts that can be given in a contracts list
+ * to the group negotiation/cancellation primitive
+ **/
+#define FRSH_MAX_N_CONTRACT_VALUES 10
-#define FRSH_RR_SLICE_CPU_TIME {0,100000000} //3 0.1 sec
+/**
+ * Default overheads of shared object protection mechanisms
+ * These values should be calibrated on each specific execution platform
+ */
-// This function must be supplied by the user to map the preemption
-// level values given in the contracts for the servers, 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]
+// fixed overhead for saving the environment and subsequently
+// aborting a critical section; units in nanoseconds
-int
-frsh_priority_map (unsigned long plevel);
+#define FRSH_SO_FIXED_ABORT_OVHD 0
-// 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 comparissons
-#define FRSH_MAX_SIZE_SHARED_OBJ_ID 65
+// fixed overhead for copying a memory area, in nanoseconds
+#define FRSH_SO_FIXED_AREA_OVHD 0
-//Maximum number of networks accesible from a node
-#define FRSH_MAX_N_NETWORK_IDS 1
+// variable overhead for copying a memory area; units in nanoseconds per kbyte
-//Maximum number of servers that can be given in a servers list
-//to the group negotiation/cancellation primitive
+#define FRSH_SO_NANOS_PER_KB 0
-#define FRSH_MAX_N_SERVER_VALUES 10
-//Maximum number of contracts that can be given in a contracts list
-//to the group negotiation/cancellation primitive
+/*@}*/
-#define FRSH_MAX_N_CONTRACT_VALUES 10
+/*@}*/
#endif /* _FRSH_CONFIGURATION_PARAMETERS_H_ */
+