1 //----------------------------------------------------------------------
2 // Copyright (C) 2006 - 2007 by the FRESCOR consortium:
4 // Universidad de Cantabria, SPAIN
5 // University of York, UK
6 // Scuola Superiore Sant'Anna, ITALY
7 // Kaiserslautern University, GERMANY
8 // Univ. Politecnica 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
18 // The 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 // This file is part of FOSA (Frsh Operating System Abstraction)
33 // FOSA is free software; you can redistribute it and/or modify it
34 // under terms of the GNU General Public License as published by the
35 // Free Software Foundation; either version 2, or (at your option) any
36 // later version. FOSA is distributed in the hope that it will be
37 // useful, but WITHOUT ANY WARRANTY; without even the implied warranty
38 // of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
39 // General Public License for more details. You should have received a
40 // copy of the GNU General Public License along with FOSA; see file
41 // COPYING. If not, write to the Free Software Foundation, 675 Mass Ave,
42 // Cambridge, MA 02139, USA.
44 // As a special exception, including FOSA header files in a file,
45 // instantiating FOSA generics or templates, or linking other files
46 // with FOSA objects to produce an executable application, does not
47 // by itself cause the resulting executable application to be covered
48 // by the GNU General Public License. This exception does not
49 // however invalidate any other reasons why the executable file might be
50 // covered by the GNU Public License.
51 // -----------------------------------------------------------------------
52 //fosa_app_def_sched.h
53 //==============================================
54 // ******** ****** ******** **********
55 // **///// /** ** **////// /** /**
56 // ** /** ** /** /** /**
57 // ******* /** ** /********* /**********
58 // **//// /** ** ////////** /**//////**
59 // ** /** ** /** /** /**
60 // ** /** ** ******** /** /**
61 // // /******/ //////// // //
63 // FOSA(Frescor Operating System Adaptation layer)
64 //================================================
67 #ifndef FOSA_APP_DEF_SCHED_H_
68 #define FOSA_APP_DEF_SCHED_H_
70 #include "fosa_types.h"
75 * @defgroup appdefsched Application Defined Scheduling
78 * This module defines the function and types for an abstraction of
79 * the Application Defined Scheduling.
86 /********************************
87 * Application-defined scheduling
88 ********************************/
91 * We make the following ASSUMPTIONS:
93 * - The ADS always executes in the user memory space, so we don't
94 * need to manage the memory space translation.
96 * - Only one application scheduler exists, so we don't need an
101 * fosa_ads_scheduler_create()
103 * Create the application defined scheduler
105 * The application defined scheduler is created with the primitive
106 * operations specified in the object pointed to by scheduler_ops.
108 * The clock used to read the time immediately before the invocation
109 * of each primitive operation, to be reported to the scheduler via
110 * the current_time parameter of each primitive operation is the
111 * FOSA_CLOCK_REALTIME clock.
113 * The scheduler_data_size parameter is used to request that a memory
114 * area of this size must be created and reserved for the scheduler to
115 * store its state. A pointer to this area is passed to the scheduler
116 * operations in the sched_data parameter.
118 * Parameter init_arg points to an area that contains configuration
119 * information for the scheduler. The function creates a memory area
120 * of init_arg_size bytes and copies into it the area pointed by
121 * arg. A pointer to this new created area will be passed to the
122 * primitive operation init() in its arg parameter.
124 * This function must be called before any other function in this
127 * In addition it must be called at a priority level no greater than
128 * the priority at which the scheduler operations execute. This
129 * priority is defined as the maximum SCHED_FIFO priority in the
130 * system minus the configuration parameter FOSA_ADS_SCHEDULER_PRIO_DIFF.
132 * Returns 0 if successful; otherwise it returns an error code:
134 * FOSA_EINVAL: The value of scheduler_ops was invalid \n
135 * FOSA_EAGAIN: The system lacks enough resources to create the
138 * Alternatively, in case of error the implementation is allowed to
139 * notify it to the system console and then terminate the FRSH
140 * implementation and dependant applications
142 int fosa_ads_scheduler_create
143 (const fosa_ads_scheduler_ops_t * scheduler_ops,
144 size_t scheduler_data_size,
146 size_t init_args_size);
149 * fosa_thread_attr_set_appscheduled()
151 * Set the appscheduled attribute of a thread attributes object
153 * This function is used to set the appscheduled attribute in the
154 * object pointed to by attr. This attribute controls the kind of
155 * scheduling used for threads created with it. If true, the thread is
156 * scheduled by the application scheduler. If not, it is scheduled by
157 * the system under a fixed priority scheduler
159 * Returns 0 if successful; otherwise it returns an error code:
161 * FOSA_EINVAL: The value of attr is invalid
163 * Alternatively, in case of error the implementation is allowed to
164 * notify it to the system console and then terminate the FRSH
165 * implementation and dependant applications
167 int fosa_thread_attr_set_appscheduled
168 (fosa_thread_attr_t *attr,
172 * fosa_thread_attr_get_appscheduled()
174 * Get the appscheduled attribute of a thread attributes object
176 * This function is used to get the appscheduled attribute in the
177 * object pointed to by attr. This attribute controls the kind of
178 * scheduling used for threads created with it. If true, the thread is
179 * scheduled by the application scheduler. If not, it is scheduled by
180 * the system under a fixed priority scheduler.
182 * Returns 0 if successful; otherwise it returns an error code:
184 * FOSA_EINVAL: The value of attr is invalid
186 * Alternatively, in case of error the implementation is allowed to
187 * notify it to the system console and then terminate the FRSH
188 * implementation and dependant applications
190 int fosa_thread_attr_get_appscheduled
191 (const fosa_thread_attr_t *attr,
195 * fosa_thread_attr_set_appsched_params()
197 * Set the appsched_param attribute of a thread attributes object
199 * This function is used to set the appsched_param attribute in the
200 * object pointed to by attr. For those threads with appscheduled set
201 * to true, this attribute represents the application-specific
202 * scheduling parameters. If successful, the function shall set the
203 * size of the appsched_param attribute to the value specified by
204 * paramsize, and shall copy the scheduling parameters occupying
205 * paramsize bytes and pointed to by param into that attribute
207 * Returns 0 if successful; otherwise it returns an error code:
209 * FOSA_EINVAL: The value of attr is invalid, or paramsize is less than
210 * zero or larger than FOSA_ADS_SCHEDPARAM_MAX
212 * Alternatively, in case of error the implementation is allowed to
213 * notify it to the system console and then terminate the FRSH
214 * implementation and dependant applications
216 int fosa_thread_attr_set_appsched_params
217 (fosa_thread_attr_t *attr,
222 * fosa_thread_attr_get_appsched_params()
224 * Get the appsched_param attribute of a thread attributes object
226 * This function is used to get the appsched_param attribute from the
227 * object pointed to by attr. For those threads with appscheduled set
228 * to true, this attribute represents the application-specific
229 * scheduling parameters. If successful, the function shall set the
230 * value pointed to by paramsize to the size of the appsched_param
231 * attribute, and shall copy the scheduling parameters occupying
232 * paramsize bytes into the variable pointed to by param. This
233 * variable should be capable of storing a number of bytes equal to
236 * Returns 0 if successful; otherwise it returns an error code:
238 * FOSA_EINVAL: The value of attr is invalid
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_thread_attr_get_appsched_params
245 (const fosa_thread_attr_t *attr,
250 * fosa_ads_set_appscheduled()
252 * Dynamically set the appscheduled attribute of a thread
254 * This function is used to dynamically set 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:
262 * FOSA_EINVAL: The value of thread is invalid
264 * FOSA_EREJECT: the attachment of the thread to the frsh schehduler
265 * was rejected by the frsh scheduler possibly because of
266 * incorrect attributes, or because the requested minimum
267 * capacity cannot be guaranteed
269 * Alternatively, in case of error the implementation is allowed to
270 * notify it to the system console and then terminate the FRSH
271 * implementation and dependant applications
273 int fosa_ads_set_appscheduled
274 (fosa_thread_id_t thread,
278 * fosa_ads_getappscheduled()
280 * Dynamically get the appscheduled attribute of a thread
282 * This function is used to dynamically get the appscheduled attribute
283 * of the thread identified by thread. This attribute controls the
284 * kind of scheduling used for threads created with it. If true, the
285 * thread is scheduled by the application scheduler. If not, it is
286 * scheduled by the system under a fixed priority scheduler
288 * Returns 0 if successful; otherwise it returns an error code:
290 * FOSA_EINVAL: The value of thread is invalid
292 * Alternatively, in case of error the implementation is allowed to
293 * notify it to the system console and then terminate the FRSH
294 * implementation and dependant applications
296 int fosa_ads_get_appscheduled
297 (fosa_thread_id_t thread,
302 * fosa_ads_setappschedparam()
304 * Dynamically set the appsched_param attribute of a thread
306 * This function is used to dynamically set 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 size of the appsched_param attribute to the
311 * value specified by paramsize, and shall copy the scheduling
312 * parameters occupying paramsize bytes and pointed to by param into
315 * Returns 0 if successful; otherwise it returns an error code:
317 * FOSA_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_set_appsched_params
325 (fosa_thread_id_t thread,
330 * fosa_ads_get_appsched_params()
332 * Dynamically get the appsched_param attribute of a thread
334 * This function is used to dynamically get the appsched_param
335 * attribute of the thread identified by thread. For those threads
336 * with appscheduled set to true, this attribute represents the
337 * application-specific scheduling parameters. If successful, the
338 * function shall set the variable pointed to by paramsize to the size
339 * of the appsched_param attribute, and shall copy the scheduling
340 * parameters occupying paramsize bytes into the variable pointed to
341 * by param. This variable should be capable of storing a number of
342 * bytes equal to paramsize.
344 * Returns 0 if successful; otherwise it returns an error code:
346 * FOSA_EINVAL: The value of thread is invalid, or paramsize is less than
347 * zero or larger than FOSA_ADS_SCHEDPARAM_MAX
349 * Alternatively, in case of error the implementation is allowed to
350 * notify it to the system console and then terminate the FRSH
351 * implementation and dependant applications.
353 int fosa_ads_get_appsched_params
354 (fosa_thread_id_t thread,
359 /*********************************
362 * A scheduling actions object is used to specify a series of actions
363 * to be performed by the system at the end of a scheduler primitive
364 * operation. The order of the actions added to the object shall be
367 *********************************/
370 * fosa_adsactions_add_reject()
372 * Add a reject-thread action
374 * This function adds a thread-reject action to the object referenced
375 * by sched_actions, that will serve to notify that the thread
376 * identified by thread has not been accepted by the scheduler to be
377 * scheduled by it, possibly because the thread contained invalid
378 * application scheduling attributes, or because there are not enough
379 * resources for the new thread. At the end of the new_thread()
380 * scheduler primitive operation, the parent of the rejected thread
381 * waiting on a fosa_thread_create() or the rejected thread itself
382 * waiting on a fosa_ads_set_appscheduled() function shall complete the
383 * function with an error code of FOSA_EREJECT. If no reject-thread action
384 * is added during the new_thread() scheduler primitive operation, the
385 * thread is accepted to be scheduled by the scheduler and the
386 * associated fosa_thread_create() or the fosa_ads_set_appscheduled()
387 * function shall be completed without error. For the function to
388 * succeed, it has to be called from the new_thread() primitive
389 * operation and for the thread that is requesting attachment to the
392 * Returns 0 if successful; otherwise it returns an error code:
394 * FOSA_ENOMEM: There is insufficient memory to add this action \n
395 * FOSA_EPOLICY: The thread specified by thread is not the one requesting
396 * attachment to the scheduler, or the function is not being
397 * called from the new_thread primitive operation \n
398 * FOSA_EINVAL: The value specified by sched_actions is invalid \n
400 * Alternatively, in case of error the implementation is allowed to
401 * notify it to the system console and then terminate the FRSH
402 * implementation and dependant applications
404 int fosa_adsactions_add_reject(
405 fosa_ads_actions_t *sched_actions,
406 fosa_thread_id_t thread);
409 * fosa_adsactions_add_activate()
411 * Add a thread-activate action
413 * This function adds a thread-activate action to the object
414 * referenced by sched_actions. In case the thread had been previously
415 * suspended via posix_appsched_actions_addsuspend(), it will be
416 * activated at the end of the primitive operation.
418 * In those implementations that do not support urgency scheduling,
419 * the urgencu value is ignored. These implementations cannot support
420 * the frsh hierarchical scheduling module.
422 * In those implementations supporting urgency-scheduling, the action
423 * will cause the change of the urgency of the thread to the value
424 * specified in the urgency argument. Besides, if the thread was
425 * already active at the time the thread-activate action is executed,
426 * the change or urgency will imply a reordering of the thread in its
427 * priority queue, so that for threads of the same priority, those
428 * with more urgency will be scheduled before those of less urgency.
430 * Returns 0 if successful; otherwise it returns an error code:
432 * FOSA_ENOMEM: There is insufficient memory to add this action \n
433 * FOSA_EPOLICY: The thread specified by thread has its appscheduled
434 * attribute set to false \n
435 * FOSA_EINVAL: The value specified by sched_actions is invalid \n
437 * Alternatively, in case of error the implementation is allowed to
438 * notify it to the system console and then terminate the FRSH
439 * implementation and dependant applications
441 int fosa_adsactions_add_activate(
442 fosa_ads_actions_t *sched_actions,
443 fosa_thread_id_t thread,
444 fosa_ads_urgency_t urgency);
447 * fosa_adsactions_add_suspend()
449 * Add a thread-suspend action
451 * This function adds a thread-suspend action to the object referenced
452 * by sched_actions, that will cause the thread identified by thread
453 * to be suspended waiting for a thread-activate action at the end of
454 * the scheduler operation. If the thread was already waiting for a
455 * thread-activate action the thread-suspend action has no effect. It
456 * is an error trying to suspend a thread that is blocked by the
459 * Returns 0 if successful; otherwise it returns an error code:
461 * FOSA_ENOMEM: There is insufficient memory to add this action \n
462 * FOSA_EPOLICY: The thread specified by thread has its appscheduled
463 * attribute set to false \n
464 * FOSA_EINVAL: The value specified by sched_actions is invalid \n
466 * Alternatively, in case of error the implementation is allowed to
467 * notify it to the system console and then terminate the FRSH
468 * implementation and dependant applications
470 int fosa_adsactions_add_suspend(
471 fosa_ads_actions_t *sched_actions,
472 fosa_thread_id_t thread);
475 * fosa_adsactions_add_timeout()
477 * Add a timeout action
479 * This function adds a timeout action to the object referenced by
480 * sched_actions, that will cause the timeout() scheduler operation to
481 * be invoked if no other scheduler operation is invoked before
482 * timeout expires. The timeout shall expire when the clock specified by
483 * clock_id reaches the absolute time specified by the at_time
486 * Returns 0 if successful; otherwise it returns an error code:
488 * FOSA_ENOMEM: There is insufficient memory to add this action \n
489 * FOSA_EINVAL: The value specified by sched_actions is invalid \n
491 * Alternatively, in case of error the implementation is allowed to
492 * notify it to the system console and then terminate the FRSH
493 * implementation and dependant applications
495 int fosa_adsactions_add_timeout(
496 fosa_ads_actions_t *sched_actions,
497 fosa_clock_id_t clock_id,
498 const fosa_abs_time_t *at_time);
501 * fosa_adsactions_add_thread_notification()
503 * Add a timed-thread-notification action
505 * This function adds a thread-notification action associated with the
506 * thread specified in the thread argument that will cause the
507 * notification_for_thread() scheduler operation to be invoked at the
508 * time specified by at_time. This operation shall be invoked when the
509 * clock specified by clock_id reaches the absolute time specified by
510 * the at_time argument. In particular, a cpu-time clock may be used
511 * for parameter clock_id.Only one thread-notification can be active
512 * for each thread and clock. Calling the function shall remove the
513 * former thread-notification, if any, that had been programmed for
514 * the same thread and clock. A value of NULL for parameter at_time is
515 * used to cancel a previous thread-notification, if any, for the
516 * thread specified by thread and the clock specified by clock_id.
518 * Returns 0 if successful; otherwise it returns an error code:
520 * FOSA_ENOMEM: There is insufficient memory to add this action \n
521 * FOSA_EPOLICY: The thread specified by thread has its appscheduled
522 * attribute set to false \n
523 * FOSA_EINVAL: The value specified by sched_actions is invalid \n
525 * Alternatively, in case of error the implementation is allowed to
526 * notify it to the system console and then terminate the FRSH
527 * implementation and dependant applications
529 int fosa_adsactions_add_thread_notification(
530 fosa_ads_actions_t *sched_actions,
531 fosa_thread_id_t thread,
532 fosa_clock_id_t clock_id,
533 const fosa_abs_time_t *at_time);
537 * fosa_ads_set_handled_signal_set()
539 * Specifiy the set of signals that will be handled by the application
542 * This function is used to dynamically set the set of signals that
543 * are handled by the application scheduler. When a signal included
544 * in this set is generated, the signal() primitive operation of the
545 * application scheduler shall be executed. When a signal in tis set
546 * is generated, it shall always imply the execution of the signal()
547 * primitive operation, regardless of whether that signal could be
548 * accepted by some other thread. Once the signal() primitive
549 * operation is executed the signal is consumed, so no signal handlers
550 * shall be executed and no threads using a sigwait operation shall
551 * return for that particular signal instance. For this function to
552 * succeed, it has to be called from a primitive operation of a
555 * The size of the array is specified by argument size.
557 * Returns 0 if successful; otherwise it returns an error code:
559 * FOSA_EPOLICY: The function has not been called from a scheduler
560 * primitive operation \n
561 * FOSA_EINVAL: The value specified by set is invalid \n
563 * Alternatively, in case of error the implementation is allowed to
564 * notify it to the system console and then terminate the FRSH
565 * implementation and dependant applications
567 int fosa_ads_set_handled_signal_set(fosa_signal_t set[], int size);
571 * fosa_signal_queue_scheduler()
573 * Queue a signal destinated to the scheduler
575 * This is a special case of fosa_signal_queue() in which the
576 * destinator is the scheduler itself. It is needed by the service
577 * thread to notify the results to the scheduler.
579 * The problem with this case is that, depending on the implementation,
580 * this call would be translated to a true signal or to a scheduler
581 * notification message.
583 * Besides for the scheduler we don't have always a destinator
584 * thread_id needed in fosa_signal_queue for OSE.
586 * So the fosa implementation will solve this issue internally.
588 * Returns 0 if successful; otherwise it returns an error code:
589 * FOSA_EINVAL: the signal specified by signal is not
590 * between FOSA_SIGNAL_MIN and FOSA_SIGNAL_MAX
592 * FOSA_EAGAIN: no resources are available to queue the signal; the
593 * maximum number of queued signals has been reached, or a
594 * systemwide resource limit has been exceeded
596 * Alternatively, in case of error the implementation is allowed to
597 * notify it to the system console and then terminate the FRSH
598 * implementation and dependant applications
600 int fosa_signal_queue_scheduler(fosa_signal_t signal, fosa_signal_info_t info);
604 * fosa_ads_invoke_withdata()
606 * Explicitly invoke the scheduler, with data
608 * This function can be used by any thread in the process to invoke
609 * the ads scheduler or to share data with it.
611 * If successful, the function shall cause the execution of the
612 * primitive operation explicit_call_with_data() of the ads scheduler
613 * with its thread parameter equal to the thread ID of the calling
614 * thread, and its msg_size parameter equal to msg_size. In addition,
615 * if msg_size is larger than zero, the function shall make available
616 * to the scheduler a memory area whose contents are identical to the
617 * memory area pointed to by msg in the msg parameter of the
618 * explicit_call_with_data() primitive operation (note that copying
619 * the information is not needed).
621 * The function shall not return until the system has finished
622 * execution of the explicit_call_with_data() primitive operation. If
623 * the reply argument is non NULL, the memory area pointed to by the
624 * reply parameter of explicit_call_with_data() primitive operation is
625 * copied into the memory area pointed to by reply, and its size is
626 * copied into the variable pointed to by reply_size. The size of the
627 * reply information is limited to the value FOSA_ADS_SCHEDINFO_MAX.
629 * The function shall fail if the size specified by msg_size is larger
630 * than FOSA_ADS_SCHEDINFO_MAX. The function shall fail if primitive
631 * operation explicit_call_with_data() is set to NULL for the ads
634 * Returns 0 if successful; otherwise it returns an error code:
636 * FOSA_EPOLICY: The function been called from inside a scheduler
637 * primitive operation \n
638 * FOSA_EINVAL: The value of msg_size is less than zero or larger than
639 * FOSA_ADS_SCHEDINFO_MAX \n
640 * FOSA_EMASKED: The operation cannot be executed because the primitive
641 * operation explicit_call_with_data() is set to NULL \n
643 * Alternatively, in case of error the implementation is allowed to
644 * notify it to the system console and then terminate the FRSH
645 * implementation and dependant applications
647 int fosa_ads_invoke_withdata
648 (const void *msg, size_t msg_size, void *reply, size_t *reply_size);
654 #endif /* !FOSA_APP_DEF_SCHED_H_ */