Subversion Repositories shark

Rev

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

Rev Author Line No. Line
881 trimarchi 1
//fsf_hierarchical.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
// hierarchical scheduling management
13
//===================================================================
14
 
15
#include <time.h>
16
#include "fsf_basic_types.h"
17
#include "fsf_core.h"
18
 
19
#ifndef _FSF_HIERARCHICAL_H_
20
#define _FSF_HIERARCHICAL_H_
21
 
22
#define FSF_HIERARCHICAL_MODULE_SUPPORTED       1
23
 
24
//// The definition of this types is in fsf_basic_types.h
25
//
26
//// Scheduling policies
27
//typedef enum {FSF_FP, FSF_EDF, FSF_TABLE_DRIVEN, FSF_NONE} 
28
//    fsf_sched_policy_t;
29
//
30
//// Scheduling policy and parameters
31
//typedef struct {
32
//  fsf_sched_policy_t    policy;
33
//  void *                params;
34
//} fsf_sched_params_t;
35
//// The params member is a pointer to one of the 
36
//// following:
37
////    FP:  int (priority)
38
////    EDF: struct timespec (deadline)
39
////    TABLE_DRIVEN : struct fsf_table_driven_params_t
40
//
41
//
42
////Scheduling parameters for the table-driven policy (t.b.d)
43
//typedef struct {
44
//  // list of target windows (t.b.d.) 
45
//  // deadline (for the API): end of september
46
//} fsf_table_driven_params_t;
47
//
48
//
49
////Initialization information for a scheduling policy
50
//typedef void * fsf_sched_init_info_t;
51
//// It shall be one of the following:
52
////    FP:  none
53
////    EDF: none
54
////    TABLE_DRIVEN : struct timespec (schedule duration)
55
//
56
 
928 trimarchi 57
// Constants for assigning default values
58
#define FSF_DEFAULT_SCHED_POLICY        FSF_NONE
59
 
60
 
61
/**
62
   \ingroup hiermodule  
63
 
64
   This call has the following effects:
65
    - FP:  none
66
    - EDF: none
67
    - TABLE_DRIVEN :
68
       Records the schedule duration, and starts the
69
       schedule at the time of the call. After the
70
       schedule duration has elapsed, the schedule in
71
       the table is repeated.
72
 
73
     @param [in] server server id
74
     @param [in] info TBD
75
 
76
     @retval FSF_ERR_BAD_ARGUMENT if the value of the server argument
77
            is not in range or info is NULL
78
     @retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD if the calling thread is not
79
            scheduled under the FSF
80
     @retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or not
81
             running
82
     @retval FSF_ERR_NOT_CONTRACTED_SERVER if the server of the calling
83
             thread has been cancelled or it is not valid
881 trimarchi 84
*/
85
int fsf_init_local_scheduler(
86
   fsf_server_id_t       server,
87
   fsf_sched_init_info_t info);
88
 
89
 
90
/////////////////////////////////////////////////
91
//                       CONTRACT PARAMETERS
92
////////////////////////////////////////////////
93
 
928 trimarchi 94
/**
95
   \ingroup hiermodule
96
 
97
   The operation updates the specified contract parameters object by
98
   setting its scheduling policy to the specified input parameter.
99
   The default policy is FSF_NONE, which means that only one thread
100
   may be bound to the server
101
 
102
   @param [in] contract pointer to the contract
103
   @param [in] sched_policy local scheduling policy for this server.
104
     Can be FSF_FP, FSF_EDF, FSF_TABLE_DRIVEN, FSF_NONE.
105
 
106
   @retval 0 if the operation is succesful
107
   @retval FSF_ERR_BAD_ARGUMENT if sched_policy is not one of the supported
108
       ones, or contract is NULL
109
 
889 trimarchi 110
*/
881 trimarchi 111
int
112
fsf_set_contract_scheduling_policy
113
  (fsf_contract_parameters_t *contract,
114
   fsf_sched_policy_t         sched_policy);
115
 
116
 
928 trimarchi 117
/**
118
   \ingroup hiermodule
119
 
120
   This operation obtains from the specified contract parameters
121
   object its scheduling policy, and copies it to the place pointed to
122
   by the corresponding input parameter.
123
 
124
   @param [in] contract pointer to the contract
125
   @param [out] sched_policy pointer to a variable that will contain
126
                the scheduling policy
127
 
128
   @retval 0 if the operation is succesful
129
   @retval FSF_ERR_BAD_ARGUMENT if sched_policy or contract are NULL
130
 
889 trimarchi 131
*/
881 trimarchi 132
int
133
fsf_get_contract_scheduling_policy
134
  (const fsf_contract_parameters_t *contract,
135
   fsf_sched_policy_t              *sched_policy);
136
 
137
 
928 trimarchi 138
/**
139
   \ingroup hiermodule
140
 
141
   This operation creates a thread and binds it to the specified
142
   server, which must have a policy different than FSF_NONE. The new
143
   thread is created with the arguments thread, attr, thread_code and
144
   arg as they are defined for the pthread_create() POSIX function
145
   call, and its local scheduling parameters are set to the value
146
   stored in the variable pointed to by sched_params, which must be
147
   compatible with the server's scheduling policy. Then, the function
148
   binds the created thread to the new server. The attr parameter is
149
   overwritten as necessary to introduce the adequate scheduling
150
   policy and priority, according to the preemption level given in the
151
   contract and the fsf_priority_map() function defined by the user.
152
 
153
   @param [in] server server id
154
   @param [in] sched_params scheduling parameters for the thread
155
   @param [out] thread the thread id after creation
156
   @param [in] attr attributes for the task (see pthread_create())
157
   @param [in] thread_code pointer to a function that implements the
158
       thread code
159
   @param [in] arg arguments for the thread
160
 
161
   @retval 0 if the operation is succesful
162
   @retval FSF_ERR_BAD_ARGUMENT if the value of the server argument
163
           is not in range, or sched_params is NULL
164
   @retval FSF_ERR_SCHED_POLICY_NOT_COMPATIBLE if the scheduling policy
881 trimarchi 165
       in sched_params is not compatible to the server's one.
928 trimarchi 166
   @retval FSF_ERR_INTERNAL_ERROR erroneous binding or malfunction of the FSF
881 trimarchi 167
       main scheduler
928 trimarchi 168
   @retval FSF_ERR_NOT_CONTRACTED_SERVER if the referenced server is not valid
881 trimarchi 169
 
928 trimarchi 170
   @retval others It may also return any of  the errors that may be
171
       returned by the pthread_create()POSIX function call
881 trimarchi 172
*/
173
 
174
int
175
fsf_create_local_thread
176
  (fsf_server_id_t        server,
177
   fsf_sched_params_t    *sched_params,
178
   pthread_t             *thread,
179
   pthread_attr_t        *attr,
180
   fsf_thread_code_t      thread_code,
181
   void                  *arg);
182
 
928 trimarchi 183
/**
184
   \ingroup hiermodule
185
 
186
   This operation associates a thread with a server, which must have a
187
   policy different than FSF_NONE. The thread's local scheduling
188
   parameters are set to the value stored in the variable pointed to
189
   by sched_params, which must be compatible with the server's
190
   scheduling policy. After the call the thread starts consuming the
191
   server's budget and is executed according to the contract
192
   established for that server and to its scheduling policy. If the
193
   thread was already bound to another server, it is effectively
194
   unbound from it and bound to the specified one.
881 trimarchi 195
 
928 trimarchi 196
   Implementation dependent issue: In order to allow the usage of
197
   application defined schedulers, the given thread must not have the
198
   scheduling policy SCHED_APP and at the same time be attached to an
199
   application scheduler different than the fsf scheduler.
881 trimarchi 200
 
928 trimarchi 201
   @param [in] server server id
202
   @param [in] thread thread id
203
   @param [in] sched_params scheduling parameters for the thread
204
 
205
   @retval 0 if the operation is succesful
206
   @retval FSF_ERR_BAD_ARGUMENT if the server argument does not complain with
881 trimarchi 207
       the expected format or valid range, the given thread does not exist,
208
       or sched_params is NULL
928 trimarchi 209
   @retval FSF_ERR_SCHED_POLICY_NOT_COMPATIBLE if the scheduling policy
881 trimarchi 210
       in sched_params is not compatible to the server's one.
928 trimarchi 211
   @retval FSF_ERR_INTERNAL_ERROR erroneous binding or malfunction of the FSF
881 trimarchi 212
       main scheduler
928 trimarchi 213
   @retval FSF_ERR_UNKNOWN_APPSCHEDULED_THREAD if the thread is attached to
881 trimarchi 214
       an application defined scheduler different than the fsf scheduler
928 trimarchi 215
   @retval FSF_ERR_NOT_CONTRACTED_SERVER if the referenced server is not valid
881 trimarchi 216
*/
217
int  
218
fsf_bind_local_thread_to_server
219
  (fsf_server_id_t      server,
220
   pthread_t            thread,
221
   fsf_sched_params_t  *sched_params);
222
 
223
 
928 trimarchi 224
/**
225
   \ingroup hiermodule
226
 
227
   This function changes the local scheduling parameters of the thread
228
   to the value pointed to by sched_params. This value must be
229
   compatible with the scheduling policy of the server to which the
230
   thread is bound.
231
 
232
   @param [in] thread thread id
233
   @param [in] sched_params scheduling parameters
234
 
235
   @retval 0 if the operation is succesful
236
   @retval FSF_ERR_BAD_ARGUMENT if the given thread does not exist,
881 trimarchi 237
       or sched_params is NULL
928 trimarchi 238
   @retval FSF_ERR_SCHED_POLICY_NOT_COMPATIBLE if the thread is already bound
881 trimarchi 239
       and the scheduling policy in sched_params is not compatible to the
240
       one of the thread's server.
928 trimarchi 241
   @retval FSF_ERR_NOT_SCHEDULED_THREAD if the given thread is not scheduled
881 trimarchi 242
       under the FSF
928 trimarchi 243
   @retval FSF_ERR_INTERNAL_ERROR erroneous binding or malfunction of the FSF
881 trimarchi 244
       main scheduler
928 trimarchi 245
   @retval FSF_ERR_UNKNOWN_APPSCHEDULED_THREAD if the thread is attached to
881 trimarchi 246
       an application defined scheduler different than the fsf scheduler
928 trimarchi 247
   @retval FSF_ERR_NOT_CONTRACTED_SERVER if the thread is bound and its server
881 trimarchi 248
       is not valid
249
*/
250
int  
251
fsf_set_local_thread_sched_parameters
252
  (pthread_t                     thread,
253
   const fsf_sched_params_t  *sched_params);
254
 
255
 
928 trimarchi 256
/**
257
   \ingroup hiermodule
258
 
259
   This function stores the local scheduling parameters of the
260
   specified thread in the variable pointed to by sched_params
261
 
262
   @param [in] thread thread id
263
   @param [out] sched_params scheduling parameters
264
 
265
   @retval 0 if the operation is succesful
266
   @retval FSF_ERR_BAD_ARGUMENT if sched_params is NULL or the thread does
267
           not exist
268
   @retval FSF_ERR_NOT_SCHEDULED_THREAD if the given thread is not scheduled
881 trimarchi 269
       under the FSF
270
*/
271
int  
272
fsf_get_local_thread_sched_parameters
273
  (pthread_t            thread,
274
   fsf_sched_params_t  *sched_params);
275
 
276
 
277
#endif // _FSF_HIERARCHICAL_H_