1 // -----------------------------------------------------------------------
2 // Copyright (C) 2006 - 2008 FRESCOR consortium partners:
4 // Universidad de Cantabria, SPAIN
5 // University of York, UK
6 // Scuola Superiore Sant'Anna, ITALY
7 // Kaiserslautern University, GERMANY
8 // Univ. Politécnica Valencia, SPAIN
9 // Czech Technical University in Prague, CZECH REPUBLIC
11 // Thales Communication S.A. FRANCE
12 // Visual Tools S.A. SPAIN
13 // Rapita Systems Ltd UK
16 // See http://www.frescor.org for a link to partners' websites
18 // FRESCOR project (FP6/2005/IST/5-034026) is funded
19 // in part by the European Union Sixth Framework Programme
20 // The European Union is not liable of any use that may be
24 // based on previous work (FSF) done in the FIRST project
26 // Copyright (C) 2005 Mälardalen University, SWEDEN
27 // Scuola Superiore S.Anna, ITALY
28 // Universidad de Cantabria, SPAIN
29 // University of York, UK
31 // FSF API web pages: http://marte.unican.es/fsf/docs
32 // http://shark.sssup.it/contrib/first/docs/
34 // This file is part of FOSA (Frsh Operating System Adaption)
36 // FOSA is free software; you can redistribute it and/or modify it
37 // under terms of the GNU General Public License as published by the
38 // Free Software Foundation; either version 2, or (at your option) any
39 // later version. FOSA is distributed in the hope that it will be
40 // useful, but WITHOUT ANY WARRANTY; without even the implied warranty
41 // of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
42 // General Public License for more details. You should have received a
43 // copy of the GNU General Public License along with FOSA; see file
44 // COPYING. If not, write to the Free Software Foundation, 675 Mass Ave,
45 // Cambridge, MA 02139, USA.
47 // As a special exception, including FOSA header files in a file,
48 // instantiating FOSA generics or templates, or linking other files
49 // with FOSA objects to produce an executable application, does not
50 // by itself cause the resulting executable application to be covered
51 // by the GNU General Public License. This exception does not
52 // however invalidate any other reasons why the executable file might be
53 // covered by the GNU Public License.
54 // -----------------------------------------------------------------------
55 //fosa_app_def_sched.h
56 //==============================================
57 // ******** ****** ******** **********
58 // **///// /** ** **////// /** /**
59 // ** /** ** /** /** /**
60 // ******* /** ** /********* /**********
61 // **//// /** ** ////////** /**//////**
62 // ** /** ** /** /** /**
63 // ** /** ** ******** /** /**
64 // // /******/ //////// // //
66 // FOSA(Frescor Operating System Adaptation layer)
67 //================================================
71 /***************************************************************
72 * Application-defined scheduling not implemented in POSIX/Linux
73 **************************************************************/
76 * fosa_ads_scheduler_create()
78 * Create the application defined scheduler
80 * The application defined scheduler is created with the primitive
81 * operations specified in the object pointed to by scheduler_ops.
83 * The clock used to read the time immediately before the invocation
84 * of each primitive operation, to be reported to the scheduler via
85 * the current_time parameter of each primitive operation is the
86 * FOSA_CLOCK_REALTIME clock.
88 * The scheduler_data_size parameter is used to request that a memory
89 * area of this size must be created and reserved for the scheduler to
90 * store its state. A pointer to this area is passed to the scheduler
91 * operations in the sched_data parameter.
93 * Parameter init_arg points to an area that contains configuration
94 * information for the scheduler. The function creates a memory area
95 * of init_arg_size bytes and copies into it the area pointed by
96 * arg. A pointer to this new created area will be passed to the
97 * primitive operation init() in its arg parameter.
99 * Returns 0 if successful; otherwise it returns an error code:
100 * EINVAL: The value of scheduler_ops was invalid
101 * EAGAIN: The system lacks enough resources to create the scheduler
103 * Alternatively, in case of error the implementation is allowed to
104 * notify it to the system console and then terminate the FRSH
105 * implementation and dependant applications
107 * The fosa_ads_scheduler_create function must be called before any
108 * other function in this header file
110 int fosa_ads_scheduler_create(const fosa_ads_scheduler_ops_t * scheduler_ops,
111 size_t scheduler_data_size, void * init_args,
112 size_t init_args_size)
118 * fosa_thread_attr_set_appscheduled()
120 * Set the appscheduled attribute of a thread attributes object
122 * This function is used to set the appscheduled attribute in the
123 * object pointed to by attr. This attribute controls the kind of
124 * scheduling used for threads created with it. If true, the thread is
125 * scheduled by the application scheduler. If not, it is scheduled by
126 * the system under a fixed priority scheduler
128 * Returns 0 if successful; otherwise it returns an error code:
129 * EINVAL: The value of attr is invalid
131 * Alternatively, in case of error the implementation is allowed to
132 * notify it to the system console and then terminate the FRSH
133 * implementation and dependant applications
135 int fosa_thread_attr_set_appscheduled(fosa_thread_attr_t *attr,
142 * fosa_thread_attr_get_appscheduled()
144 * Get the appscheduled attribute of a thread attributes object
146 * This function is used to get the appscheduled attribute in the
147 * object pointed to by attr. This attribute controls the kind of
148 * scheduling used for threads created with it. If true, the thread is
149 * scheduled by the application scheduler. If not, it is scheduled by
150 * the system under a fixed priority scheduler.
152 * Returns 0 if successful; otherwise it returns an error code:
153 * EINVAL: The value of attr is invalid
155 * Alternatively, in case of error the implementation is allowed to
156 * notify it to the system console and then terminate the FRSH
157 * implementation and dependant applications
159 int fosa_thread_attr_get_appscheduled(const fosa_thread_attr_t *attr,
166 * fosa_thread_attr_set_appsched_params()
168 * Set the appsched_param attribute of a thread attributes object
170 * This function is used to set the appsched_param attribute in the
171 * object pointed to by attr. For those threads with appscheduled set
172 * to true, this attribute represents the application-specific
173 * scheduling parameters. If successful, the function shall set the
174 * size of the appsched_param attribute to the value specified by
175 * paramsize, and shall copy the scheduling parameters occupying
176 * paramsize bytes and pointed to by param into that attribute
178 * Returns 0 if successful; otherwise it returns an error code:
179 * EINVAL: The value of attr is invalid, or paramsize is less than
180 * zero or larger than FOSA_ADS_SCHEDPARAM_MAX
182 * Alternatively, in case of error the implementation is allowed to
183 * notify it to the system console and then terminate the FRSH
184 * implementation and dependant applications
186 int fosa_thread_attr_set_appsched_params(fosa_thread_attr_t *attr,
194 * fosa_thread_attr_get_appsched_params()
196 * Get the appsched_param attribute of a thread attributes object
198 * This function is used to get the appsched_param attribute from the
199 * object pointed to by attr. For those threads with appscheduled set
200 * to true, this attribute represents the application-specific
201 * scheduling parameters. If successful, the function shall set the
202 * value pointed to by paramsize to the size of the appsched_param
203 * attribute, and shall copy the scheduling parameters occupying
204 * paramsize bytes into the variable pointed to by param. This
205 * variable should be capable of storing a number of bytes equal to
208 * Returns 0 if successful; otherwise it returns an error code:
209 * EINVAL: The value of attr is invalid
211 * Alternatively, in case of error the implementation is allowed to
212 * notify it to the system console and then terminate the FRSH
213 * implementation and dependant applications
215 int fosa_thread_attr_get_appsched_params(const fosa_thread_attr_t *attr,
216 void *param, size_t *paramsize)
222 * fosa_ads_set_appscheduled()
224 * Dynamically set the appscheduled attribute of a thread
226 * This function is used to dynamically set the appscheduled attribute
227 * of the thread identified by thread. This attribute controls the
228 * kind of scheduling used for threads created with it. If true, the
229 * thread is scheduled by the application scheduler. If not, it is
230 * scheduled by the system under a fixed priority scheduler.
232 * Returns 0 if successful; otherwise it returns an error code:
233 * EINVAL: The value of thread is invalid
235 * EREJECT: the attachment of the thread to the frsh schehduler
236 * was rejected by the frsh scheduler possibly because of
237 * incorrect attributes, or because the requested minimum
238 * capacity cannot be guaranteed
240 * Alternatively, in case of error the implementation is allowed to
241 * notify it to the system console and then terminate the FRSH
242 * implementation and dependant applications
244 int fosa_ads_set_appscheduled(fosa_thread_id_t thread, bool appscheduled)
250 * fosa_ads_getappscheduled()
252 * Dynamically get the appscheduled attribute of a thread
254 * This function is used to dynamically get the appscheduled attribute
255 * of the thread identified by thread. This attribute controls the
256 * kind of scheduling used for threads created with it. If true, the
257 * thread is scheduled by the application scheduler. If not, it is
258 * scheduled by the system under a fixed priority scheduler
260 * Returns 0 if successful; otherwise it returns an error code:
261 * EINVAL: The value of thread is invalid
263 * Alternatively, in case of error the implementation is allowed to
264 * notify it to the system console and then terminate the FRSH
265 * implementation and dependant applications
267 int fosa_ads_get_appscheduled(fosa_thread_id_t thread, bool *appscheduled)
274 * fosa_ads_setappschedparam()
276 * Dynamically set the appsched_param attribute of a thread
278 * This function is used to dynamically set the appsched_param
279 * attribute of the thread identified by thread. For those threads
280 * with appscheduled set to true, this attribute represents the
281 * application-specific scheduling parameters. If successful, the
282 * function shall set the size of the appsched_param attribute to the
283 * value specified by paramsize, and shall copy the scheduling
284 * parameters occupying paramsize bytes and pointed to by param into
287 * Returns 0 if successful; otherwise it returns an error code:
288 * EINVAL: The value of thread is invalid, or paramsize is less than
289 * zero or larger than FOSA_ADS_SCHEDPARAM_MAX
291 * Alternatively, in case of error the implementation is allowed to
292 * notify it to the system console and then terminate the FRSH
293 * implementation and dependant applications
295 int fosa_ads_set_appsched_params(fosa_thread_id_t thread,
296 const void *param, size_t paramsize)
302 * fosa_ads_get_appsched_params()
304 * Dynamically get the appsched_param attribute of a thread
306 * This function is used to dynamically get the appsched_param
307 * attribute of the thread identified by thread. For those threads
308 * with appscheduled set to true, this attribute represents the
309 * application-specific scheduling parameters. If successful, the
310 * function shall set the variable pointed to by paramsize to the size
311 * of the appsched_param attribute, and shall copy the scheduling
312 * parameters occupying paramsize bytes into the variable pointed to
313 * by param. This variable should be capable of storing a number of
314 * bytes equal to paramsize.
316 * Returns 0 if successful; otherwise it returns an error code:
317 * EINVAL: The value of thread is invalid, or paramsize is less than
318 * zero or larger than FOSA_ADS_SCHEDPARAM_MAX
320 * Alternatively, in case of error the implementation is allowed to
321 * notify it to the system console and then terminate the FRSH
322 * implementation and dependant applications.
324 int fosa_ads_get_appsched_params(fosa_thread_id_t thread,
325 void *param, size_t *paramsize)
331 /*********************************
334 * A scheduling actions object is used to specify a series of actions
335 * to be performed by the system at the end of a scheduler primitive
336 * operation. The order of the actions added to the object shall be
339 *********************************/
342 * fosa_adsactions_add_reject()
344 * Add a reject-thread action
346 * This function adds a thread-reject action to the object referenced
347 * by sched_actions, that will serve to notify that the thread
348 * identified by thread has not been accepted by the scheduler to be
349 * scheduled by it, possibly because the thread contained invalid
350 * application scheduling attributes, or because there are not enough
351 * resources for the new thread. At the end of the new_thread()
352 * scheduler primitive operation, the parent of the rejected thread
353 * waiting on a fosa_thread_create() or the rejected thread itself
354 * waiting on a fosa_ads_set_appscheduled() function shall complete the
355 * function with an error code of EREJECT. If no reject-thread action
356 * is added during the new_thread() scheduler primitive operation, the
357 * thread is accepted to be scheduled by the scheduler and the
358 * associated fosa_thread_create() or the fosa_ads_set_appscheduled()
359 * function shall be completed without error. For the function to
360 * succeed, it has to be called from the new_thread() primitive
361 * operation and for the thread that is requesting attachment to the
364 * Returns 0 if successful; otherwise it returns an error code:
365 * ENOMEM: There is insufficient memory to add this action
366 * FOSA_EPOLICY: The thread specified by thread is not the one requesting
367 * attachment to the scheduler, or the function is not being
368 * called from the new_thread primitive operation
369 * EINVAL: The value specified by sched_actions is invalid
371 * Alternatively, in case of error the implementation is allowed to
372 * notify it to the system console and then terminate the FRSH
373 * implementation and dependant applications
375 int fosa_adsactions_add_reject(fosa_ads_actions_t *sched_actions,
376 fosa_thread_id_t thread)
382 * fosa_adsactions_add_activate()
384 * Add a thread-activate action
386 * This function adds a thread-activate action to the object
387 * referenced by sched_actions. In case the thread had been previously
388 * suspended via posix_appsched_actions_addsuspend(), it will be
389 * activated at the end of the primitive operation.
391 * In those implementations that do not support urgency scheduling,
392 * the urgencu value is ignored. These implementations cannot support
393 * the frsh hierarchical scheduling module.
395 * In those implementations supporting urgency-scheduling, the action
396 * will cause the change of the urgency of the thread to the value
397 * specified in the urgency argument. Besides, if the thread was
398 * already active at the time the thread-activate action is executed,
399 * the change or urgency will imply a reordering of the thread in its
400 * priority queue, so that for threads of the same priority, those
401 * with more urgency will be scheduled before those of less urgency.
403 * Returns 0 if successful; otherwise it returns an error code:
404 * ENOMEM: There is insufficient memory to add this action
405 * FOSA_EPOLICY: The thread specified by thread has its appscheduled
406 * attribute set to false,
407 * EINVAL: The value specified by sched_actions is invalid
409 * Alternatively, in case of error the implementation is allowed to
410 * notify it to the system console and then terminate the FRSH
411 * implementation and dependant applications
413 int fosa_adsactions_add_activate(fosa_ads_actions_t *sched_actions,
414 fosa_thread_id_t thread,
415 fosa_ads_urgency_t urgency)
421 * fosa_adsactions_add_suspend()
423 * Add a thread-suspend action
425 * This function adds a thread-suspend action to the object referenced
426 * by sched_actions, that will cause the thread identified by thread
427 * to be suspended waiting for a thread-activate action at the end of
428 * the scheduler operation. If the thread was already waiting for a
429 * thread-activate action the thread-suspend action has no effect. It
430 * is an error trying to suspend a thread that is blocked by the
433 * Returns 0 if successful; otherwise it returns an error code:
434 * ENOMEM: There is insufficient memory to add this action
435 * FOSA_EPOLICY: The thread specified by thread has its appscheduled
436 * attribute set to false,
437 * EINVAL: The value specified by sched_actions is invalid
439 * Alternatively, in case of error the implementation is allowed to
440 * notify it to the system console and then terminate the FRSH
441 * implementation and dependant applications
443 int fosa_adsactions_add_suspend(fosa_ads_actions_t *sched_actions,
444 fosa_thread_id_t thread)
450 * fosa_adsactions_add_timeout()
452 * Add a timeout action
454 * This function adds a timeout action to the object referenced by
455 * sched_actions, that will cause the timeout() scheduler operation to
456 * be invoked if no other scheduler operation is invoked before
457 * timeout expires. The timeout shall expire when the clock specified by
458 * clock_id reaches the absolute time specified by the at_time
461 * Returns 0 if successful; otherwise it returns an error code:
462 * ENOMEM: There is insufficient memory to add this action
463 * EINVAL: The value specified by sched_actions is invalid
465 * Alternatively, in case of error the implementation is allowed to
466 * notify it to the system console and then terminate the FRSH
467 * implementation and dependant applications
469 int fosa_adsactions_add_timeout(fosa_ads_actions_t *sched_actions,
470 fosa_clock_id_t clock_id,
471 const fosa_abs_time_t *at_time)
477 * fosa_adsactions_add_thread_notification()
479 * Add a timed-thread-notification action
481 * This function adds a thread-notification action associated with the
482 * thread specified in the thread argument that will cause the
483 * notification_for_thread() scheduler operation to be invoked at the
484 * time specified by at_time. This operation shall be invoked when the
485 * clock specified by clock_id reaches the absolute time specified by
486 * the at_time argument. In particular, a cpu-time clock may be used
487 * for parameter clock_id.Only one thread-notification can be active
488 * for each thread and clock. Calling the function shall remove the
489 * former thread-notification, if any, that had been programmed for
490 * the same thread and clock. A value of NULL for parameter at_time is
491 * used to cancel a previous thread-notification, if any, for the
492 * thread specified by thread and the clock specified by clock_id.
494 * Returns 0 if successful; otherwise it returns an error code:
495 * ENOMEM: There is insufficient memory to add this action
496 * FOSA_EPOLICY: The thread specified by thread has its appscheduled
497 * attribute set to false,
498 * EINVAL: The value specified by sched_actions is invalid
500 * Alternatively, in case of error the implementation is allowed to
501 * notify it to the system console and then terminate the FRSH
502 * implementation and dependant applications
504 int fosa_adsactions_add_thread_notification(fosa_ads_actions_t *sched_actions,
505 fosa_thread_id_t thread,
506 fosa_clock_id_t clock_id,
507 const fosa_abs_time_t *at_time)
514 * fosa_ads_set_handled_signal_set()
516 * Specifiy the set of signals that will be handled by the application
519 * This function is used to dynamically set the set of signals that
520 * are handled by the application scheduler. When a signal included
521 * in this set is generated, the signal() primitive operation of the
522 * application scheduler shall be executed. When a signal in tis set
523 * is generated, it shall always imply the execution of the signal()
524 * primitive operation, regardless of whether that signal could be
525 * accepted by some other thread. Once the signal() primitive
526 * operation is executed the signal is consumed, so no signal handlers
527 * shall be executed and no threads using a sigwait operation shall
528 * return for that particular signal instance. For this function to
529 * succeed, it has to be called from a primitive operation of a
532 * Returns 0 if successful; otherwise it returns an error code:
533 * FOSA_EPOLICY: The function has not been called from a scheduler
534 * primitive operation
535 * EINVAL: The value specified by set is invalid
537 * Alternatively, in case of error the implementation is allowed to
538 * notify it to the system console and then terminate the FRSH
539 * implementation and dependant applications
541 int fosa_ads_set_handled_signal_set(fosa_signal_t set[], int size)
548 * fosa_signal_queue_scheduler()
550 * Queue a signal destinated to the scheduler
552 * This is a special case of fosa_signal_queue() in which the
553 * destinator is the scheduler itself. It is needed by the service
554 * thread to notify the results to the scheduler.
556 * The problem with this case is that, depending on the implementation,
557 * this call would be translated to a true signal or to a scheduler
558 * notification message.
560 * Besides for the scheduler we don't have always a destinator
561 * thread_id needed in fosa_signal_queue for OSE.
563 * So the fosa implementation will solve this issue internally.
565 * Returns 0 if successful; otherwise it returns an error code:
566 * FOSA_EINVAL: the signal specified by signal is not
567 * between FOSA_SIGNAL_MIN and FOSA_SIGNAL_MAX
569 * FOSA_EAGAIN: no resources are available to queue the signal; the
570 * maximum number of queued signals has been reached, or a
571 * systemwide resource limit has been exceeded
573 * Alternatively, in case of error the implementation is allowed to
574 * notify it to the system console and then terminate the FRSH
575 * implementation and dependant applications
577 int fosa_signal_queue_scheduler(fosa_signal_t signal, fosa_signal_info_t info)
583 * fosa_ads_invoke_withdata()
585 * Explicitly invoke the scheduler, with data
587 * This function can be used by any thread in the process to invoke
588 * the ads scheduler or to share data with it.
590 * If successful, the function shall cause the execution of the
591 * primitive operation explicit_call_with_data() of the ads scheduler
592 * with its thread parameter equal to the thread ID of the calling
593 * thread, and its msg_size parameter equal to msg_size. In addition,
594 * if msg_size is larger than zero, the function shall make available
595 * to the scheduler a memory area whose contents are identical to the
596 * memory area pointed to by msg in the msg parameter of the
597 * explicit_call_with_data() primitive operation (note that copying
598 * the information is not needed).
600 * The function shall not return until the system has finished
601 * execution of the explicit_call_with_data() primitive operation. If
602 * the reply argument is non NULL, the memory area pointed to by the
603 * reply parameter of explicit_call_with_data() primitive operation is
604 * copied into the memory area pointed to by reply, and its size is
605 * copied into the variable pointed to by reply_size. The size of the
606 * reply information is limited to the value FOSA_ADS_SCHEDINFO_MAX.
608 * The function shall fail if the size specified by msg_size is larger
609 * than FOSA_ADS_SCHEDINFO_MAX. The function shall fail if primitive
610 * operation explicit_call_with_data() is set to NULL for the ads
613 * Returns 0 if successful; otherwise it returns an error code:
614 * FOSA_EPOLICY: The function been called from inside a scheduler
615 * primitive operation
616 * EINVAL: The value of msg_size is less than zero or larger than
617 * FOSA_ADS_SCHEDINFO_MAX
618 * FOSA_EMASKED: The operation cannot be executed because the primitive
619 * operation explicit_call_with_data() is set to NULL
621 * Alternatively, in case of error the implementation is allowed to
622 * notify it to the system console and then terminate the FRSH
623 * implementation and dependant applications
625 int fosa_ads_invoke_withdata(const void *msg, size_t msg_size,
626 void *reply, size_t *reply_size)