Subversion Repositories shark

//====================================================================================

//       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_