Subversion Repositories shark

Rev

Rev 1063 | Details | Compare with Previous | Last modification | View Log | RSS feed

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