Blame |
Last modification |
View Log
| RSS feed
//====================================================================================
// 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"
#ifndef _FSF_CONTRACT_H_
#define _FSF_CONTRACT_H_
//////////////////////////////////////////////////////////////////
// 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;
typedef struct {
int size; // = 0
fsf_critical_section_data_t section[FSF_MAX_N_CRITICAL_SECTIONS];
} fsf_critical_sections_t;
typedef int fsf_scheduler_id_t;
#define FSF_SCHEDULER_POSIX 0
#define FSF_SCHEDULER_EDF 1
#define FSF_SCHEDULER_RM 2
// 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 false
#define FSF_DEFAULT_DEADLINE {0,0}
#define FSF_DEFAULT_SCHEDULER FSF_SCHEDULER_POSIX
// 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_BIND_THREAD 2003009
#define FSF_ERR_UNBIND_THREAD 2003010
#define FSF_ERR_CREATE_THREAD 2003011
#define FSF_ERR_SERVER_USED 2003012
#define FSF_ERR_INVALID_SERVER 2003013
#define FSF_ERR_CREATE_SERVER 2003014
//////////////////////////////////////////////////////////////
// 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).
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);
int
fsf_get_local_scheduler_parameter
(const fsf_contract_parameters_t *contract,
fsf_scheduler_id_t *local_scheduler_id);
//////////////////////////////////////////////////////////////
// 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;
// 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_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,
void *rt_arg);
//Description: 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 policy and priority, according to the preemption level
//given in the contract and the fsf_priority_map() function defined by
//the user. If the contract is rejected, the thread is not created and
//the corresponding error is returned.
int
fsf_negotiate_contract_for_myself
(const fsf_contract_parameters_t *contract,
fsf_server_id_t *server,
void *rt_arg);
//Description: 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.
//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.
int
fsf_bind_thread_to_server
(fsf_server_id_t server,
pthread_t thread,
void *rt_arg);
//Description: 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, 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.
//FIRST project development issue: In this phase of the project, only
//one thread is allowed to be bound to a server, sharing a server by
//multiple threads is planned to be allowed in the next phase of
//the project.
int
fsf_unbind_thread_from_server (pthread_t thread);
//Description: 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.
//Implementation dependent issue: in the implementation with an
//application scheduler, the thread is still attached to the fsf
//scheduler, but suspended.
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.
#endif // _FSF_CONTRACT_H_