Subversion Repositories shark

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

//fsf_init_local_scheduler: 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.
/*
    [ERR@RETURNED:
     FSF_ERR_BAD_ARGUMENT : if the value of the server argument is not in range,
       or info is NULL
     FSF_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
       scheduled under the FSF
     FSF_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running
     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);


// Constants for assigning default values
#define FSF_DEFAULT_SCHED_POLICY        FSF_NONE


/////////////////////////////////////////////////
//                       CONTRACT PARAMETERS
////////////////////////////////////////////////

//fsf_set_contract_scheduling_policy: 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
/*
    [ERR@RETURNED:
     FSF_ERR_BAD_ARGUMENT : if sched_policy is not in range,
       or contract is NULL
    ]
*/

int
fsf_set_contract_scheduling_policy
  (fsf_contract_parameters_t *contract,
   fsf_sched_policy_t         sched_policy);


//fsf_get_contract_scheduling_policy: This operation obtains from the
//specified contract parameters object its scheduling policy, and
//copies it to the place pointed to by the corresponding input
//parameter.
/*
    [ERR@RETURNED:
     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);


//fsf_create_local_thread: : 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.
/*
    [ERR@RETURNED:
     FSF_ERR_BAD_ARGUMENT : if the value of the server argument is not in range,
       or sched_params is NULL
     FSF_ERR_SCHED_POLICY_NOT_COMPATIBLE : if the scheduling policy
       in sched_params is not compatible to the server's one.
     FSF_ERR_INTERNAL_ERROR : erroneous binding or malfunction of the FSF
       main scheduler
     FSF_ERR_NOT_CONTRACTED_SERVER : if the referenced server is not valid
     FSF_ERR_SERVER_WORKLOAD_NOT_COMPATIBLE: if the kind of workload
       of the server is FSF_OVERHEAD
     
     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);

//fsf_bind_local_thread_to_server: 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.

/*
    [ERR@RETURNED:
     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
     FSF_ERR_SCHED_POLICY_NOT_COMPATIBLE : if the scheduling policy
       in sched_params is not compatible to the server's one.
     FSF_ERR_INTERNAL_ERROR : erroneous binding or malfunction of the FSF
       main scheduler
     FSF_ERR_UNKNOWN_APPSCHEDULED_THREAD : if the thread is attached to
       an application defined scheduler different than the fsf scheduler
     FSF_ERR_NOT_CONTRACTED_SERVER : if the referenced server is not valid
     FSF_ERR_SERVER_WORKLOAD_NOT_COMPATIBLE: if the kind of workload
       of the server is FSF_OVERHEAD
    ]
*/

int  
fsf_bind_local_thread_to_server
  (fsf_server_id_t      server,
   pthread_t            thread,
   fsf_sched_params_t  *sched_params);
     

// fsf_set_local_thread_sched_parameters: 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.
/*
    [ERR@RETURNED:
     FSF_ERR_BAD_ARGUMENT : if the given thread does not exist,
       or sched_params is NULL
     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.
     FSF_ERR_NOT_SCHEDULED_THREAD : if the given thread is not scheduled
       under the FSF
     FSF_ERR_INTERNAL_ERROR : erroneous binding or malfunction of the FSF
       main scheduler
     FSF_ERR_UNKNOWN_APPSCHEDULED_THREAD : if the thread is attached to
       an application defined scheduler different than the fsf scheduler
     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);


// fsf_get_local_thread_sched_parameters: this function stores the
// local scheduling parameters of the specified thread in the variable
// pointed to by sched_params
/*
    [ERR@RETURNED:
     FSF_ERR_BAD_ARGUMENT : if sched_params is NULL or the thread does
        not exist
     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_