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"
73 * @defgroup appdefsched Application Defined Scheduling
76 * This module defines the function and types for an abstraction of
77 * the Application Defined Scheduling.
84 /********************************
85 * Application-defined scheduling
86 ********************************/
89 * We make the following ASSUMPTIONS:
91 * - The ADS always executes in the user memory space, so we don't
92 * need to manage the memory space translation.
94 * - Only one application scheduler exists, so we don't need an
99 * fosa_ads_scheduler_create()
101 * Create the application defined scheduler
103 * The application defined scheduler is created with the primitive
104 * operations specified in the object pointed to by scheduler_ops.
106 * The clock used to read the time immediately before the invocation
107 * of each primitive operation, to be reported to the scheduler via
108 * the current_time parameter of each primitive operation is the
109 * FOSA_CLOCK_REALTIME clock.
111 * The scheduler_data_size parameter is used to request that a memory
112 * area of this size must be created and reserved for the scheduler to
113 * store its state. A pointer to this area is passed to the scheduler
114 * operations in the sched_data parameter.
116 * Parameter init_arg points to an area that contains configuration
117 * information for the scheduler. The function creates a memory area
118 * of init_arg_size bytes and copies into it the area pointed by
119 * arg. A pointer to this new created area will be passed to the
120 * primitive operation init() in its arg parameter.
122 * This function must be called before any other function in this
125 * In addition it must be called at a priority level no greater than
126 * the priority at which the scheduler operations execute. This
127 * priority is defined as the maximum SCHED_FIFO priority in the
128 * system minus the configuration parameter FOSA_ADS_SCHEDULER_PRIO_DIFF.
130 * Returns 0 if successful; otherwise it returns an error code:
132 * FOSA_EINVAL: The value of scheduler_ops was invalid \n
133 * FOSA_EAGAIN: The system lacks enough resources to create the
136 * Alternatively, in case of error the implementation is allowed to
137 * notify it to the system console and then terminate the FRSH
138 * implementation and dependant applications
140 int fosa_ads_scheduler_create
141 (const fosa_ads_scheduler_ops_t * scheduler_ops,
142 size_t scheduler_data_size,
144 size_t init_args_size);
147 * fosa_thread_attr_set_appscheduled()
149 * Set the appscheduled attribute of a thread attributes object
151 * This function is used to set the appscheduled attribute in the
152 * object pointed to by attr. This attribute controls the kind of
153 * scheduling used for threads created with it. If true, the thread is
154 * scheduled by the application scheduler. If not, it is scheduled by
155 * the system under a fixed priority scheduler
157 * Returns 0 if successful; otherwise it returns an error code:
159 * FOSA_EINVAL: The value of attr is invalid
161 * Alternatively, in case of error the implementation is allowed to
162 * notify it to the system console and then terminate the FRSH
163 * implementation and dependant applications
165 int fosa_thread_attr_set_appscheduled
166 (frsh_thread_attr_t *attr,
170 * fosa_thread_attr_get_appscheduled()
172 * Get the appscheduled attribute of a thread attributes object
174 * This function is used to get the appscheduled attribute in the
175 * object pointed to by attr. This attribute controls the kind of
176 * scheduling used for threads created with it. If true, the thread is
177 * scheduled by the application scheduler. If not, it is scheduled by
178 * the system under a fixed priority scheduler.
180 * Returns 0 if successful; otherwise it returns an error code:
182 * FOSA_EINVAL: The value of attr is invalid
184 * Alternatively, in case of error the implementation is allowed to
185 * notify it to the system console and then terminate the FRSH
186 * implementation and dependant applications
188 int fosa_thread_attr_get_appscheduled
189 (const frsh_thread_attr_t *attr,
193 * fosa_thread_attr_set_appsched_params()
195 * Set the appsched_param attribute of a thread attributes object
197 * This function is used to set the appsched_param attribute in the
198 * object pointed to by attr. For those threads with appscheduled set
199 * to true, this attribute represents the application-specific
200 * scheduling parameters. If successful, the function shall set the
201 * size of the appsched_param attribute to the value specified by
202 * paramsize, and shall copy the scheduling parameters occupying
203 * paramsize bytes and pointed to by param into that attribute
205 * Returns 0 if successful; otherwise it returns an error code:
207 * FOSA_EINVAL: The value of attr is invalid, or paramsize is less than
208 * zero or larger than FOSA_ADS_SCHEDPARAM_MAX
210 * Alternatively, in case of error the implementation is allowed to
211 * notify it to the system console and then terminate the FRSH
212 * implementation and dependant applications
214 int fosa_thread_attr_set_appsched_params
215 (frsh_thread_attr_t *attr,
220 * fosa_thread_attr_get_appsched_params()
222 * Get the appsched_param attribute of a thread attributes object
224 * This function is used to get the appsched_param attribute from the
225 * object pointed to by attr. For those threads with appscheduled set
226 * to true, this attribute represents the application-specific
227 * scheduling parameters. If successful, the function shall set the
228 * value pointed to by paramsize to the size of the appsched_param
229 * attribute, and shall copy the scheduling parameters occupying
230 * paramsize bytes into the variable pointed to by param. This
231 * variable should be capable of storing a number of bytes equal to
234 * Returns 0 if successful; otherwise it returns an error code:
236 * FOSA_EINVAL: The value of attr is invalid
238 * Alternatively, in case of error the implementation is allowed to
239 * notify it to the system console and then terminate the FRSH
240 * implementation and dependant applications
242 int fosa_thread_attr_get_appsched_params
243 (const frsh_thread_attr_t *attr,
248 * fosa_ads_set_appscheduled()
250 * Dynamically set the appscheduled attribute of a thread
252 * This function is used to dynamically set the appscheduled attribute
253 * of the thread identified by thread. This attribute controls the
254 * kind of scheduling used for threads created with it. If true, the
255 * thread is scheduled by the application scheduler. If not, it is
256 * scheduled by the system under a fixed priority scheduler.
258 * Returns 0 if successful; otherwise it returns an error code:
260 * FOSA_EINVAL: The value of thread is invalid
262 * FOSA_EREJECT: the attachment of the thread to the frsh schehduler
263 * was rejected by the frsh scheduler possibly because of
264 * incorrect attributes, or because the requested minimum
265 * capacity cannot be guaranteed
267 * Alternatively, in case of error the implementation is allowed to
268 * notify it to the system console and then terminate the FRSH
269 * implementation and dependant applications
271 int fosa_ads_set_appscheduled
272 (frsh_thread_id_t thread,
276 * fosa_ads_getappscheduled()
278 * Dynamically get the appscheduled attribute of a thread
280 * This function is used to dynamically get the appscheduled attribute
281 * of the thread identified by thread. This attribute controls the
282 * kind of scheduling used for threads created with it. If true, the
283 * thread is scheduled by the application scheduler. If not, it is
284 * scheduled by the system under a fixed priority scheduler
286 * Returns 0 if successful; otherwise it returns an error code:
288 * FOSA_EINVAL: The value of thread is invalid
290 * Alternatively, in case of error the implementation is allowed to
291 * notify it to the system console and then terminate the FRSH
292 * implementation and dependant applications
294 int fosa_ads_get_appscheduled
295 (frsh_thread_id_t thread,
300 * fosa_ads_setappschedparam()
302 * Dynamically set the appsched_param attribute of a thread
304 * This function is used to dynamically set the appsched_param
305 * attribute of the thread identified by thread. For those threads
306 * with appscheduled set to true, this attribute represents the
307 * application-specific scheduling parameters. If successful, the
308 * function shall set the size of the appsched_param attribute to the
309 * value specified by paramsize, and shall copy the scheduling
310 * parameters occupying paramsize bytes and pointed to by param into
313 * Returns 0 if successful; otherwise it returns an error code:
315 * FOSA_EINVAL: The value of thread is invalid, or paramsize is less than
316 * zero or larger than FOSA_ADS_SCHEDPARAM_MAX
318 * Alternatively, in case of error the implementation is allowed to
319 * notify it to the system console and then terminate the FRSH
320 * implementation and dependant applications
322 int fosa_ads_set_appsched_params
323 (frsh_thread_id_t thread,
328 * fosa_ads_get_appsched_params()
330 * Dynamically get the appsched_param attribute of a thread
332 * This function is used to dynamically get the appsched_param
333 * attribute of the thread identified by thread. For those threads
334 * with appscheduled set to true, this attribute represents the
335 * application-specific scheduling parameters. If successful, the
336 * function shall set the variable pointed to by paramsize to the size
337 * of the appsched_param attribute, and shall copy the scheduling
338 * parameters occupying paramsize bytes into the variable pointed to
339 * by param. This variable should be capable of storing a number of
340 * bytes equal to paramsize.
342 * Returns 0 if successful; otherwise it returns an error code:
344 * FOSA_EINVAL: The value of thread is invalid, or paramsize is less than
345 * zero or larger than FOSA_ADS_SCHEDPARAM_MAX
347 * Alternatively, in case of error the implementation is allowed to
348 * notify it to the system console and then terminate the FRSH
349 * implementation and dependant applications.
351 int fosa_ads_get_appsched_params
352 (frsh_thread_id_t thread,
357 /*********************************
360 * A scheduling actions object is used to specify a series of actions
361 * to be performed by the system at the end of a scheduler primitive
362 * operation. The order of the actions added to the object shall be
365 *********************************/
368 * fosa_adsactions_add_reject()
370 * Add a reject-thread action
372 * This function adds a thread-reject action to the object referenced
373 * by sched_actions, that will serve to notify that the thread
374 * identified by thread has not been accepted by the scheduler to be
375 * scheduled by it, possibly because the thread contained invalid
376 * application scheduling attributes, or because there are not enough
377 * resources for the new thread. At the end of the new_thread()
378 * scheduler primitive operation, the parent of the rejected thread
379 * waiting on a fosa_thread_create() or the rejected thread itself
380 * waiting on a fosa_ads_set_appscheduled() function shall complete the
381 * function with an error code of FOSA_EREJECT. If no reject-thread action
382 * is added during the new_thread() scheduler primitive operation, the
383 * thread is accepted to be scheduled by the scheduler and the
384 * associated fosa_thread_create() or the fosa_ads_set_appscheduled()
385 * function shall be completed without error. For the function to
386 * succeed, it has to be called from the new_thread() primitive
387 * operation and for the thread that is requesting attachment to the
390 * Returns 0 if successful; otherwise it returns an error code:
392 * FOSA_ENOMEM: There is insufficient memory to add this action \n
393 * FOSA_EPOLICY: The thread specified by thread is not the one requesting
394 * attachment to the scheduler, or the function is not being
395 * called from the new_thread primitive operation \n
396 * FOSA_EINVAL: The value specified by sched_actions is invalid \n
398 * Alternatively, in case of error the implementation is allowed to
399 * notify it to the system console and then terminate the FRSH
400 * implementation and dependant applications
402 int fosa_adsactions_add_reject(
403 fosa_ads_actions_t *sched_actions,
404 frsh_thread_id_t thread);
407 * fosa_adsactions_add_activate()
409 * Add a thread-activate action
411 * This function adds a thread-activate action to the object
412 * referenced by sched_actions. In case the thread had been previously
413 * suspended via posix_appsched_actions_addsuspend(), it will be
414 * activated at the end of the primitive operation.
416 * In those implementations that do not support urgency scheduling,
417 * the urgencu value is ignored. These implementations cannot support
418 * the frsh hierarchical scheduling module.
420 * In those implementations supporting urgency-scheduling, the action
421 * will cause the change of the urgency of the thread to the value
422 * specified in the urgency argument. Besides, if the thread was
423 * already active at the time the thread-activate action is executed,
424 * the change or urgency will imply a reordering of the thread in its
425 * priority queue, so that for threads of the same priority, those
426 * with more urgency will be scheduled before those of less urgency.
428 * Returns 0 if successful; otherwise it returns an error code:
430 * FOSA_ENOMEM: There is insufficient memory to add this action \n
431 * FOSA_EPOLICY: The thread specified by thread has its appscheduled
432 * attribute set to false \n
433 * FOSA_EINVAL: The value specified by sched_actions is invalid \n
435 * Alternatively, in case of error the implementation is allowed to
436 * notify it to the system console and then terminate the FRSH
437 * implementation and dependant applications
439 int fosa_adsactions_add_activate(
440 fosa_ads_actions_t *sched_actions,
441 frsh_thread_id_t thread,
442 fosa_ads_urgency_t urgency);
445 * fosa_adsactions_add_suspend()
447 * Add a thread-suspend action
449 * This function adds a thread-suspend action to the object referenced
450 * by sched_actions, that will cause the thread identified by thread
451 * to be suspended waiting for a thread-activate action at the end of
452 * the scheduler operation. If the thread was already waiting for a
453 * thread-activate action the thread-suspend action has no effect. It
454 * is an error trying to suspend a thread that is blocked by the
457 * Returns 0 if successful; otherwise it returns an error code:
459 * FOSA_ENOMEM: There is insufficient memory to add this action \n
460 * FOSA_EPOLICY: The thread specified by thread has its appscheduled
461 * attribute set to false \n
462 * FOSA_EINVAL: The value specified by sched_actions is invalid \n
464 * Alternatively, in case of error the implementation is allowed to
465 * notify it to the system console and then terminate the FRSH
466 * implementation and dependant applications
468 int fosa_adsactions_add_suspend(
469 fosa_ads_actions_t *sched_actions,
470 frsh_thread_id_t thread);
473 * fosa_adsactions_add_timeout()
475 * Add a timeout action
477 * This function adds a timeout action to the object referenced by
478 * sched_actions, that will cause the timeout() scheduler operation to
479 * be invoked if no other scheduler operation is invoked before
480 * timeout expires. The timeout shall expire when the clock specified by
481 * clock_id reaches the absolute time specified by the at_time
484 * Returns 0 if successful; otherwise it returns an error code:
486 * FOSA_ENOMEM: There is insufficient memory to add this action \n
487 * FOSA_EINVAL: The value specified by sched_actions is invalid \n
489 * Alternatively, in case of error the implementation is allowed to
490 * notify it to the system console and then terminate the FRSH
491 * implementation and dependant applications
493 int fosa_adsactions_add_timeout(
494 fosa_ads_actions_t *sched_actions,
495 fosa_clock_id_t clock_id,
496 const struct timespec *at_time);
499 * fosa_adsactions_add_thread_notification()
501 * Add a timed-thread-notification action
503 * This function adds a thread-notification action associated with the
504 * thread specified in the thread argument that will cause the
505 * notification_for_thread() scheduler operation to be invoked at the
506 * time specified by at_time. This operation shall be invoked when the
507 * clock specified by clock_id reaches the absolute time specified by
508 * the at_time argument. In particular, a cpu-time clock may be used
509 * for parameter clock_id.Only one thread-notification can be active
510 * for each thread and clock. Calling the function shall remove the
511 * former thread-notification, if any, that had been programmed for
512 * the same thread and clock. A value of NULL for parameter at_time is
513 * used to cancel a previous thread-notification, if any, for the
514 * thread specified by thread and the clock specified by clock_id.
516 * Returns 0 if successful; otherwise it returns an error code:
518 * FOSA_ENOMEM: There is insufficient memory to add this action \n
519 * FOSA_EPOLICY: The thread specified by thread has its appscheduled
520 * attribute set to false \n
521 * FOSA_EINVAL: The value specified by sched_actions is invalid \n
523 * Alternatively, in case of error the implementation is allowed to
524 * notify it to the system console and then terminate the FRSH
525 * implementation and dependant applications
527 int fosa_adsactions_add_thread_notification(
528 fosa_ads_actions_t *sched_actions,
529 frsh_thread_id_t thread,
530 fosa_clock_id_t clock_id,
531 const struct timespec *at_time);
535 * fosa_ads_set_handled_signal_set()
537 * Specifiy the set of signals that will be handled by the application
540 * This function is used to dynamically set the set of signals that
541 * are handled by the application scheduler. When a signal included
542 * in this set is generated, the signal() primitive operation of the
543 * application scheduler shall be executed. When a signal in tis set
544 * is generated, it shall always imply the execution of the signal()
545 * primitive operation, regardless of whether that signal could be
546 * accepted by some other thread. Once the signal() primitive
547 * operation is executed the signal is consumed, so no signal handlers
548 * shall be executed and no threads using a sigwait operation shall
549 * return for that particular signal instance. For this function to
550 * succeed, it has to be called from a primitive operation of a
553 * The size of the array is specified by argument size.
555 * Returns 0 if successful; otherwise it returns an error code:
557 * FOSA_EPOLICY: The function has not been called from a scheduler
558 * primitive operation \n
559 * FOSA_EINVAL: The value specified by set is invalid \n
561 * Alternatively, in case of error the implementation is allowed to
562 * notify it to the system console and then terminate the FRSH
563 * implementation and dependant applications
565 int fosa_ads_set_handled_signal_set(frsh_signal_t set[], int size);
569 * fosa_signal_queue_scheduler()
571 * Queue a signal destinated to the scheduler
573 * This is a special case of fosa_signal_queue() in which the
574 * destinator is the scheduler itself. It is needed by the service
575 * thread to notify the results to the scheduler.
577 * The problem with this case is that, depending on the implementation,
578 * this call would be translated to a true signal or to a scheduler
579 * notification message.
581 * Besides for the scheduler we don't have always a destinator
582 * thread_id needed in frsh_signal_queue for OSE.
584 * So the fosa implementation will solve this issue internally.
586 * Returns 0 if successful; otherwise it returns an error code:
587 * FOSA_EINVAL: the signal specified by signal is not
588 * between FOSA_SIGNAL_MIN and FOSA_SIGNAL_MAX
590 * FOSA_EAGAIN: no resources are available to queue the signal; the
591 * maximum number of queued signals has been reached, or a
592 * systemwide resource limit has been exceeded
594 * Alternatively, in case of error the implementation is allowed to
595 * notify it to the system console and then terminate the FRSH
596 * implementation and dependant applications
598 int fosa_signal_queue_scheduler(frsh_signal_t signal, frsh_signal_info_t info);
602 * fosa_ads_invoke_withdata()
604 * Explicitly invoke the scheduler, with data
606 * This function can be used by any thread in the process to invoke
607 * the ads scheduler or to share data with it.
609 * If successful, the function shall cause the execution of the
610 * primitive operation explicit_call_with_data() of the ads scheduler
611 * with its thread parameter equal to the thread ID of the calling
612 * thread, and its msg_size parameter equal to msg_size. In addition,
613 * if msg_size is larger than zero, the function shall make available
614 * to the scheduler a memory area whose contents are identical to the
615 * memory area pointed to by msg in the msg parameter of the
616 * explicit_call_with_data() primitive operation (note that copying
617 * the information is not needed).
619 * The function shall not return until the system has finished
620 * execution of the explicit_call_with_data() primitive operation. If
621 * the reply argument is non NULL, the memory area pointed to by the
622 * reply parameter of explicit_call_with_data() primitive operation is
623 * copied into the memory area pointed to by reply, and its size is
624 * copied into the variable pointed to by reply_size. The size of the
625 * reply information is limited to the value FOSA_ADS_SCHEDINFO_MAX.
627 * The function shall fail if the size specified by msg_size is larger
628 * than FOSA_ADS_SCHEDINFO_MAX. The function shall fail if primitive
629 * operation explicit_call_with_data() is set to NULL for the ads
632 * Returns 0 if successful; otherwise it returns an error code:
634 * FOSA_EPOLICY: The function been called from inside a scheduler
635 * primitive operation \n
636 * FOSA_EINVAL: The value of msg_size is less than zero or larger than
637 * FOSA_ADS_SCHEDINFO_MAX \n
638 * FOSA_EMASKED: The operation cannot be executed because the primitive
639 * operation explicit_call_with_data() is set to NULL \n
641 * Alternatively, in case of error the implementation is allowed to
642 * notify it to the system console and then terminate the FRSH
643 * implementation and dependant applications
645 int fosa_ads_invoke_withdata
646 (const void *msg, size_t msg_size, void *reply, size_t *reply_size);
651 #endif /* !FOSA_APP_DEF_SCHED_H_ */