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
 
983 lipari 19
/**
20
   @file This file contains the functions and definitions for the core
21
   module.
22
 
23
   The file contains all fuinctions and data structures for the core
24
   module of the FSF.
25
 */
26
 
881 trimarchi 27
//fsf_core.h
28
//=================================================================
29
//       FFFFFFIII   RRRRR      SSTTTTTTT
30
//      FF         IIR   RR    SS
31
//     FF           IR        SS
32
//    FFFFFF         RRRR    SSSSST
33
//   FF       FI       RRR  SS
34
//  FF         II     RRR  SS
35
// FF           IIIIIR    RS
36
//
37
// Basic FSF(FIRST Scheduling Framework) contract management
38
//================================================================
39
 
929 lipari 40
 
881 trimarchi 41
#include <time.h>
42
#include <pthread.h>
43
#include <sys/types.h>
983 lipari 44
#include <stdbool.h>  
881 trimarchi 45
 
46
#include "fsf_configuration_parameters.h"
47
#include "fsf_opaque_types.h"
48
#include "fsf_basic_types.h"
49
 
50
#ifndef _FSF_CORE_H_
51
#define _FSF_CORE_H_
52
 
53
 
983 lipari 54
//////////////////////////////////////////////////////////////////////
55
//           INITIALIZATION SERVICES 
56
//////////////////////////////////////////////////////////////////////
881 trimarchi 57
 
993 lipari 58
/**
59
   \ingroup coremodule
881 trimarchi 60
 
983 lipari 61
   We cannot call any fsf functions before fsf_init. After calling
62
   fsf_init, the main will be executing in the background. Then, it
63
   can do the negotiations, create the threads and, if needed,
64
   activate them via some user-specified synchronization mechanism. It
65
   may also create a contract for itself. The second time this
66
   function is called it fails.
67
 
68
   @retval 0 if the system is initialized
69
   @retval FSF_ERR_SYSTEM_ALREADY_INITIALIZED if the function has already
70
           been called before
71
 
72
   @retval others It may also return any of the errors that may be
73
         returned by the underlying operating system primitives
74
         required to perform the FSF system start up
75
*/
76
int fsf_init();
77
 
881 trimarchi 78
/**
993 lipari 79
   \ingroup coremodule
80
 
881 trimarchi 81
   This function converts an error code to an error message that is
82
   stored in the buffer starting at the location pointed to by
83
   message. The size of this buffer is specified by the size
84
   argument. If the error message is longer than size-1, it is
85
   truncated to that length. Regardless of whether the message is
86
   truncated or not, a final zero character that marks the end of the
87
   string is stored in the buffer.  The function fails if the error
88
   code passed does not correspond to any of the fsf error codes.
983 lipari 89
 
90
   @retval FSF_ERR_BAD_ARGUMENT  error is not a valid value
881 trimarchi 91
*/
92
int fsf_strerror (int error, char *message, size_t size);
93
 
983 lipari 94
 
881 trimarchi 95
/////////////////////////////////////////////////////////////
96
//                       CONTRACT PARAMETERS
97
/////////////////////////////////////////////////////////////
98
 
993 lipari 99
/**
983 lipari 100
   \ingroup coremodule
881 trimarchi 101
 
102
    The operation receives a pointer to a contract parameters object
103
    and initializes it, setting it to the default values.
104
    The default values are:
983 lipari 105
    - budget min and max are set to 0;
106
    - period min and max are set to 0;
107
    - the workload is unbounded (FSF_INDETERMINATE);
108
    - the server deadline is equal to the period;
109
    - the budget and deadline overrun are not notified;
985 julio 110
    - the granularity is set to "continuous" (FSF_CONTINUOUS);
983 lipari 111
    - the quality and importance are set to the default values;
112
    - the scheduling policy is FSF_NONE.
881 trimarchi 113
 
114
    @param     contract the pointer to the contract variable.
983 lipari 115
    @retval   FSF_ERR_BAD_ARGUMENT   contract is NULL
881 trimarchi 116
*/
117
int fsf_initialize_contract (fsf_contract_parameters_t *contract);
118
 
119
//  budget_min                => {0,0};
120
//  period_max                => {0,0};
121
//  budget_max                => {0,0};
122
//  period_min                => {0,0};
123
//  workload                  => DEFAULT_WORKLOAD;
124
 
125
//  d_equals_t                => DEFAULT_D_EQUALS_T; (false or true)
126
//  deadline                  => DEFAULT_DEADLINE;
127
//  budget_overrun_sig_notify => 0;  (signal number)
128
//  budget_overrun_sig_value  => {0, NULL};
129
//  deadline_miss_sig_notify  => 0;  (signal number)
130
//  deadline_miss_sig_value   => {0, NULL};
131
//
132
//  granularity               => DEFAULT_GRANULARITY;
133
//  utilization_set;          => size = 0
985 julio 134
//  quality                   => DEFAULT_QUALITY; (0, range 0..2**32-1)
135
//  importance                => DEFAULT_IMPORTANCE; (1, range 1..5)
881 trimarchi 136
//
137
//  preemption_level          => 0; (range 1..2**32-1)
138
//  critical_sections;        => size = 0
139
 
140
//  sched_policy              => DEFAULT_SCHED_POLICY
141
//                              (FSF_NONE)
985 julio 142
 
143
//  network_id                => FSF_NULL_NETWORK_ID;
144
//                               (0)
145
//  granted_capacity_flag     => false;
881 trimarchi 146
 
147
/**
993 lipari 148
   \ingroup coremodule
149
 
881 trimarchi 150
   The operation updates the specified contract parameters object by
151
   setting its budget, period, and workload to the specified input
152
   parameters. (Note: the workload is a basic parameter because
153
   bounded tasks are triggered by the scheduler (see the
154
   fsf_schedule_timed_job() operation), while indeterminate tasks are
155
   not; therefore, their programming model is quite different).
156
 
983 lipari 157
   @param contract          the pointer to the contract object
881 trimarchi 158
   @param [in] budget_min   the minimum budget for the contract
159
   @param [in] period_max   the maximum period for the contract
983 lipari 160
   @param [in] workload     the kind of workload (can be FSF_BOUNDED or
161
                            FSF_INDETERMINATE)
881 trimarchi 162
 
983 lipari 163
   @retval 0 if the operation is succesful
164
   @retval FSF_ERR_BAD_ARGUMENT if any of the pointers is NULL
881 trimarchi 165
       or if only one of the timespec values is 0, and also if the workload
985 julio 166
       is not a proper value (FSF_INDETERMINATE, FSF_BOUNDED or FSF_OVERHEAD)
881 trimarchi 167
*/
168
int
169
fsf_set_contract_basic_parameters
170
  (fsf_contract_parameters_t *contract,
171
   const struct timespec     *budget_min,
172
   const struct timespec     *period_max,
173
   fsf_workload_t            workload);
174
 
175
/**
993 lipari 176
   \ingroup coremodule
177
 
881 trimarchi 178
   This operation obtains from the specified contract parameters
179
   object its budget, period, and workload, and copies them to the
180
   places pointed to by the corresponding input parameters.
181
 
182
   @param [in] contract   the pointer to the contract object
183
   @param[out] budget_min pointer to the variable that will contain
184
   the minimum budget
185
   @param[out] period_max pointer to the variable that will contain the
186
   max_period
187
   @param[out] workload pointer to the variable that will contain the
188
   workload type
189
 
983 lipari 190
   @retval  FSF_ERR_BAD_ARGUMENT :  if contract is NULL
881 trimarchi 191
*/
192
int
193
fsf_get_contract_basic_parameters
194
  (const fsf_contract_parameters_t *contract,
195
   struct timespec  *budget_min,
196
   struct timespec  *period_max,
197
   fsf_workload_t   *workload);
198
 
199
 
200
/**
993 lipari 201
   \ingroup coremodule
202
 
881 trimarchi 203
   The operation updates the specified contract parameters
204
   object, specifying the additional parameters requirements of
205
   a contract.
206
 
207
   @param  contract The pointer to the contract object
208
 
209
   @param [in] d_equals_t It is a boolean value, set to true (1) if the
210
                 we want to specify a deadline different from the period
211
                 for the contract.
212
   @param [in] deadline If the previous parameter is set to true,
213
                 this parameter should be set to NULL_DEADLINE. Otherwise,
214
                 it contains the desired deadline value.
983 lipari 215
 
881 trimarchi 216
   @param [in] budget_overrun_sig_notify contains the number of posix signal
217
                 that must be raised if the budget of the server is overrun.
218
                 If the value of this parameter is NULL_SIGNAL, no signal will
219
                 be raised.
220
   @param [in] budget_overrun_sig_value contains the value that will be
221
                 passed to the signal "catcher" when the signal is raised.
222
                 This parameters is not used if the budget_overrun_sig_notify
223
                 parameters is set to NULL_SIGNAL.
224
   @param [in] deadline_miss_sig_notify contains the number of posix
225
                 signal that must be raised if the deadline of the server
226
                 is missed. If the value of this parameter is NULL_SIGNAL,
227
                 no signal is raised.
228
   @param [in] deadline_miss_sig_value contains the value that will be
229
                 passed to the signal "catcher" when the signal is raised.
230
                 This parameters is not used if the budget_overrun_sig_notify
231
                 parameters is set to NULL_SIGNAL
232
 
983 lipari 233
   @retval 0    if the operation is succesful
234
   @retval FSF_BAD_ARGUMENT if contract is NULL or  
881 trimarchi 235
       (d_equals_t is true and  deadline is not FSF_NULL_DEADLINE) or
236
       (budget_overrun_sig_notify is not a valid signal)  or
237
       (deadline_miss_sig_notify is not a valid signal)  or
238
       (d_equals_t is false but (deadline is FSF_NULL_DEADLINE or its value
983 lipari 239
                                 is grater than the contracts maximum period))
881 trimarchi 240
 
241
   @see sigexplanation
242
*/
243
int
244
fsf_set_contract_timing_requirements
245
  (fsf_contract_parameters_t *contract,
246
   bool                   d_equals_t,
247
   const struct timespec *deadline,
248
   int                    budget_overrun_sig_notify,
249
   union sigval           budget_overrun_sig_value,
250
   int                    deadline_miss_sig_notify,
251
   union sigval           deadline_miss_sig_value);
252
 
253
/**
993 lipari 254
   \ingroup coremodule
255
 
881 trimarchi 256
   The operation obtains the corresponding input parameters from the
257
   specified contract parameters object. If d_equals_t is true, the
258
   deadline will not be updated.
259
 
983 lipari 260
   @retval FSF_ERR_BAD_ARGUMENT if contract is NULL
261
 
262
   @see fsf_set_contract_timing_requirements
881 trimarchi 263
*/
264
int
265
fsf_get_contract_timing_requirements
266
  (const fsf_contract_parameters_t *contract,
267
   bool                    *d_equals_t,
268
   struct timespec         *deadline,
269
   int                     *budget_overrun_sig_notify,
270
   union sigval            *budget_overrun_sig_value,
271
   int                     *deadline_miss_sig_notify,
272
   union sigval            *deadline_miss_sig_value);
273
 
274
//////////////////////////////////////////////////////////////////
275
//                 SYNCHRONIZATION OBJECTS
276
//////////////////////////////////////////////////////////////////
277
 
278
 
279
/**
983 lipari 280
   \ingroup coremodule
281
 
881 trimarchi 282
   This operation creates and initializes a synchronization object
283
   variable managed by the scheduler, and returns a handle to it in
284
   the variable pointed to by synch_handle.
285
 
983 lipari 286
   @param[out] synch_handle pointer to the variable that will contain
287
                the handle to the newly created synchronization object
881 trimarchi 288
 
983 lipari 289
   @retval  0 if the operation is succesful
290
   @retval  FSF_ERR_BAD_ARGUMENT   if synch_handle is 0
291
   @retval  FSF_ERR_TOO_MANY_SYNCH_OBJS  if the number of synchronization
292
             objects in the system has already exceeded the maximum
293
   @retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD  if the calling thread is not
294
            scheduled under the FSF
295
   @retval  FSF_ERR_INVALID_SCHEDULER_REPLY  the scheduler is wrong
296
             or not running
881 trimarchi 297
*/
298
int
299
fsf_create_synch_obj
300
    (fsf_synch_obj_handle_t *synch_handle);
301
 
983 lipari 302
/**
993 lipari 303
   \ingroup coremodule
974 trimarchi 304
 
881 trimarchi 305
   This function sends a notification to the synchronization object
983 lipari 306
   specified as parameter. If there is at least one server waiting on
307
   the synchronization object, the corresponding thread is unblocked,
308
   and the server rules for budget recharging apply.
881 trimarchi 309
 
983 lipari 310
   If more than one server is waiting, just one of them is woken.
311
   However, which one is woken is implementation dependent.
312
 
313
   If no thread is waiting on the synchronization object, the
314
   notification is queued.
315
 
881 trimarchi 316
   @param [in] synch_handle the handle of the synchronization object to
317
                  notify.
318
 
983 lipari 319
   @retval 0 if the operation is completed succesfully
320
   @retval FSF_ERR_BAD_ARGUMENT   if synch_handle is 0
321
   @retval FSF_ERR_INVALID_SYNCH_OBJ_HANDLE if the handle is not valid
322
   @retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD  if the calling thread
323
              is not scheduled under the FSF
324
   @retval FSF_ERR_INVALID_SCHEDULER_REPLY  the scheduler is wrong or
325
              not running
326
   @retval FSF_ERR_TOO_MANY_EVENTS_IN_SYNCH_OBJ  if the number of
327
              events stored in the synchronization object reaches the
328
              maximum defined in the configuration parameter header file
881 trimarchi 329
 
983 lipari 330
   @see fsf_schedule_triggered_job, fsf_timed_schedule_triggered_job
881 trimarchi 331
*/
332
int
333
fsf_signal_synch_obj
334
    (fsf_synch_obj_handle_t synch_handle);
335
 
336
/**
993 lipari 337
   \ingroup coremodule
338
 
881 trimarchi 339
   This operation destroys the synchronization object (created by a
340
   previous call to fsf_create_synch_obj) that is referenced by the
341
   synch_handle variable. After calling this operation, the
342
   synch_handle variable can not be used until it is initialized again
343
   by a call to fsf_create_synch_obj.
344
 
345
   @param synch_handle the handle to the synchronization object
346
             to be destroyed
347
 
983 lipari 348
   @retval 0 if the operation is succesful
349
   @retval FSF_ERR_INVALID_SYNCH_OBJ_HANDLE is the handle is not valid
350
   @retval FSF_ERR_BAD_ARGUMENT   if synch_handle is 0
351
   @retval FSF_ERR_INVALID_SYNCH_OBJ_HANDLE if the handle is not valid
352
   @retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD if the calling thread is not
881 trimarchi 353
       scheduled under the FSF
983 lipari 354
   @retval FSF_ERR_INVALID_SCHEDULER_REPLY  the scheduler is wrong or
355
       not running
881 trimarchi 356
 
983 lipari 357
   @see fsf_create_synch_obj
881 trimarchi 358
*/
359
int
360
fsf_destroy_synch_obj
361
    (fsf_synch_obj_handle_t synch_handle);
362
 
363
 
364
////////////////////////////////////////////////////
365
//           SCHEDULING BOUNDED WORKLOADS
366
////////////////////////////////////////////////////
367
 
368
/**
993 lipari 369
   \ingroup coremodule
370
 
881 trimarchi 371
   This operation is invoked by threads associated with bounded
372
   workload servers to indicate that a job has been completed (and
373
   that the scheduler may reassign the unused capacity of the current
374
   job to other servers). It is also invoked when the first job of
983 lipari 375
   such threads has to be scheduled.
881 trimarchi 376
 
377
   As an effect, the system will make the current server's budget zero
378
   for the remainder of the server's period, and will not replenish
379
   the budget until the specified absolute time.  At that time, all
380
   pending budget replenishments (if any) are made effective. Once the
381
   server has a positive budget and the scheduler schedules the
382
   calling thread again, the call returns and at that time, except for
383
   those parameters equal to NULL pointers, the system reports the
384
   current period and budget for the current job, whether the deadline
385
   of the previous job was missed or not, and whether the budget of
386
   the previous job was overrun or not.
387
 
388
   In a system with hierarchical scheduling, since this call makes the
389
   budget zero, the other threads in the same server are not run. As
993 lipari 390
   mentioned above, only when the call finishes the budget may be
881 trimarchi 391
   replenished.
392
 
393
   @param [in] abs_time     absolute time at which the budget will be
394
                            replenished
395
 
396
   @param [out] next_budget upon return of this function, the variable
397
                            pointed by this function will be equal to
398
                            the current server budget. If this parameter is
399
                            set to NULL, no action is taken.
400
 
401
   @param [out] next_period upon return of this function, the variable
402
                            pointed by this function will be equal to
403
                            the current server period. If this parameter is
404
                            set to NULL, no action is taken.
405
 
406
   @param [out] was_deadline_missed upon return of this function, the
407
                            variable pointed by this function will be
408
                            equal to true if the previous server deadline
409
                            was missed, to false otherwise. If this
410
                            parameter is set to NULL, no action is
411
                            taken.
412
 
983 lipari 413
   @param [out] was_budget_overran upon return of this function, the
881 trimarchi 414
                            variable pointed by this function will be
415
                            equal to true if the previous server budget was
416
                            overrun, to false otherwise. If this
417
                            parameter is set to NULL, no action is
418
                            taken.
419
 
983 lipari 420
   @retval 0 if the operation is succesful
421
   @retval FSF_ERR_INVALID_SCHEDULER_REPLY  the scheduler is wrong or
422
              not running
423
   @retval FSF_ERR_INTERNAL_ERROR  erroneous binding or malfunction of the FSF
881 trimarchi 424
       main scheduler
983 lipari 425
   @retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD if the calling thread is
426
       not scheduled under the FSF
985 julio 427
   @retval FSF_ERR_NOT_BOUND if the calling thread does not have a valid
881 trimarchi 428
       server bound to it
985 julio 429
   @retval FSF_ERR_BAD_ARGUMENT  if abs_time is NULL
430
   @retval FSF_ERR_SERVER_WORKLOAD_NOT_COMPATIBLE  if the kind of workload of
431
       the server is not FSF_BOUNDED
881 trimarchi 432
 
985 julio 433
 
881 trimarchi 434
   @sa fsf_schedule_triggered_job, fsf_timed_schedule_triggered_job
435
*/
436
int
437
fsf_schedule_timed_job
438
  (const struct timespec *abs_time,
439
   struct timespec       *next_budget,
440
   struct timespec       *next_period,
441
   bool                  *was_deadline_missed,
442
   bool                  *was_budget_overran);
443
 
444
/**
993 lipari 445
   \ingroup coremodule
446
 
881 trimarchi 447
   This operation is invoked by threads associated with bounded
448
   workload servers to indicate that a job has been completed (and
449
   that the scheduler may reassign the unused capacity of the current
450
   job to other servers). It is also invoked when the first job of
451
   such threads has to be scheduled. If the specified synchronization
452
   object has events queued, one of them is dequeued; otherwise the
453
   server will wait upon the specified synchronization object, the
454
   server's budget will be made zero for the remainder of the server's
455
   period, and the implementation will not replenish the budget until
983 lipari 456
   the specified synchronization object is signalled.
881 trimarchi 457
 
983 lipari 458
   At that time, all pending budget replenishments (if any) are made
459
   effective. Once the server has a positive budget and the scheduler
460
   schedules the calling thread again, the call returns and at that
461
   time, except for those parameters equal to NULL pointers, the
462
   system reports the current period and budget for the current job,
463
   whether the deadline of the previous job was missed or not, and
464
   whether the budget of the previous job was overrun or not.
465
 
881 trimarchi 466
   In a system with hierarchical scheduling, since this call makes the
467
   budget zero, the other threads in the same server are not run. As
468
   mentioned above, only when the call finishes the budget may be
469
   replenished.
470
 
983 lipari 471
   @param [in]  synch_handle   handle of the synchronization object
881 trimarchi 472
 
983 lipari 473
   @param [out] next_budget    upon return of this function, the variable
474
                               pointed by this function will be equal
475
                               to the current server budget. If this
476
                               parameter is set to NULL, no action is
477
                               taken.
478
   @param [out] next_period    upon return of this function, the variable
479
                               pointed by this function will be equal to
480
                               the current server period. If this parameter is
481
                               set to NULL, no action is taken.
881 trimarchi 482
 
983 lipari 483
   @param [out] was_deadline_missed upon return of this function, the
484
                            variable pointed by this function will be
485
                            equal to true if the previous server deadline
486
                            was missed, to false otherwise. If this
487
                            parameter is set to NULL, no action is
488
                            taken.
489
 
490
   @param [out] was_budget_overran upon return of this function, the
491
                            variable pointed by this function will be
492
                            equal to true if the previous server budget was
493
                            overrun, to false otherwise. If this
494
                            parameter is set to NULL, no action is
495
                            taken.
496
 
497
   @retval 0 if the operation is succesful
985 julio 498
   @retval  FSF_ERR_INVALID_SYNCH_OBJ_HANDLE if the synch_handle is not valid
499
   @retval  FSF_ERR_BAD_ARGUMENT   if synch_handle is 0
983 lipari 500
   @retval  FSF_ERR_INVALID_SCHEDULER_REPLY  the scheduler is wrong or not
501
            running
502
   @retval  FSF_ERR_INTERNAL_ERROR  erroneous binding or malfunction of
503
            the FSF main scheduler
504
   @retval  FSF_ERR_NOT_SCHEDULED_CALLING_THREAD if the calling thread
505
            is not scheduled under the FSF
985 julio 506
   @retval  FSF_ERR_NOT_BOUND if the calling thread does not have
983 lipari 507
            a valid server bound to it
985 julio 508
   @retval  FSF_ERR_SERVER_WORKLOAD_NOT_COMPATIBLE: if the kind of workload
509
            of the server is not FSF_BOUNDED
983 lipari 510
 
511
   @sa fsf_schedule_triggered_job, fsf_schedule_timed_job
512
 
881 trimarchi 513
*/
514
int
515
fsf_schedule_triggered_job
516
  (fsf_synch_obj_handle_t  synch_handle,
517
   struct timespec         *next_budget,
518
   struct timespec         *next_period,
519
   bool                    *was_deadline_missed,
520
   bool                    *was_budget_overran);
521
 
522
 
523
/**
993 lipari 524
   \ingroup coremodule
525
 
881 trimarchi 526
   This call is the same as fsf_schedule_triggered_job, but with an
527
   absolute timeout. The timed_out argument, indicates whether the
528
   function returned because of a timeout or not
529
 
985 julio 530
   @retval FSF_ERR_INVALID_SYNCH_OBJ_HANDLE if the synch_handle is not valid
983 lipari 531
   @retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or
532
       not running
533
   @retval FSF_ERR_INTERNAL_ERROR  erroneous binding or malfunction
534
       of the FSF main scheduler
535
   @retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD if the calling thread is
536
       not scheduled under the FSF
985 julio 537
   @retval FSF_ERR_NOT_BOUND  if the calling thread does not have a valid
881 trimarchi 538
       server bound to it
985 julio 539
   @retval FSF_ERR_BAD_ARGUMENT   if synch_handle is 0, or the abs_timeout
540
       argument is NULL, or its value is in the past
541
   @retval FSF_ERR_SERVER_WORKLOAD_NOT_COMPATIBLE: if the kind of workload
542
            of the server is not FSF_BOUNDED
881 trimarchi 543
 
983 lipari 544
   @see fsf_schedule_triggered_job
881 trimarchi 545
*/
546
int
547
fsf_timed_schedule_triggered_job
548
  (fsf_synch_obj_handle_t  synch_handle,
549
   const struct timespec   *abs_timeout,
550
   bool                    *timed_out,
551
   struct timespec         *next_budget,
552
   struct timespec         *next_period,
553
   bool                    *was_deadline_missed,
554
   bool                    *was_budget_overran);
555
 
556
 
557
///////////////////////////////////////////////////////////////////
993 lipari 558
//                 CONTRACT NEGOTIATION OPERATIONS
881 trimarchi 559
///////////////////////////////////////////////////////////////////
560
 
561
/**
983 lipari 562
   \ingroup coremodule
881 trimarchi 563
 
564
   The operation negotiates a contract for a new server. If the
565
   on-line admission test is enabled it determines whether the
566
   contract can be admitted or not based on the current contracts
567
   established in the system. Then it creates the server and
568
   recalculates all necessary parameters for the contracts already
983 lipari 569
   present in the system.
881 trimarchi 570
 
983 lipari 571
   This is a potentially blocking operation; it returns when the
572
   system has either rejected the contract, or admitted it and made it
573
   effective. It returns zero and places the server identification
574
   number in the location pointed to by the server input parameter if
575
   accepted, or an error if rejected.  No thread is bound to the newly
576
   created server, which will be idle until a thread is bound to
577
   it. This operation can only be executed by threads that are already
578
   bound to an active server and therefore are being scheduled by the
579
   fsf scheduler.
881 trimarchi 580
 
983 lipari 581
   @param [in] contract pointer to the contract
582
   @param [out] server server id
583
 
584
   @retval 0 if the call is succesful
585
   @retval FSF_ERR_INVALID_SCHEDULER_REPLY  the scheduler is wrong or not
586
                                            running
587
   @retval FSF_ERR_INTERNAL_ERROR  erroneous binding or malfunction of the FSF
588
                                   main scheduler
589
   @retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD  
590
                                   if the calling thread is not scheduled
591
                                   under the FSF
592
   @retval FSF_ERR_BAD_ARGUMENT    if the contract or server arguments
593
                                   are NULL
985 julio 594
   @retval FSF_ERR_TOO_MANY_SERVERS if there is no space for more servers
595
                                    (the maximum number of them is already
596
                                    reached)
597
   @retval FSF_ERR_CONTRACT_REJECTED  if the contract is rejected
881 trimarchi 598
*/
599
int
600
fsf_negotiate_contract
601
  (const fsf_contract_parameters_t *contract,
602
   fsf_server_id_t      *server);
603
 
604
/**
993 lipari 605
   \ingroup coremodule
606
 
881 trimarchi 607
   This operation negotiates a contract for a new server, creates a
608
   thread and binds it to the server. If the contract is accepted, the
609
   operation creates a thread with the arguments thread, attr,
610
   thread_code and arg as they are defined for the pthread_create()
611
   POSIX function call, and attaches it to the fsf scheduler. Then, it
612
   binds the created thread to the new server. It returns zero and
613
   puts the server identification number in the location pointed to by
983 lipari 614
   the server input parameter.
881 trimarchi 615
 
983 lipari 616
   The attr parameter is overwritten as necessary to introduce the
617
   adequate scheduling attributes, according to the information given
618
   in the contract.
619
 
881 trimarchi 620
   The server is created with the FSF_NONE scheduling policy, which
621
   means no hierarchical scheduling, and only one thread per server,
985 julio 622
   except for the case of background tasks.
881 trimarchi 623
 
983 lipari 624
   If the contract is rejected, the thread is not created and the
625
   corresponding error is returned.
626
 
627
   @param [in] contract pointer to the contract
628
   @param [out] server server id
629
   @param [out] thread thread id
630
   @param [in] attr threads attributes
631
   @param [in] thread_code  pointer to the function that implements
632
               the thread
633
   @param [in] arg  arguments for the thread
634
 
635
   @retval  FSF_ERR_BAD_ARGUMENT  if the contract or server arguments are NULL
636
   @retval  FSF_ERR_CONTRACT_REJECTED  if the contract is rejected
985 julio 637
   @retval  FSF_ERR_SERVER_WORKLOAD_NOT_COMPATIBLE if the kind of workload
638
            in the contract is FSF_OVERHEAD
639
 
983 lipari 640
   @retval  others it may also return all the errors that may be returned
641
            by the pthread_create()POSIX function call
881 trimarchi 642
 
643
*/
644
int
645
fsf_negotiate_contract_for_new_thread
646
  (const fsf_contract_parameters_t *contract,
647
   fsf_server_id_t      *server,
648
   pthread_t            *thread,
649
   pthread_attr_t       *attr,
650
   fsf_thread_code_t     thread_code,
651
   void                 *arg);
652
 
653
/**
993 lipari 654
   \ingroup coremodule
655
 
881 trimarchi 656
   This operation negotiates a contract for a new server, and binds
657
   the calling thread to it. If the contract is accepted it returns
658
   zero and copies the server identification number in the location
659
   pointed to by the server input parameter.  If it is rejected, an
660
   error is returned.
661
 
662
   The server is created with the FSF_NONE scheduling policy, which
663
   means no hierarchical scheduling, and only one thread per server,
985 julio 664
   except for the case of background tasks.
881 trimarchi 665
 
993 lipari 666
   <i> Implementation dependent issue for Marte OS: to allow the usage of
881 trimarchi 667
   application defined schedulers, the calling thread must not have
668
   the SCHED_APP scheduling policy and at the same time be attached to
669
   an application scheduler different than the fsf scheduler; in such
670
   case, an error is returned. After a successful call the calling
671
   thread will have the SCHED_APP scheduling policy and will be
993 lipari 672
   attached to the fsf scheduler.</i>
881 trimarchi 673
 
983 lipari 674
   @param [in] contract pointer to the contract
675
   @param [out] server id
676
 
677
   @retval 0 if the contract negotation is succesful
678
   @retval  FSF_ERR_UNKNOWN_APPSCHEDULED_THREAD  if the thread is attached to
881 trimarchi 679
       an application defined scheduler different than the fsf scheduler
983 lipari 680
   @retval FSF_ERR_BAD_ARGUMENT  if the contract or server arguments
681
       are NULL
682
   @retval FSF_ERR_CONTRACT_REJECTED  if the contract is rejected.
985 julio 683
   @retval FSF_ERR_SERVER_WORKLOAD_NOT_COMPATIBLE if the kind of workload
684
            in the contract is FSF_OVERHEAD
881 trimarchi 685
*/
686
int
687
fsf_negotiate_contract_for_myself
688
  (const fsf_contract_parameters_t *contract,
689
   fsf_server_id_t      *server);
690
 
691
 
692
/**
993 lipari 693
   \ingroup coremodule
694
 
983 lipari 695
   This operation associates a thread with a server, which means that
696
   it starts consuming the server's budget and is executed according
697
   to the contract established for that server. If the thread is
698
   already bound to another server, and error is returned.
881 trimarchi 699
 
700
   It fails if the server's policy is different than FSF_NONE, or if
701
   there is already a thread bound to this server
702
 
993 lipari 703
   <i> Implementation dependent issue for MARTE OS: In order to allow the usage of
881 trimarchi 704
   application defined schedulers, the given thread must not have the
705
   scheduling policy SCHED_APP and at the same time be attached to an
993 lipari 706
   application scheduler different than the fsf scheduler. </i>
881 trimarchi 707
 
983 lipari 708
   @param [in] server id
709
   @param [in] thread id
710
 
711
   @retval FSF_ERR_INTERNAL_ERROR  erroneous binding or malfunction
712
       of the FSF main scheduler
713
   @retval FSF_ERR_UNKNOWN_APPSCHEDULED_THREAD if the thread is attached to
881 trimarchi 714
       an application defined scheduler different than the fsf scheduler
993 lipari 715
   @retval FSF_ERR_BAD_ARGUMENT if the server value does not comply with the
881 trimarchi 716
       expected format or valid range or the given thread does not exist
983 lipari 717
   @retval FSF_ERR_NOT_CONTRACTED_SERVER if the referenced server
718
       is not valid
985 julio 719
   @retval FSF_ERR_ALREADY_BOUND if the given server has a thread
720
       already bound
721
   @retval FSF_ERR_SERVER_WORKLOAD_NOT_COMPATIBLE if the kind of workload
722
       in the contract is FSF_OVERHEAD
881 trimarchi 723
 
724
*/
725
int
726
fsf_bind_thread_to_server
727
  (fsf_server_id_t server,
728
   pthread_t       thread);
729
 
730
 
731
/**
993 lipari 732
   \ingroup coremodule
733
 
881 trimarchi 734
   This operation unbinds a thread from a server.  Since threads with
993 lipari 735
   no server associated are not allowed to execute, they remain in a
881 trimarchi 736
   dormant state until they are either eliminated or bound again.
737
 
738
   If the thread is inside a critical section the effects of this call
993 lipari 739
   are deferred until the critical section is ended.
881 trimarchi 740
 
741
   Implementation dependent issue: in the implementation with an
742
   application scheduler, the thread is still attached to the fsf
743
   scheduler, but suspended.
744
 
983 lipari 745
   @param [in] thread thread id
746
 
747
   @retval 0 if the operation is succesful
748
   @retval FSF_ERR_INTERNAL_ERROR  erroneous binding or malfunction of the FSF
881 trimarchi 749
       main scheduler
983 lipari 750
   @retval FSF_ERR_BAD_ARGUMENT  if the given thread does not exist
751
   @retval FSF_ERR_NOT_SCHEDULED_THREAD  if the given thread is not scheduled
881 trimarchi 752
       under the FSF
983 lipari 753
   @retval FSF_ERR_UNKNOWN_APPSCHEDULED_THREAD if the thread is attached to
881 trimarchi 754
       an application defined scheduler different than the fsf scheduler
983 lipari 755
   @retval FSF_ERR_NOT_BOUND if the given thread does not have a valid
881 trimarchi 756
       server bound to it
757
*/
758
int
759
fsf_unbind_thread_from_server (pthread_t thread);
760
 
761
/**
993 lipari 762
   \ingroup coremodule
763
 
881 trimarchi 764
   This operation stores the Id of the server associated with the
765
   specified thread in the variable pointed to by server. It returns
766
   an error if the thread does not exist, it is not under the control
767
   of the scheduling framework, or is not bound.
768
 
983 lipari 769
   @param [in] thread thread id
770
   @param [out] server server
771
 
772
   @retval 0 if the operation is succesful
773
   @return FSF_ERR_NOT_SCHEDULED_THREAD if the given thread is not scheduled
881 trimarchi 774
       under the FSF
985 julio 775
   @return FSF_ERR_NOT_BOUND if the given thread does not have a valid
881 trimarchi 776
       server bound to it
983 lipari 777
   @return FSF_ERR_BAD_ARGUMENT if the given thread does not exist or the
881 trimarchi 778
       server argument is NULL
779
*/
780
int
781
fsf_get_server
782
  (pthread_t       thread,
783
   fsf_server_id_t *server);
784
 
785
/**
786
   This operation stores the contract parameters currently associated
787
   with the specified server in the variable pointed to by
788
   contract. It returns an error if the server id is incorrect.
789
 
983 lipari 790
   @param [in] server server id
791
   @param [out] contract pointer to the contract structure
792
 
793
   @retval 0 if the operation is succesful
794
   @retval FSF_ERR_BAD_ARGUMENT  if the contract argument is
795
         NULL or the value of the server argument is not in range
796
   @retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD if the calling thread is not
881 trimarchi 797
       scheduled under the FSF
983 lipari 798
   @retval FSF_ERR_INVALID_SCHEDULER_REPLY  the scheduler is wrong or
799
       not running
800
   @retval FSF_ERR_NOT_CONTRACTED_SERVER if the server of the calling thread
881 trimarchi 801
       has been cancelled or it is not valid
802
*/
803
int
804
fsf_get_contract
805
   (fsf_server_id_t server,
806
    fsf_contract_parameters_t *contract);
807
 
808
/**
993 lipari 809
   \ingroup coremodule
810
 
881 trimarchi 811
   The operation eliminates the specified server
812
   and recalculates all necessary parameters for the contracts
813
   remaining in the system. This is a potentially blocking operation;
814
   it returns when the system has made the changes effective.
815
 
983 lipari 816
   @param [in] server server id
881 trimarchi 817
 
983 lipari 818
   @retval 0 if the operation is succesful
819
   @retval FSF_ERR_BAD_ARGUMENT   if the value of server is not in range
820
   @retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD  if the calling thread is not
821
           scheduled under the FSF
822
   @retval FSF_ERR_INVALID_SCHEDULER_REPLY  the scheduler is wrong or not
823
           running
824
   @retval FSF_ERR_NOT_CONTRACTED_SERVER  if the server of the calling thread
825
           has been cancelled or it is not valid
881 trimarchi 826
*/
827
int
828
fsf_cancel_contract (fsf_server_id_t server);
829
 
830
 
831
/**
993 lipari 832
   \ingroup coremodule
833
 
881 trimarchi 834
   The operation renegotiates a contract for an existing server. If
835
   the on-line admission test is enabled it determines whether the
836
   contract can be admitted or not based on the current contracts
837
   established in the system. If it cannot be admitted, the old
838
   contract remains in effect and an error is returned. If it can be
839
   admitted, it recalculates all necessary parameters for the
840
   contracts already present in the system anr returns zero. This is a
841
   potentially blocking operation; it returns when the system has
842
   either rejected the new contract, or admitted it and made it
843
   effective.
844
 
983 lipari 845
   @param [in]  new_contract a pointer to the new contract
846
   @param [in]  server server id
847
 
848
   @retval 0 if the operation is succesful
849
   @retval FSF_ERR_BAD_ARGUMENT  if the new_contract argument is NULL or the  
881 trimarchi 850
       value of the server argument is not in range
983 lipari 851
   @retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD if the calling thread is not
881 trimarchi 852
       scheduled under the FSF
983 lipari 853
   @retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or not
854
       running
855
   @retval FSF_ERR_NOT_CONTRACTED_SERVER if the server of the calling thread
881 trimarchi 856
       has been cancelled or it is not valid
985 julio 857
   @retval FSF_ERR_REJECTED_CONTRACT if the renegotiation fails
881 trimarchi 858
*/
859
int
860
fsf_renegotiate_contract
861
  (const fsf_contract_parameters_t *new_contract,
862
   fsf_server_id_t server);
863
 
864
/**
993 lipari 865
   \ingroup coremodule
866
 
881 trimarchi 867
   The operation enqueues a renegotiate operation for an existing
868
   server, and returns immediately. The renegotiate operation is
983 lipari 869
   performed asynchronously and the calling thread may continue
870
   executing normally. Of course, wheter the operation is performed
871
   immediately or not depends on the relative priority of the service
872
   thread and the calling thread, on the scheduler used, etc.
881 trimarchi 873
 
983 lipari 874
   When the renegotiation is completed, if the on-line admission test
875
   is enabled it determines whether the contract can be admitted or
876
   not based on the current contracts established in the system. If it
877
   cannot be admitted, the old contract remains in effect. If it can
878
   be admitted, it recalculates all necessary parameters for the
879
   contracts already present in the system. When the operation is
880
   completed, notification is made to the caller, if requested, via a
881
   signal. The status of the operation (in progress, admitted,
882
   rejected) can be checked with the get_renegotiation_status
883
   operation.  The argument sig_notify can be NULL_SIGNAL (no
884
   notification), or any POSIX signal; and in this case sig_value is
885
   to be sent with the signal.
886
 
887
   @param [in] new_contract pointer to the new contract to be negotiated
888
   @param [in] server  server id
889
   @param [in] sig_notify NULL (no signal) or any POSIX signal
890
   @param [in] sig_value a sigval structure that contains values to be
891
               passed to the signal handler. Valid only if sig_notify
892
               is different from NULL.
893
 
894
   @retval 0 if the call is succesful
895
   @retval FSF_ERR_BAD_ARGUMENT  if the new_contract argument is NULL, the  
881 trimarchi 896
       value of the server argument is not in range or sig_notify is
897
       neither NULL nor a valid POSIX signal
983 lipari 898
   @retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD if the calling thread is not
881 trimarchi 899
       scheduled under the FSF
983 lipari 900
   @retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or not
901
       running
902
   @retval FSF_ERR_NOT_CONTRACTED_SERVER if the server of the calling thread
881 trimarchi 903
       has been cancelled or it is not valid
904
 
905
*/
906
int
907
fsf_request_contract_renegotiation
908
  (const fsf_contract_parameters_t *new_contract,
909
   fsf_server_id_t                  server,
910
   int                              sig_notify,
911
   union sigval                     sig_value);
912
 
983 lipari 913
/**
993 lipari 914
   \ingroup coremodule
915
 
881 trimarchi 916
   The operation reports on the status of the last renegotiation
917
   operation enqueued for the specified server. It is callable even
918
   after notification of the completion of such operation, if
983 lipari 919
   requested.
881 trimarchi 920
 
983 lipari 921
   @param [in] server server id
922
   @param [out] renegotiation_status the status of the renegotiation;
923
 
924
   @retval 0 if succesful completion;
925
   @retval FSF_ERR_BAD_ARGUMENT  if the renegotiation_status argument is
881 trimarchi 926
       NULL or the value of the server argument is not in range
983 lipari 927
   @retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD if the calling thread is not
881 trimarchi 928
       scheduled under the FSF
983 lipari 929
   @retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or not
930
       running
931
   @retval FSF_ERR_NOT_CONTRACTED_SERVER if the server of the calling thread
881 trimarchi 932
       has been cancelled or it is not valid
933
*/
934
int
935
fsf_get_renegotiation_status
936
  (fsf_server_id_t server,
937
   fsf_renegotiation_status_t *renegotiation_status);
938
 
983 lipari 939
 
985 julio 940
////////////////////////////////////////////////////////////////////////
941
//           CHANGE OF MODE: GROUPS OF CONTRACTS 
942
////////////////////////////////////////////////////////////////////////
983 lipari 943
 
944
 
945
/**
993 lipari 946
   \ingroup coremodule
947
 
983 lipari 948
   This operation analizes the schedulability of the context that
993 lipari 949
   results from negotiating the contracts specified in the
983 lipari 950
   contracts_up list and cacelling the contracts referenced by the
951
   servers_down list. If the overall negotiation is successful, a new
952
   server will be created for each of the elements of the contracts_up
953
   group, the servers in servers_down will be cancelled, the list of
954
   new server ids will be returned in the variable pointed to by
955
   servers_up, and the variable pointed to by accepted will be made
956
   true. Otherwise, this variable will be made false, and no other
957
   effect will take place. The function returns the corresponding
958
   error code if any of the contracts is not correct or any of the
959
   server is is not valid.
960
 
961
   @param [in] contracts_up list of contracts to negotiate
962
   @param [in] servers_down list of contracts to be canceled
963
   @param [out] servers_up list of server ids that have been created, they are
964
      given in the same order as the contract_up list of contracts;
965
   @param [out] accepted if the operation is succesful;
966
 
967
   @retval 0 if succesful completion;
968
   @retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or
969
           not running
970
   @retval FSF_ERR_INTERNAL_ERROR erroneous binding or malfunction of the FSF
971
       main scheduler
972
   @retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD if the calling thread is
973
           not scheduled under the FSF
974
   @retval FSF_ERR_BAD_ARGUMENT if any of the servers_up or accepted arguments
975
       is NULL, if the contracts_up and servers_down arguments are both NULL,
976
       or any of them has erroneous size or its elements are NULL or not in the
977
       valid range respectively
978
*/
979
int
980
fsf_negotiate_group
981
   (const fsf_contracts_group_t *contracts_up,
982
    const fsf_servers_group_t   *servers_down,
983
    fsf_servers_group_t         *servers_up,
984
    bool                        *accepted);
985
 
986
 
881 trimarchi 987
////////////////////////////////////////////////////
988
//           OBTAINING INFORMATION FROM THE SCHEDULER
989
////////////////////////////////////////////////////
990
 
991
 
992
/**
983 lipari 993
   \ingroup coremodule
994
 
995
   Returns true if the system is configured with the on-line admission
996
   test enabled, or false otherwise.
881 trimarchi 997
*/
998
bool
999
fsf_is_admission_test_enabled();
1000
 
1001
/**
993 lipari 1002
   \ingroup coremodule
1003
 
881 trimarchi 1004
   This function stores the current execution time spent by the
1005
   threads bound to the specified server in the variable pointed to by
1006
   cpu_time.
1007
 
983 lipari 1008
   @param [in] server server id
1009
   @param [out] cpu_time pointer to a timespec structure that will contain
1010
         the cpu time consumed by the threads that are bound to the
1011
         specific server, since its creation.
1012
 
1013
   @retval 0 if succesful completion
1014
   @retval FSF_ERR_BAD_ARGUMENT if the value of the server argument is
1015
       not in range or cpu_time is NULL
1016
   @retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD if the calling thread is not
881 trimarchi 1017
       scheduled under the FSF
983 lipari 1018
   @retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or
1019
       not running
1020
   @retval FSF_ERR_NOT_CONTRACTED_SERVER if the server of the calling thread
881 trimarchi 1021
       has been cancelled or it is not valid
1022
*/
1023
int
1024
fsf_get_cpu_time
1025
   (fsf_server_id_t server,
1026
    struct timespec *cpu_time);
1027
 
1028
/**
993 lipari 1029
   \ingroup coremodule
1030
 
881 trimarchi 1031
   This function stores in the variable pointed to by budget the
1032
   remaining execution-time budget associated with the specified
983 lipari 1033
   server.
881 trimarchi 1034
 
983 lipari 1035
   @param [in] server server id
1036
   @param [out] budget pointer to a timespec structure that will
1037
     contain the remaining budget
1038
 
1039
   @retval 0 if succesful completion
1040
   @retval FSF_ERR_BAD_ARGUMENT if the value of the server argument is
1041
       not in range or budget is NULL
1042
   @retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD if the calling thread is not
881 trimarchi 1043
       scheduled under the FSF
983 lipari 1044
   @retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or
1045
       not running
1046
   @retval FSF_ERR_NOT_CONTRACTED_SERVER if the server of the calling thread
881 trimarchi 1047
       has been cancelled or it is not valid
1048
*/
1049
int
1050
fsf_get_remaining_budget
1051
   (fsf_server_id_t server,
1052
    struct timespec *budget);
1053
 
1054
 
1055
/**
993 lipari 1056
   \ingroup coremodule
1057
 
983 lipari 1058
   This function stores in the variables pointed to by budget and
1059
   period, the execution-time budget and the period respectively
1060
   associated with the specified server. If any of these pointers is
1061
   NULL, the corresponding information is not stored.
881 trimarchi 1062
 
983 lipari 1063
   @param [in] server server id
1064
   @param [out] budget budget available for the current server instance
1065
   @param [out] period period available for the current server instance
1066
 
1067
   @retval 0 if succesful completion
1068
   @retval FSF_ERR_BAD_ARGUMENT if the value of the server argument is
1069
       not in range, budget is NULL or period is NULL
1070
   @retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD if the calling thread is not
881 trimarchi 1071
       scheduled under the FSF
983 lipari 1072
   @retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or not
1073
     running
1074
   @retval FSF_ERR_NOT_CONTRACTED_SERVER if the server of the calling thread
881 trimarchi 1075
       has been cancelled or it is not valid
1076
*/
1077
int
1078
fsf_get_budget_and_period
1079
   (fsf_server_id_t server,
1080
    struct timespec *budget,
1081
    struct timespec *period);
1082
 
1083
/////////////////////////////////////////////////////////////////////
1084
//           SERVICE THREAD TUNING
1085
/////////////////////////////////////////////////////////////////////
1086
 
993 lipari 1087
 
881 trimarchi 1088
/**
983 lipari 1089
   \ingroup coremodule
1090
 
1091
   This function allows the application to change the period and
1092
   budget of the service thread that makes the
881 trimarchi 1093
   negotiations. Increasing the utilization of this thread makes the
1094
   negotiations faster, but introduces additional load in the system
1095
   that may decrease the bandwidth available for the servers. For this
983 lipari 1096
   call, the system will make a schedulability analysis to determine
1097
   if the new situation is acceptable or not. This is reported back in
1098
   the variable pointed to by accepted. If the new service thread data
1099
   is accepted, the system will reassign budgets and periods to the
1100
   servers according to the new bandwidth available, in the same way
1101
   as it does for a regular contract negotiation.
881 trimarchi 1102
 
1103
   When its budget is exhausted, the service thread may run in the
983 lipari 1104
   background.
881 trimarchi 1105
 
1106
   The service thread starts with a default budget and period that are
983 lipari 1107
   configurable.
993 lipari 1108
 
1109
   <i> Implementation dependency for MARTE OS: in the fixed priority
1110
   implementation of fsf, the default priority is lower than the
1111
   priority of any server, but higher than the background. According
1112
   to the implementation-dependent module the priority is adjustable
1113
   by means of a function that changes its preemption level.</i>
1114
 
881 trimarchi 1115
 
983 lipari 1116
   @param [in] budget budget for the service thread
1117
   @param [in] period for the service thread
1118
   @param [out] accepted true is the change has been accepted
881 trimarchi 1119
 
983 lipari 1120
 
1121
   @retval 0 is the operation is succesful
1122
   @retval FSF_ERR_BAD_ARGUMENT if any of the pointer arguments is NULL or
881 trimarchi 1123
       the budget value is greater than the period value
983 lipari 1124
   @retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD if the calling thread is not
881 trimarchi 1125
       scheduled under the FSF
983 lipari 1126
   @retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong or
1127
       not running
1128
   @retval FSF_ERR_NOT_CONTRACTED_SERVER if the server of the calling thread
881 trimarchi 1129
       has been cancelled or it is not valid
1130
*/
1131
int
1132
fsf_set_service_thread_data
1133
   (const struct timespec *budget,
1134
    const struct timespec *period,
1135
    bool                  *accepted);
1136
 
1137
/**
993 lipari 1138
   \ingroup coremodule
1139
 
1140
   This function returns in the variables pointed by budget and
881 trimarchi 1141
   period, respectively, the current budget and period of the service
1142
   thread.
983 lipari 1143
 
1144
   @param [out] budget   current budget of the service thread
1145
   @param [out] period   current period of the service thread
881 trimarchi 1146
 
983 lipari 1147
   @retval FSF_ERR_BAD_ARGUMENT if any of the pointer arguments is NULL
1148
   @retval FSF_ERR_NOT_SCHEDULED_CALLING_THREAD if the calling thread is not
881 trimarchi 1149
       scheduled under the FSF
983 lipari 1150
   @retval FSF_ERR_INVALID_SCHEDULER_REPLY the scheduler is wrong
1151
       or not running
1152
   @retval FSF_ERR_NOT_CONTRACTED_SERVER if the server of the calling thread
881 trimarchi 1153
       has been cancelled or it is not valid
1154
*/
1155
int
1156
fsf_get_service_thread_data
1157
   (struct timespec *budget,
1158
    struct timespec *period);
1159
 
1160
#endif // _FSF_CORE_H_