Subversion Repositories shark

Rev

Rev 889 | Rev 929 | Go to most recent revision | Details | Compare with Previous | Last modification | View Log | RSS feed

Rev Author Line No. Line
881 trimarchi 1
//fsf_shared_objects.h
2
//==================================================
3
//       FFFFFFIII   RRRRR      SSTTTTTTT
4
//      FF         IIR   RR    SS
5
//     FF           IR        SS
6
//    FFFFFF         RRRR    SSSSST
7
//   FF       FI       RRR  SS
8
//  FF         II     RRR  SS
9
// FF           IIIIIR    RS
10
//
11
// FSF(FIRST Scheduling Framework) 
12
// shared objects functionality
13
//====================================================
14
 
15
#include <pthread.h>
16
#include "fsf_basic_types.h"
17
#include "fsf_core.h"
18
 
19
#ifndef _FSF_SHARED_OBJECTS_H_
20
#define _FSF_SHARED_OBJECTS_H_
21
 
22
#define FSF_SHARED_OBJECTS_MODULE_SUPPORTED       1
23
 
24
 
25
// These constants are defined in the fsf_configuration_parameters.h
26
// file:
27
 
28
//#define FSF_MAX_N_SHARED_OBJECTS    100
29
//#define FSF_MAX_N_CRITICAL_SECTIONS 20
30
 
31
 
32
//// The definition of this types is in fsf_basic_types.h
33
//
34
//// Shared object identifier (null character terminated string)
35
//typedef char  * fsf_shared_obj_id_t;     
36
//
37
//// Shared object handle (opaque type)
38
//typedef FSF_SHARED_OBJ_HANDLE_T_OPAQUE  fsf_shared_obj_handle_t; 
39
//
40
//// Critical section data
41
//typedef struct {
42
//   fsf_shared_obj_handle_t obj_handle;
43
//   struct timespec         wcet;  //Execution time
44
//} fsf_critical_section_data_t;
45
//
46
//// List of critical sections
47
//typedef struct {
48
//  int size; // = 0
49
//  fsf_critical_section_data_t  
50
//      section[FSF_MAX_N_CRITICAL_SECTIONS];
51
//} fsf_critical_sections_t;
52
//
53
 
54
/////////////////////////////////////////////////////
55
//           SHARED OBJECTS & OPERATIONS MANAGEMENT
56
/////////////////////////////////////////////////////
57
 
928 trimarchi 58
/**
59
   \ingroup shobjmodule
60
 
61
   Initialization of shared objects. If the object identified by
62
   obj_id does not yet exist it is created, a handle to the object is
63
   returned in the variable pointed to by obj_handle, and the
64
   specified mutex is initialized with the appropriate attributes
65
   necessary for the current implementation.  If the object already
66
   exists, the function fails.
67
 
68
   @param [in] obj_id shared object id
69
   @param [out] obj_handle pointer to a shared object handle
70
   @param [out] mutex pointer to a mutex variable
71
 
72
   @retval 0 if the operation is succesful
73
   @retval FSF_ERR_BAD_ARGUMENT if obj_id, obj_handle, or mutex are NULL
74
   @retval FSF_ERR_SHARED_OBJ_ALREADY_INITIALIZED if the object identified
881 trimarchi 75
       by obj_id already exists
928 trimarchi 76
   @retval others It may also return any of the error codes that are
77
       returned by the pthread_mutex_init() POSIX function call
881 trimarchi 78
*/
79
int fsf_init_shared_object
80
   (fsf_shared_obj_id_t      obj_id,
81
    fsf_shared_obj_handle_t *obj_handle,
82
    pthread_mutex_t         *mutex);
83
 
84
 
928 trimarchi 85
/**
86
   \ingroup shobjmodule
87
 
88
   Getting the handle of shared
89
   objects. If the object already exists a handle to the object is
90
   returned in the variable pointed to by obj_handle. Otherwise, an
91
   error code is returned by the function.
92
 
93
   @param [in] obj_id shared object id
94
   @param [out] obj_handle pointer to a shared object handle
95
 
96
   @retval 0 if the operation is succesful
97
   @retval FSF_ERR_BAD_ARGUMENT if obj_id or obj_handle are NULL
98
   @retval FSF_ERR_SHARED_OBJ_NOT_INITIALIZED if the shared object identified
881 trimarchi 99
       by obj_id does not exist
928 trimarchi 100
   @retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
881 trimarchi 101
       scheduled under the FSF
928 trimarchi 102
   @retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or not
103
       running
104
   @retval FSF_ERR_NOT_CONTRACTED_SERVER : if the server of the calling
105
       thread has been cancelled or it is not valid
881 trimarchi 106
*/
107
int fsf_get_shared_object_handle
108
   (fsf_shared_obj_id_t      obj_id,
109
    fsf_shared_obj_handle_t *obj_handle);
110
 
928 trimarchi 111
/**
112
   \ingroup shobjmodule
113
 
114
   Getting the mutex of shared objects. If the object exists, a
115
   pointer to its associated mutex is returned in the variable pointed
116
   to by mutex. Otherwise, an error code is returned by the function.
117
 
118
   @param [in] obj_handle  shared object handle
119
   @param [out] mutex pointer to a pointer to a mutex variable,
120
        (remember that the function give back a pointer to a mutex!)
121
 
122
   @retval 0 if the operation is succesful
123
   @retval FSF_ERR_BAD_ARGUMENT if obj_handle or mutex are NULL
124
   @retval FSF_ERR_SHARED_OBJ_NOT_INITIALIZED if the shared object identified
881 trimarchi 125
       by obj_id does not exist
928 trimarchi 126
   @retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
881 trimarchi 127
       scheduled under the FSF
928 trimarchi 128
   @retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or not
129
       running
130
   @retval FSF_ERR_NOT_CONTRACTED_SERVER if the server of the calling thread
881 trimarchi 131
       has been cancelled or it is not valid
132
*/
133
int fsf_get_shared_object_mutex
134
   (fsf_shared_obj_handle_t  obj_handle,
135
    pthread_mutex_t          **mutex);
136
 
137
 
138
/////////////////////////////////////////////////////
139
//                       CONTRACT PARAMETERS
140
/////////////////////////////////////////////////////
141
 
928 trimarchi 142
/**
143
   \ingroup shobjmodule
144
 
145
   The operation updates the specified contract parameters object by
146
   setting its critical sections to the specified input parameter.
147
 
148
 
149
   @param[in] contract the service contract
150
   @param[in] critical_sections list of critical sections accessed by tasks
151
       belonging to the contract
152
 
153
   @retval 0 if the operation is succesful
154
   @retval FSF_ERR_BAD_ARGUMENT :if any of the pointers is NULL or
881 trimarchi 155
       the size of the critical_sections structure is less than zero
156
       or grater than FSF_MAX_N_CRITICAL_SECTIONS
157
*/
158
int
159
fsf_set_contract_synchronization_parameters
160
  (fsf_contract_parameters_t     *contract,
161
   const fsf_critical_sections_t *critical_sections);
162
 
163
 
928 trimarchi 164
/**
165
   \ingroup shobjmodule
166
 
167
   The operation obtains from the specified contract parameters object
168
   its critical sections, and copies them to the places pointed to by
169
   the specified input parameter.  Only those critical_section_data
170
   records that are in use in the critical_sections structure are
171
   copied (according to its size field).
172
 
173
   @param[in] contract pointer to a contract
174
   @param[out] critical_sections list of critical sections to be filled
175
 
176
   @retval 0 if the operation is succesful
177
   @retval FSF_ERR_BAD_ARGUMENT if any of the pointers is NULL
889 trimarchi 178
*/
881 trimarchi 179
int
180
fsf_get_contract_synchronization_parameters
181
  (const fsf_contract_parameters_t *contract,
182
   fsf_critical_sections_t         *critical_sections);
183
 
184
 
185
#endif // _FSF_SHARED_OBJECTS_H_