1 // -----------------------------------------------------------------------
2 // Copyright (C) 2006 - 2007 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. 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 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
23 // This file is part of the FRSH implementation
25 // FRSH is free software; you can redistribute it and/or modify
26 // it under the terms of the GNU General Public License as published by
27 // the Free Software Foundation; either version 2, or (at your option)
30 // FRSH is distributed in the hope that it will be useful, but
31 // WITHOUT ANY WARRANTY; without even the implied warranty of
32 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
33 // General Public License for more details.
35 // You should have received a copy of the GNU General Public License
36 // distributed with FRSH; see file COPYING. If not, write to the
37 // Free Software Foundation, 59 Temple Place - Suite 330, Boston, MA
40 // As a special exception, if you include this header file into source
41 // files to be compiled, this header file does not by itself cause
42 // the resulting executable to be covered by the GNU General Public
43 // License. This exception does not however invalidate any other
44 // reasons why the executable file might be covered by the GNU General
46 // -----------------------------------------------------------------------
47 //fosa_app_def_sched.h
48 //==============================================
49 // ******** ****** ******** **********
50 // **///// /** ** **////// /** /**
51 // ** /** ** /** /** /**
52 // ******* /** ** /********* /**********
53 // **//// /** ** ////////** /**//////**
54 // ** /** ** /** /** /**
55 // ** /** ** ******** /** /**
56 // // /******/ //////// // //
58 // FOSA(Frescor Operating System Adaptation layer)
59 //================================================
62 #ifndef FOSA_APP_DEF_SCHED_H_
63 #define FOSA_APP_DEF_SCHED_H_
66 * @defgroup appdefsched Application Defined Scheduling
69 * This module defines the function and types for an abstraction of
70 * the Application Defined Scheduling.
77 /********************************
78 * Application-defined scheduling
79 ********************************/
82 * We make the following ASSUMPTIONS:
84 * - The ADS always executes in the user memory space, so we don't
85 * need to manage the memory space translation.
87 * - Only one application scheduler exists, so we don't need an
92 * fosa_ads_scheduler_create()
94 * Create the application defined scheduler
96 * The application defined scheduler is created with the primitive
97 * operations specified in the object pointed to by scheduler_ops.
99 * The clock used to read the time immediately before the invocation
100 * of each primitive operation, to be reported to the scheduler via
101 * the current_time parameter of each primitive operation is the
102 * FOSA_CLOCK_REALTIME clock.
104 * The scheduler_data_size parameter is used to request that a memory
105 * area of this size must be created and reserved for the scheduler to
106 * store its state. A pointer to this area is passed to the scheduler
107 * operations in the sched_data parameter.
109 * Parameter init_arg points to an area that contains configuration
110 * information for the scheduler. The function creates a memory area
111 * of init_arg_size bytes and copies into it the area pointed by
112 * arg. A pointer to this new created area will be passed to the
113 * primitive operation init() in its arg parameter.
115 * Returns 0 if successful; otherwise it returns an error code:
116 * EINVAL: The value of scheduler_ops was invalid
117 * EAGAIN: The system lacks enough resources to create the scheduler
119 * Alternatively, in case of error the implementation is allowed to
120 * notify it to the system console and then terminate the FRSH
121 * implementation and dependant applications
123 int fosa_ads_scheduler_create
124 (const fosa_ads_scheduler_ops_t * scheduler_ops,
125 size_t scheduler_data_size,
127 size_t init_args_size);
130 * fosa_thread_attr_set_appscheduled()
132 * Set the appscheduled attribute of a thread attributes object
134 * This function is used to set the appscheduled attribute in the
135 * object pointed to by attr. This attribute controls the kind of
136 * scheduling used for threads created with it. If true, the thread is
137 * scheduled by the application scheduler. If not, it is scheduled by
138 * the system under a fixed priority scheduler
140 * Returns 0 if successful; otherwise it returns an error code:
141 * EINVAL: The value of attr is invalid
143 * Alternatively, in case of error the implementation is allowed to
144 * notify it to the system console and then terminate the FRSH
145 * implementation and dependant applications
147 int fosa_thread_attr_set_appscheduled
148 (frsh_thread_attr_t *attr,
152 * fosa_thread_attr_get_appscheduled()
154 * Get the appscheduled attribute of a thread attributes object
156 * This function is used to get the appscheduled attribute in the
157 * object pointed to by attr. This attribute controls the kind of
158 * scheduling used for threads created with it. If true, the thread is
159 * scheduled by the application scheduler. If not, it is scheduled by
160 * the system under a fixed priority scheduler.
162 * Returns 0 if successful; otherwise it returns an error code:
163 * EINVAL: The value of attr is invalid
165 * Alternatively, in case of error the implementation is allowed to
166 * notify it to the system console and then terminate the FRSH
167 * implementation and dependant applications
169 int fosa_thread_attr_get_appscheduled
170 (const frsh_thread_attr_t *attr,
174 * fosa_thread_attr_set_appsched_params()
176 * Set the appsched_param attribute of a thread attributes object
178 * This function is used to set the appsched_param attribute in the
179 * object pointed to by attr. For those threads with appscheduled set
180 * to true, this attribute represents the application-specific
181 * scheduling parameters. If successful, the function shall set the
182 * size of the appsched_param attribute to the value specified by
183 * paramsize, and shall copy the scheduling parameters occupying
184 * paramsize bytes and pointed to by param into that attribute
186 * Returns 0 if successful; otherwise it returns an error code:
187 * EINVAL: The value of attr is invalid, or paramsize is less than
188 * zero or larger than FOSA_ADS_SCHEDPARAM_MAX
190 * Alternatively, in case of error the implementation is allowed to
191 * notify it to the system console and then terminate the FRSH
192 * implementation and dependant applications
194 int fosa_thread_attr_set_appsched_params
195 (frsh_thread_attr_t *attr,
200 * fosa_thread_attr_get_appsched_params()
202 * Get the appsched_param attribute of a thread attributes object
204 * This function is used to get the appsched_param attribute from the
205 * object pointed to by attr. For those threads with appscheduled set
206 * to true, this attribute represents the application-specific
207 * scheduling parameters. If successful, the function shall set the
208 * value pointed to by paramsize to the size of the appsched_param
209 * attribute, and shall copy the scheduling parameters occupying
210 * paramsize bytes into the variable pointed to by param. This
211 * variable should be capable of storing a number of bytes equal to
214 * Returns 0 if successful; otherwise it returns an error code:
215 * EINVAL: The value of attr is invalid
217 * Alternatively, in case of error the implementation is allowed to
218 * notify it to the system console and then terminate the FRSH
219 * implementation and dependant applications
221 int fosa_thread_attr_get_appsched_params
222 (const frsh_thread_attr_t *attr,
227 * fosa_ads_set_appscheduled()
229 * Dynamically set the appscheduled attribute of a thread
231 * This function is used to dynamically set the appscheduled attribute
232 * of the thread identified by thread. This attribute controls the
233 * kind of scheduling used for threads created with it. If true, the
234 * thread is scheduled by the application scheduler. If not, it is
235 * scheduled by the system under a fixed priority scheduler.
237 * Returns 0 if successful; otherwise it returns an error code:
238 * EINVAL: The value of thread is invalid
240 * EREJECT: the attachment of the thread to the frsh schehduler
241 * was rejected by the frsh scheduler possibly because of
242 * incorrect attributes, or because the requested minimum
243 * capacity cannot be guaranteed
245 * Alternatively, in case of error the implementation is allowed to
246 * notify it to the system console and then terminate the FRSH
247 * implementation and dependant applications
249 int fosa_ads_set_appscheduled
250 (frsh_thread_id_t thread,
254 * fosa_ads_getappscheduled()
256 * Dynamically get the appscheduled attribute of a thread
258 * This function is used to dynamically get the appscheduled attribute
259 * of the thread identified by thread. This attribute controls the
260 * kind of scheduling used for threads created with it. If true, the
261 * thread is scheduled by the application scheduler. If not, it is
262 * scheduled by the system under a fixed priority scheduler
264 * Returns 0 if successful; otherwise it returns an error code:
265 * EINVAL: The value of thread is invalid
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_get_appscheduled
272 (frsh_thread_id_t thread,
277 * fosa_ads_setappschedparam()
279 * Dynamically set the appsched_param attribute of a thread
281 * This function is used to dynamically set the appsched_param
282 * attribute of the thread identified by thread. For those threads
283 * with appscheduled set to true, this attribute represents the
284 * application-specific scheduling parameters. If successful, the
285 * function shall set the size of the appsched_param attribute to the
286 * value specified by paramsize, and shall copy the scheduling
287 * parameters occupying paramsize bytes and pointed to by param into
290 * Returns 0 if successful; otherwise it returns an error code:
291 * EINVAL: The value of thread is invalid, or paramsize is less than
292 * zero or larger than FOSA_ADS_SCHEDPARAM_MAX
294 * Alternatively, in case of error the implementation is allowed to
295 * notify it to the system console and then terminate the FRSH
296 * implementation and dependant applications
298 int fosa_ads_set_appsched_params
299 (frsh_thread_id_t thread,
304 * fosa_ads_get_appsched_params()
306 * Dynamically get the appsched_param attribute of a thread
308 * This function is used to dynamically get the appsched_param
309 * attribute of the thread identified by thread. For those threads
310 * with appscheduled set to true, this attribute represents the
311 * application-specific scheduling parameters. If successful, the
312 * function shall set the variable pointed to by paramsize to the size
313 * of the appsched_param attribute, and shall copy the scheduling
314 * parameters occupying paramsize bytes into the variable pointed to
315 * by param. This variable should be capable of storing a number of
316 * bytes equal to paramsize.
318 * Returns 0 if successful; otherwise it returns an error code:
319 * EINVAL: The value of thread is invalid, or paramsize is less than
320 * zero or larger than FOSA_ADS_SCHEDPARAM_MAX
322 * Alternatively, in case of error the implementation is allowed to
323 * notify it to the system console and then terminate the FRSH
324 * implementation and dependant applications.
326 int fosa_ads_get_appsched_params
327 (frsh_thread_id_t thread,
332 /*********************************
335 * A scheduling actions object is used to specify a series of actions
336 * to be performed by the system at the end of a scheduler primitive
337 * operation. The order of the actions added to the object shall be
340 *********************************/
343 * fosa_adsactions_add_reject()
345 * Add a reject-thread action
347 * This function adds a thread-reject action to the object referenced
348 * by sched_actions, that will serve to notify that the thread
349 * identified by thread has not been accepted by the scheduler to be
350 * scheduled by it, possibly because the thread contained invalid
351 * application scheduling attributes, or because there are not enough
352 * resources for the new thread. At the end of the new_thread()
353 * scheduler primitive operation, the parent of the rejected thread
354 * waiting on a fosa_thread_create() or the rejected thread itself
355 * waiting on a fosa_ads_set_appscheduled() function shall complete the
356 * function with an error code of EREJECT. If no reject-thread action
357 * is added during the new_thread() scheduler primitive operation, the
358 * thread is accepted to be scheduled by the scheduler and the
359 * associated fosa_thread_create() or the fosa_ads_set_appscheduled()
360 * function shall be completed without error. For the function to
361 * succeed, it has to be called from the new_thread() primitive
362 * operation and for the thread that is requesting attachment to the
365 * Returns 0 if successful; otherwise it returns an error code:
366 * ENOMEM: There is insufficient memory to add this action
367 * EPOLICY: The thread specified by thread is not the one requesting
368 * attachment to the scheduler, or the function is not being
369 * called from the new_thread primitive operation
370 * EINVAL: The value specified by sched_actions is invalid
372 * Alternatively, in case of error the implementation is allowed to
373 * notify it to the system console and then terminate the FRSH
374 * implementation and dependant applications
376 int fosa_adsactions_add_reject(
377 fosa_ads_actions_t *sched_actions,
378 frsh_thread_id_t thread);
381 * fosa_adsactions_add_activate()
383 * Add a thread-activate action
385 * This function adds a thread-activate action to the object
386 * referenced by sched_actions. In case the thread had been previously
387 * suspended via posix_appsched_actions_addsuspend(), it will be
388 * activated at the end of the primitive operation.
390 * In those implementations that do not support urgency scheduling,
391 * the urgencu value is ignored. These implementations cannot support
392 * the frsh hierarchical scheduling module.
394 * In those implementations supporting urgency-scheduling, the action
395 * will cause the change of the urgency of the thread to the value
396 * specified in the urgency argument. Besides, if the thread was
397 * already active at the time the thread-activate action is executed,
398 * the change or urgency will imply a reordering of the thread in its
399 * priority queue, so that for threads of the same priority, those
400 * with more urgency will be scheduled before those of less urgency.
402 * Returns 0 if successful; otherwise it returns an error code:
403 * ENOMEM: There is insufficient memory to add this action
404 * EPOLICY: The thread specified by thread has its appscheduled
405 * attribute set to false,
406 * EINVAL: The value specified by sched_actions is invalid
408 * Alternatively, in case of error the implementation is allowed to
409 * notify it to the system console and then terminate the FRSH
410 * implementation and dependant applications
412 int fosa_adsactions_add_activate(
413 fosa_ads_actions_t *sched_actions,
414 frsh_thread_id_t thread,
415 fosa_ads_urgency_t urgency);
418 * fosa_adsactions_add_suspend()
420 * Add a thread-suspend action
422 * This function adds a thread-suspend action to the object referenced
423 * by sched_actions, that will cause the thread identified by thread
424 * to be suspended waiting for a thread-activate action at the end of
425 * the scheduler operation. If the thread was already waiting for a
426 * thread-activate action the thread-suspend action has no effect. It
427 * is an error trying to suspend a thread that is blocked by the
430 * Returns 0 if successful; otherwise it returns an error code:
431 * ENOMEM: There is insufficient memory to add this action
432 * EPOLICY: The thread specified by thread has its appscheduled
433 * attribute set to false,
434 * EINVAL: The value specified by sched_actions is invalid
436 * Alternatively, in case of error the implementation is allowed to
437 * notify it to the system console and then terminate the FRSH
438 * implementation and dependant applications
440 int fosa_adsactions_add_suspend(
441 fosa_ads_actions_t *sched_actions,
442 frsh_thread_id_t thread);
445 * fosa_adsactions_add_timeout()
447 * Add a timeout action
449 * This function adds a timeout action to the object referenced by
450 * sched_actions, that will cause the timeout() scheduler operation to
451 * be invoked if no other scheduler operation is invoked before
452 * timeout expires. The timeout shall expire when the clock specified by
453 * clock_id reaches the absolute time specified by the at_time
456 * Returns 0 if successful; otherwise it returns an error code:
457 * ENOMEM: There is insufficient memory to add this action
458 * EPOLICY: The thread specified by thread has its appscheduled
459 * attribute set to false,
460 * EINVAL: The value specified by sched_actions is invalid
462 * Alternatively, in case of error the implementation is allowed to
463 * notify it to the system console and then terminate the FRSH
464 * implementation and dependant applications
466 int fosa_adsactions_add_timeout(
467 fosa_ads_actions_t *sched_actions,
468 fosa_clock_id_t clock_id,
469 const struct timespec *at_time);
472 * fosa_adsactions_add_thread_notification()
474 * Add a timed-thread-notification action
476 * This function adds a thread-notification action associated with the
477 * thread specified in the thread argument that will cause the
478 * notification_for_thread() scheduler operation to be invoked at the
479 * time specified by at_time. This operation shall be invoked when the
480 * clock specified by clock_id reaches the absolute time specified by
481 * the at_time argument. In particular, a cpu-time clock may be used
482 * for parameter clock_id.Only one thread-notification can be active
483 * for each thread and clock. Calling the function shall remove the
484 * former thread-notification, if any, that had been programmed for
485 * the same thread and clock. A value of NULL for parameter at_time is
486 * used to cancel a previous thread-notification, if any, for the
487 * thread specified by thread and the clock specified by clock_id.
489 * Returns 0 if successful; otherwise it returns an error code:
490 * ENOMEM: There is insufficient memory to add this action
491 * EPOLICY: The thread specified by thread has its appscheduled
492 * attribute set to false,
493 * EINVAL: The value specified by sched_actions is invalid
495 * Alternatively, in case of error the implementation is allowed to
496 * notify it to the system console and then terminate the FRSH
497 * implementation and dependant applications
499 int fosa_adsactions_add_thread_notification(
500 fosa_ads_actions_t *sched_actions,
501 frsh_thread_id_t thread,
502 fosa_clock_id_t clock_id,
503 const struct timespec *at_time);
507 * fosa_ads_set_handled_signal_set()
509 * Specifiy the set of signals that will be handled by the application
512 * This function is used to dynamically set the set of signals that
513 * are handled by the application scheduler. When a signal included
514 * in this set is generated, the signal() primitive operation of the
515 * application scheduler shall be executed. When a signal in tis set
516 * is generated, it shall always imply the execution of the signal()
517 * primitive operation, regardless of whether that signal could be
518 * accepted by some other thread. Once the signal() primitive
519 * operation is executed the signal is consumed, so no signal handlers
520 * shall be executed and no threads using a sigwait operation shall
521 * return for that particular signal instance. For this function to
522 * succeed, it has to be called from a primitive operation of a
525 * Returns 0 if successful; otherwise it returns an error code:
526 * EPOLICY: The function has not been called from a scheduler
527 * primitive operation
528 * EINVAL: The value specified by set is invalid
530 * Alternatively, in case of error the implementation is allowed to
531 * notify it to the system console and then terminate the FRSH
532 * implementation and dependant applications
534 int fosa_ads_set_handled_signal_set(frsh_signal_t set[]);
538 * fosa_ads_invoke_withdata()
540 * Explicitly invoke the scheduler, with data
542 * This function can be used by any thread in the process to invoke
543 * the ads scheduler or to share data with it.
545 * If successful, the function shall cause the execution of the
546 * primitive operation explicit_call_with_data() of the ads scheduler
547 * with its thread parameter equal to the thread ID of the calling
548 * thread, and its msg_size parameter equal to msg_size. In addition,
549 * if msg_size is larger than zero, the function shall make available
550 * to the scheduler a memory area whose contents are identical to the
551 * memory area pointed to by msg in the msg parameter of the
552 * explicit_call_with_data() primitive operation (note that copying
553 * the information is not needed).
555 * The function shall not return until the system has finished
556 * execution of the explicit_call_with_data() primitive operation. If
557 * the reply argument is non NULL, the memory area pointed to by the
558 * reply parameter of explicit_call_with_data() primitive operation is
559 * copied into the memory area pointed to by reply, and its size is
560 * copied into the variable pointed to by reply_size. The size of the
561 * reply information is limited to the value FOSA_ADS_SCHEDINFO_MAX.
563 * The function shall fail if the size specified by msg_size is larger
564 * than FOSA_ADS_SCHEDINFO_MAX. The function shall fail if primitive
565 * operation explicit_call_with_data() is set to NULL for the ads
568 * Returns 0 if successful; otherwise it returns an error code:
569 * EPOLICY: The function been called from inside a scheduler
570 * primitive operation
571 * EINVAL: The value of msg_size is less than zero or larger than
572 * FOSA_ADS_SCHEDINFO_MAX
573 * EMASKED: The operation cannot be executed because the primitive
574 * operation explicit_call_with_data() is set to NULL
576 * Alternatively, in case of error the implementation is allowed to
577 * notify it to the system console and then terminate the FRSH
578 * implementation and dependant applications
580 int fosa_ads_invoke_withdata
581 (const void *msg, size_t msg_size, void *reply, size_t *reply_size);
586 #endif /* !FOSA_APP_DEF_SCHED_H_ */