/shark/trunk/ports/first/fsf_include/fsf_contract.h |
---|
0,0 → 1,619 |
//==================================================================================== |
// 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 FSF(FIRST Scheduling Framework) contract management |
// S.Ha.R.K. Implementation |
//===================================================================== |
#include <time.h> |
#include <sys/boolean.h> |
#include <sys/types.h> |
#include "fsf_configuration_parameters.h" |
#include "fsf_opaque_types.h" |
#include "edfstar.h" |
#include "rmstar.h" |
#include "posixstar.h" |
#include "nonestar.h" |
#ifndef _FSF_CONTRACT_H_ |
#define _FSF_CONTRACT_H_ |
/* S.Ha.R.K. Init */ |
int FSF_register_module(int server_level, bandwidth_t max_bw); |
////////////////////////////////////////////////////////////////// |
// BASIC TYPES AND CONSTANTS |
////////////////////////////////////////////////////////////////// |
typedef enum {FSF_BOUNDED, FSF_INDETERMINATE} fsf_workload_t; |
typedef enum {FSF_CONTINUOUS, FSF_DISCRETE} fsf_granularity_t; |
typedef struct { |
struct timespec budget; // Execution time |
struct timespec period; // Period |
} fsf_utilization_value_t; |
typedef struct { |
int size; // = 0 |
fsf_utilization_value_t unit[FSF_MAX_N_UTILIZATION_VALUES]; |
} fsf_utilization_set_t; |
typedef unsigned long fsf_preemption_level_t; // range 1..2**32-1 |
typedef struct { |
struct timespec wcet; // Execution time |
fsf_preemption_level_t plevel; // Preemption_Level, range 1..2**32-1 |
} fsf_critical_section_data_t; |
// Definition of basic types |
typedef unsigned int fsf_shared_op_id_t; |
typedef unsigned int fsf_shared_obj_id_t; |
// Operations |
// The first field contains the id of the related object |
// the second field contains an identifier of the operation |
// this identifier is unique for the object but needs not to be unique |
// for the system. In other words, there can be two operations with the |
// same identifier belonging to different shared objects: they are |
// effectively two distinct operations; two different operations on the |
// same object must have different identifiers |
typedef struct { |
fsf_shared_obj_id_t obj_id; // Object identification |
fsf_shared_op_id_t op_id; // Operation Identification |
struct timespec wcet; // Execution time |
} fsf_shared_operation_t; |
// Shared object |
// the first field is the number of distinct operations on the |
// shared object. It is initialized to 0. |
// the second field is the id of the object, must be unique in the system. |
// the third field is a list of shared operations. |
typedef struct { |
int size; // = 0 |
fsf_critical_section_data_t section[FSF_MAX_N_CRITICAL_SECTIONS]; |
} fsf_critical_sections_t; |
typedef struct { |
int size; // = 0 |
fsf_shared_obj_id_t obj_id; // object id |
fsf_shared_operation_t shared_op[FSF_MAX_SHARED_OPERATION]; |
} fsf_shared_object_t; |
typedef struct { |
int size; // =0 |
fsf_shared_operation_t operation[FSF_MAX_SHARED_OPERATION]; |
} fsf_shared_operations_t; |
typedef int fsf_scheduler_id_t; |
#define FSF_SCHEDULER_POSIX 0 |
#define FSF_SCHEDULER_EDF 1 |
#define FSF_SCHEDULER_RM 2 |
#define FSF_SCHEDULER_NONE 3 |
// Constants for assigning default values |
#define FSF_DEFAULT_WORKLOAD FSF_INDETERMINATE |
#define FSF_DEFAULT_GRANULARITY FSF_CONTINUOUS |
#define FSF_DEFAULT_QUALITY 0 |
#define FSF_DEFAULT_IMPORTANCE 1 |
#define FSF_DEFAULT_D_EQUALS_T TRUE |
#define FSF_DEFAULT_DEADLINE {0,0} |
#define FSF_DEFAULT_SCHEDULER FSF_SCHEDULER_NONE |
// Constants for omitting the assignment of values to specific arguments |
// in calls to initialization functions |
#define FSF_NULL_CRITICAL_SECTIONS (fsf_critical_sections_t *)NULL |
#define FSF_NULL_UTILIZATION_SET (fsf_utilization_set_t *)NULL |
#define FSF_NULL_DEADLINE (struct timespec *)NULL |
#define FSF_NULL_SIGNAL 0 |
// Error codes |
#define FSF_ERR_NOT_INITIALIZED 2003001 |
#define FSF_ERR_TOO_MANY_TASKS 2003002 |
#define FSF_ERR_ALREADY_INITIALIZED 2003003 |
#define FSF_ERR_BAD_ARGUMENT 2003004 |
#define FSF_ERR_INVALID_SYNCH_OBJECT_HANDLE 2003005 |
#define FSF_ERR_NO_RENEGOTIATION_REQUESTED 2003006 |
#define FSF_ERR_CONTRACT_REJECTED 2003007 |
#define FSF_ERR_TOO_MANY_SERVERS 2003008 |
#define FSF_ERR_CREATE_THREAD 2003009 |
#define FSF_ERR_SERVER_USED 2003010 |
#define FSF_ERR_INVALID_SERVER 2003011 |
#define FSF_ERR_CREATE_SERVER 2003012 |
////////////////////////////////////////////////////////////// |
// CONTRACT PARAMETERS |
////////////////////////////////////////////////////////////// |
// Contract parameters type; it is an opaque type |
typedef FSF_CONTRACT_PARAMETERS_T_OPAQUE fsf_contract_parameters_t; |
int |
fsf_initialize_contract(fsf_contract_parameters_t *contract); |
//Description: The operation receives a pointer to a contract parameters |
//object and initializes it, setting it to the default values. |
// budget_min => {0,0}; |
// period_max => {0,0}; |
// budget_max => {0,0}; |
// period_min => {0,0}; |
// workload => DEFAULT_WORKLOAD; |
// d_equals_t => DEFAULT_D_EQUALS_T; (false or true) |
// deadline => DEFAULT_DEADLINE; |
// budget_overrun_sig_notify => 0; (signal number) |
// budget_overrun_sig_value => {0, NULL}; |
// deadline_miss_sig_notify => 0; (signal number) |
// deadline_miss_sig_value => {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 |
int |
fsf_set_contract_basic_parameters |
(fsf_contract_parameters_t *contract, |
const struct timespec *budget_min, |
const struct timespec *period_max, |
const struct timespec *budget_max, |
const struct timespec *period_min, |
fsf_workload_t workload); |
//Description: The operation updates the specified contract parameters |
//object by setting its budget, period, and workload to the specified |
//input parameters. (Note: the workload is a basic parameter because |
//bounded tasks are triggered by the scheduler (see the Timed Schedule |
//Next Job operation, later), while indeterminate tasks are not; |
//therefore, their programming model is quite different). |
int |
fsf_get_contract_basic_parameters |
(const fsf_contract_parameters_t *contract, |
struct timespec *budget_min, |
struct timespec *period_max, |
struct timespec *budget_max, |
struct timespec *period_min, |
fsf_workload_t *workload); |
//Description: This operation obtains from the specified contract parameters |
//object its budget, period, and workload, and copies them to the places |
//pointed to by the corresponding input parameters. |
int |
fsf_set_contract_timing_requirements |
(fsf_contract_parameters_t *contract, |
bool d_equals_t, |
const struct timespec *deadline, |
int budget_overrun_sig_notify, |
union sigval budget_overrun_sig_value, |
int deadline_miss_sig_notify, |
union sigval deadline_miss_sig_value); |
//Description: The operation updates the specified contract parameters |
//object. d_equals_t is used as a boolean, deadline must be |
//NULL_DEADLINE if d_equals_t is true, budget_overrun_sig_notify or |
//deadline_miss_sig_notify may be NULL_SIGNAL (no notification) or any |
//posix signal. budget_overrun_sig_value and deadline_miss_sig_value |
//are the values to be delivered with the signal. |
int |
fsf_get_contract_timing_requirements |
(const fsf_contract_parameters_t *contract, |
bool *d_equals_t, |
struct timespec *deadline, |
int *budget_overrun_sig_notify, |
union sigval *budget_overrun_sig_value, |
int *deadline_miss_sig_notify, |
union sigval *deadline_miss_sig_value); |
//Description: The operation obtains the corresponding input |
//parameters from the specified contract parameters object. If |
//d_equals_t is true, the deadline will not be updated. |
int |
fsf_set_contract_reclamation_parameters |
(fsf_contract_parameters_t *contract, |
fsf_granularity_t granularity, |
const fsf_utilization_set_t *utilization_set, |
int quality, |
int importance); |
//Description: The operation updates the specified contract parameters |
//object by setting its granularity, utilization set, quality, and |
//importance to the specified input parameters. |
int |
fsf_get_contract_reclamation_parameters |
(const fsf_contract_parameters_t *contract, |
fsf_granularity_t *granularity, |
fsf_utilization_set_t *utilization_set, |
int *quality, |
int *importance); |
//Description: The operation obtains from the specified contract parameters |
//object its granularity, utilization set, quality, and importance. Then |
//copies them to the places pointed to by the specified input parameters. |
//Only the utilization_values of the utilization_set that are in use, are |
//copied (according to its size field). |
/* OLD VERSION |
int |
fsf_set_contract_synchronization_parameters |
(fsf_contract_parameters_t *contract, |
fsf_preemption_level_t preemption_level, |
const fsf_critical_sections_t *critical_sections); |
//Description: The operation updates the specified contract parameters |
//object by setting its preemption level and critical sections to the |
//specified input parameters. |
*/ |
int |
fsf_get_contract_synchronization_parameters |
(const fsf_contract_parameters_t *contract, |
fsf_preemption_level_t *preemption_level, |
fsf_critical_sections_t *critical_sections); |
//Description: The operation obtains from the specified contract |
//parameters object its preemption level and critical sections, and |
//copies them to the places pointed to by the specified input |
//parameters. Only those critical_section_data records that are in use |
//in the critical_sections structure are copied (according to its size |
//field). |
int |
fsf_set_local_scheduler_parameter |
(fsf_contract_parameters_t *contract, |
fsf_scheduler_id_t local_scheduler_id); |
//Description: Set the local scheduler |
int |
fsf_get_local_scheduler_parameter |
(const fsf_contract_parameters_t *contract, |
fsf_scheduler_id_t *local_scheduler_id); |
//Description: Get the local scheduler |
////////////////////////////////////////////////////////////// |
// SYNCHRONIZATION OBJECTS |
////////////////////////////////////////////////////////////// |
//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 Event Triggered Schedule Next Job operation. |
//It can also be used to signal the event either causing a waiting |
//server to wake up, or the event to be queued if no server is waiting |
//for it. It is defined by the following opaque type and has the |
//following operations: |
typedef FSF_SYNCH_OBJECT_HANDLE_T_OPAQUE fsf_synch_object_handle_t; |
int |
fsf_create_synchobject(fsf_synch_object_handle_t *synch_handle); |
//Description: 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. |
int |
fsf_signal_synchobject(fsf_synch_object_handle_t *synch_handle); |
//Description: If one or more servers are waiting upon the specified |
//synchronization object one of them is awakened; if not, the event is |
//queued at the synchronization object. |
int |
fsf_destroy_synchobject(fsf_synch_object_handle_t *synch_handle); |
//This operation destroys the synchronization object (created by a |
//previous call to fsf_create_synchobject) 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 fsf_create_synchobject. |
/////////////////////////////////////////////////////////////// |
// CONTRACT NEGOCIATION OPERATIONS |
/////////////////////////////////////////////////////////////// |
// Server Id type, that identifies a server created to manage a |
// given contract |
typedef int fsf_server_id_t; |
typedef struct { |
fsf_server_id_t server; |
TIME actual_period; |
TIME actual_budget; |
int Qs; // quality of service |
int Is; // importance of service |
bandwidth_t U; // actual bandwidth |
bandwidth_t Umin; // min bandwidth |
bandwidth_t Umax; // max bandwidth |
TIME Cmin; |
TIME Tmin; |
TIME Tmax; |
TIME deadline; |
bool d_equals_t; |
} server_elem; |
int recalculate_contract(bandwidth_t U); |
// The following type references a function that may become |
// a thread's code |
typedef void * (*fsf_thread_code_t) (void *); |
// Negotiate contract functions: The following functions are used to |
// create servers for a contract parameters specification and also to |
// assign one or more threads to a server (Note: the current |
// implementation only supports one thread per server; this limitation |
// will be removed in the next phase of the project) |
// The first time that any of these operations is called, it creates |
// all the internal management structures that are necessary for the |
// FIRST Scheduling Framework to operate properly. |
int |
fsf_negotiate_contract |
(const fsf_contract_parameters_t *contract, |
fsf_server_id_t *server); |
//Description: The operation negotiates a contract for a new |
//server. 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 server 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. It returns zero and places the |
//server identification number in the location pointed to by the |
//server input parameter if accepted, or an error if rejected. No |
//thread is bound to the newly created server, which will be idle |
//until a thread is bound to it. This operation can only be executed |
//by threads that are already bound to an active server and therefore |
//are being scheduled by the fsf scheduler. |
int |
fsf_create_thread |
(fsf_server_id_t server, |
pthread_t *thread, |
pthread_attr_t *attr, |
fsf_thread_code_t thread_code, |
void *arg, |
void *local_scheduler_arg); |
//Description: This operation creates a new thread inside a specific |
//server. The local_scheduler_arg parameter is used to pass specific |
//parameters to local scheduler. These parameters are application |
//depented. |
int |
fsf_get_server |
(fsf_server_id_t *server, |
pthread_t thread); |
//Description: This operation returns the server associated with a |
//thread. It returns an error if the thread does not exist, it is not |
//under the control of the scheduling framework, or is not bound. |
int |
fsf_cancel_contract (fsf_server_id_t *server); |
//Description: The operation eliminates the specified server 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. |
int |
fsf_renegotiate_contract |
(const fsf_contract_parameters_t *new_contract, |
fsf_server_id_t server); |
//Description: The operation renegotiates a contract for an existing |
//server. 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 anr 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. |
int |
fsf_request_contract_renegotiation |
(const fsf_contract_parameters_t *new_contract, |
fsf_server_id_t server, |
int sig_notify, |
union sigval sig_value); |
//Description: The operation enqueues a renegotiate operation for an |
//existing server, 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 |
//get_renegotiation_status operation. The argument sig_notify can be |
//NULL_SIGNAL (no notification), or any posix signal; and in this case |
//sig_value is to be sent with the signal. |
typedef enum {FSF_IN_PROGRESS, |
FSF_REJECTED, |
FSF_ADMITTED} fsf_renegotiation_status_t; |
int |
fsf_get_renegotiation_status |
(fsf_server_id_t server, |
fsf_renegotiation_status_t *renegotiation_status); |
//Description: The operation reports on the status of the last |
//renegotiation operation enqueued for the specified server. It is |
//callable even after notification of the completion of such operation, |
//if requested. |
int |
fsf_request_change_quality_and_importance |
(fsf_server_id_t server, |
int new_importance, |
int new_quality); |
//Description: The operation enqueues a request to change the quality and |
//importance parameters of the specified server, and returns immediately. |
//The change operation is performed as soon as it is practical; |
//meanwhile the system operation will continue normally. |
//////////////////////////////////////////////////////////// |
// SCHEDULING BOUNDED WORKLOADS |
//////////////////////////////////////////////////////////// |
int |
fsf_schedule_next_timed_job |
(const struct timespec *at_absolute_time, |
struct timespec *next_budget, |
struct timespec *next_period, |
bool *was_deadline_missed, |
bool *was_budget_overran); |
//Description: This operation is invoked by threads associated with |
//bounded workload servers to indicate that a job has been completed |
//(and that the scheduler may reassign the unused capacity of the |
//current job to other servers), and also when the first job require |
//to be scheduled. The system will activate the job at the specified |
//absolute time, and will then use the scheduling rules to determine |
//when the job can run, at which time the call returns. Upon return, |
//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. |
int |
fsf_schedule_next_event_triggered_job |
(fsf_synch_object_handle_t *synch_handle, |
struct timespec *next_budget, |
struct timespec *next_period, |
bool *was_deadline_missed, |
bool *was_budget_overran); |
//Description: This operation is invoked by threads associated with |
//bounded workload servers to indicate that a job has been completed |
//(and that the scheduler may reassign the unused capacity of the |
//current job to other servers), and also when the first job require |
//to be scheduled. If the specified synchronization object has events |
//queued, one of them is dequeued; otherwise the server will wait upon |
//the specified synchronization object until it is signalled. Then, the |
//system will use the scheduling rules to determine when the job can run |
//and the call will return at that time. Upon return, 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. |
////////////////////////////////////////////////////////////// |
// OBTAINING INFORMATION FROM THE SCHEDULER |
////////////////////////////////////////////////////////////// |
int |
fsf_get_available_capacity (fsf_server_id_t server, float *capacity); |
//Description: This operation returns the current spare capacity (in |
//percentage of processor or network utilization), currently assigned |
//to the importance level of the specified server. |
int |
fsf_get_total_quality (fsf_server_id_t server, int *total_quality); |
//Description: This operation returns the sum of the quality parameters |
//for all servers in the system of importance level equal to that of |
//the specified server. |
int |
fsf_is_admission_test_enabled(); |
//Description: Returns true if the system is configured with the |
//on-line admission test enabled, or false otherwise. |
// Mutex function |
// Initialization |
// here we initialize the second and third field of the structure |
void fsf_init_shared_op(fsf_shared_operation_t *op, |
fsf_shared_op_id_t op_id, |
struct timespec wcet); |
// initialization |
// The shared object id is set equal to the second parameter. |
int fsf_init_shared_object(fsf_shared_object_t *obj, |
fsf_shared_obj_id_t id); |
// Declare an operation |
// This function is used to declare that a shared object has |
// a synchronized operation on it. |
// It checks if another operation with the same id has already been |
// declared; if so, return false (-1). |
// The obj_id field of the operation is set equal to the shared object id. |
// the structure op is copied in the first free element in the array |
// shared_op pof the structure obj. If there are no more free element, |
// returns -1. |
// Returns 0 if the operation has been completed, -1 otherwise. |
int fsf_declare_shared_object_operation(fsf_shared_object_t *obj, |
fsf_shared_operation_t *op); |
int fsf_lock_object(fsf_shared_operation_t *op); |
int fsf_unlock_object(fsf_shared_operation_t *op); |
// set contract parameters |
// specify a list of operations for each contract |
// the list is specified as a pointer to an array. |
// the size of the array is specified as third parameter |
// returns 0 if all operations are correctly initialized |
// returns -1 otherwise. |
int fsf_set_contract_synchronization_parameters( |
fsf_contract_parameters_t *contract, |
const fsf_shared_operation_t *shared_ops, |
size_t op_num); |
#endif // _FSF_CONTRACT_H_ |
/shark/trunk/ports/first/fsf_include/fsf_hierarchical.h |
---|
0,0 → 1,277 |
//fsf_hierarchical.h |
//==================================================================== |
// FFFFFFIII RRRRR SSTTTTTTT |
// FF IIR RR SS |
// FF IR SS |
// FFFFFF RRRR SSSSST |
// FF FI RRR SS |
// FF II RRR SS |
// FF IIIIIR RS |
// |
// FSF(FIRST Scheduling Framework) |
// hierarchical scheduling management |
//=================================================================== |
#include <time.h> |
#include "fsf_basic_types.h" |
#include "fsf_core.h" |
#ifndef _FSF_HIERARCHICAL_H_ |
#define _FSF_HIERARCHICAL_H_ |
#define FSF_HIERARCHICAL_MODULE_SUPPORTED 1 |
//// The definition of this types is in fsf_basic_types.h |
// |
//// Scheduling policies |
//typedef enum {FSF_FP, FSF_EDF, FSF_TABLE_DRIVEN, FSF_NONE} |
// fsf_sched_policy_t; |
// |
//// Scheduling policy and parameters |
//typedef struct { |
// fsf_sched_policy_t policy; |
// void * params; |
//} fsf_sched_params_t; |
//// The params member is a pointer to one of the |
//// following: |
//// FP: int (priority) |
//// EDF: struct timespec (deadline) |
//// TABLE_DRIVEN : struct fsf_table_driven_params_t |
// |
// |
////Scheduling parameters for the table-driven policy (t.b.d) |
//typedef struct { |
// // list of target windows (t.b.d.) |
// // deadline (for the API): end of september |
//} fsf_table_driven_params_t; |
// |
// |
////Initialization information for a scheduling policy |
//typedef void * fsf_sched_init_info_t; |
//// It shall be one of the following: |
//// FP: none |
//// EDF: none |
//// TABLE_DRIVEN : struct timespec (schedule duration) |
// |
// Constants for assigning default values |
#define FSF_DEFAULT_SCHED_POLICY FSF_NONE |
/** |
\ingroup hiermodule |
This call has the following effects: |
- FP: none |
- EDF: none |
- 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. |
@param [in] server server id |
@param [in] info TBD |
@retval FSF_ERR_BAD_ARGUMENT if the value of the server argument |
is not in range or info is NULL |
@retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD if the calling thread is not |
scheduled under the FSF |
@retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or not |
running |
@retval FSF_ERR_NOT_CONTRACTED_SERVER if the server of the calling |
thread has been cancelled or it is not valid |
*/ |
int fsf_init_local_scheduler( |
fsf_server_id_t server, |
fsf_sched_init_info_t info); |
///////////////////////////////////////////////// |
// CONTRACT PARAMETERS |
//////////////////////////////////////////////// |
/** |
\ingroup hiermodule |
The operation updates the specified contract parameters object by |
setting its scheduling policy to the specified input parameter. |
The default policy is FSF_NONE, which means that only one thread |
may be bound to the server |
@param [in] contract pointer to the contract |
@param [in] sched_policy local scheduling policy for this server. |
Can be FSF_FP, FSF_EDF, FSF_TABLE_DRIVEN, FSF_NONE. |
@retval 0 if the operation is succesful |
@retval FSF_ERR_BAD_ARGUMENT if sched_policy is not one of the supported |
ones, or contract is NULL |
*/ |
int |
fsf_set_contract_scheduling_policy |
(fsf_contract_parameters_t *contract, |
fsf_sched_policy_t sched_policy); |
/** |
\ingroup hiermodule |
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. |
@param [in] contract pointer to the contract |
@param [out] sched_policy pointer to a variable that will contain |
the scheduling policy |
@retval 0 if the operation is succesful |
@retval FSF_ERR_BAD_ARGUMENT if sched_policy or contract are NULL |
*/ |
int |
fsf_get_contract_scheduling_policy |
(const fsf_contract_parameters_t *contract, |
fsf_sched_policy_t *sched_policy); |
/** |
\ingroup hiermodule |
This operation creates a thread and binds it to the specified |
server, which must have a policy different than FSF_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 server's scheduling policy. Then, the function |
binds the created thread to the new server. 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 fsf_priority_map() function defined by the user. |
@param [in] server server id |
@param [in] sched_params scheduling parameters for the thread |
@param [out] thread the thread id after creation |
@param [in] attr attributes for the task (see pthread_create()) |
@param [in] thread_code pointer to a function that implements the |
thread code |
@param [in] arg arguments for the thread |
@retval 0 if the operation is succesful |
@retval FSF_ERR_BAD_ARGUMENT if the value of the server argument |
is not in range, or sched_params is NULL |
@retval FSF_ERR_SCHED_POLICY_NOT_COMPATIBLE if the scheduling policy |
in sched_params is not compatible to the server's one. |
@retval FSF_ERR_INTERNAL_ERROR erroneous binding or malfunction of the FSF |
main scheduler |
@retval FSF_ERR_NOT_CONTRACTED_SERVER if the referenced server is not valid |
@retval others It may also return any of the errors that may be |
returned by the pthread_create()POSIX function call |
*/ |
int |
fsf_create_local_thread |
(fsf_server_id_t server, |
fsf_sched_params_t *sched_params, |
pthread_t *thread, |
pthread_attr_t *attr, |
fsf_thread_code_t thread_code, |
void *arg); |
/** |
\ingroup hiermodule |
This operation associates a thread with a server, which must have a |
policy different than FSF_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 server's |
scheduling policy. After the call the thread starts consuming the |
server's budget and is executed according to the contract |
established for that server and to its scheduling policy. If the |
thread was already bound to another server, 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 fsf scheduler. |
@param [in] server server id |
@param [in] thread thread id |
@param [in] sched_params scheduling parameters for the thread |
@retval 0 if the operation is succesful |
@retval FSF_ERR_BAD_ARGUMENT if the server argument does not complain with |
the expected format or valid range, the given thread does not exist, |
or sched_params is NULL |
@retval FSF_ERR_SCHED_POLICY_NOT_COMPATIBLE if the scheduling policy |
in sched_params is not compatible to the server's one. |
@retval FSF_ERR_INTERNAL_ERROR erroneous binding or malfunction of the FSF |
main scheduler |
@retval FSF_ERR_UNKNOWN_APPSCHEDULED_THREAD if the thread is attached to |
an application defined scheduler different than the fsf scheduler |
@retval FSF_ERR_NOT_CONTRACTED_SERVER if the referenced server is not valid |
*/ |
int |
fsf_bind_local_thread_to_server |
(fsf_server_id_t server, |
pthread_t thread, |
fsf_sched_params_t *sched_params); |
/** |
\ingroup hiermodule |
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 server to which the |
thread is bound. |
@param [in] thread thread id |
@param [in] sched_params scheduling parameters |
@retval 0 if the operation is succesful |
@retval FSF_ERR_BAD_ARGUMENT if the given thread does not exist, |
or sched_params is NULL |
@retval FSF_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 server. |
@retval FSF_ERR_NOT_SCHEDULED_THREAD if the given thread is not scheduled |
under the FSF |
@retval FSF_ERR_INTERNAL_ERROR erroneous binding or malfunction of the FSF |
main scheduler |
@retval FSF_ERR_UNKNOWN_APPSCHEDULED_THREAD if the thread is attached to |
an application defined scheduler different than the fsf scheduler |
@retval FSF_ERR_NOT_CONTRACTED_SERVER if the thread is bound and its server |
is not valid |
*/ |
int |
fsf_set_local_thread_sched_parameters |
(pthread_t thread, |
const fsf_sched_params_t *sched_params); |
/** |
\ingroup hiermodule |
This function stores the local scheduling parameters of the |
specified thread in the variable pointed to by sched_params |
@param [in] thread thread id |
@param [out] sched_params scheduling parameters |
@retval 0 if the operation is succesful |
@retval FSF_ERR_BAD_ARGUMENT if sched_params is NULL or the thread does |
not exist |
@retval FSF_ERR_NOT_SCHEDULED_THREAD if the given thread is not scheduled |
under the FSF |
*/ |
int |
fsf_get_local_thread_sched_parameters |
(pthread_t thread, |
fsf_sched_params_t *sched_params); |
#endif // _FSF_HIERARCHICAL_H_ |
/shark/trunk/ports/first/fsf_include/fsf_opaque_types.h |
---|
0,0 → 1,85 |
//fsf_opaque_types.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 FSF(FIRST Scheduling Framework) contract management opaque types |
//======================================================================= |
// Implementation dependent definitions |
#include <signal.h> |
#ifndef _FSF_OPAQUE_TYPES_H_ |
#define _FSF_OPAQUE_TYPES_H_ |
#define FSF_CONTRACT_PARAMETERS_T_OPAQUE struct { \ |
\ |
struct timespec budget_min; \ |
struct timespec period_max; \ |
struct timespec budget_max; \ |
struct timespec period_min; \ |
fsf_workload_t workload; \ |
\ |
bool d_equals_t; \ |
struct timespec deadline; \ |
int budget_overrun_sig_notify; \ |
union sigval budget_overrun_sig_value; \ |
int deadline_miss_sig_notify; \ |
union sigval deadline_miss_sig_value; \ |
\ |
fsf_granularity_t granularity; \ |
fsf_utilization_set_t utilization_set; \ |
int quality; \ |
int importance; \ |
\ |
fsf_preemption_level_t preemption_level; \ |
fsf_critical_sections_t critical_sections; \ |
\ |
fsf_sched_policy_t policy; \ |
\ |
} |
//Default values for fsf_contract_parameters_t: |
// budget_min => {0,0}; |
// period_max => {0,0}; |
// budget_max => {0,0}; |
// period_min => {0,0}; |
// workload => DEFAULT_WORKLOAD; |
// d_equals_t => DEFAULT_D_EQUALS_T; |
// (false or true) |
// deadline => DEFAULT_DEADLINE; |
// budget_overrun_sig_notify => 0; (signal number) |
// budget_overrun_sig_value => {0, NULL}; |
// deadline_miss_sig_notify => 0; (signal number) |
// deadline_miss_sig_value => {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 |
// |
// policy => DEFAULT_SCHED_POLICY; |
// (FSF_NONE) |
#define FSF_SYNCH_OBJ_HANDLE_T_OPAQUE int |
#define FSF_SHARED_OBJ_HANDLE_T_OPAQUE int |
#endif // _FSF_OPAQUE_TYPES_H_ |
/shark/trunk/ports/first/fsf_include/fsf_dynamic_reclaiming.h |
---|
0,0 → 1,23 |
//fsf_dynamic_reclaiming.h |
//=============================================== |
// FFFFFFIII RRRRR SSTTTTTTT |
// FF IIR RR SS |
// FF IR SS |
// FFFFFF RRRR SSSSST |
// FF FI RRR SS |
// FF II RRR SS |
// FF IIIIIR RS |
// |
// FSF(FIRST Scheduling Framework) |
// dynamic reclaiming capabilities |
//=============================================== |
#include "fsf_core.h" |
#ifndef _FSF_DYNAMIC_RECLAIMING_H_ |
#define _FSF_DYNAMIC_RECLAIMING_H_ |
#define FSF_DYNAMIC_RECLAIMING_MODULE_SUPPORTED 1 |
#endif // _FSF_DYNAMIC_RECLAIMING_H_ |
/shark/trunk/ports/first/fsf_include/fsf_shared_objects.h |
---|
0,0 → 1,185 |
//fsf_shared_objects.h |
//================================================== |
// FFFFFFIII RRRRR SSTTTTTTT |
// FF IIR RR SS |
// FF IR SS |
// FFFFFF RRRR SSSSST |
// FF FI RRR SS |
// FF II RRR SS |
// FF IIIIIR RS |
// |
// FSF(FIRST Scheduling Framework) |
// shared objects functionality |
//==================================================== |
#include <pthread.h> |
#include "fsf_basic_types.h" |
#include "fsf_core.h" |
#ifndef _FSF_SHARED_OBJECTS_H_ |
#define _FSF_SHARED_OBJECTS_H_ |
#define FSF_SHARED_OBJECTS_MODULE_SUPPORTED 1 |
// These constants are defined in the fsf_configuration_parameters.h |
// file: |
//#define FSF_MAX_N_SHARED_OBJECTS 100 |
//#define FSF_MAX_N_CRITICAL_SECTIONS 20 |
//// The definition of this types is in fsf_basic_types.h |
// |
//// Shared object identifier (null character terminated string) |
//typedef char * fsf_shared_obj_id_t; |
// |
//// Shared object handle (opaque type) |
//typedef FSF_SHARED_OBJ_HANDLE_T_OPAQUE fsf_shared_obj_handle_t; |
// |
//// Critical section data |
//typedef struct { |
// fsf_shared_obj_handle_t obj_handle; |
// struct timespec wcet; //Execution time |
//} fsf_critical_section_data_t; |
// |
//// List of critical sections |
//typedef struct { |
// int size; // = 0 |
// fsf_critical_section_data_t |
// section[FSF_MAX_N_CRITICAL_SECTIONS]; |
//} fsf_critical_sections_t; |
// |
///////////////////////////////////////////////////// |
// SHARED OBJECTS & OPERATIONS MANAGEMENT |
///////////////////////////////////////////////////// |
/** |
\ingroup shobjmodule |
Initialization of shared objects. If the object identified by |
obj_id 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. |
@param [in] obj_id shared object id |
@param [out] obj_handle pointer to a shared object handle |
@param [out] mutex pointer to a mutex variable |
@retval 0 if the operation is succesful |
@retval FSF_ERR_BAD_ARGUMENT if obj_id, obj_handle, or mutex are NULL |
@retval FSF_ERR_SHARED_OBJ_ALREADY_INITIALIZED if the object identified |
by obj_id already exists |
@retval others It may also return any of the error codes that are |
returned by the pthread_mutex_init() POSIX function call |
*/ |
int fsf_init_shared_object |
(fsf_shared_obj_id_t obj_id, |
fsf_shared_obj_handle_t *obj_handle, |
pthread_mutex_t *mutex); |
/** |
\ingroup shobjmodule |
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 by the function. |
@param [in] obj_id shared object id |
@param [out] obj_handle pointer to a shared object handle |
@retval 0 if the operation is succesful |
@retval FSF_ERR_BAD_ARGUMENT if obj_id or obj_handle are NULL |
@retval FSF_ERR_SHARED_OBJ_NOT_INITIALIZED if the shared object identified |
by obj_id does not exist |
@retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not |
scheduled under the FSF |
@retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or not |
running |
@retval FSF_ERR_NOT_CONTRACTED_SERVER : if the server of the calling |
thread has been cancelled or it is not valid |
*/ |
int fsf_get_shared_object_handle |
(fsf_shared_obj_id_t obj_id, |
fsf_shared_obj_handle_t *obj_handle); |
/** |
\ingroup shobjmodule |
Getting the mutex of shared objects. If the object exists, a |
pointer to its associated mutex is returned in the variable pointed |
to by mutex. Otherwise, an error code is returned by the function. |
@param [in] obj_handle shared object handle |
@param [out] mutex pointer to a pointer to a mutex variable, |
(remember that the function give back a pointer to a mutex!) |
@retval 0 if the operation is succesful |
@retval FSF_ERR_BAD_ARGUMENT if obj_handle or mutex are NULL |
@retval FSF_ERR_SHARED_OBJ_NOT_INITIALIZED if the shared object identified |
by obj_id does not exist |
@retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not |
scheduled under the FSF |
@retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or not |
running |
@retval FSF_ERR_NOT_CONTRACTED_SERVER if the server of the calling thread |
has been cancelled or it is not valid |
*/ |
int fsf_get_shared_object_mutex |
(fsf_shared_obj_handle_t obj_handle, |
pthread_mutex_t **mutex); |
///////////////////////////////////////////////////// |
// CONTRACT PARAMETERS |
///////////////////////////////////////////////////// |
/** |
\ingroup shobjmodule |
The operation updates the specified contract parameters object by |
setting its critical sections to the specified input parameter. |
@param[in] contract the service contract |
@param[in] critical_sections list of critical sections accessed by tasks |
belonging to the contract |
@retval 0 if the operation is succesful |
@retval FSF_ERR_BAD_ARGUMENT :if any of the pointers is NULL or |
the size of the critical_sections structure is less than zero |
or grater than FSF_MAX_N_CRITICAL_SECTIONS |
*/ |
int |
fsf_set_contract_synchronization_parameters |
(fsf_contract_parameters_t *contract, |
const fsf_critical_sections_t *critical_sections); |
/** |
\ingroup shobjmodule |
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). |
@param[in] contract pointer to a contract |
@param[out] critical_sections list of critical sections to be filled |
@retval 0 if the operation is succesful |
@retval FSF_ERR_BAD_ARGUMENT if any of the pointers is NULL |
*/ |
int |
fsf_get_contract_synchronization_parameters |
(const fsf_contract_parameters_t *contract, |
fsf_critical_sections_t *critical_sections); |
#endif // _FSF_SHARED_OBJECTS_H_ |
/shark/trunk/ports/first/fsf_include/fsf.h |
---|
0,0 → 1,97 |
//fsf.h |
//=========================================================== |
// FFFFFFIII RRRRR SSTTTTTTT |
// FF IIR RR SS |
// FF IR SS |
// FFFFFF RRRR SSSSST |
// FF FI RRR SS |
// FF II RRR SS |
// FF IIIIIR RS |
// |
// FSF(FIRST Scheduling Framework) available functionality |
//============================================================ |
#include "fsf_configuration_parameters.h" |
#include "fsf_opaque_types.h" |
#include "fsf_basic_types.h" |
#include "fsf_core.h" |
#include "fsf_server.h" |
// Configure theses modules by commenting out the appropiate lines |
#include "fsf_hierarchical.h" // |
#include "fsf_shared_objects.h" |
#include "fsf_dynamic_reclaiming.h" // |
#include "fsf_spare_capacity.h" |
//#include "fsf_distributed_services.h" |
#ifndef _FSF_H_ |
#define _FSF_H_ |
#ifndef FSF_HIERARCHICAL_MODULE_SUPPORTED |
#define FSF_HIERARCHICAL_MODULE_SUPPORTED 0 |
#endif //FSF_HIERARCHICAL_MODULE_SUPPORTED |
#ifndef FSF_SHARED_OBJECTS_MODULE_SUPPORTED |
#define FSF_SHARED_OBJECTS_MODULE_SUPPORTED 0 |
#endif //FSF_SHARED_OBJECTS_MODULE_SUPPORTED |
#ifndef FSF_DYNAMIC_RECLAIMING_MODULE_SUPPORTED |
#define FSF_DYNAMIC_RECLAIMING_MODULE_SUPPORTED 0 |
#endif //FSF_DYNAMIC_RECLAIMING_MODULE_SUPPORTED |
#ifndef FSF_SPARE_CAPACITY_MODULE_SUPPORTED |
#define FSF_SPARE_CAPACITY_MODULE_SUPPORTED 0 |
//Return warnings if spare_capacity module is not included: |
//get rid of the pritfs (t.b.d) |
#define fsf_set_contract_reclamation_parameters \ |
(contract, budget_max, period_min, granularity,\ |
utilization_set, quality, importance) \ |
( FSF_WRN_MODULE_NOT SUPPORTED ) |
#define fsf_get_contract_reclamation_parameters \ |
(contract, budget_max, period_min, granularity,\ |
utilization_set, quality, importance) \ |
( FSF_WRN_MODULE_NOT SUPPORTED ) |
#define fsf_request_change_quality_and_importance\ |
(server, new_importance, new_quality) \ |
( FSF_WRN_MODULE_NOT SUPPORTED ) |
#define fsf_get_total_quality (server,total_quality)\ |
( FSF_WRN_MODULE_NOT SUPPORTED ) |
#endif //FSF_SPARE_CAPACITY_MODULE_SUPPORTED |
#ifndef FSF_DISTRIBUTED_SERVICES_MODULE_SUPPORTED |
#define FSF_DISTRIBUTED_SERVICES_MODULE_SUPPORTED 0 |
#else |
//system topology, it is the same in all the |
//nodes involved |
fsf_system_topology_t system = |
{ 1, // number of networks |
{ 1, //network id |
3, //number of nodes |
// in the network |
{ 1, 2, 3, 0, 0 } //node ids |
}, |
{ 0, 0, { 0, 0, 0, 0, 0 } }, |
{ 0, 0, { 0, 0, 0, 0, 0 } }, |
{ 0, 0, { 0, 0, 0, 0, 0 } } |
} |
//this value should be different in each node. |
//But may be modified on-line before starting |
//network/remote negotiations |
fsf_node_id_t local_node_id = 1; |
#endif //FSF_DISTRIBUTED_SERVICES_MODULE_SUPPORTED |
#endif // _FSF_H_ |
/shark/trunk/ports/first/fsf_include/fsf_service_task.h |
---|
0,0 → 1,91 |
/* |
* Project: S.Ha.R.K. |
* |
* Coordinators: |
* Giorgio Buttazzo <giorgio@sssup.it> |
* Paolo Gai <pj@gandalf.sssup.it> |
* |
* Authors : |
* Giacomo Guidi <giacomo@gandalf.sssup.it> |
* Michael Trimarchi <trimarchi@gandalf.sssup.it> |
* (see the web pages for full authors list) |
* |
* ReTiS Lab (Scuola Superiore S.Anna - Pisa - Italy) |
* |
* http://www.sssup.it |
* http://retis.sssup.it |
* http://shark.sssup.it |
*/ |
/* |
* Copyright (C) 2002 Paolo Gai |
* |
* This program is free software; you can redistribute it and/or modify |
* it under the terms of the GNU General Public License as published by |
* the Free Software Foundation; either version 2 of the License, or |
* (at your option) any later version. |
* |
* This program is distributed in the hope that it will be useful, |
* but WITHOUT ANY WARRANTY; without even the implied warranty of |
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
* GNU General Public License for more details. |
* |
* You should have received a copy of the GNU General Public License |
* along with this program; if not, write to the Free Software |
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA |
* |
*/ |
#ifndef __FSF_SERVICE_TASK_H__ |
#define __FSF_SERVICE_TASK_H__ |
typedef struct { |
fsf_server_id_t server; |
TIME actual_period; |
TIME actual_budget; |
int Qs; // quality of service |
int Is; // importance of service |
bandwidth_t U; // actual bandwidth |
bandwidth_t Umin; // min bandwidth |
bandwidth_t Umax; // max bandwidth |
TIME Cmin; |
TIME Tmin; |
TIME Tmax; |
TIME deadline; |
bool d_equals_t; |
} server_elem; |
extern server_elem server_list[FSF_MAX_N_SERVERS]; |
extern int current_server; |
extern bandwidth_t fsf_max_bw; |
TASK service_task(void); |
int negotiate_contract |
(const fsf_contract_parameters_t *contract, |
fsf_server_id_t *server); |
int renegotiate_contract |
(const fsf_contract_parameters_t *contract, |
fsf_server_id_t server); |
int adjust_SERVER_budget |
(int budget, const TIME budget_actual, |
const TIME period_actual, const TIME dline_actual); |
int set_SERVER_budget_from_contract |
(const fsf_contract_parameters_t *contract, |
int *budget); |
int relink_contract_to_server(const fsf_contract_parameters_t *contract, |
fsf_server_id_t server); |
int link_contract_to_server(const fsf_contract_parameters_t *contract, |
fsf_server_id_t server); |
int add_contract(const fsf_contract_parameters_t *contract); |
#endif |
/shark/trunk/ports/first/fsf_include/fsf_basic_types.h |
---|
0,0 → 1,190 |
//fsf_basic_types.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 FSF(FIRST Scheduling Framework) common types |
//======================================================================= |
// |
#include <time.h> |
#include "fsf_opaque_types.h" |
#include "fsf_configuration_parameters.h" |
#ifndef _FSF_BASIC_TYPES_H_ |
#define _FSF_BASIC_TYPES_H_ |
// Definition of types and constants used in fsf modules |
/** |
\file fsf_basic_types.hh Contains the basic types |
This file contains the definition of the basec types used in |
the FSF. |
*/ |
// |
// Types for the core module |
// |
/// Kind of workload expected in servers |
typedef enum {FSF_BOUNDED, FSF_INDETERMINATE, FSF_OVERHEAD} fsf_workload_t; |
/// Constants for assigning default values |
/// @{ |
#define FSF_DEFAULT_WORKLOAD FSF_INDETERMINATE |
#define FSF_DEFAULT_D_EQUALS_T false |
#define FSF_DEFAULT_DEADLINE {0,0} //struct timespec |
/// @} |
/// Constants for omitting the assignment of values |
/// to specific arguments in calls to |
/// initialization functions |
/// @{ |
#define FSF_NULL_DEADLINE (struct timespec *)NULL |
#define FSF_NULL_SIGNAL 0 |
/// @} |
// |
// Types for the spare capacity module |
// |
/// Granularity of spare capacity requirements |
typedef enum {FSF_CONTINUOUS, FSF_DISCRETE} fsf_granularity_t; |
/// Utilization (budget and period) value |
typedef struct { |
struct timespec budget; // Execution time |
struct timespec period; // Period |
} fsf_utilization_value_t; |
/// List of utilization values |
typedef struct { |
int size; // = 0 |
fsf_utilization_value_t |
value[FSF_MAX_N_UTILIZATION_VALUES]; |
} fsf_utilization_set_t; |
/// Constants for assigning default values |
/// @{ |
#define FSF_DEFAULT_GRANULARITY FSF_CONTINUOUS |
#define FSF_DEFAULT_QUALITY 0 |
#define FSF_DEFAULT_IMPORTANCE 1 |
/// @} |
/// Constants for omitting the assignment of values to specific |
/// arguments in calls to initialization functions |
#define FSF_NULL_UTILIZATION_SET \ |
(fsf_utilization_set_t *)NULL |
// |
// Types for the implementation specific module |
// |
/// Implementation specific preemption level values |
typedef unsigned long fsf_preemption_level_t; |
// range 1..2**32-1 |
// |
// Types for the shared objects module |
// |
/// Shared object identifier (null character terminated string) |
typedef char * fsf_shared_obj_id_t; |
/// Shared object handle (opaque type) |
typedef FSF_SHARED_OBJ_HANDLE_T_OPAQUE fsf_shared_obj_handle_t; |
/// Critical section data |
typedef struct { |
fsf_shared_obj_handle_t obj_handle; |
struct timespec wcet; //Execution time |
} fsf_critical_section_data_t; |
/// List of critical sections |
typedef struct { |
int size; // = 0 |
fsf_critical_section_data_t |
section[FSF_MAX_N_CRITICAL_SECTIONS]; |
} fsf_critical_sections_t; |
// |
// Types for the hierarchical module |
// |
/// Scheduling policies |
typedef enum {FSF_FP, FSF_POSIX, FSF_RM, FSF_EDF, FSF_TABLE_DRIVEN, FSF_NONE} |
fsf_sched_policy_t; |
/// Scheduling policy and parameters |
/// The params member is a pointer to one of the |
/// following: |
/// FP: int (priority) |
/// EDF: struct timespec (deadline) |
/// TABLE_DRIVEN : struct fsf_table_driven_params_t |
typedef struct { |
fsf_sched_policy_t policy; |
void * params; |
} fsf_sched_params_t; |
/// Scheduling parameters for the table-driven policy (t.b.d) |
typedef struct { |
// list of target windows (t.b.d.) |
// deadline (for the API): end of september |
} fsf_table_driven_params_t; |
/// Initialization information for a scheduling policy |
/// It shall be one of the following: |
/// FP: none |
/// EDF: none |
/// TABLE_DRIVEN : struct timespec (schedule duration) |
typedef void * fsf_sched_init_info_t; |
/// Error codes |
/// @{ |
#define FSF_ERR_TOO_MANY_TASKS 0x02003001 |
#define FSF_ERR_BAD_ARGUMENT 0x02003002 |
#define FSF_ERR_INVALID_SYNCH_OBJ_HANDLE 0x02003003 |
#define FSF_ERR_NO_RENEGOTIATION_REQUESTED 0x02003004 |
#define FSF_ERR_CONTRACT_REJECTED 0x02003005 |
#define FSF_ERR_NOT_SCHEDULED_CALLING_THREAD 0x02003006 // ?? |
#define FSF_ERR_UNBOUND 0x02003007 |
#define FSF_ERR_UNKNOWN_APPSCHEDULED_THREAD 0x02003008 |
#define FSF_ERR_NOT_CONTRACTED_SERVER 0x02003009 |
#define FSF_ERR_NOT_SCHEDULED_THREAD 0x02003010 |
#define FSF_ERR_TOO_MANY_SERVICE_JOBS 0x02003011 |
#define FSF_ERR_TOO_MANY_SYNCH_OBJS 0x02003012 |
#define FSF_ERR_TOO_MANY_SERVERS_IN_SYNCH_OBJ 0x02003013 |
#define FSF_ERR_TOO_MANY_EVENTS_IN_SYNCH_OBJ 0x02003014 |
#define FSF_ERR_INTERNAL_ERROR 0x02003015 |
#define FSF_ERR_TOO_MANY_SERVERS 0x02003016 |
#define FSF_ERR_INVALID_SCHEDULER_REPLY 0x02003017 |
#define FSF_ERR_TOO_MANY_PENDING_REPLENISHMENTS 0x02003018 |
#define FSF_WRN_MODULE_NOT_SUPPORTED 0x02004001 |
// added by Julio |
#define FSF_ERR_SYSTEM_ALREADY_INITIALIZED 0x02004002 |
#define FSF_ERR_SHARED_OBJ_ALREADY_INITIALIZED 0x02004003 |
#define FSF_ERR_SHARED_OBJ_NOT_INITIALIZED 0x02004004 |
#define FSF_ERR_SCHED_POLICY_NOT_COMPATIBLE 0x02004005 |
// added by Peppe |
#define FSF_WRN_UNSUPPORTED_FEATURE 0x02004006 |
///@} |
#endif // _FSF_BASIC_TYPES_H_ |
/shark/trunk/ports/first/fsf_include/fsf_spare_capacity.h |
---|
0,0 → 1,227 |
//fsf_spare_capacity.h |
//=================================================== |
// FFFFFFIII RRRRR SSTTTTTTT |
// FF IIR RR SS |
// FF IR SS |
// FFFFFF RRRR SSSSST |
// FF FI RRR SS |
// FF II RRR SS |
// FF IIIIIR RS |
// |
// FSF(FIRST Scheduling Framework) |
// spare capacity sharing functionality |
//=================================================== |
#include <time.h> |
#include <stdint.h> |
#include "fsf_basic_types.h" |
#include "fsf_core.h" |
#ifndef _FSF_SPARE_CAPACITY_H_ |
#define _FSF_SPARE_CAPACITY_H_ |
#define FSF_SPARE_CAPACITY_MODULE_SUPPORTED 1 |
#define FSF_MAX_QUALITY 100 |
#define FSF_MIN_QUALITY 0 |
#define FSF_MAX_IMPORTANCE 5 |
#define FSF_MIN_IMPORTANCE 1 |
//// The definition of this types is in fsf_basic_types.h |
// |
//// Granularity of spare capacity requirements |
//typedef enum {FSF_CONTINUOUS, FSF_DISCRETE} fsf_granularity_t; |
// |
//// Utilization (budget and period) value |
//typedef struct { |
// struct timespec budget; // Execution time |
// struct timespec period; // Period |
//} fsf_utilization_value_t; |
// |
////List of utilization values |
//typedef struct { |
// int size; // = 0 |
// fsf_utilization_value_t |
// value[FSF_MAX_N_UTILIZATION_VALUES]; |
// //unit change to value..... |
//} fsf_utilization_set_t; |
// |
// |
//// Constants for assigning default values |
//#define FSF_DEFAULT_GRANULARITY FSF_CONTINUOUS |
//#define FSF_DEFAULT_QUALITY 0 |
//#define FSF_DEFAULT_IMPORTANCE 1 |
// |
// |
//// Constants for omitting the assignment of values to specific |
//// arguments in calls to initialization functions |
// |
//#define FSF_NULL_UTILIZATION_SET (fsf_utilization_set_t *)NULL |
// |
/** |
\ingroup sparemodule |
The operation updates the specified contract parameters object by |
setting its maximum usable budget, minimum period, granularity, |
utilization set, quality, and importance to the specified input |
parameters. |
@param [in] contract pointer ot the contract |
@param [in] budget_max maximum budget this contract can obtain |
@param [in] period_min minimum period this contract can obtain |
@param [in] granularity can be either FSF_CONTINUOUS or FSF_DISCRETE |
@param [in] utilization_set in case the granularity is set to |
FSF_DISCRETE it contains a list possible pairs (budget,period) |
@param [in] quality a number between FSF_MIN_QUALITY and FSF_MAX_QUALITY, |
to control how the spare capacity is shared between |
contracts with the same importance. The higher |
is this number, the more likely we get a large increase |
in the capacity |
@param [in] importance a numer between FSF_MIN_IMPORTANCE and |
FSF_MAX_IMPORTANCE, used to control how the spare capacity |
is shared. The higher the number, the more likely we get |
some spare capacity. |
@retval 0 if the call is succesful |
@retval FSF_ERR_BAD_ARGUMENT if contract is NULL or one of the |
following conditions is true: |
- (budget_max value is grater than period_max or smaller than |
budget_min); |
- (period_min is smaller than budget_mint or larger than period_max); |
- (granularity is neither FSF_CONTINUOUS nor FSF_DISCRETE); |
- (granularity is FSF_CONTINUOUS and |
utilization_set is not FSF_NULL_UTILIZATION_SET) |
- (granularity is FSF_DISCRETE and utilization_set is |
FSF_NULL_UTILIZATION_SET) |
- (utilization_set is not FSF_NULL_UTILIZATION_SET and |
(size of utilization_set less than 2 or greater |
than FSF_MAX_N_UTILIZATION_VALUES) |
- (quality < 0) |
- (importance is less than 1 or greater than FSF_N_IMPORTANCE_LEVELS) |
- (the utilization_set elements are not in increasing utilization order) |
- (the first utilization value in the utilization_set does not match |
the pair (budget_min, period_max) of the contract); |
- (the last utilization value in the utilization_set does not match |
the pair (budget_max, period_min) of the contract). |
*/ |
int |
fsf_set_contract_reclamation_parameters |
(fsf_contract_parameters_t *contract, |
const struct timespec *budget_max, |
const struct timespec *period_min, |
fsf_granularity_t granularity, |
const fsf_utilization_set_t *utilization_set, |
int quality, |
int importance); |
/** |
\ingroup sparemodule |
The operation obtains from the specified contract parameters |
object its granularity, utilization set, quality, and |
importance. Then copies them to the variables pointed to by the |
specified input parameters. Only the utilization_values of the |
utilization_set that are in use, are copied (according to its size |
field). |
@retval 0 if the operation is succesful |
@retval FSF_ERR_BAD_ARGUMENT : if contract is NULL |
@see fsf_set_contract_reclamation_parameters |
*/ |
int |
fsf_get_contract_reclamation_parameters |
(const fsf_contract_parameters_t *contract, |
struct timespec *budget_max, |
struct timespec *period_min, |
fsf_granularity_t *granularity, |
fsf_utilization_set_t *utilization_set, |
int *quality, |
int *importance); |
/** |
\ingroup sparemodule |
The operation enqueues a request to change the quality and |
importance parameters of the specified server, and returns |
immediately. The change operation is performed as soon as it is |
practical; meanwhile the system operation will continue normally. |
@param server server id |
@param new_importance the new importance |
@param new_quality the new requested quality |
@retval FSF_ERR_BAD_ARGUMENT if |
- the value of the server argument is not in range or |
- (quality < 0) |
- (importance is less than 1 or greater than FSF_N_IMPORTANCE_LEVELS). |
@retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD if the calling thread is not |
scheduled under the FSF |
@retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or |
not running |
@retval FSF_ERR_NOT_CONTRACTED_SERVER if the server has been cancelled |
or it is not valid |
*/ |
int |
fsf_request_change_quality_and_importance |
(fsf_server_id_t server, |
int new_importance, |
int new_quality); |
/** |
\ingroup sparemodule |
This operation calculates the sum of the quality parameters for all |
servers in the system of importance level equal to that of the |
specified server, and stores it in the variable pointed to by |
total_quality. |
@param [in] server server id |
@param [out] total_quality the total quality in the system |
@retval FSF_ERR_BAD_ARGUMENT if the value of the server argument |
is not in range or total_quality is NULL |
@retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD if the calling thread is not |
scheduled under the FSF |
@retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or |
not running |
@retval FSF_ERR_NOT_CONTRACTED_SERVER if the server has been |
cancelled or it is not valid |
*/ |
int |
fsf_get_total_quality |
(fsf_server_id_t server, int *total_quality); |
/** |
\ingroup sparemodule |
This operation stores in the variable pointed to by capacity the |
spare capacity currently available for the importance level of the |
specified server. The capacity is the utilization (of the |
processor or of the network) and it is represented by an integer |
number between 0 (no utilization) and UINT32_MAX (all |
utilization). |
@retval FSF_ERR_BAD_ARGUMENT if the value of the server argument is |
not in range or capacity is NULL |
@retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD if the calling thread is not |
scheduled under the FSF |
@retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or |
not running |
@retval FSF_ERR_NOT_CONTRACTED_SERVER if the server has been cancelled |
or it is not valid |
*/ |
int |
fsf_get_available_capacity ( |
fsf_server_id_t server, uint32_t *capacity); |
/* @} */ |
#endif // _FSF_SPARE_CAPACITY_H_ |
/shark/trunk/ports/first/fsf_include/fsf_core.h |
---|
0,0 → 1,1221 |
//fsf_core.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 FSF(FIRST Scheduling Framework) contract management |
//================================================================ |
#include <time.h> |
#include <pthread.h> |
#include <sys/types.h> |
#include <stdbool.h> |
#include "fsf_configuration_parameters.h" |
#include "fsf_opaque_types.h" |
#include "fsf_basic_types.h" |
#ifndef _FSF_CORE_H_ |
#define _FSF_CORE_H_ |
////////////////////////////////////////////////////////////////////// |
// INITIALIZATION SERVICES |
////////////////////////////////////////////////////////////////////// |
/** |
\ingroup coremodule |
\defgroup core_init Initialization and utilities |
@{ |
*/ |
/** |
We cannot call any fsf functions before fsf_init. After calling |
fsf_init, the main will be executing in the background. Then, it |
can do the negotiations, create the threads and, if needed, |
activate them via some user-specified synchronization mechanism. It |
may also create a contract for itself. The second time this |
function is called it fails. |
@retval 0 if the system is initialized |
@retval FSF_ERR_SYSTEM_ALREADY_INITIALIZED if the function has already |
been called before |
@retval others It may also return any of the errors that may be |
returned by the underlying operating system primitives |
required to perform the FSF system start up |
*/ |
int fsf_init(); |
/** |
This function converts an error code to an error message that is |
stored in the buffer starting at the location pointed to by |
message. The size of this buffer is specified by the size |
argument. If the error message is longer than size-1, it is |
truncated to that length. Regardless of whether the message is |
truncated or not, a final zero character that marks the end of the |
string is stored in the buffer. The function fails if the error |
code passed does not correspond to any of the fsf error codes. |
@retval FSF_ERR_BAD_ARGUMENT error is not a valid value |
*/ |
int fsf_strerror (int error, char *message, size_t size); |
/* @} */ |
///////////////////////////////////////////////////////////// |
// CONTRACT PARAMETERS |
///////////////////////////////////////////////////////////// |
/** |
\ingroup coremodule |
\defgroup core_contract Contract Creation and Initialization. |
These functions are used to create and initialize a contract, and |
set its parameters. |
*/ |
/*@{*/ |
/** |
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 FSF_CONTRACT_PARAMETERS_T_OPAQUE fsf_contract_parameters_t; |
/** |
The operation receives a pointer to a contract parameters object |
and initializes it, setting it to the default values. |
The default values are: |
- budget min and max are set to 0; |
- period min and max are set to 0; |
- the workload is unbounded (FSF_INDETERMINATE); |
- the server deadline is equal to the period; |
- the budget and deadline overrun are not notified; |
- the granularity is set to "continuous"; |
- the quality and importance are set to the default values; |
- the scheduling policy is FSF_NONE. |
@param contract the pointer to the contract variable. |
@retval FSF_ERR_BAD_ARGUMENT contract is NULL |
*/ |
int fsf_initialize_contract (fsf_contract_parameters_t *contract); |
// budget_min => {0,0}; |
// period_max => {0,0}; |
// budget_max => {0,0}; |
// period_min => {0,0}; |
// workload => DEFAULT_WORKLOAD; |
// d_equals_t => DEFAULT_D_EQUALS_T; (false or true) |
// deadline => DEFAULT_DEADLINE; |
// budget_overrun_sig_notify => 0; (signal number) |
// budget_overrun_sig_value => {0, NULL}; |
// deadline_miss_sig_notify => 0; (signal number) |
// deadline_miss_sig_value => {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 |
// (FSF_NONE) |
/** |
The operation updates the specified contract parameters object by |
setting its budget, period, and workload to the specified input |
parameters. (Note: the workload is a basic parameter because |
bounded tasks are triggered by the scheduler (see the |
fsf_schedule_timed_job() operation), 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 FSF_BOUNDED or |
FSF_INDETERMINATE) |
@retval 0 if the operation is succesful |
@retval FSF_ERR_BAD_ARGUMENT if any of the pointers is NULL |
or if only one of the timespec values is 0, and also if the workload |
is not a proper value (FSF_INDETERMINATE or FSF_BOUNDED) |
*/ |
int |
fsf_set_contract_basic_parameters |
(fsf_contract_parameters_t *contract, |
const struct timespec *budget_min, |
const struct timespec *period_max, |
fsf_workload_t workload); |
/** |
This operation obtains from the specified contract parameters |
object its budget, period, and workload, and copies them to the |
places pointed to by the corresponding input parameters. |
@param [in] contract the pointer to the contract object |
@param[out] budget_min pointer to the variable that will contain |
the minimum budget |
@param[out] period_max pointer to the variable that will contain the |
max_period |
@param[out] workload pointer to the variable that will contain the |
workload type |
@retval FSF_ERR_BAD_ARGUMENT : if contract is NULL |
*/ |
int |
fsf_get_contract_basic_parameters |
(const fsf_contract_parameters_t *contract, |
struct timespec *budget_min, |
struct timespec *period_max, |
fsf_workload_t *workload); |
/** |
The operation updates the specified contract parameters |
object, specifying the additional parameters requirements of |
a contract. |
@param contract The pointer to the contract object |
@param [in] d_equals_t It is a boolean value, set to true (1) if the |
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 should be set to NULL_DEADLINE. Otherwise, |
it contains the desired deadline value. |
(PEPPE: should be return with error otherwise?) |
@param [in] budget_overrun_sig_notify contains the number of posix signal |
that must be raised if the budget of the server is overrun. |
If the value of this parameter is NULL_SIGNAL, no signal will |
be raised. |
@param [in] budget_overrun_sig_value 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_sig_notify |
parameters is set to NULL_SIGNAL. |
@param [in] deadline_miss_sig_notify contains the number of posix |
signal that must be raised if the deadline of the server |
is missed. If the value of this parameter is NULL_SIGNAL, |
no signal is raised. |
@param [in] deadline_miss_sig_value 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_sig_notify |
parameters is set to NULL_SIGNAL |
@retval 0 if the operation is succesful |
@retval FSF_BAD_ARGUMENT if contract is NULL or |
(d_equals_t is true and deadline is not FSF_NULL_DEADLINE) or |
(budget_overrun_sig_notify is not a valid signal) or |
(deadline_miss_sig_notify is not a valid signal) or |
(d_equals_t is false but (deadline is FSF_NULL_DEADLINE or its value |
is grater than the contract´s maximum period)) |
@see sigexplanation |
*/ |
int |
fsf_set_contract_timing_requirements |
(fsf_contract_parameters_t *contract, |
bool d_equals_t, |
const struct timespec *deadline, |
int budget_overrun_sig_notify, |
union sigval budget_overrun_sig_value, |
int deadline_miss_sig_notify, |
union sigval deadline_miss_sig_value); |
/** |
The operation obtains the corresponding input parameters from the |
specified contract parameters object. If d_equals_t is true, the |
deadline will not be updated. |
@retval FSF_ERR_BAD_ARGUMENT if contract is NULL |
@see fsf_set_contract_timing_requirements |
*/ |
int |
fsf_get_contract_timing_requirements |
(const fsf_contract_parameters_t *contract, |
bool *d_equals_t, |
struct timespec *deadline, |
int *budget_overrun_sig_notify, |
union sigval *budget_overrun_sig_value, |
int *deadline_miss_sig_notify, |
union sigval *deadline_miss_sig_value); |
/*@}*/ |
////////////////////////////////////////////////////////////////// |
// SYNCHRONIZATION OBJECTS |
////////////////////////////////////////////////////////////////// |
/** |
\ingroup coremodule |
\defgroup core_synch Synchronization objects |
These objects are used to synchronize threads belonging to bounded |
workload servers. |
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. |
*/ |
/*@{*/ |
/** |
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 fsf_schedule_triggered_job() operation. It |
can also be used to signal the event either causing a waiting |
server to wake up, or the event to be queued if no server is |
waiting for it. |
*/ |
typedef FSF_SYNCH_OBJ_HANDLE_T_OPAQUE fsf_synch_obj_handle_t; |
/** |
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] pointer to the variable that will contain the handle to the |
newly created synchronization object |
@retval 0 if the operation is succesful |
@retval FSF_ERR_BAD_ARGUMENT if synch_handle is 0 |
@retval FSF_ERR_TOO_MANY_SYNCH_OBJS if the number of synchronization |
objects in the system has already exceeded the maximum |
@retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD if the calling thread is not |
scheduled under the FSF |
@retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong |
or not running |
*/ |
int |
fsf_create_synch_obj |
(fsf_synch_obj_handle_t *synch_handle); |
/** |
This function sends a notification to the synchronization object |
specified as parameter. If there is at least one server waiting on |
the synchronization object, the corresponding thread is unblocked, |
and the server rules for budget recharging apply. |
If more than one server is waiting, just one of them is woken. |
However, which one is woken is implementation dependent. |
If no thread is waiting on the synchronization object, the |
notification is queued. |
@param [in] synch_handle the handle of the synchronization object to |
notify. |
@retval 0 if the operation is completed succesfully |
@retval FSF_ERR_BAD_ARGUMENT if synch_handle is 0 |
@retval FSF_ERR_INVALID_SYNCH_OBJ_HANDLE if the handle is not valid |
@retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD if the calling thread |
is not scheduled under the FSF |
@retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or |
not running |
@retval FSF_ERR_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 |
@see fsf_schedule_triggered_job, fsf_timed_schedule_triggered_job |
*/ |
int |
fsf_signal_synch_obj |
(fsf_synch_obj_handle_t synch_handle); |
/** |
This operation destroys the synchronization object (created by a |
previous call to fsf_create_synch_obj) 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 fsf_create_synch_obj. |
@param synch_handle the handle to the synchronization object |
to be destroyed |
@retval 0 if the operation is succesful |
@retval FSF_ERR_INVALID_SYNCH_OBJ_HANDLE is the handle is not valid |
@retval FSF_ERR_BAD_ARGUMENT if synch_handle is 0 |
@retval FSF_ERR_INVALID_SYNCH_OBJ_HANDLE if the handle is not valid |
@retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD if the calling thread is not |
scheduled under the FSF |
@retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or |
not running |
@see fsf_create_synch_obj |
*/ |
int |
fsf_destroy_synch_obj |
(fsf_synch_obj_handle_t synch_handle); |
//////////////////////////////////////////////////// |
// SCHEDULING BOUNDED WORKLOADS |
//////////////////////////////////////////////////// |
/** |
This operation is invoked by threads associated with bounded |
workload servers to indicate that a job has been completed (and |
that the scheduler may reassign the unused capacity of the current |
job to other servers). It is also invoked when the first job of |
such threads has to be scheduled. (PEPPE: I have a question, what |
happens to the budget? if I do not get it wrong, the replenishment |
time is set to abs_time and the bandwidth of the server up to time |
abs_time can be reassigned. Is it true? what is the exact |
relationship between this abs_time and the server period? What if |
the user specifies an abs_time less than the end of the current |
server period??) |
As an effect, the system will make the current server's budget zero |
for the remainder of the server'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 |
server 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 server 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 server 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 server 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 server 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 server budget was |
overrun, to false otherwise. If this |
parameter is set to NULL, no action is |
taken. |
@retval 0 if the operation is succesful |
@retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or |
not running |
@retval FSF_ERR_INTERNAL_ERROR erroneous binding or malfunction of the FSF |
main scheduler |
@retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD if the calling thread is |
not scheduled under the FSF |
@retval FSF_ERR_UNBOUND if the calling thread does not have a valid |
server bound to it |
@retval FSF_ERR_BAD_ARGUMENT if the workload of the server is not |
FSF_BOUNDED |
@sa fsf_schedule_triggered_job, fsf_timed_schedule_triggered_job |
*/ |
int |
fsf_schedule_timed_job |
(const struct timespec *abs_time, |
struct timespec *next_budget, |
struct timespec *next_period, |
bool *was_deadline_missed, |
bool *was_budget_overran); |
/** |
This operation is invoked by threads associated with bounded |
workload servers to indicate that a job has been completed (and |
that the scheduler may reassign the unused capacity of the current |
job to other servers). It is also invoked when the first job of |
such threads has to be scheduled. If the specified synchronization |
object has events queued, one of them is dequeued; otherwise the |
server will wait upon the specified synchronization object, the |
server's budget will be made zero for the remainder of the server's |
period, and the implementation will not replenish the budget until |
the specified synchronization object is signalled. |
At that time, all pending budget replenishments (if any) are made |
effective. Once the server 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 server are not run. As |
mentioned above, only when the call finishes the budget may be |
replenished. |
@param [in] synch_handle handle of the synchronization object |
@param [out] next_budget upon return of this function, the variable |
pointed by this function will be equal |
to the current server 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 server 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 server 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 server budget was |
overrun, to false otherwise. If this |
parameter is set to NULL, no action is |
taken. |
@retval 0 if the operation is succesful |
@retval FSF_ERR_INVALID_SYNCH_OBJ_HANDLE if the handle is not valid |
@retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or not |
running |
@retval FSF_ERR_INTERNAL_ERROR erroneous binding or malfunction of |
the FSF main scheduler |
@retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD if the calling thread |
is not scheduled under the FSF |
@retval FSF_ERR_UNBOUND if the calling thread does not have |
a valid server bound to it |
@retval FSF_ERR_BAD_ARGUMENT if the workload of the server is not |
FSF_BOUNDED or the synch_handle given is not valid |
@sa fsf_schedule_triggered_job, fsf_schedule_timed_job |
*/ |
int |
fsf_schedule_triggered_job |
(fsf_synch_obj_handle_t synch_handle, |
struct timespec *next_budget, |
struct timespec *next_period, |
bool *was_deadline_missed, |
bool *was_budget_overran); |
/** |
This call is the same as fsf_schedule_triggered_job, but with an |
absolute timeout. The timed_out argument, indicates whether the |
function returned because of a timeout or not |
@retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or |
not running |
@retval FSF_ERR_INTERNAL_ERROR erroneous binding or malfunction |
of the FSF main scheduler |
@retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD if the calling thread is |
not scheduled under the FSF |
@retval FSF_ERR_UNBOUND if the calling thread does not have a valid |
server bound to it |
@retval FSF_ERR_BAD_ARGUMENT if the workload of the server is not |
FSF_BOUNDED, the synch_handle given is not valid or the abs_timeout |
argument is NULL or its value is in the past |
@see fsf_schedule_triggered_job |
*/ |
int |
fsf_timed_schedule_triggered_job |
(fsf_synch_obj_handle_t synch_handle, |
const struct timespec *abs_timeout, |
bool *timed_out, |
struct timespec *next_budget, |
struct timespec *next_period, |
bool *was_deadline_missed, |
bool *was_budget_overran); |
/*@}*/ |
/////////////////////////////////////////////////////////////////// |
// CONTRACT NEGOCIATION OPERATIONS |
/////////////////////////////////////////////////////////////////// |
/** |
\ingroup coremodule |
\defgroup core_negotiate Negotiate contract functions |
The following functions are used to create servers for a contract |
parameters specification and also to assign one or more threads to |
a server (Note: the current implementation only supports one thread |
per server; this limitation will be removed in the next phase of |
the project) |
*/ |
/*@{*/ |
/** |
Server Id type, that identifies a server created to manage a given |
contract |
*/ |
typedef int fsf_server_id_t; // => 0 |
/** |
The type references a function that may become a thread's |
code |
*/ |
typedef void * (*fsf_thread_code_t) (void *); |
/** |
The operation negotiates a contract for a new server. 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 server 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. It returns zero and places the server identification |
number in the location pointed to by the server input parameter if |
accepted, or an error if rejected. No thread is bound to the newly |
created server, which will be idle until a thread is bound to |
it. This operation can only be executed by threads that are already |
bound to an active server and therefore are being scheduled by the |
fsf scheduler. |
@param [in] contract pointer to the contract |
@param [out] server server id |
@retval 0 if the call is succesful |
@retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or not |
running |
@retval FSF_ERR_INTERNAL_ERROR erroneous binding or malfunction of the FSF |
main scheduler |
@retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD |
if the calling thread is not scheduled |
under the FSF |
@retval FSF_ERR_BAD_ARGUMENT if the contract or server arguments |
are NULL |
*/ |
int |
fsf_negotiate_contract |
(const fsf_contract_parameters_t *contract, |
fsf_server_id_t *server); |
/** |
This operation negotiates a contract for a new server, creates a |
thread and binds it to the server. If the contract is accepted, the |
operation creates a thread with the arguments thread, attr, |
thread_code and arg as they are defined for the pthread_create() |
POSIX function call, and attaches it to the fsf scheduler. Then, it |
binds the created thread to the new server. It returns zero and |
puts the server identification number in the location pointed to by |
the server input parameter. |
The attr parameter is overwritten as necessary to introduce the |
adequate scheduling attributes, according to the information given |
in the contract. |
The server is created with the FSF_NONE scheduling policy, which |
means no hierarchical scheduling, and only one thread per server, |
except for the case of background tasks (see below) |
If the contract is rejected, the thread is not created and the |
corresponding error is returned. |
@param [in] contract pointer to the contract |
@param [out] server server id |
@param [out] thread thread id |
@param [in] attr threads attributes |
@param [in] thread_code pointer to the function that implements |
the thread |
@param [in] arg arguments for the thread |
@retval FSF_ERR_BAD_ARGUMENT if the contract or server arguments are NULL |
@retval FSF_ERR_CONTRACT_REJECTED if the contract is rejected |
@retval others it may also return all the errors that may be returned |
by the pthread_create()POSIX function call |
*/ |
int |
fsf_negotiate_contract_for_new_thread |
(const fsf_contract_parameters_t *contract, |
fsf_server_id_t *server, |
pthread_t *thread, |
pthread_attr_t *attr, |
fsf_thread_code_t thread_code, |
void *arg); |
/** |
This operation negotiates a contract for a new server, and binds |
the calling thread to it. If the contract is accepted it returns |
zero and copies the server identification number in the location |
pointed to by the server input parameter. If it is rejected, an |
error is returned. |
The server is created with the FSF_NONE scheduling policy, which |
means no hierarchical scheduling, and only one thread per server, |
except for the case of background tasks (see below) |
Implementation dependent issue: In order to allow the usage of |
application defined schedulers, the calling thread must not have |
the SCHED_APP scheduling policy and at the same time be attached to |
an application scheduler different than the fsf scheduler; in such |
case, an error is returned. After a successful call the calling |
thread will have the SCHED_APP scheduling policy and will be |
attached to the fsf scheduler. |
@param [in] contract pointer to the contract |
@param [out] server id |
@retval 0 if the contract negotation is succesful |
@retval FSF_ERR_UNKNOWN_APPSCHEDULED_THREAD if the thread is attached to |
an application defined scheduler different than the fsf scheduler |
@retval FSF_ERR_BAD_ARGUMENT if the contract or server arguments |
are NULL |
@retval FSF_ERR_CONTRACT_REJECTED if the contract is rejected. |
*/ |
int |
fsf_negotiate_contract_for_myself |
(const fsf_contract_parameters_t *contract, |
fsf_server_id_t *server); |
/** |
This operation associates a thread with a server, which means that |
it starts consuming the server's budget and is executed according |
to the contract established for that server. If the thread is |
already bound to another server, and error is returned. |
It fails if the server's policy is different than FSF_NONE, or if |
there is already a thread bound to this server |
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 fsf scheduler. |
@param [in] server id |
@param [in] thread id |
@retval FSF_ERR_INTERNAL_ERROR erroneous binding or malfunction |
of the FSF main scheduler |
@retval FSF_ERR_UNKNOWN_APPSCHEDULED_THREAD if the thread is attached to |
an application defined scheduler different than the fsf scheduler |
@retval FSF_ERR_BAD_ARGUMENT if the server value does not complain with the |
expected format or valid range or the given thread does not exist |
@retval FSF_ERR_NOT_CONTRACTED_SERVER if the referenced server |
is not valid |
@retval FSF_ERR_ALREADY_BOUND if the thread is already bound to |
another server. |
*/ |
int |
fsf_bind_thread_to_server |
(fsf_server_id_t server, |
pthread_t thread); |
/** |
This operation unbinds a thread from a server. Since threads with |
no server associated are not allow 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 fsf |
scheduler, but suspended. |
@param [in] thread thread id |
@retval 0 if the operation is succesful |
@retval FSF_ERR_INTERNAL_ERROR erroneous binding or malfunction of the FSF |
main scheduler |
@retval FSF_ERR_BAD_ARGUMENT if the given thread does not exist |
@retval FSF_ERR_NOT_SCHEDULED_THREAD if the given thread is not scheduled |
under the FSF |
@retval FSF_ERR_UNKNOWN_APPSCHEDULED_THREAD if the thread is attached to |
an application defined scheduler different than the fsf scheduler |
@retval FSF_ERR_NOT_BOUND if the given thread does not have a valid |
server bound to it |
*/ |
int |
fsf_unbind_thread_from_server (pthread_t thread); |
/** |
This operation stores the Id of the server associated with the |
specified thread in the variable pointed to by server. It returns |
an error if the thread does not exist, it is not under the control |
of the scheduling framework, or is not bound. |
@param [in] thread thread id |
@param [out] server server |
@retval 0 if the operation is succesful |
@retrun FSF_ERR_NOT_SCHEDULED_THREAD if the given thread is not scheduled |
under the FSF |
@retrun FSF_ERR_UNBOUND if the given thread does not have a valid |
server bound to it |
@retrun FSF_ERR_BAD_ARGUMENT if the given thread does not exist or the |
server argument is NULL |
*/ |
int |
fsf_get_server |
(pthread_t thread, |
fsf_server_id_t *server); |
/** |
This operation stores the contract parameters currently associated |
with the specified server in the variable pointed to by |
contract. It returns an error if the server id is incorrect. |
@param [in] server server id |
@param [out] contract pointer to the contract structure |
@retval 0 if the operation is succesful |
@retval FSF_ERR_BAD_ARGUMENT if the contract argument is |
NULL or the value of the server argument is not in range |
@retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD if the calling thread is not |
scheduled under the FSF |
@retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or |
not running |
@retval FSF_ERR_NOT_CONTRACTED_SERVER if the server of the calling thread |
has been cancelled or it is not valid |
*/ |
int |
fsf_get_contract |
(fsf_server_id_t server, |
fsf_contract_parameters_t *contract); |
/** |
The operation eliminates the specified server |
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. |
@param [in] server server id |
@retval 0 if the operation is succesful |
@retval FSF_ERR_BAD_ARGUMENT if the value of server is not in range |
@retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD if the calling thread is not |
scheduled under the FSF |
@retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or not |
running |
@retval FSF_ERR_NOT_CONTRACTED_SERVER if the server of the calling thread |
has been cancelled or it is not valid |
*/ |
int |
fsf_cancel_contract (fsf_server_id_t server); |
/** |
The operation renegotiates a contract for an existing server. 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 anr 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. |
@param [in] new_contract a pointer to the new contract |
@param [in] server server id |
@retval 0 if the operation is succesful |
@retval FSF_ERR_BAD_ARGUMENT if the new_contract argument is NULL or the |
value of the server argument is not in range |
@retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD if the calling thread is not |
scheduled under the FSF |
@retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or not |
running |
@retval FSF_ERR_NOT_CONTRACTED_SERVER if the server of the calling thread |
has been cancelled or it is not valid |
*/ |
int |
fsf_renegotiate_contract |
(const fsf_contract_parameters_t *new_contract, |
fsf_server_id_t server); |
/** |
The operation enqueues a renegotiate operation for an existing |
server, and returns immediately. The renegotiate operation is |
performed asynchronously and the calling thread may continue |
executing normally. Of course, wheter the operation is performed |
immediately or not depends on the relative priority of the service |
thread and the calling thread, on the scheduler used, etc. |
When the renegotiation is completed, 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 get_renegotiation_status |
operation. The argument sig_notify can be NULL_SIGNAL (no |
notification), or any POSIX signal; and in this case sig_value is |
to be sent with the signal. |
@param [in] new_contract pointer to the new contract to be negotiated |
@param [in] server server id |
@param [in] sig_notify NULL (no signal) or any POSIX signal |
@param [in] sign_value a sigval structure that contains values to be |
passed to the signal handler. Valid only if sig_notify |
is different from NULL. |
@retval 0 if the call is succesful |
@retval FSF_ERR_BAD_ARGUMENT if the new_contract argument is NULL, the |
value of the server argument is not in range or sig_notify is |
neither NULL nor a valid POSIX signal |
@retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD if the calling thread is not |
scheduled under the FSF |
@retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or not |
running |
@retval FSF_ERR_NOT_CONTRACTED_SERVER if the server of the calling thread |
has been cancelled or it is not valid |
*/ |
int |
fsf_request_contract_renegotiation |
(const fsf_contract_parameters_t *new_contract, |
fsf_server_id_t server, |
int sig_notify, |
union sigval sig_value); |
/** |
Possible values returned by fsf_get_renegotiation_status |
*/ |
typedef enum {FSF_IN_PROGRESS, |
FSF_REJECTED, |
FSF_ADMITTED} |
fsf_renegotiation_status_t; |
/** |
The operation reports on the status of the last renegotiation |
operation enqueued for the specified server. It is callable even |
after notification of the completion of such operation, if |
requested. |
@param [in] server server id |
@param [out] renegotiation_status the status of the renegotiation; |
@retval 0 if succesful completion; |
@retval FSF_ERR_BAD_ARGUMENT if the renegotiation_status argument is |
NULL or the value of the server argument is not in range |
@retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD if the calling thread is not |
scheduled under the FSF |
@retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or not |
running |
@retval FSF_ERR_NOT_CONTRACTED_SERVER if the server of the calling thread |
has been cancelled or it is not valid |
*/ |
int |
fsf_get_renegotiation_status |
(fsf_server_id_t server, |
fsf_renegotiation_status_t *renegotiation_status); |
//Data types |
/// List of contracts to negotiate |
typedef struct { |
int size; |
fsf_contract_parameters_t* contracts[FSF_MAX_N_SERVERS]; |
} fsf_contracts_group_t; |
/// List of servers to cancel |
typedef struct { |
int size; |
fsf_server_id_t servers[FSF_MAX_N_SERVERS]; |
} fsf_servers_group_t; |
/** |
This operation analizes the schedulability of the context that |
results from negitiating the contracts specified in the |
contracts_up list and cacelling the contracts referenced by the |
servers_down list. If the overall negotiation is successful, a new |
server will be created for each of the elements of the contracts_up |
group, the servers in servers_down will be cancelled, the list of |
new server ids will be returned in the variable pointed to by |
servers_up, and the variable pointed to by accepted will be made |
true. Otherwise, this variable will be made false, and no other |
effect will take place. The function returns the corresponding |
error code if any of the contracts is not correct or any of the |
server is is not valid. |
@param [in] contracts_up list of contracts to negotiate |
@param [in] contracts_down list of contracts to be canceled |
@param [out] servers_up list of server ids that have been created, they are |
given in the same order as the contract_up list of contracts; |
@param [out] accepted if the operation is succesful; |
@retval 0 if succesful completion; |
@retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or |
not running |
@retval FSF_ERR_INTERNAL_ERROR erroneous binding or malfunction of the FSF |
main scheduler |
@retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD if the calling thread is |
not scheduled under the FSF |
@retval FSF_ERR_BAD_ARGUMENT if any of the servers_up or accepted arguments |
is NULL, if the contracts_up and servers_down arguments are both NULL, |
or any of them has erroneous size or its elements are NULL or not in the |
valid range respectively |
*/ |
int |
fsf_negotiate_group |
(const fsf_contracts_group_t *contracts_up, |
const fsf_servers_group_t *severs_down, |
fsf_servers_group_t *severs_up, |
bool *accepted); |
/*@}*/ |
//////////////////////////////////////////////////// |
// OBTAINING INFORMATION FROM THE SCHEDULER |
//////////////////////////////////////////////////// |
/** |
\ingroup coremodule |
\defgroup core_sched_info Obtaining information from the scheduler. |
This group of function is used to get informations from the |
scheduler, like execution time of a task, remaining budget of a |
server, etc. |
@{ |
*/ |
/** |
Returns true if the system is configured with the on-line admission |
test enabled, or false otherwise. |
*/ |
bool |
fsf_is_admission_test_enabled(); |
/** |
This function stores the current execution time spent by the |
threads bound to the specified server in the variable pointed to by |
cpu_time. |
@param [in] server server id |
@param [out] cpu_time pointer to a timespec structure that will contain |
the cpu time consumed by the threads that are bound to the |
specific server, since its creation. |
@retval 0 if succesful completion |
@retval FSF_ERR_BAD_ARGUMENT if the value of the server argument is |
not in range or cpu_time is NULL |
@retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD if the calling thread is not |
scheduled under the FSF |
@retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or |
not running |
@retval FSF_ERR_NOT_CONTRACTED_SERVER if the server of the calling thread |
has been cancelled or it is not valid |
*/ |
int |
fsf_get_cpu_time |
(fsf_server_id_t server, |
struct timespec *cpu_time); |
/** |
This function stores in the variable pointed to by budget the |
remaining execution-time budget associated with the specified |
server. |
@param [in] server server id |
@param [out] budget pointer to a timespec structure that will |
contain the remaining budget |
@retval 0 if succesful completion |
@retval FSF_ERR_BAD_ARGUMENT if the value of the server argument is |
not in range or budget is NULL |
@retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD if the calling thread is not |
scheduled under the FSF |
@retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or |
not running |
@retval FSF_ERR_NOT_CONTRACTED_SERVER if the server of the calling thread |
has been cancelled or it is not valid |
*/ |
int |
fsf_get_remaining_budget |
(fsf_server_id_t server, |
struct timespec *budget); |
/** |
This function stores in the variables pointed to by budget and |
period, the execution-time budget and the period respectively |
associated with the specified server. If any of these pointers is |
NULL, the corresponding information is not stored. |
@param [in] server server id |
@param [out] budget budget available for the current server instance |
@param [out] period period available for the current server instance |
@retval 0 if succesful completion |
@retval FSF_ERR_BAD_ARGUMENT if the value of the server argument is |
not in range, budget is NULL or period is NULL |
@retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD if the calling thread is not |
scheduled under the FSF |
@retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or not |
running |
@retval FSF_ERR_NOT_CONTRACTED_SERVER if the server of the calling thread |
has been cancelled or it is not valid |
*/ |
int |
fsf_get_budget_and_period |
(fsf_server_id_t server, |
struct timespec *budget, |
struct timespec *period); |
/* @} */ |
///////////////////////////////////////////////////////////////////// |
// SERVICE THREAD TUNING |
///////////////////////////////////////////////////////////////////// |
/** |
\ingroup coremodule |
\defgroup core_service_thread Service Thread |
These functions are to the initialization and tuning of the service |
thread. |
@todo specify that the default budget and periods are in the |
configuration file. |
Implementation dependency: in the fixed priority implementation of |
fsf, the default priority is lower than the priority of any server, |
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. |
@{ |
*/ |
/** |
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 servers. 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 |
servers 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. |
@param [in] budget budget for the service thread |
@param [in] period for the service thread |
@param [out] accepted true is the change has been accepted |
@retval 0 is the operation is succesful |
@retval FSF_ERR_BAD_ARGUMENT if any of the pointer arguments is NULL or |
the budget value is greater than the period value |
@retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD if the calling thread is not |
scheduled under the FSF |
@retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or |
not running |
@retval FSF_ERR_NOT_CONTRACTED_SERVER if the server of the calling thread |
has been cancelled or it is not valid |
*/ |
int |
fsf_set_service_thread_data |
(const struct timespec *budget, |
const struct timespec *period, |
bool *accepted); |
/** |
this function returns in the variables pointed by budget and |
period, respectively, the current budget and period of the service |
thread. |
@param [out] budget current budget of the service thread |
@param [out] period current period of the service thread |
@retval FSF_ERR_BAD_ARGUMENT if any of the pointer arguments is NULL |
@retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD if the calling thread is not |
scheduled under the FSF |
@retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong |
or not running |
@retval FSF_ERR_NOT_CONTRACTED_SERVER if the server of the calling thread |
has been cancelled or it is not valid |
*/ |
int |
fsf_get_service_thread_data |
(struct timespec *budget, |
struct timespec *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 servers, special background contracts may be created |
for specifying the synchronization requirements. |
The way of specifying a background contract is by setting |
budget_min = period_max = 0. Negotiation may fail if the contract |
uses shared_objects. If the contract has no shared_objects the |
returned server id represents the background and may be used to |
bind more than one thread. If the contract has shared objects a |
server is created to keep track of them, but the associated threads |
are executed in the background, together with the other background |
threads |
@todo [PEPPE: this will be put in the general description of the core |
module] |
*/ |
#endif // _FSF_CORE_H_ |
/shark/trunk/ports/first/fsf_include/fsf_configuration_parameters.h |
---|
0,0 → 1,182 |
//fsf_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 FSF(FIRST Scheduling Framework) configuration parameters |
//============================================================== |
////////////////////////////////////////////////////// |
// Definitions required to configure the fsf |
// scheduling algorithms. |
#include <sys/boolean.h> |
#ifndef _FSF_CONFIGURATION_PARAMETERS_H_ |
#define _FSF_CONFIGURATION_PARAMETERS_H_ |
// This symbol specifies whether the scheduler will make a |
// schedulability test of the requested contract or not |
#define FSF_ADMISSION_TEST_IS_ENABLED true |
// Tune these values for optimizing the amount of memory used by the |
// implementation |
// Maximum number of accepted contracts (servers) |
#define FSF_MAX_N_SERVERS 10 |
// Maximum number of threads that may be scheduled by the framework |
#define FSF_MAX_N_THREADS 11 |
// Maximum number of critical sections that can be stored in a |
// contract parameters object |
#define FSF_MAX_N_CRITICAL_SECTIONS 10 |
// Maximum number of utilization values (pairs of budget and period) |
// that can be stored in a contract parameters object |
#define FSF_MAX_N_UTILIZATION_VALUES 5 |
// Maximum number of synchronization objects |
#define FSF_MAX_N_SYNCH_OBJECTS 5 |
// Maximum number of shared objects |
#define FSF_MAX_N_SHARED_OBJECTS 100 |
//////////////////////////////////////////// |
// 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 FSF_SCHEDULER_PRIORITY 30 |
// Real-time signal number reserved for the application scheduler to |
// manage its timers. |
#define FSF_SCHEDULER_SIGNAL SIGRTMIN |
// The highest priority that can be assigned to an application thread, |
// it should be defined as one level less than the |
// FSF_SCHEDULER_PRIORITY |
#define FSF_HIGHEST_THREAD_PRIORITY FSF_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 FSF_LOWEST_THREAD_PRIORITY 2 |
// 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 FSF_MAX_N_SERVICE_JOBS FSF_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 FSF_SERVICE_THREAD_PERIOD {0,100000000} //0.1 seg |
// Initial budget of the service thread (timespec) |
#define FSF_SERVICE_THREAD_BUDGET {0,10000000} //0.01 seg |
// Initial priority of the service thread, it has to be lower than the |
// FSF_SCHEDULER_PRIORITY, and is set according to its period and the |
// expected response times for reconfiguration or tunning of the |
// system. |
#define FSF_SERVICE_THREAD_PRIORITY 1 |
// Numeric identifier of the service thread, used for tracing |
#define FSF_SERVICE_THREAD_IDNAME 0x55555555 |
//Maximum number of servers that can be simultaneusly waiting for |
//being signaled in a synchronization object |
#define FSF_MAX_N_SERVERS_IN_SYNCH_OBJECT 4 |
//Maximum number of events that can be pending to be signaled in a |
//synchronization object |
#define FSF_MAX_N_EVENTS_IN_SYNCH_OBJECT 100 |
//Maximum number of pending replenishments in each sporadic server |
#define FSF_MAX_N_PENDING_REPLENISHMENTS 25 |
// 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: |
// [FSF_LOWEST_THREAD_PRIORITY, FSF_HIGHEST_THREAD_PRIORITY] |
int |
fsf_priority_map (unsigned long plevel); |
// This symbol specifies whether the scheduling system will make |
// traces of the servers, the scheduler and the service thread |
// operation and make them available through the fsf_print_traces |
// function |
#define FSF_TRACING_SERVICE_IS_ENABLED true |
#endif /* _FSF_CONFIGURATION_PARAMETERS_H_ */ |
/shark/trunk/ports/first/first-contract.c |
---|
48,8 → 48,13 |
} |
} |
int fsf_init() { |
FSF_start_service_task(); |
} |
int fsf_initialize_contract |
(fsf_contract_parameters_t *contract) |
{ |
/shark/trunk/ports/first/include/fsf.h |
---|
File deleted |
/shark/trunk/ports/first/include/fsf_basic_types.h |
---|
File deleted |
/shark/trunk/ports/first/include/fsf_core.h |
---|
File deleted |
/shark/trunk/ports/first/include/fsf_contract.h |
---|
File deleted |
/shark/trunk/ports/first/include/fsf_dynamic_reclaiming.h |
---|
File deleted |
/shark/trunk/ports/first/include/fsf_hierarchical.h |
---|
File deleted |
/shark/trunk/ports/first/include/fsf_configuration_parameters.h |
---|
File deleted |
/shark/trunk/ports/first/include/fsf_opaque_types.h |
---|
File deleted |
/shark/trunk/ports/first/include/fsf_server.h |
---|
42,7 → 42,7 |
#define SERVER_getbudgetinfo GRUBSTAR_getbudgetinfo |
#define SERVER_get_last_reclaiming GRUBSTAR_get_last_reclaiming |
#define SERVER_get_remain_capacity GRUBSTAR_get_remain_capacity |
#define SERVER_return_bandwidth GRUBSTAR_return_bandwidth |
//#define SERVER_return_bandwidth GRUBSTAR_return_bandwidth |
#define SERVER_disable_server GRUBSTAR_disable_server |
#define SERVER_get_renegotiation_status GRUBSTAR_get_renegotiation_status |
#endif |
/shark/trunk/ports/first/first-server.c |
---|
17,12 → 17,8 |
#include <modules/hartport.h> |
#include <modules/cabs.h> |
#include "fsf_basic_types.h" |
#include "fsf_configuration_parameters.h" |
#include "fsf_core.h" |
#include "fsf_server.h" |
#include "fsf.h" |
#include "fsf_service_task.h" |
#include "fsf_hierarchical.h" |
#include "message.h" |
#include "posixstar.h" |
79,10 → 75,14 |
void FSF_start_service_task(void) { |
int err; |
struct timespec default_period = {0,50000000}; |
struct timespec default_budget = {0,1000000}; |
struct timespec default_period = FSF_SERVICE_THREAD_PERIOD; |
struct timespec default_budget = FSF_SERVICE_THREAD_BUDGET; |
DUMMY_TASK_MODEL m; |
fsf_sched_params_t pr; |
pr.policy=FSF_NONE; |
pr.params=&m; |
dummy_task_default_model(m); |
// create the service task |
98,7 → 98,7 |
negotiate_contract(&service_contract,&service_server); |
//server_task = task_create("stask",service_task,model,NULL); |
err = fsf_create_thread(service_server,&server_task,NULL,service_task,NULL,&m); |
err = fsf_create_local_thread(service_server,&pr, &server_task,NULL,(fsf_thread_code_t)service_task,NULL); |
if (err) { |
cprintf("error creating service task\n"); |
sys_shutdown_message("Could not create service_task"); |
445,6 → 445,9 |
return FSF_ERR_UNKNOWN_APPSCHEDULED_THREAD; |
scheduler_id = SERVER_get_local_scheduler_id_from_budget(fsf_server_level,server); |
if (scheduler_id!=sched_params->policy) |
return FSF_ERR_SCHED_POLICY_NOT_COMPATIBLE; |
/* Check if thread is already bind */ |
switch(scheduler_id) { |
451,8 → 454,8 |
case FSF_RM: |
{ |
TASK_MODEL *m=(TASK_MODEL*)sched_params; |
HARD_TASK_MODEL *h=(HARD_TASK_MODEL *)sched_params; |
TASK_MODEL *m=(TASK_MODEL*)(sched_params->params); |
HARD_TASK_MODEL *h=(HARD_TASK_MODEL *)(sched_params->params); |
if (m->pclass != HARD_PCLASS) |
return FSF_ERR_SCHED_POLICY_NOT_COMPATIBLE; |
474,8 → 477,8 |
case FSF_EDF: |
{ |
TASK_MODEL *m=(TASK_MODEL*)sched_params; |
HARD_TASK_MODEL *h=(HARD_TASK_MODEL *)sched_params; |
TASK_MODEL *m=(TASK_MODEL*)(sched_params->params); |
HARD_TASK_MODEL *h=(HARD_TASK_MODEL *)(sched_params->params); |
if (m->pclass != HARD_PCLASS) |
return FSF_ERR_SCHED_POLICY_NOT_COMPATIBLE; |
495,7 → 498,7 |
case FSF_POSIX: |
{ |
TASK_MODEL *m=(TASK_MODEL*)sched_params; |
TASK_MODEL *m=(TASK_MODEL*)(sched_params->params); |
if (m->pclass != NRT_PCLASS) |
return FSF_ERR_SCHED_POLICY_NOT_COMPATIBLE; |
519,7 → 522,7 |
SYS_FLAGS f; |
f=kern_fsave(); |
msg->command = STD_SET_NEW_MODEL; |
msg->param = (void *)(sched_params); |
msg->param = (void *)(sched_params->params); |
level_table[local_scheduler_level]->public_message(local_scheduler_level,thread,msg); |
msg->command = STD_SET_NEW_LEVEL; |
584,13 → 587,13 |
return 0; |
} |
int fsf_create_thread |
(fsf_server_id_t server, |
pthread_t *thread, |
pthread_attr_t *attr, |
fsf_thread_code_t thread_code, |
void *arg, |
void *local_scheduler_arg) |
int fsf_create_local_thread |
(fsf_server_id_t server, |
fsf_sched_params_t *local_scheduler_arg, |
pthread_t *thread, |
pthread_attr_t *attr, |
fsf_thread_code_t thread_code, |
void *arg) |
{ |
int local_scheduler_level,scheduler_id; |
879,6 → 882,19 |
} |
bandwidth_t SERVER_return_bandwidth() { |
int i=0; |
bandwidth_t U; |
U=0; |
for(i=0;i<current_server;i++) { |
U+=server_list[i].Umin; |
} |
return U; |
} |
int recalculate_contract(bandwidth_t U) { |
bandwidth_t current_bandwidth; |
unsigned int temp_U; |
896,7 → 912,7 |
#endif |
/* The current bandwidth is the min bandwidth */ |
//current_bandwidth=SERVER_return_bandwidth(fsf_server_level); |
current_bandwidth=SERVER_return_bandwidth(fsf_server_level); |
#ifdef FSF_DEBUG |
kern_printf("(nserver %d)", current_server); |
#endif |
/shark/trunk/ports/first/makefile |
---|
17,7 → 17,7 |
OBJS = $(FIRST) |
C_OPT += -I./include -I. -I.. |
C_OPT += -I./fsf_include -I./include -I. -I.. |
include $(BASE)/config/lib.mk |