Subversion Repositories shark

/*

 * 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

 *

 */

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

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

// 

/**

   \file fsf_basic_types.h

 */

#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

//

// Types for the core module

//

/**

   This data type is used for defining the workload parameter in the

   contract specification functions.

   It can have the following values:

   - FSF_BOUNDED:  The workload generated by the task(s) in the server is bounded

   - FSF_INDETERMINATE: The workload generated by the task(s) in the server is indeterminate

   - FSF_OVERHEAD: The workload generated by the task(s) in the server is TBD

 */

typedef enum {FSF_BOUNDED, FSF_INDETERMINATE, FSF_OVERHEAD} fsf_workload_t;                          

/// Default value for the workload parameter

#define FSF_DEFAULT_WORKLOAD       FSF_INDETERMINATE

/// Default value for the parameter d_equal_t in the contract initialization

#define FSF_DEFAULT_D_EQUALS_T     false

// Default value for the server relative deadline

#define FSF_DEFAULT_DEADLINE       {0,0} //struct timespec

// Constants for omitting the assignment of values

// to specific arguments in calls to

// initialization functions

/// A null deadline

#define FSF_NULL_DEADLINE     (struct timespec *)NULL

/// A null signal

#define FSF_NULL_SIGNAL       0

/**

   This data type is used to express the list of possible values

   returned by fsf_get_renegotiation_status. It can assume the

   following values:

*/

typedef enum {FSF_IN_PROGRESS,

              FSF_REJECTED,

              FSF_ADMITTED,

              FSF_NOT_REQUESTED}

    fsf_renegotiation_status_t;

/**

    Synchronization object handle type, this an opaque type

    used to signaling of servers

*/

typedef FSF_SYNCH_OBJ_HANDLE_T_OPAQUE fsf_synch_obj_handle_t;

/**

    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 *);

//

// Types for the spare capacity module

//

/**

   Granularity of spare capacity requirements.  This data type is used

   in the spare capacity module to specify the kind of granularity in

   spare capacity allocation when creating a new contract.

   A variable of this type can assume the following values:

   - FSF_CONTINUOUS the utilization assigned to the server by the

     spare capacity module can assume any value between the minimum

     (Cmin / Tmax) and the maximum (Cmax/Tmin).

   - FSF_DISCRETE the utilization assigned to the server can assume

     only values in a discrete set of pairs (C,T) (to be specified

     with a variable of type fsf_utilization_set_t)

*/

typedef enum {FSF_CONTINUOUS, FSF_DISCRETE} fsf_granularity_t;

/**

   This data type is used in the spare capacity module to specify

   pairs of (budget,period) that can be assigned by the spare capacity

   distribution algorithm to the server.

   respectively.

*/

typedef struct {

  /// server capacity

  struct timespec    budget;

  /// server period

  struct timespec    period;

} fsf_utilization_value_t;

/**

   This data type is used in the spare capacity module to specify a

   set of possible pairs (C,T) that can be assigned to the server.

 */

typedef struct {

  /// lenght of the array

  int                         size; // = 0

  /// array of pairs (C,T)

  fsf_utilization_value_t    

      value[FSF_MAX_N_UTILIZATION_VALUES];

} fsf_utilization_set_t;

/// List of servers to cancel

typedef  struct {

  int             size;

  fsf_server_id_t servers[FSF_MAX_N_SERVERS];

} fsf_servers_group_t;

/// The defualt granularity

#define FSF_DEFAULT_GRANULARITY         FSF_CONTINUOUS

/// Defaut value for the quality parameter

#define FSF_DEFAULT_QUALITY             0

/// Default value for the importance parameter

#define FSF_DEFAULT_IMPORTANCE          1

/// Constant for omitting the assignment of values to the 

/// fsf_utilizazion_set_t parameter in call to the contract initialization 

/// functions

#define FSF_NULL_UTILIZATION_SET     \

   (fsf_utilization_set_t *)NULL

/// Maximum value of the quality parameter

#define FSF_MAX_QUALITY     (2**32 -1)

/// Minimum value of the quality parameter

#define FSF_MIN_QUALITY     0

/// Maximum value of the importance parameter

#define FSF_MAX_IMPORTANCE  FSF_N_IMPORTANCE_LEVELS

/// Minimum value of the importance parameter

#define FSF_MIN_IMPORTANCE  1

//

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

   /// handle of shared object

   fsf_shared_obj_handle_t obj_handle;

  /// Execution time of critical section

   struct timespec         wcet;  

} fsf_critical_section_data_t;

/**

   This data type is used to specify the critical sections for the contract and is a part of shared object module.

 */

/// List of critical sections

typedef struct {

  /// lenght of the array

  int size; // = 0

  /// array of critical sections

  fsf_critical_section_data_t  

      section[FSF_MAX_N_CRITICAL_SECTIONS];

} fsf_critical_sections_t;

//

// Types for the hierarchical module

//

/**

   This data type is used for defining scheduling polices in a contract

   or the behaviour of a task.

   It can have the following values:

   - FSF_EDF:  EDF policy

   - FSF_RR: Round robin policy

   - FSF_TABLE_DRIVEN: Table driven policy

   - FSF_NONE: Defines that the contract can accept one thread

 */

/// Scheduling policies

typedef enum {FSF_FP, FSF_EDF, FSF_TABLE_DRIVEN, FSF_RR, FSF_FEDF,FSF_NONE}

    fsf_sched_policy_t;

/**

   This data type is used to specify the scheduling policy and parameters for each task in the hierarchical module.

 */

/// Real time parameters

typedef struct {

/// The params member specify the scheduling policy

  fsf_sched_policy_t    policy;

/// The params member is a pointer to one of the

/// following:

///    FP:  int (priority)

///    EDF: struct timespec (deadline)

///    RR:  none

///    TABLE_DRIVEN : struct fsf_table_driven_params_t

  void *                params;

} fsf_sched_params_t;

/**

   This data type is used to specify a target window of a task.  

 */

///Target window for the table-driven scheduler

typedef struct fsf_target_window {

/// The start time of the target window

   struct timespec   start;

/// The end time of the target window

   struct timespec   end;

/// The computation time of the task in the target window

   struct timespec   comp_time;

} fsf_target_window;

/**

   This data type is used to specify the window of activation for each task in the table driven scheduler.  

 */

/// Real time parameters for table drivern

typedef struct {

  /// The params indicates the lenght of the array

  int size;

  /// The params rappresent the array of target windows

  fsf_target_window  table[FSF_MAX_N_TARGET_WINDOWS];

} fsf_table_driven_params_t;

///Initialization information for a scheduling policy

/// It shall be one of the following:

///    FP:  none

///    EDF: none

///    RR: struct timespec (slice duration)

///    TABLE_DRIVEN : struct timespec (schedule duration)

typedef void * fsf_sched_init_info_t;

// Constant for assigning default values

#define FSF_DEFAULT_SCHED_POLICY        FSF_NONE

//

// Types for the distributed services module

//

// Type designating the network ids. They need not

// be sequential numbers.

typedef unsigned int       fsf_network_id_t;

#define FSF_DEFAULT_NETWORK_ID          1

#define FSF_NULL_NETWORK_ID             0

//opaque types for fsf endpoints

typedef FSF_SEND_ENDPOINT_T_OPAQUE   fsf_send_endpoint_t;

typedef FSF_RECEIVE_ENDPOINT_T_OPAQUE fsf_receive_endpoint_t;

/**

   \ingroup distjmodule

   The node_address type specifies the node address in a

   communication-protocol-independent way. The actual address is

   obtained via a configuration dependent mapping function

*/

typedef unsigned int  fsf_node_address_t;

/**

   \ingroup distjmodule

   The port type specifies the information that is necessary to get in

   contact with the thread in the receiving node, in a

   protocol-independent way.  The actual port number is obtained via a

   configuration dependent mapping function

*/

typedef unsigned int  fsf_port_t;

/**

    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;

/// List of contracts to negotiate

typedef struct {

  int  size;

  fsf_contract_parameters_t*  contracts[FSF_MAX_N_SERVERS];

} fsf_contracts_group_t;

// Error codes

#define FSF_ERR_BASE_VALUE                      0x02004000

#define FSF_ERR_TOO_MANY_TASKS                  0x02004001

#define FSF_ERR_BAD_ARGUMENT                    0x02004002

#define FSF_ERR_INVALID_SYNCH_OBJ_HANDLE        0x02004003

#define FSF_ERR_NO_RENEGOTIATION_REQUESTED      0x02004004

#define FSF_ERR_CONTRACT_REJECTED               0x02004005

#define FSF_ERR_NOT_SCHEDULED_CALLING_THREAD    0x02004006

#define FSF_ERR_NOT_BOUND                       0x02004007

#define FSF_ERR_UNKNOWN_SCHEDULED_THREAD        0x02004008

#define FSF_ERR_NOT_CONTRACTED_SERVER           0x02004009

#define FSF_ERR_NOT_SCHEDULED_THREAD            0x0200400A

#define FSF_ERR_TOO_MANY_SERVICE_JOBS           0x0200400B

#define FSF_ERR_TOO_MANY_SYNCH_OBJS             0x0200400C

#define FSF_ERR_TOO_MANY_SERVERS_IN_SYNCH_OBJ   0x0200400D

#define FSF_ERR_TOO_MANY_EVENTS_IN_SYNCH_OBJ    0x0200400E

#define FSF_ERR_INTERNAL_ERROR                  0x0200400F

#define FSF_ERR_TOO_MANY_SERVERS                0x02004010

#define FSF_ERR_INVALID_SCHEDULER_REPLY         0x02004011

#define FSF_ERR_TOO_MANY_PENDING_REPLENISHMENTS 0x02004012

#define FSF_ERR_SYSTEM_ALREADY_INITIALIZED      0x02004013

#define FSF_ERR_SHARED_OBJ_ALREADY_INITIALIZED  0x02004014

#define FSF_ERR_SHARED_OBJ_NOT_INITIALIZED      0x02004015

#define FSF_ERR_SCHED_POLICY_NOT_COMPATIBLE     0x02004016

#define FSF_ERR_SERVER_WORKLOAD_NOT_COMPATIBLE  0x02004017

#define FSF_ERR_ALREADY_BOUND                   0x02004018

#define FSF_ERR_WRONG_NETWORK                   0x02004019

#define FSF_ERR_TOO_LARGE                       0x0200401A

#define FSF_ERR_BUFFER_FULL                     0x0200401B

#define FSF_ERR_NO_SPACE                        0x0200401C

#define FSF_ERR_NO_MESSAGES                     0x0200401D

#define FSF_WRN_MODULE_NOT_SUPPORTED            0x0200401E

#define FSF_ERR_SYSTEM_NOT_INITIALIZED          0x0200401F

#define FSF_ERR_TOO_MANY_SHARED_OBJS            0x02004020

#define FSF_ERR_LAST_VALUE                      0x02004020

#endif // _FSF_BASIC_TYPES_H_