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. 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 FRSH API
36 // FRSH API is free software; you can redistribute it and/or modify
37 // it under the terms of the GNU General Public License as published by
38 // the Free Software Foundation; either version 2, or (at your option)
41 // FRSH API is distributed in the hope that it will be useful, but
42 // WITHOUT ANY WARRANTY; without even the implied warranty of
43 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
44 // General Public License for more details.
46 // You should have received a copy of the GNU General Public License
47 // distributed with FRSH API; see file COPYING. If not, write to the
48 // Free Software Foundation, 59 Temple Place - Suite 330, Boston, MA
51 // As a special exception, if you include this header file into source
52 // files to be compiled, this header file does not by itself cause
53 // the resulting executable to be covered by the GNU General Public
54 // License. This exception does not however invalidate any other
55 // reasons why the executable file might be covered by the GNU General
57 // -----------------------------------------------------------------------
58 //frsh_shared_objects.h
60 //==============================================
61 // ******** ******* ******** ** **
62 // **///// /**////** **////// /** /**
63 // ** /** /** /** /** /**
64 // ******* /******* /********* /**********
65 // **//// /**///** ////////** /**//////**
66 // ** /** //** /** /** /**
67 // ** /** //** ******** /** /**
68 // // // // //////// // //
70 // FRSH(FRescor ScHeduler), pronounced "fresh"
71 //==============================================
73 #ifndef _FRSH_SHARED_OBJECTS_H_
74 #define _FRSH_SHARED_OBJECTS_H_
76 #include "frsh_fosa.h"
77 #include "frsh_shared_objects_types.h"
78 #include "frsh_core_types.h"
81 #define FRSH_SHAREDOBJS_MODULE_SUPPORTED 1
84 * @file frsh_shared_objects.h
88 * @defgroup sharedobj Shared Objects module
90 * This module includes the functions to declare and use shared
91 * objects in different critical sections.
93 * A shared object is an abstraction of a mutex giving it a name and a
94 * possible priority ceiling.
96 * A critical section represents a usage of a shared object with a wcet.
97 * One or more critical sections can be included in a contract.
99 * There are two types of shared_objects: protected and unprotected.
101 * - <b>UNPROTECTED shared objects</b>. These shared objects are always
102 * used in trusted critical sections for which the worst-case
103 * execution times can be guaranteed not to be exceeded by the
104 * application designer (eg because tools have been used to verify
105 * the schedulability off-line). Given these conditions, there is
106 * no need to have a mechanism to monitor their execution time, with
107 * the corresponding savings in overhead.
109 * - <b>PROTECTED shared objects</b>. For these shared objects a mechanism
110 * may be used in one or more of their critical sections to monitor
111 * and enforce their worst-case execution time. These shared
112 * objects are restricted to data in regular memory because a
113 * mechanism to save and restore the state is necessary in order to
114 * cleanly abort a misbehaving critical section.\n
116 * Critical sections are categorized depending on wcet monitoring and
117 * rollback capability.
119 * - <b>UNCHECKED critical sections</b>. These critical sections are
120 * not monitored by FRSH for wcet compliance. Their wcet value is
121 * used only for analysis purposes (calculation of blocking times).
123 * - <b>READ critical sections</b>. These critical sections have
124 * their wcet enforced but they don't have any rollback action
125 * applied when their wcet is exceeded.
127 * - <b>WRITE critical sections</b>. These critical sections have
128 * their wcet monitored and they have a rollback mechanism applied
129 * to their memory areas prior to being aborted for exceeding their
132 * READ and WRITE critical sections must use PROTECTED shared objects,
133 * but UNCHECKED critical sections may use PROTECTED or UNPROTECTED
136 * The monitoring mechanism for READ and WRITE critical section works
137 * by executing them indirectly via a registered callback function.
138 * UNCHECKED critical sections are executed directly by the
141 * The rollback mechanism for WRITE critical sections requires an
142 * additional registration of the memory areas that the callback
143 * function may modify. With this data FRSH will do an initial saving
144 * of this areas that will used for restoration when there is a rollback
147 * Note that extra time for the saving and the restoration must be
148 * included in the wcet specified for a WRITE critical section.
149 * Functions are provided to assist the developer in calculating this
152 * The reason for allowing the use of PROTECTED shared objects in
153 * UNCHECKED critical sections is to allow for legacy or trusted
154 * code that would use UNCHECKED critical sections to share a shared
155 * object with an untrusted code using READ or WRITE critical sections.
157 * This module makes use of the following constants defined in
158 * frsh_configuration_parameters.h. We list them with our proposed
161 * FRSH_MAX_N_SHARED_OBJECTS 100 \n
162 * FRSH_MAX_N_CRITICAL_SECTIONS 20\n
163 * FRSH_MAX_N_MEMORY_AREAS 4\n
169 /////////////////////////////////////////////////////
170 // SHARED OBJECTS & OPERATIONS MANAGEMENT
171 /////////////////////////////////////////////////////
173 * @defgroup so_opp_mgmnt Shared Objects & Operations
176 * These functions are used to declare shared objects and link them
183 * frsh_sharedobj_init()
185 * Initialization of shared objects. If the object identified by
186 * obj_label does not yet exist, it is created, a handle to the object is
187 * returned in the variable pointed to by obj_handle, and the
188 * specified mutex is initialized with the appropriate attributes
189 * necessary for the current implementation. If the object already
190 * exists, the function fails. The object is created according to the
191 * kind of object (protected or unprotected) specified by obj_kind
193 * @param[in] obj_label Label defined by the application. Char * for
194 * a string of SHAREDOBJ_LABEL_MAXLENGTH
195 * characters (+ null terminating \0).
197 * @param[in] obj_kind Whether it is protected or unprotected.
199 * @param[out] obj_handle Placeholder for the shared object handle.
201 * @param[out] mutex Placeholder for the mutex.
203 * @return 0 if no error \n
204 * FRSH_ERR_BAD_ARGUMENT : if obj_label, obj_handle, or mutex are NULL \n
205 * FRSH_ERR_SHARED_OBJ_ALREADY_INITIALIZED : if the object identified
206 * by label already exists \n
207 * FRSH_ERR_TOO_MANY_SHARED_OBJS : if the number of already
208 * initialized shared objects exceed the
209 * FRSH_MAX_N_SHARED_OBJECTS configuration parameter. \n
211 * It may also return any of the error codes that are returned by
212 * fosa_mutex_init() and fosa_mutex_set_prioceiling().
215 int frsh_sharedobj_init
217 frsh_sharedobj_kind_t obj_kind,
218 frsh_sharedobj_handle_t *obj_handle,
219 frsh_mutex_t *mutex);
224 * frsh_sharedobj_get_handle()
226 * Getting the handle of shared objects. If the object already exists
227 * a handle to the object is returned in the variable pointed to by
228 * obj_handle. Otherwise, an error code is returned.
230 * @param[in] obj_label Defined by the application at object creation
231 * time. Char * for a string of SHAREDOBJ_LABEL_MAXLENGTH
232 * characters (+ null terminating \0).
234 * @param[out] obj_handle Placeholder for the object handle.
236 * @return 0 if no error \n
237 * FRSH_ERR_BAD_ARGUMENT : if label or obj_handle are NULL \n
238 * FRSH_ERR_SHARED_OBJ_NOT_INITIALIZED : if the shared object identified
239 * by obj_label does not exist \n
240 * FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
241 * scheduled under FRSH \n
242 * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not
244 * FRSH_ERR_NOT_CONTRACTED_VRES : if the vres of the calling thread
245 * has been cancelled or it is not valid \n
247 * It may also return any of the error codes that are returned by the
248 * fosa_mutex_init() function call
251 int frsh_sharedobj_get_handle
253 frsh_sharedobj_handle_t *obj_handle);
257 * frsh_sharedobj_get_mutex()
259 * Getting the mutex of shared objects.
261 * @param[in] obj_handle Handle of the shared object
263 * @param[out] mutex Placeholder for A POINTER to a pointer of the
264 * mutex. We give the pointer to discourage the
265 * application of using a local copy of the mutex.
267 * @return 0 if no error \n
268 * FRSH_ERR_BAD_ARGUMENT : if obj_handle or mutex are NULL or obj_handle
269 * is not correct or reference a wrong shared object \n
270 * FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
271 * scheduled under the FRSH \n
272 * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not
274 * FRSH_ERR_NOT_CONTRACTED_VRES : if the vres of the calling thread
275 * has been cancelled or it is not valid
278 int frsh_sharedobj_get_mutex
279 (frsh_sharedobj_handle_t obj_handle,
280 frsh_mutex_t **mutex);
283 * frsh_sharedobj_get_obj_kind()
285 * Get the object kind (protected/unprotected) of the object handle.
287 * @param[in] obj_handle Handle of the shared object
289 * @param[out] obj_kind Placeholder for an enumeration variable of
290 * protected / unprotected.
292 * @return 0 if no error \n
293 * FRSH_ERR_BAD_ARGUMENT : if obj_handle or mutex are NULL or obj_handle
294 * is not correct or reference a wrong shared object \n
295 * FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
296 * scheduled under the FRSH \n
297 * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not
299 * FRSH_ERR_NOT_CONTRACTED_VRES : if the vres of the calling thread
300 * has been cancelled or it is not valid
303 int frsh_sharedobj_get_obj_kind
304 (frsh_sharedobj_handle_t obj_handle,
305 frsh_sharedobj_kind_t *obj_kind);
308 * frsh_sharedobj_remove()
310 * Allows the implementation to remove a shared object when the last
311 * vres referencing it is cancelled. This removes the object id and
312 * other internal data associated with the object, but does not remove
313 * the mutex; this is done by the application through the common POSIX
316 * @return 0 if no error \n
317 * FRSH_ERR_BAD_ARGUMENT : if obj_handle is NULL or obj_handle
318 * is not correct or references a wrong shared object \n
319 * FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
320 * scheduled under the FRSH \n
321 * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not
323 * FRSH_ERR_NOT_CONTRACTED_VRES : if the vres of the calling thread
324 * has been cancelled or it is not valid
327 int frsh_sharedobj_remove
328 (frsh_sharedobj_handle_t obj_handle);
334 /////////////////////////////////////////////////////
336 /////////////////////////////////////////////////////
338 * @defgroup so_critical Critical Sections
341 * These functions are used to create and manage the parameters
342 * of critical sections. Critical sections are operations that
343 * make use of a shared object in a mutually exclusive way.
351 * Initialize the critical section pointed to by csect
352 * with a handle to its shared object, and the worst-case execution
355 * The operation_kind is set to FRSH_CSOK_UNCHECKED.
357 * @param[in] obj_handle Shared object previously initialised.
359 * @param[in] wcet Execution time of the critical section. This
360 * budget is consumed in parallel with the vres budget.
362 * @param[out] cset Critical section memory placeholder.
364 * @return 0 if no error \n
365 * FRSH_ERR_BAD_ARGUMENT : if obj_handle is NULL \b or \n
366 * obj_handle is not correct or references a wrong shared object \b or \n
367 * if wcet is in the wrong format for specifying a time interval value \n
368 * FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
369 * scheduled under the FRSH \n
370 * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not
372 * FRSH_ERR_NOT_CONTRACTED_VRES : if the vres of the calling thread
373 * has been cancelled or it is not valid
377 (frsh_sharedobj_handle_t obj_handle,
378 struct timespec wcet,
379 frsh_csect_t *csect);
383 * frsh_csect_get_sharedobj_handle()
385 * Get in the variable pointed to by obj_handle the handle to the
386 * shared object stored in the critical section referenced by csect
388 * @return 0 if no error \n
389 * FRSH_ERR_BAD_ARGUMENT : if cset or obj_handle are NULL or cset
391 * FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
392 * scheduled under the FRSH \n
393 * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not
395 * FRSH_ERR_NOT_CONTRACTED_VRES : if the vres of the calling thread
396 * has been cancelled or it is not valid
399 int frsh_csect_get_sharedobj_handle
400 (const frsh_csect_t *cset,
401 frsh_sharedobj_handle_t * obj_handle);
404 * frsh_csect_get_wcet()
406 * Get in the variable pointed to by wcet the worst-case execution time
407 * of the operation stored in the critical section referenced by csect.
409 * @return 0 if no error \n
410 * FRSH_ERR_BAD_ARGUMENT : if cset or wcet are NULL or cset
412 * FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
413 * scheduled under FRSH \n
414 * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not
416 * FRSH_ERR_NOT_CONTRACTED_VRES : if the vres of the calling thread
417 * has been cancelled or it is not valid
420 int frsh_csect_get_wcet
421 (const frsh_csect_t *cset,
422 struct timespec *wcet);
426 * frsh_csect_register_read_op()
428 * Register the given operation with the critical section and set
429 * op_kind to FRSH_CSOK_READ.
431 * The function returns an error if the shared_object is unprotected.
433 * @return 0 if no error \n
434 * FRSH_ERR_BAD_ARGUMENT : if cset or op are NULL or if csect points
435 * to a wrong critical section or if the shared_object is of type
437 * FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
438 * scheduled under FRSH \n
439 * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not
441 * FRSH_ERR_NOT_CONTRACTED_VRES : if the vres of the calling thread
442 * has been cancelled or it is not valid
445 int frsh_csect_register_read_op
450 * frsh_csect_register_write_op()
452 * Register the given operation with the critical section, register
453 * the memory areas and set op_kind to FRSH_CSOK_WRITE.
455 * If the memory areas are empty the functions returns an error.
457 * The function returns an error if the shared_object is unprotected.
459 * @return 0 if no error \n
460 * FRSH_ERR_BAD_ARGUMENT : if op, cset or areas are NULL or cset points
461 * to a wrong critical section or if the shared_object of csect
462 * is of type unprotected.
463 * FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
464 * scheduled under the FRSH \n
465 * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not
467 * FRSH_ERR_NOT_CONTRACTED_VRES : if the vres of the calling thread
468 * has been cancelled or it is not valid
471 int frsh_csect_register_write_op
474 const frsh_memory_areas_t *areas);
478 * frsh_csect_get_op_kind()
480 * Returns the type of operation (read/write/unchecked) of the critical section.
482 * @return 0 if no error \n
483 * FRSH_ERR_BAD_ARGUMENT : if cset or op_kind are NULL or cset
485 * FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
486 * scheduled under FRSH \n
487 * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not
489 * FRSH_ERR_NOT_CONTRACTED_VRES : if the vres of the calling thread
490 * has been cancelled or it is not valid
493 int frsh_csect_get_op_kind
494 (const frsh_csect_t *cset,
495 frsh_csect_op_kind_t *op_kind);
499 * frsh_csect_get_read_op()
501 * Get into the variable pointed to by op the operation pointer stored
502 * in the critical section referenced by cset.
504 * If the csect is of type write or unchecked it returns an error.
506 * @return 0 if no error \n
507 * FRSH_ERR_BAD_ARGUMENT : if cset is NULL or points to a wrong
508 * critical section, or to a critical section that is not of the
509 * FRSH_CSOK_READ kind \n
510 * FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
511 * scheduled under FRSH \n
512 * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not
514 * FRSH_ERR_NOT_CONTRACTED_VRES : if the vres of the calling thread
515 * has been cancelled or it is not valid
518 int frsh_csect_get_read_op
519 (const frsh_csect_t *cset,
520 frsh_csect_op_t *op);
525 * frsh_csect_get_write_op()
527 * Get the oparation pointer and the memory areas stored in the csect.
529 * If the csect is of type read or unchecked.
531 * @return 0 if no error \n
532 * FRSH_ERR_BAD_ARGUMENT : if cset is NULL or points to a wrong
533 * critical section, or to a critical section that is not of the
534 * FRSH_CSOK_WRITE kind \n
535 * FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
536 * scheduled under FRSH \n
537 * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not
539 * FRSH_ERR_NOT_CONTRACTED_VRES : if the vres of the calling thread
540 * has been cancelled or it is not valid \n
543 int frsh_csect_get_write_op
544 (const frsh_csect_t *cset,
546 frsh_memory_areas_t *areas);
550 * frsh_csect_invoke()
552 * Invoke the registered operation in the critical section, with the pointers
553 * to the input and output parameters specified by input_arg and
556 * If the section is of type FRSH_CSOK_UNCHECKED, the function returns
559 * For read operations, the mutex is locked, the cset budget is set equal
560 * to the wcet, the registered read operation is invoked, and then the
561 * mutex is unlocked; if the csect budget expires, the operation is
562 * interrupted, the mutex is unlocked, and the function returns with
565 * For write operations, the mutex is locked, the registered memory
566 * areas are backed up, the csect budget is set equal to the wcet, the
567 * registered write operation is called, and the mutex is unlocked. If
568 * the csect budget expires, the operation is interrupted, the backed-up
569 * memory areas are recovered, the mutex is unlocked, and the function
570 * returns with an error code. The blocking time suffered by higher
571 * priority tasks is at most the wcet of the operation plus the backup
572 * time plus the recovery time.
574 * If the shared object in the critical section is not protected it
577 * @return 0 if no error \n
578 * FRSH_ERR_BAD_ARGUMENT : if cset is NULL or points to a wrong
579 * critical section, or to a critical section that is unprotected \n
580 * FRSH_ERR_BUDGET_EXPIRED : the csect budget expired and the protected
581 * operation was interrupted \n
582 * FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
583 * scheduled under FRSH \n
584 * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not
586 * FRSH_ERR_NOT_CONTRACTED_VRES : if the vres of the calling thread
587 * has been cancelled or it is not valid
590 int frsh_csect_invoke
591 (const frsh_csect_t *cset,
592 const void * input_arg,
596 * frsh_csect_get_blocking_time()
598 * Get in the variable pointed to by blocking the maximum blocking
599 * time of the operation of the referenced protected critical section.
601 * For read operations, the maximum blocking time is the wcet.
603 * For write operations, the maximum blocking time suffered by higher
604 * priority tasks is the wcet of the operation plus the backup time
605 * plus the recovery time.
607 * @return 0 if no error \n
608 * FRSH_ERR_BAD_ARGUMENT : if cset or blocking are NULL or if csect
609 * points to a wrong critical section, or to a critical section
610 * that is unprotected \n
611 * FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
612 * scheduled under FRSH \n
613 * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not
615 * FRSH_ERR_NOT_CONTRACTED_VRES : if the vres of the calling thread
616 * has been cancelled or it is not valid
619 int frsh_csect_get_blocking_time
620 (const frsh_csect_t *cset,
621 struct timespec *blocking);
624 /*@}*/ /* For so_critical group */
627 /////////////////////////////////////////////////////
628 // CONTRACT PARAMETERS
629 /////////////////////////////////////////////////////
631 * @defgroup so_contract Shared Objects & Contract Parameters
634 * These functions are used to link shared objects to contracts via
642 * frsh_contract_set_csects()
644 * The operation updates the specified contract parameters object by
645 * setting its critical sections to the specified input parameter.
647 * @return 0 if no error \n
648 * FRSH_ERR_BAD_ARGUMENT : if any of the pointers is NULL or
649 * the size of the critical_sections structure is less than zero
650 * or grater than FRSH_MAX_N_CRITICAL_SECTIONS
653 int frsh_contract_set_csects
654 (frsh_contract_t *contract,
655 const frsh_csects_group_t *critical_sections);
658 * frsh_contract_get_csects()
660 * The operation obtains from the specified contract parameters object
661 * its critical sections, and copies them to the places pointed to by
662 * the specified input parameter. Only those critical_section_data
663 * records that are in use in the critical_sections structure are
664 * copied (according to its size field).
666 * @return 0 if no error \n
667 * FRSH_ERR_BAD_ARGUMENT : if any of the pointers is NULL
670 int frsh_contract_get_csects
671 (const frsh_contract_t *contract,
672 frsh_csects_group_t *critical_sections);
674 /*@}*/ /* For so_contract group */
676 /*@}*/ /* For shared_objects group */
678 #endif // _FRSH_SHARED_OBJECTS_H_