Subversion Repositories shark

Rev

Go to most recent revision | Details | Last modification | View Log | RSS feed

Rev Author Line No. Line
881 trimarchi 1
//====================================================================================
2
//       FFFFFFIII   RRRRR      SSTTTTTTT
3
//      FF         IIR   RR    SS
4
//     FF           IR        SS
5
//    FFFFFF         RRRR    SSSSST      
6
//   FF       FI       RRR  SS
7
//  FF         II     RRR  SS
8
// FF           IIIIIR    RS 
9
//       
10
// Basic FSF(FIRST Scheduling Framework) contract management
11
// S.Ha.R.K. Implementation
12
//=====================================================================
13
 
14
#include <time.h>
15
#include <sys/boolean.h>
16
#include <sys/types.h>
17
 
18
#include "fsf_configuration_parameters.h"
19
#include "fsf_opaque_types.h"
20
 
21
#include "edfstar.h"
22
#include "rmstar.h"
23
#include "posixstar.h"
24
#include "nonestar.h"
25
 
26
#ifndef _FSF_CONTRACT_H_
27
#define _FSF_CONTRACT_H_
28
 
29
 
30
 
31
/* S.Ha.R.K. Init */
32
int FSF_register_module(int server_level, bandwidth_t max_bw);
33
 
34
//////////////////////////////////////////////////////////////////
35
//                     BASIC TYPES AND CONSTANTS
36
//////////////////////////////////////////////////////////////////
37
 
38
typedef enum {FSF_BOUNDED, FSF_INDETERMINATE} fsf_workload_t;
39
 
40
typedef enum {FSF_CONTINUOUS, FSF_DISCRETE} fsf_granularity_t;
41
 
42
typedef struct {
43
  struct timespec    budget;    // Execution time
44
  struct timespec    period;    // Period
45
} fsf_utilization_value_t;
46
 
47
typedef struct {
48
  int                         size; // = 0
49
  fsf_utilization_value_t     unit[FSF_MAX_N_UTILIZATION_VALUES];
50
} fsf_utilization_set_t;
51
 
52
typedef unsigned long         fsf_preemption_level_t; // range 1..2**32-1
53
 
54
typedef struct {
55
  struct timespec          wcet;      // Execution time
56
  fsf_preemption_level_t   plevel;    // Preemption_Level, range 1..2**32-1
57
} fsf_critical_section_data_t;
58
 
59
 
60
// Definition of basic types
61
 
62
typedef unsigned int  fsf_shared_op_id_t;
63
typedef unsigned int  fsf_shared_obj_id_t;
64
 
65
// Operations
66
// The first field contains the id of the related object
67
// the second field contains an identifier of the operation
68
//   this identifier is unique for the object but needs not to be unique
69
//   for the system. In other words, there can be two operations with the 
70
//   same identifier belonging to different shared objects: they are 
71
//   effectively two distinct operations; two different operations on the 
72
//   same object must have different identifiers
73
 
74
typedef struct {
75
  fsf_shared_obj_id_t      obj_id;    // Object identification
76
  fsf_shared_op_id_t       op_id;     // Operation Identification
77
  struct timespec          wcet;      // Execution time
78
} fsf_shared_operation_t;
79
 
80
// Shared object
81
// the first field is the number of distinct operations on the 
82
//    shared object. It is initialized to 0.
83
// the second field is the id of the object, must be unique in the system.
84
// the third field is a list of shared operations.
85
 
86
 
87
 
88
 
89
typedef struct {
90
  int                          size; // = 0
91
  fsf_critical_section_data_t  section[FSF_MAX_N_CRITICAL_SECTIONS];
92
} fsf_critical_sections_t;
93
 
94
typedef struct {
95
  int                      size;      // = 0
96
  fsf_shared_obj_id_t      obj_id;    // object id
97
  fsf_shared_operation_t   shared_op[FSF_MAX_SHARED_OPERATION];
98
} fsf_shared_object_t;
99
 
100
typedef struct {
101
  int size; // =0
102
  fsf_shared_operation_t       operation[FSF_MAX_SHARED_OPERATION];
103
} fsf_shared_operations_t;
104
 
105
typedef int fsf_scheduler_id_t;
106
 
107
#define FSF_SCHEDULER_POSIX             0
108
#define FSF_SCHEDULER_EDF               1
109
#define FSF_SCHEDULER_RM                2
110
#define FSF_SCHEDULER_NONE              3
111
 
112
// Constants for assigning default values
113
#define FSF_DEFAULT_WORKLOAD            FSF_INDETERMINATE
114
#define FSF_DEFAULT_GRANULARITY         FSF_CONTINUOUS
115
#define FSF_DEFAULT_QUALITY             0
116
#define FSF_DEFAULT_IMPORTANCE          1
117
#define FSF_DEFAULT_D_EQUALS_T          TRUE
118
#define FSF_DEFAULT_DEADLINE            {0,0}
119
#define FSF_DEFAULT_SCHEDULER           FSF_SCHEDULER_NONE
120
 
121
// Constants for omitting the assignment of values to specific arguments
122
// in calls to initialization functions
123
#define FSF_NULL_CRITICAL_SECTIONS      (fsf_critical_sections_t *)NULL
124
#define FSF_NULL_UTILIZATION_SET        (fsf_utilization_set_t *)NULL
125
#define FSF_NULL_DEADLINE               (struct timespec *)NULL
126
#define FSF_NULL_SIGNAL                 0
127
 
128
 
129
// Error codes
130
#define FSF_ERR_NOT_INITIALIZED                 2003001
131
#define FSF_ERR_TOO_MANY_TASKS                  2003002
132
#define FSF_ERR_ALREADY_INITIALIZED             2003003
133
#define FSF_ERR_BAD_ARGUMENT                    2003004
134
#define FSF_ERR_INVALID_SYNCH_OBJECT_HANDLE     2003005
135
#define FSF_ERR_NO_RENEGOTIATION_REQUESTED      2003006
136
#define FSF_ERR_CONTRACT_REJECTED               2003007
137
#define FSF_ERR_TOO_MANY_SERVERS                2003008
138
#define FSF_ERR_CREATE_THREAD                   2003009
139
#define FSF_ERR_SERVER_USED                     2003010
140
#define FSF_ERR_INVALID_SERVER                  2003011
141
#define FSF_ERR_CREATE_SERVER                   2003012
142
 
143
//////////////////////////////////////////////////////////////
144
//                       CONTRACT PARAMETERS
145
//////////////////////////////////////////////////////////////
146
 
147
// Contract parameters type; it is an opaque type
148
typedef FSF_CONTRACT_PARAMETERS_T_OPAQUE fsf_contract_parameters_t;
149
 
150
int
151
fsf_initialize_contract(fsf_contract_parameters_t *contract);
152
 
153
//Description: The operation receives a pointer to a contract parameters
154
//object and initializes it, setting it to the default values.
155
//  budget_min                  => {0,0};                              
156
//  period_max                  => {0,0};                              
157
//  budget_max                  => {0,0};                              
158
//  period_min                  => {0,0};                              
159
//  workload                    => DEFAULT_WORKLOAD;                   
160
 
161
//  d_equals_t                  => DEFAULT_D_EQUALS_T; (false or true)
162
//  deadline                    => DEFAULT_DEADLINE;                     
163
//  budget_overrun_sig_notify   => 0;                  (signal number)
164
//  budget_overrun_sig_value    => {0, NULL};
165
//  deadline_miss_sig_notify    => 0;                  (signal number)
166
//  deadline_miss_sig_value     => {0, NULL};
167
//                                                         
168
//  granularity                 => DEFAULT_GRANULARITY;               
169
//  utilization_set;            => size = 0                         
170
//  quality                     => DEFAULT_QUALITY;     (range 0..100)
171
//  importance                  => DEFAULT_IMPORTANCE;    (range 1..5)
172
//                                                         
173
//  preemption_level            => 0;               (range 1..2**32-1)
174
//  critical_sections;          => size = 0                         
175
 
176
 
177
int
178
fsf_set_contract_basic_parameters
179
  (fsf_contract_parameters_t *contract,
180
   const struct timespec  *budget_min,
181
   const struct timespec  *period_max,
182
   const struct timespec  *budget_max,
183
   const struct timespec  *period_min,
184
   fsf_workload_t          workload);
185
 
186
//Description: The operation updates the specified contract parameters
187
//object by setting its budget, period, and workload to the specified
188
//input parameters. (Note: the workload is a basic parameter because
189
//bounded tasks are triggered by the scheduler (see the Timed Schedule
190
//Next Job operation, later), while indeterminate tasks are not;
191
//therefore, their programming model is quite different).
192
 
193
int
194
fsf_get_contract_basic_parameters
195
  (const fsf_contract_parameters_t *contract,
196
   struct timespec  *budget_min,
197
   struct timespec  *period_max,
198
   struct timespec  *budget_max,
199
   struct timespec  *period_min,
200
   fsf_workload_t   *workload);
201
 
202
//Description: This operation obtains from the specified contract parameters
203
//object its budget, period, and workload, and copies them to the places
204
//pointed to by the corresponding input parameters.
205
 
206
int
207
fsf_set_contract_timing_requirements
208
  (fsf_contract_parameters_t *contract,
209
   bool                   d_equals_t,
210
   const struct timespec *deadline,
211
   int                    budget_overrun_sig_notify,
212
   union sigval           budget_overrun_sig_value,
213
   int                    deadline_miss_sig_notify,
214
   union sigval           deadline_miss_sig_value);
215
 
216
//Description: The operation updates the specified contract parameters
217
//object. d_equals_t is used as a boolean, deadline must be
218
//NULL_DEADLINE if d_equals_t is true, budget_overrun_sig_notify or
219
//deadline_miss_sig_notify may be NULL_SIGNAL (no notification) or any
220
//posix signal. budget_overrun_sig_value and deadline_miss_sig_value
221
//are the values to be delivered with the signal.
222
 
223
int
224
fsf_get_contract_timing_requirements
225
  (const fsf_contract_parameters_t *contract,
226
   bool                            *d_equals_t,
227
   struct timespec                 *deadline,
228
   int                             *budget_overrun_sig_notify,
229
   union sigval                    *budget_overrun_sig_value,
230
   int                             *deadline_miss_sig_notify,
231
   union sigval                    *deadline_miss_sig_value);
232
 
233
//Description: The operation obtains the corresponding input
234
//parameters from the specified contract parameters object. If
235
//d_equals_t is true, the deadline will not be updated.
236
 
237
int  
238
fsf_set_contract_reclamation_parameters
239
  (fsf_contract_parameters_t *contract,
240
   fsf_granularity_t            granularity,
241
   const fsf_utilization_set_t *utilization_set,
242
   int                          quality,
243
   int                          importance);
244
 
245
//Description: The operation updates the specified contract parameters
246
//object by setting its granularity, utilization set, quality, and
247
//importance to the specified input parameters.
248
 
249
int  
250
fsf_get_contract_reclamation_parameters
251
  (const fsf_contract_parameters_t *contract,
252
   fsf_granularity_t               *granularity,
253
   fsf_utilization_set_t           *utilization_set,
254
   int                             *quality,
255
   int                             *importance);
256
 
257
//Description: The operation obtains from the specified contract parameters
258
//object its granularity, utilization set, quality, and importance. Then
259
//copies them to the places pointed to by the specified input parameters.
260
//Only the utilization_values of the utilization_set that are in use, are
261
//copied (according to its size field). 
262
 
263
 
264
/* OLD VERSION
265
int
266
fsf_set_contract_synchronization_parameters
267
  (fsf_contract_parameters_t     *contract,
268
   fsf_preemption_level_t         preemption_level,
269
   const fsf_critical_sections_t *critical_sections);
270
 
271
//Description: The operation updates the specified contract parameters
272
//object by setting its preemption level and critical sections to the
273
//specified input parameters.
274
 
275
*/
276
 
277
int
278
fsf_get_contract_synchronization_parameters
279
  (const fsf_contract_parameters_t *contract,
280
   fsf_preemption_level_t          *preemption_level,
281
   fsf_critical_sections_t         *critical_sections);
282
 
283
//Description: The operation obtains from the specified contract
284
//parameters object its preemption level and critical sections, and
285
//copies them to the places pointed to by the specified input
286
//parameters.  Only those critical_section_data records that are in use
287
//in the critical_sections structure are copied (according to its size
288
//field).
289
 
290
int
291
fsf_set_local_scheduler_parameter
292
  (fsf_contract_parameters_t *contract,
293
   fsf_scheduler_id_t local_scheduler_id);
294
 
295
//Description: Set the local scheduler
296
 
297
int
298
fsf_get_local_scheduler_parameter
299
  (const fsf_contract_parameters_t *contract,
300
   fsf_scheduler_id_t *local_scheduler_id);
301
 
302
//Description: Get the local scheduler
303
 
304
//////////////////////////////////////////////////////////////
305
//                 SYNCHRONIZATION OBJECTS
306
//////////////////////////////////////////////////////////////
307
 
308
//An abstract synchronization object is defined by the application.
309
//This object can be used by an application to wait for an event to
310
//arrive by invoking the Event Triggered Schedule Next Job operation.
311
//It can also be used to signal the event either causing a waiting
312
//server to wake up, or the event to be queued if no server is waiting
313
//for it.  It is defined by the following opaque type and has the
314
//following operations:
315
 
316
typedef FSF_SYNCH_OBJECT_HANDLE_T_OPAQUE fsf_synch_object_handle_t;
317
 
318
int
319
fsf_create_synchobject(fsf_synch_object_handle_t *synch_handle);
320
 
321
//Description: This operation creates and initializes a
322
//synchronization object variable managed by the scheduler, and
323
//returns a handle to it in the variable pointed to by synch_handle.
324
 
325
int
326
fsf_signal_synchobject(fsf_synch_object_handle_t *synch_handle);
327
 
328
//Description: If one or more servers are waiting upon the specified
329
//synchronization object one of them is awakened; if not, the event is
330
//queued at the synchronization object.
331
 
332
int
333
fsf_destroy_synchobject(fsf_synch_object_handle_t *synch_handle);
334
 
335
//This operation destroys the synchronization object (created by a
336
//previous call to fsf_create_synchobject) that is referenced by the
337
//synch_handle variable. After calling this operation, the
338
//synch_handle variable can not be used until it is initialized again
339
//by a call to fsf_create_synchobject.
340
 
341
 
342
///////////////////////////////////////////////////////////////
343
//                 CONTRACT NEGOCIATION OPERATIONS
344
///////////////////////////////////////////////////////////////
345
 
346
// Server Id type, that identifies a server created to manage a 
347
// given contract
348
 
349
typedef int      fsf_server_id_t;
350
 
351
 
352
typedef struct {
353
        fsf_server_id_t  server;
354
        TIME             actual_period;
355
        TIME             actual_budget;
356
        int              Qs;    // quality of service
357
        int              Is;    // importance of service
358
        bandwidth_t      U;     // actual bandwidth
359
        bandwidth_t      Umin;  // min bandwidth
360
        bandwidth_t      Umax;  // max bandwidth
361
        TIME             Cmin;  
362
        TIME             Tmin;
363
        TIME             Tmax;
364
        TIME             deadline;
365
        bool             d_equals_t;
366
} server_elem;
367
 
368
int recalculate_contract(bandwidth_t U);
369
 
370
 
371
// The following type references a function that may become 
372
// a thread's code
373
 
374
typedef void * (*fsf_thread_code_t) (void *);
375
 
376
// Negotiate contract functions: The following functions are used to
377
// create servers for a contract parameters specification and also to
378
// assign one or more threads to a server (Note: the current
379
// implementation only supports one thread per server; this limitation
380
// will be removed in the next phase of the project)
381
 
382
// The first time that any of these operations is called, it creates
383
// all the internal management structures that are necessary for the
384
// FIRST Scheduling Framework to operate properly.
385
 
386
int
387
fsf_negotiate_contract
388
  (const fsf_contract_parameters_t *contract,
389
   fsf_server_id_t      *server);
390
 
391
//Description: The operation negotiates a contract for a new
392
//server. If the on-line admission test is enabled it determines
393
//whether the contract can be admitted or not based on the current
394
//contracts established in the system. Then it creates the server and
395
//recalculates all necessary parameters for the contracts already
396
//present in the system. This is a potentially blocking operation; it
397
//returns when the system has either rejected the contract, or
398
//admitted it and made it effective. It returns zero and places the
399
//server identification number in the location pointed to by the
400
//server input parameter if accepted, or an error if rejected.  No
401
//thread is bound to the newly created server, which will be idle
402
//until a thread is bound to it. This operation can only be executed
403
//by threads that are already bound to an active server and therefore
404
//are being scheduled by the fsf scheduler.
405
 
406
int
407
fsf_create_thread
408
  (fsf_server_id_t    server,
409
   pthread_t         *thread,
410
   pthread_attr_t    *attr,
411
   fsf_thread_code_t  thread_code,
412
   void              *arg,
413
   void              *local_scheduler_arg);
414
 
415
//Description: This operation creates a new thread inside a specific
416
//server. The local_scheduler_arg parameter is used to pass specific
417
//parameters to local scheduler. These parameters are application
418
//depented.
419
 
420
int
421
fsf_get_server
422
  (fsf_server_id_t *server,
423
   pthread_t       thread);
424
 
425
//Description: This operation returns the server associated with a
426
//thread. It returns an error if the thread does not exist, it is not 
427
//under the control of the scheduling framework, or is not bound.
428
 
429
int
430
fsf_cancel_contract (fsf_server_id_t *server);
431
 
432
//Description: The operation eliminates the specified server and
433
//recalculates all necessary parameters for the contracts remaining in 
434
//the system. This is a potentially blocking operation; it returns when 
435
//the system has made the changes effective.
436
 
437
int
438
fsf_renegotiate_contract
439
  (const fsf_contract_parameters_t *new_contract,
440
   fsf_server_id_t server);
441
 
442
//Description: The operation renegotiates a contract for an existing
443
//server. If the on-line admission test is enabled it determines
444
//whether the contract can be admitted or not based on the current
445
//contracts established in the system. If it cannot be admitted, the
446
//old contract remains in effect and an error is returned. If it can
447
//be admitted, it recalculates all necessary parameters for the
448
//contracts already present in the system anr returns zero. This is a
449
//potentially blocking operation; it returns when the system has
450
//either rejected the new contract, or admitted it and made it
451
//effective.
452
 
453
int
454
fsf_request_contract_renegotiation
455
  (const fsf_contract_parameters_t *new_contract,
456
   fsf_server_id_t                  server,
457
   int                              sig_notify,
458
   union sigval                     sig_value);
459
 
460
//Description: The operation enqueues a renegotiate operation for an
461
//existing server, and returns immediately. The renegotiate operation
462
//is performed asynchronously, as soon as it is practical; meanwhile
463
//the system operation will continue normally. When the renegotiation
464
//is made, if the on-line admission test is enabled it determines
465
//whether the contract can be admitted or not based on the current
466
//contracts established in the system. If it cannot be admitted, the
467
//old contract remains in effect. If it can be admitted, it
468
//recalculates all necessary parameters for the contracts already
469
//present in the system. When the operation is completed, notification
470
//is made to the caller, if requested, via a signal. The status of the
471
//operation (in progress, admitted, rejected) can be checked with the
472
//get_renegotiation_status operation.  The argument sig_notify can be
473
//NULL_SIGNAL (no notification), or any posix signal; and in this case
474
//sig_value is to be sent with the signal.
475
 
476
typedef enum {FSF_IN_PROGRESS,
477
              FSF_REJECTED,
478
              FSF_ADMITTED} fsf_renegotiation_status_t;
479
 
480
int
481
fsf_get_renegotiation_status
482
  (fsf_server_id_t server,
483
   fsf_renegotiation_status_t *renegotiation_status);
484
 
485
//Description: The operation reports on the status of the last
486
//renegotiation operation enqueued for the specified server. It is 
487
//callable even after notification of the completion of such operation,
488
//if requested.
489
 
490
int
491
fsf_request_change_quality_and_importance
492
  (fsf_server_id_t server,
493
   int new_importance,
494
   int new_quality);
495
 
496
//Description: The operation enqueues a request to change the quality and 
497
//importance parameters of the specified server, and returns immediately.
498
//The change operation is performed as soon as it is practical;
499
//meanwhile the system operation will continue normally.
500
 
501
 
502
////////////////////////////////////////////////////////////
503
//                  SCHEDULING BOUNDED WORKLOADS
504
////////////////////////////////////////////////////////////
505
 
506
int
507
fsf_schedule_next_timed_job
508
  (const struct timespec *at_absolute_time,
509
   struct timespec       *next_budget,
510
   struct timespec       *next_period,
511
   bool                  *was_deadline_missed,
512
   bool                  *was_budget_overran);
513
 
514
//Description: This operation is invoked by threads associated with
515
//bounded workload servers to indicate that a job has been completed
516
//(and that the scheduler may reassign the unused capacity of the
517
//current job to other servers), and also when the first job require
518
//to be scheduled. The system will activate the job at the specified 
519
//absolute time, and will then use the scheduling rules to determine 
520
//when the job can run, at which time the call returns. Upon return, 
521
//the system reports the current period and budget for the current
522
//job, whether the deadline of the previous job was missed or not, 
523
//and whether the budget of the previous job was overrun or not.
524
 
525
 
526
int
527
fsf_schedule_next_event_triggered_job
528
  (fsf_synch_object_handle_t *synch_handle,
529
   struct timespec           *next_budget,
530
   struct timespec           *next_period,
531
   bool                      *was_deadline_missed,
532
   bool                      *was_budget_overran);
533
 
534
//Description: This operation is invoked by threads associated with
535
//bounded workload servers to indicate that a job has been completed
536
//(and that the scheduler may reassign the unused capacity of the
537
//current job to other servers), and also when the first job require
538
//to be scheduled. If the specified synchronization object has events 
539
//queued, one of them is dequeued; otherwise the server will wait upon 
540
//the specified synchronization object until it is signalled. Then, the 
541
//system will use the scheduling rules to determine when the job can run 
542
//and the call will return at that time. Upon return, the system reports
543
//the current period and budget for the current job, whether the deadline
544
//of the previous job was missed or not, and whether the budget of the
545
//previous job was overrun or not.
546
 
547
 
548
//////////////////////////////////////////////////////////////
549
//           OBTAINING INFORMATION FROM THE SCHEDULER
550
//////////////////////////////////////////////////////////////
551
 
552
int
553
fsf_get_available_capacity (fsf_server_id_t server, float *capacity);
554
 
555
//Description: This operation returns the current spare capacity (in 
556
//percentage of processor or network utilization), currently assigned 
557
//to the importance level of the specified server.
558
 
559
int
560
fsf_get_total_quality (fsf_server_id_t server, int *total_quality);
561
 
562
//Description: This operation returns the sum of the quality parameters 
563
//for all servers in the system of importance level equal to that of 
564
//the specified server.
565
 
566
int
567
fsf_is_admission_test_enabled();
568
 
569
//Description: Returns true if the system is configured with the 
570
//on-line admission test enabled, or false otherwise.
571
 
572
 
573
// Mutex function
574
 
575
// Initialization
576
// here we initialize the second and third field of the structure
577
void fsf_init_shared_op(fsf_shared_operation_t     *op,
578
                        fsf_shared_op_id_t  op_id,
579
                        struct timespec     wcet);
580
 
581
// initialization
582
// The shared object id is set equal to the second parameter.
583
int fsf_init_shared_object(fsf_shared_object_t *obj,
584
                            fsf_shared_obj_id_t id);
585
 
586
// Declare an operation
587
// This function is used to declare that a shared object has 
588
//    a synchronized operation on it. 
589
// It checks if another operation with the same id has already been 
590
//    declared; if so, return false (-1).
591
// The obj_id field of the operation is set equal to the shared object id.
592
// the structure op is copied in the first free element in the array 
593
//    shared_op pof the structure obj. If there are no more free element, 
594
//    returns -1.
595
// Returns 0 if the operation has been completed, -1 otherwise.
596
 
597
int fsf_declare_shared_object_operation(fsf_shared_object_t *obj,
598
                                        fsf_shared_operation_t *op);
599
 
600
 
601
int fsf_lock_object(fsf_shared_operation_t *op);
602
 
603
int fsf_unlock_object(fsf_shared_operation_t *op);
604
 
605
// set contract parameters
606
// specify a list of operations for each contract
607
// the list is specified as a pointer to an array.
608
// the size of the array is specified as third parameter
609
// returns 0 if all operations are correctly initialized
610
// returns -1 otherwise.
611
 
612
int fsf_set_contract_synchronization_parameters(
613
    fsf_contract_parameters_t *contract,
614
    const fsf_shared_operation_t *shared_ops,
615
    size_t op_num);
616
 
617
 
618
 
619
#endif // _FSF_CONTRACT_H_