X-Git-Url: https://rtime.felk.cvut.cz/gitweb/frescor/frsh-include.git/blobdiff_plain/2273a48ed0df5be47005d79d7a8ce351fc32503e..HEAD:/frsh_shared_objects.h diff --git a/frsh_shared_objects.h b/frsh_shared_objects.h index 9e02369..cca6c15 100644 --- a/frsh_shared_objects.h +++ b/frsh_shared_objects.h @@ -1,5 +1,5 @@ // ----------------------------------------------------------------------- -// Copyright (C) 2006 - 2007 FRESCOR consortium partners: +// Copyright (C) 2006 - 2009 FRESCOR consortium partners: // // Universidad de Cantabria, SPAIN // University of York, UK @@ -12,7 +12,7 @@ // Visual Tools S.A. SPAIN // Rapita Systems Ltd UK // Evidence ITALY -// +// // See http://www.frescor.org for a link to partners' websites // // FRESCOR project (FP6/2005/IST/5-034026) is funded @@ -22,7 +22,7 @@ // // // based on previous work (FSF) done in the FIRST project -// +// // Copyright (C) 2005 Mälardalen University, SWEDEN // Scuola Superiore S.Anna, ITALY // Universidad de Cantabria, SPAIN @@ -31,29 +31,26 @@ // FSF API web pages: http://marte.unican.es/fsf/docs // http://shark.sssup.it/contrib/first/docs/ // -// This file is part of FRSH API -// -// FRSH API is free software; you can redistribute it and/or modify -// it under the terms of the GNU General Public License as published by -// the Free Software Foundation; either version 2, or (at your option) -// any later version. +// This file is part of FRSH (FRescor ScHeduler) // -// FRSH API is distributed in the hope that it will be useful, but -// WITHOUT ANY WARRANTY; without even the implied warranty of -// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -// General Public License for more details. +// FRSH is free software; you can redistribute it and/or modify it +// under terms of the GNU General Public License as published by the +// Free Software Foundation; either version 2, or (at your option) any +// later version. FRSH is distributed in the hope that it will be +// useful, but WITHOUT ANY WARRANTY; without even the implied warranty +// of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +// General Public License for more details. You should have received a +// copy of the GNU General Public License along with FRSH; see file +// COPYING. If not, write to the Free Software Foundation, 675 Mass Ave, +// Cambridge, MA 02139, USA. // -// You should have received a copy of the GNU General Public License -// distributed with FRSH API; see file COPYING. If not, write to the -// Free Software Foundation, 59 Temple Place - Suite 330, Boston, MA -// 02111-1307, USA. -// -// As a special exception, if you include this header file into source -// files to be compiled, this header file does not by itself cause -// the resulting executable to be covered by the GNU General Public -// License. This exception does not however invalidate any other -// reasons why the executable file might be covered by the GNU General -// Public License. +// As a special exception, including FRSH header files in a file, +// instantiating FRSH generics or templates, or linking other files +// with FRSH objects to produce an executable application, does not +// by itself cause the resulting executable application to be covered +// by the GNU General Public License. This exception does not +// however invalidate any other reasons why the executable file might be +// covered by the GNU Public License. // ----------------------------------------------------------------------- //frsh_shared_objects.h @@ -73,19 +70,15 @@ #ifndef _FRSH_SHARED_OBJECTS_H_ #define _FRSH_SHARED_OBJECTS_H_ -#include #include "frsh_shared_objects_types.h" #include "frsh_core_types.h" +FRSH_CPP_BEGIN_DECLS -#define FRSH_SHARED_OBJECTS_MODULE_SUPPORTED 1 +#define FRSH_SHAREDOBJS_MODULE_SUPPORTED 1 /** * @file frsh_shared_objects.h - * - * This file contains the types, definitions and function prototypes - * for usage of shared objects and critical sections in the FRSH - * Scheduling Framework. **/ /** @@ -97,79 +90,74 @@ * A shared object is an abstraction of a mutex giving it a name and a * possible priority ceiling. * - * A critical section associates a shared object with a wcet. + * A critical section represents a usage of a shared object with a wcet. * One or more critical sections can be included in a contract. * * There are two types of shared_objects: protected and unprotected. - * Protected shared objects have FRSH alone managing the mutex while - * unprotected shared objects have the mutex residing in the - * application memory space. - * - * There are also two types of critical sections: time-enforced and - * non-time-enforced. - * - * - Non-time-enforced critical sections are considered only for - * analysis purposes. They inform FRSH about which shared objects - * are used in which contracts in order to compute blocking times. - * - * Non-time-enforced critical sections are executed directly by the - * application and it is the designer's responsibility to respect - * the specified wcet. - * - * Non-time-enforced critical sections can only contain unprotected - * shared objects because their mutex must be visible to the - * application. - * - * - Timed-enforced cricital sections provide not only analysis - * information but also the needed means for FRSH to enforce the - * wcet of the critical section in a clean way. - * - * FRSH aborts the execution of the critical section if its wcet - * gets exceeded. A backup-rollback mechanism of pre-declared - * memory areas preserves the original values of those areas in - * case the critical section is aborted. - * - * This time protection comes at a penalty of more complexity: - * - Extra blocking time is accounted for the backup and the - * possible need of restoration of the modified memory areas. - * - * - The application cannot modify directly the memory areas and - * therefore cannot execute the critical section directly. - * Instead it executes it indirectly through - * frsh_invoke_critical_section() providing a callback to the - * critical section. - * - * We allow timed-enforced critical sections to be used with protected - * or unprotected shared objects although we recommend to use - * protected shared objects whenever possible. - * - * The reason to allow unprotected shared objects in time-enforced - * critical sections is to allow the sharing of the mutex with legacy - * applications that cannot be rearranged into callback functions. - * This is not possible with protected shared objects because shared - * objects don't give visibility of the mutex to the application. - * - * - * A FRSH shared object is an association of: - * - a mutex with an optional priority celing. - * - a name (obj_id) and - * - a type (protected or unprotected). - * - * A FRSH critical section is an association of: - * - a shared object - * - a wcet (which is EXTRA from the allocated budget). - * - An operation pointer (NULL if non-time-enforced). - * - An attribute operation kind (non-enforced, write or read). - * - A list of memory areas modified by the operation (when it is - * write). + * + * - UNPROTECTED shared objects. These shared objects are always + * used in trusted critical sections for which the worst-case + * execution times can be guaranteed not to be exceeded by the + * application designer (eg because tools have been used to verify + * the schedulability off-line). Given these conditions, there is + * no need to have a mechanism to monitor their execution time, with + * the corresponding savings in overhead. + * + * - PROTECTED shared objects. For these shared objects a mechanism + * may be used in one or more of their critical sections to monitor + * and enforce their worst-case execution time. These shared + * objects are restricted to data in regular memory because a + * mechanism to save and restore the state is necessary in order to + * cleanly abort a misbehaving critical section.\n + * + * Critical sections are categorized depending on wcet monitoring and + * rollback capability. + * + * - UNCHECKED critical sections. These critical sections are + * not monitored by FRSH for wcet compliance. Their wcet value is + * used only for analysis purposes (calculation of blocking times). + * + * - READ critical sections. These critical sections have + * their wcet enforced but they don't have any rollback action + * applied when their wcet is exceeded. + * + * - WRITE critical sections. These critical sections have + * their wcet monitored and they have a rollback mechanism applied + * to their memory areas prior to being aborted for exceeding their + * declared wcet. + * + * READ and WRITE critical sections must use PROTECTED shared objects, + * but UNCHECKED critical sections may use PROTECTED or UNPROTECTED + * shared objects. + * + * The monitoring mechanism for READ and WRITE critical section works + * by executing them indirectly via a registered callback function. + * UNCHECKED critical sections are executed directly by the + * application. + * + * The rollback mechanism for WRITE critical sections requires an + * additional registration of the memory areas that the callback + * function may modify. With this data FRSH will do an initial saving + * of this areas that will used for restoration when there is a rollback + * operation. + * + * Note that extra time for the saving and the restoration must be + * included in the wcet specified for a WRITE critical section. + * Functions are provided to assist the developer in calculating this + * extra time. + * + * The reason for allowing the use of PROTECTED shared objects in + * UNCHECKED critical sections is to allow for legacy or trusted + * code that would use UNCHECKED critical sections to share a shared + * object with an untrusted code using READ or WRITE critical sections. * * This module makes use of the following constants defined in * frsh_configuration_parameters.h. We list them with our proposed * default values. * - * FRSH_MAX_N_SHARED_OBJECTS 100 - * FRSH_MAX_N_CRITICAL_SECTIONS 20 - * FRSH_MAX_N_MEMORY_AREAS 4 + * FRSH_MAX_N_SHARED_OBJECTS 100 \n + * FRSH_MAX_N_CRITICAL_SECTIONS 20\n + * FRSH_MAX_N_MEMORY_AREAS 4\n * * @{ **/ @@ -189,107 +177,107 @@ **/ /** - * frsh_init_shared_object() + * frsh_sharedobj_init() * * Initialization of shared objects. If the object identified by - * obj_id does not yet exist it is created, a handle to the object is + * obj_label does not yet exist, it is created, a handle to the object is * returned in the variable pointed to by obj_handle, and the * specified mutex is initialized with the appropriate attributes * necessary for the current implementation. If the object already * exists, the function fails. The object is created according to the * kind of object (protected or unprotected) specified by obj_kind * - * @param[in] obj_id Object ID defined by the application. + * @param[in] obj_label Label defined by the application. Char * for + * a string of FRSH_MAX_SIZE_SHARED_OBJ_LABEL + * characters (+ null terminating \0). * * @param[in] obj_kind Whether it is protected or unprotected. * * @param[out] obj_handle Placeholder for the shared object handle. * - * @param[out] mutex Placeholder for the mutex. (Ignored for - * protected shared objects). + * @param[out] mutex Placeholder for the mutex. * - * @return - * FRSH_ERR_BAD_ARGUMENT : if obj_id, obj_handle, or mutex are NULL + * @return 0 if no error \n + * FRSH_ERR_BAD_ARGUMENT : if obj_label, obj_handle, or mutex are NULL \n * FRSH_ERR_SHARED_OBJ_ALREADY_INITIALIZED : if the object identified - * by obj_id already exists + * by label already exists \n * FRSH_ERR_TOO_MANY_SHARED_OBJS : if the number of already * initialized shared objects exceed the - * FRSH_MAX_N_SHARED_OBJECTS configuration parameter. - * + * FRSH_MAX_N_SHARED_OBJECTS configuration parameter. \n + * . * It may also return any of the error codes that are returned by - * the pthread_mutex_init(), pthread_mutexattr_init(), - * pthread_mutexattr_destroy(), pthread_mutexattr_setprotocol() or - * pthread_mutexattr_setprioceiling() POSIX function calls + * fosa_mutex_init() and fosa_mutex_set_prioceiling(). * **/ -int frsh_init_shared_object - (frsh_shared_obj_id_t obj_id, - frsh_shared_obj_kind_t obj_kind, - frsh_shared_obj_handle_t *obj_handle, - pthread_mutex_t *mutex); +int frsh_sharedobj_init + (char *obj_label, + frsh_sharedobj_kind_t obj_kind, + frsh_sharedobj_handle_t *obj_handle, + frsh_mutex_t *mutex); /** - * frsh_get_shared_obj_handle() + * frsh_sharedobj_get_handle() * * Getting the handle of shared objects. If the object already exists * a handle to the object is returned in the variable pointed to by - * obj_handle. Otherwise, an error code is returned by the function. + * obj_handle. Otherwise, an error code is returned. * - * @param[in] obj_id Defined by the application at object creation - * time. + * @param[in] obj_label Defined by the application at object creation + * time. Char * for a string of FRSH_MAX_SIZE_SHARED_OBJ_LABEL + * characters (+ null terminating \0). * * @param[out] obj_handle Placeholder for the object handle. * - * @return - * FRSH_ERR_BAD_ARGUMENT : if obj_id or obj_handle are NULL + * @return 0 if no error \n + * FRSH_ERR_BAD_ARGUMENT : if label or obj_handle are NULL \n * FRSH_ERR_SHARED_OBJ_NOT_INITIALIZED : if the shared object identified - * by obj_id does not exist + * by obj_label does not exist \n * FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not - * scheduled under the FRSH - * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running - * FRSH_ERR_NOT_CONTRACTED_SERVER : if the server of the calling thread - * has been cancelled or it is not valid - * + * scheduled under FRSH \n + * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not + * running \n + * FRSH_ERR_NOT_CONTRACTED_VRES : if the vres of the calling thread + * has been cancelled or it is not valid \n + * . * It may also return any of the error codes that are returned by the - * pthread_mutex_init() POSIX function call + * fosa_mutex_init() function call * **/ -int frsh_get_shared_obj_handle - (frsh_shared_obj_id_t obj_id, - frsh_shared_obj_handle_t *obj_handle); +int frsh_sharedobj_get_handle + (char *obj_label, + frsh_sharedobj_handle_t *obj_handle); /** - * frsh_get_shared_obj_mutex() + * frsh_sharedobj_get_mutex() * * Getting the mutex of shared objects. * - * This function returns an error if the shared object is protected. - * * @param[in] obj_handle Handle of the shared object * * @param[out] mutex Placeholder for A POINTER to a pointer of the * mutex. We give the pointer to discourage the * application of using a local copy of the mutex. * - * @return + * @return 0 if no error \n * FRSH_ERR_BAD_ARGUMENT : if obj_handle or mutex are NULL or obj_handle - * is not correct or reference a wrong shared object + * is not correct or reference a wrong shared object \n * FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not - * scheduled under the FRSH - * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running - * FRSH_ERR_NOT_CONTRACTED_SERVER : if the server of the calling thread + * scheduled under the FRSH \n + * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not + * running \n + * FRSH_ERR_NOT_CONTRACTED_VRES : if the vres of the calling thread * has been cancelled or it is not valid * **/ -int frsh_get_shared_obj_mutex - (frsh_shared_obj_handle_t obj_handle, - pthread_mutex_t **mutex); +int frsh_sharedobj_get_mutex + (frsh_sharedobj_handle_t obj_handle, + frsh_mutex_t **mutex); /** - * frsh_get_shared_obj_obj_kind() + * frsh_sharedobj_get_obj_kind() * * Get the object kind (protected/unprotected) of the object handle. * @@ -298,41 +286,43 @@ int frsh_get_shared_obj_mutex * @param[out] obj_kind Placeholder for an enumeration variable of * protected / unprotected. * - * @return + * @return 0 if no error \n * FRSH_ERR_BAD_ARGUMENT : if obj_handle or mutex are NULL or obj_handle - * is not correct or reference a wrong shared object + * is not correct or reference a wrong shared object \n * FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not - * scheduled under the FRSH - * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running - * FRSH_ERR_NOT_CONTRACTED_SERVER : if the server of the calling thread - * has been cancelled or it is not valid + * scheduled under the FRSH \n + * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not + * running \n + * FRSH_ERR_NOT_CONTRACTED_VRES : if the vres of the calling thread + * has been cancelled or it is not valid * **/ -int frsh_get_shared_obj_obj_kind - (frsh_shared_obj_handle_t obj_handle, - frsh_shared_obj_kind_t *obj_kind); +int frsh_sharedobj_get_obj_kind + (frsh_sharedobj_handle_t obj_handle, + frsh_sharedobj_kind_t *obj_kind); /** - * frsh_remove_shared_obj() + * frsh_sharedobj_remove() * * Allows the implementation to remove a shared object when the last - * server referencing it is cancelled. This removes the object id and + * vres referencing it is cancelled. This removes the object id and * other internal data associated with the object, but does not remove * the mutex; this is done by the application through the common POSIX - * API + * API. * - * @return + * @return 0 if no error \n * FRSH_ERR_BAD_ARGUMENT : if obj_handle is NULL or obj_handle - * is not correct or references a wrong shared object + * is not correct or references a wrong shared object \n * FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not - * scheduled under the FRSH - * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running - * FRSH_ERR_NOT_CONTRACTED_SERVER : if the server of the calling thread - * has been cancelled or it is not valid + * scheduled under the FRSH \n + * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not + * running \n + * FRSH_ERR_NOT_CONTRACTED_VRES : if the vres of the calling thread + * has been cancelled or it is not valid * **/ -int frsh_remove_shared_obj - (frsh_shared_obj_handle_t obj_handle); +int frsh_sharedobj_remove + (frsh_sharedobj_handle_t obj_handle); @@ -353,261 +343,226 @@ int frsh_remove_shared_obj **/ /** - * frsh_init_csect() + * frsh_csect_init() * * Initialize the critical section pointed to by csect - * with its kind of operation, a handle - * to its shared object, and the worst-case execution time. + * with a handle to its shared object, and the worst-case execution + * time. * - * This function is common to critical sections time-enforced and - * non-time-enforced. + * The operation_kind is set to FRSH_CSOK_UNCHECKED. * * @param[in] obj_handle Shared object previously initialised. * - * @param[in] wcet Execution time of the critical section. Note that - * normal budgets associated with contracts must NOT - * include this time. + * @param[in] wcet Execution time of the critical section. This + * budget is consumed in parallel with the vres budget. * - * @param[out] cset Critical section memory placeholder. + * @param[out] csect Critical section memory placeholder. * - * @return - * FRSH_ERR_BAD_ARGUMENT : if obj_handle is NULL or obj_handle - * is not correct or references a wrong shared object, or if - * op_kind is wrong, or if wcet is in the wrong format for - * specifying a time interval value, or if the shared object is - * unprotected and the kind of critical section is not unprotected, - * or if the shared object is protected and the kind of critical - * section is unprotected. + * @return 0 if no error \n + * FRSH_ERR_BAD_ARGUMENT : if obj_handle is NULL \b or \n + * obj_handle is not correct or references a wrong shared object \b or \n + * if wcet is in the wrong format for specifying a time interval value \n * FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not - * scheduled under the FRSH - * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running - * FRSH_ERR_NOT_CONTRACTED_SERVER : if the server of the calling thread + * scheduled under the FRSH \n + * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not + * running \n + * FRSH_ERR_NOT_CONTRACTED_VRES : if the vres of the calling thread * has been cancelled or it is not valid * **/ -int frsh_init_csect - (frsh_shared_obj_handle_t obj_handle, - struct timespec wcet, - frsh_critical_section_data_t *cset); +int frsh_csect_init + (frsh_sharedobj_handle_t obj_handle, + frsh_rel_time_t wcet, + frsh_csect_t *csect); /** - * frsh_get_csect_obj_handle() + * frsh_csect_get_sharedobj_handle() * * Get in the variable pointed to by obj_handle the handle to the * shared object stored in the critical section referenced by csect * - * @return: - * FRSH_ERR_BAD_ARGUMENT : if cset or obj_handle are NULL or cset - * is not correct + * @return 0 if no error \n + * FRSH_ERR_BAD_ARGUMENT : if csect or obj_handle are NULL or csect + * is not correct \n * FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not - * scheduled under the FRSH - * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running - * FRSH_ERR_NOT_CONTRACTED_SERVER : if the server of the calling thread + * scheduled under the FRSH \n + * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not + * running \n + * FRSH_ERR_NOT_CONTRACTED_VRES : if the vres of the calling thread * has been cancelled or it is not valid * **/ -int frsh_get_csect_obj_handle - (const frsh_critical_section_data_t *cset, - frsh_shared_obj_handle_t * obj_handle); +int frsh_csect_get_sharedobj_handle + (const frsh_csect_t *csect, + frsh_sharedobj_handle_t * obj_handle); /** - * frsh_get_csect_wcet() + * frsh_csect_get_wcet() * * Get in the variable pointed to by wcet the worst-case execution time * of the operation stored in the critical section referenced by csect. * - * @return: - * FRSH_ERR_BAD_ARGUMENT : if cset or wcet are NULL or cset - * is not correct + * @return 0 if no error \n + * FRSH_ERR_BAD_ARGUMENT : if csect or wcet are NULL or csect + * is not correct \n * FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not - * scheduled under the FRSH - * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running - * FRSH_ERR_NOT_CONTRACTED_SERVER : if the server of the calling thread + * scheduled under FRSH \n + * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not + * running \n + * FRSH_ERR_NOT_CONTRACTED_VRES : if the vres of the calling thread * has been cancelled or it is not valid * **/ -int frsh_get_csect_wcet - (const frsh_critical_section_data_t *cset, - struct timespec *wcet); +int frsh_csect_get_wcet + (const frsh_csect_t *csect, + frsh_rel_time_t *wcet); /** - * frsh_register_csect_read_op() + * frsh_csect_register_read_op() * - * Set the read operation in the protected-read critical section - * referenced by cset. + * Register the given operation with the critical section and set + * op_kind to FRSH_CSOK_READ. * - * If a previously operation (read or write) was already registered - * the function returns an error. Operations cannot be changed, you - * need to destroy the csect and create a new one if you want to - * change the operation. + * The function returns an error if the shared_object is unprotected. * - * @return: - * FRSH_ERR_BAD_ARGUMENT : if cset is NULL or points to a wrong - * critical section, or to a critical section that is not of the - * FRSH_OP_READ kind, or to a critical section which already - * contains a registered operation + * @return 0 if no error \n + * FRSH_ERR_BAD_ARGUMENT : if csect or op are NULL or if csect points + * to a wrong critical section or if the shared_object is of type + * unprotected. * FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not - * scheduled under the FRSH - * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running - * FRSH_ERR_NOT_CONTRACTED_SERVER : if the server of the calling thread + * scheduled under FRSH \n + * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not + * running \n + * FRSH_ERR_NOT_CONTRACTED_VRES : if the vres of the calling thread * has been cancelled or it is not valid * **/ -int frsh_register_csect_read_op - (frsh_critical_section_data_t *cset, - frsh_critical_section_op_t op); +int frsh_csect_register_read_op + (frsh_csect_t *csect, + frsh_csect_op_t op); /** - * frsh_register_csect_write_op() + * frsh_csect_register_write_op() * - * Set the write operation and the associated memory areas to be backed-up - * in the protected-write critical section referenced by cset + * Register the given operation with the critical section, register + * the memory areas and set op_kind to FRSH_CSOK_WRITE. * * If the memory areas are empty the functions returns an error. * - * If a previously operation (read or write) was already registered - * the function returns an error. Operations cannot be changed, you - * need to destroy the csect and create a new one if you want to - * change the operation. - * - * @return - * FRSH_ERR_BAD_ARGUMENT : if cset or areas are NULL or cset points - * to a wrong critical section, or to a critical section that is - * not of the FRSH_OP_WRITE kind, or to a critical section which already - * contains a registered operation, or if area points to a wrong - * memory areas variable. + * The function returns an error if the shared_object is unprotected. + * + * @return 0 if no error \n + * FRSH_ERR_BAD_ARGUMENT : if op, csect or areas are NULL or csect points + * to a wrong critical section, or areas has a wrong size, or if the + * shared_object of csect is of type unprotected. * FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not - * scheduled under the FRSH - * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running - * FRSH_ERR_NOT_CONTRACTED_SERVER : if the server of the calling thread + * scheduled under the FRSH \n + * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not + * running \n + * FRSH_ERR_NOT_CONTRACTED_VRES : if the vres of the calling thread * has been cancelled or it is not valid * **/ -int frsh_register_csect_write_op - (frsh_critical_section_data_t *cset, - frsh_critical_section_op_t op, +int frsh_csect_register_write_op + (frsh_csect_t *csect, + frsh_csect_op_t op, const frsh_memory_areas_t *areas); /** - * frsh_get_csect_op_kind() + * frsh_csect_get_op_kind() * - * Returns the type of operation (read/write) of the critical section - * or FRSH_CSOT_NONE if no operation is currently defined. + * Returns the type of operation (read/write/unchecked) of the critical section. * - * Get in the variable pointed to by op_kind the kind of - * operation (read or write) stored in the critical section referenced by csect - * - * @return: - * FRSH_ERR_BAD_ARGUMENT : if cset or op_kind are NULL or cset - * is not correct + * @return 0 if no error \n + * FRSH_ERR_BAD_ARGUMENT : if csect or op_kind are NULL or csect + * is not correct \n * FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not - * scheduled under the FRSH - * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running - * FRSH_ERR_NOT_CONTRACTED_SERVER : if the server of the calling thread + * scheduled under FRSH \n + * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not + * running \n + * FRSH_ERR_NOT_CONTRACTED_VRES : if the vres of the calling thread * has been cancelled or it is not valid * **/ -int frsh_get_csect_op_kind - (const frsh_critical_section_data_t *cset, - frsh_critical_section_op_kind_t *op_kind); +int frsh_csect_get_op_kind + (const frsh_csect_t *csect, + frsh_csect_op_kind_t *op_kind); /** - * frsh_get_csect_read_op() + * frsh_csect_get_read_op() * * Get into the variable pointed to by op the operation pointer stored - * in the critical section referenced by cset. - * - * If the operation is of write type it returns an error. + * in the critical section referenced by csect. * - * If the operation has not yet been registered it returns a NULL value. + * If the csect is of type write or unchecked it returns an error. * - * [@return: - * FRSH_ERR_BAD_ARGUMENT : if cset is NULL or points to a wrong + * @return 0 if no error \n + * FRSH_ERR_BAD_ARGUMENT : if csect is NULL or points to a wrong * critical section, or to a critical section that is not of the - * FRSH_OP_READ kind + * FRSH_CSOK_READ kind \n * FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not - * scheduled under the FRSH - * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running - * FRSH_ERR_NOT_CONTRACTED_SERVER : if the server of the calling thread + * scheduled under FRSH \n + * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not + * running \n + * FRSH_ERR_NOT_CONTRACTED_VRES : if the vres of the calling thread * has been cancelled or it is not valid * **/ -int frsh_get_csect_read_op - (const frsh_critical_section_data_t *cset, - frsh_critical_section_op_t *op); +int frsh_csect_get_read_op + (const frsh_csect_t *csect, + frsh_csect_op_t *op); /** - * frsh_get_csect_write_op() + * frsh_csect_get_write_op() * - * Get into the operation pointer and the memory areas associated to a - * write operation in a critical section. + * Get the operation pointer and the memory areas stored in the csect. * - * If the operation is of read type it returns an error. + * If the csect is of type read or unchecked. * - * @return - * FRSH_ERR_BAD_ARGUMENT : if cset is NULL or points to a wrong + * @return 0 if no error \n + * FRSH_ERR_BAD_ARGUMENT : if csect is NULL or points to a wrong * critical section, or to a critical section that is not of the - * FRSH_OP_WRITE kind + * FRSH_CSOK_WRITE kind \n * FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not - * scheduled under the FRSH - * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running - * FRSH_ERR_NOT_CONTRACTED_SERVER : if the server of the calling thread - * has been cancelled or it is not valid + * scheduled under FRSH \n + * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not + * running \n + * FRSH_ERR_NOT_CONTRACTED_VRES : if the vres of the calling thread + * has been cancelled or it is not valid \n * **/ -int frsh_get_csect_write_op - (const frsh_critical_section_data_t *cset, - frsh_critical_section_op_t *op, +int frsh_csect_get_write_op + (const frsh_csect_t *csect, + frsh_csect_op_t *op, frsh_memory_areas_t *areas); -/** - * frsh_get_csect_memory_areas() - * - * Get into the variable pointed to by areas the memory areas associated - * with the write operation stored in the protected-write critical section - * referenced by cset. - * - * If the operation is of read type it returns an error. - * - * @return: - * FRSH_ERR_BAD_ARGUMENT : if cset is NULL or points to a wrong - * critical section, or to a critical section that is not of the - * FRSH_OP_WRITE kind - * FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not - * scheduled under the FRSH - * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running - * FRSH_ERR_NOT_CONTRACTED_SERVER : if the server of the calling thread - * has been cancelled or it is not valid - * - **/ -int frsh_get_csect_memory_areas - (const frsh_critical_section_data_t *cset, - frsh_memory_areas_t *areas); /** * frsh_csect_invoke() * - * Invoke the referenced protected critical section, with the pointers + * Invoke the registered operation in the critical section, with the pointers * to the input and output parameters specified by input_arg and - * output arg, setting a budget for the operation and executing the - * registered operation. + * output arg. + * + * If the section is of type FRSH_CSOK_UNCHECKED, the function returns + * an error. * - * For read operations, the mutex is locked, the budget is set equal + * For read operations, the mutex is locked, the csect budget is set equal * to the wcet, the registered read operation is invoked, and then the - * mutex is unlocked; if the budget expires, the operation is + * mutex is unlocked; if the csect budget expires, the operation is * interrupted, the mutex is unlocked, and the function returns with * an error code. * * For write operations, the mutex is locked, the registered memory - * areas are backed up, a budget is set equal to the wcet, the + * areas are backed up, the csect budget is set equal to the wcet, the * registered write operation is called, and the mutex is unlocked. If - * the budget expires, the operation is interrupted, the backed-up + * the csect budget expires, the operation is interrupted, the backed-up * memory areas are recovered, the mutex is unlocked, and the function * returns with an error code. The blocking time suffered by higher * priority tasks is at most the wcet of the operation plus the backup @@ -616,51 +571,79 @@ int frsh_get_csect_memory_areas * If the shared object in the critical section is not protected it * returns an error. * - * If no operation has yet been registered it returns an error. - * - * @return: - * FRSH_ERR_BAD_ARGUMENT : if cset is NULL or points to a wrong - * critical section, or to a critical section that is unprotected - * FRSH_ERR_BUDGET_EXPIRED : the budget expired and the protected - * operation was interrupted + * @return 0 if no error \n + * FRSH_ERR_BAD_ARGUMENT : if csect is NULL or points to a wrong + * critical section, or to a critical section that is unprotected \n + * FRSH_ERR_BUDGET_EXPIRED : the csect budget expired and the protected + * operation was interrupted \n * FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not - * scheduled under the FRSH - * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running - * FRSH_ERR_NOT_CONTRACTED_SERVER : if the server of the calling thread + * scheduled under FRSH \n + * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not + * running \n + * FRSH_ERR_NOT_CONTRACTED_VRES : if the vres of the calling thread * has been cancelled or it is not valid * **/ int frsh_csect_invoke - (const frsh_critical_section_data_t *cset, + (const frsh_csect_t *csect, const void * input_arg, void * output_arg); /** - * frsh_get_csect_blocking_time() + * frsh_csect_get_blocking_time() * * Get in the variable pointed to by blocking the maximum blocking * time of the operation of the referenced protected critical section. * - * For read operations, the maximum blocking time is the wcet. + * For read or unchecked operations, the maximum blocking time is the wcet. * * For write operations, the maximum blocking time suffered by higher * priority tasks is the wcet of the operation plus the backup time * plus the recovery time. * - * @return: - * FRSH_ERR_BAD_ARGUMENT : if cset or blocking are NULL or if csect + * @return 0 if no error \n + * FRSH_ERR_BAD_ARGUMENT : if csect or blocking are NULL or if csect * points to a wrong critical section, or to a critical section - * that is unprotected + * that is unprotected \n * FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not - * scheduled under the FRSH - * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not running - * FRSH_ERR_NOT_CONTRACTED_SERVER : if the server of the calling thread + * scheduled under FRSH \n + * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not + * running \n + * FRSH_ERR_NOT_CONTRACTED_VRES : if the vres of the calling thread * has been cancelled or it is not valid * **/ int frsh_csect_get_blocking_time - (const frsh_critical_section_data_t *cset, - struct timespec *blocking); + (const frsh_csect_t *csect, + frsh_rel_time_t *blocking); + + +/** + * frsh_csect_destroy() + * + * Destroy a critical section, deallocating all the resources that may + * have been allocated to it. + **/ +int frsh_csect_destroy + (frsh_csect_t *csect); + +/** + * frsh_csect_register_thread() + * + * Register the calling thread for invoking time-protected critical + * sections via frsh_csect_invoke. + **/ +int frsh_csect_register_thread(); + +/** + * frsh_csect_deregister_thread() + * + * Deregister the calling thread from being able to invoke + * time-protected critical sections. This operation releases system + * resources that may have been allocated for the thread. + **/ +int frsh_csect_deregister_thread(); + /*@}*/ /* For so_critical group */ @@ -681,23 +664,23 @@ int frsh_csect_get_blocking_time /** - * frsh_set_contract_synchronization_parameters() + * frsh_contract_set_csects() * * The operation updates the specified contract parameters object by * setting its critical sections to the specified input parameter. * - * @return + * @return 0 if no error \n * FRSH_ERR_BAD_ARGUMENT : if any of the pointers is NULL or * the size of the critical_sections structure is less than zero - * or grater than FRSH_MAX_N_CRITICAL_SECTIONS + * or greater than FRSH_MAX_N_CRITICAL_SECTIONS * **/ -int frsh_set_contract_synchronization_parameters - (frsh_contract_parameters_t *contract, - const frsh_critical_sections_t *critical_sections); +int frsh_contract_set_csects + (frsh_contract_t *contract, + const frsh_csects_group_t *critical_sections); /** - * frsh_get_contract_synchronization_parameters() + * frsh_contract_get_csects() * * The operation obtains from the specified contract parameters object * its critical sections, and copies them to the places pointed to by @@ -705,16 +688,18 @@ int frsh_set_contract_synchronization_parameters * records that are in use in the critical_sections structure are * copied (according to its size field). * - * @return: + * @return 0 if no error \n * FRSH_ERR_BAD_ARGUMENT : if any of the pointers is NULL * **/ -int frsh_get_contract_synchronization_parameters - (const frsh_contract_parameters_t *contract, - frsh_critical_sections_t *critical_sections); +int frsh_contract_get_csects + (const frsh_contract_t *contract, + frsh_csects_group_t *critical_sections); /*@}*/ /* For so_contract group */ /*@}*/ /* For shared_objects group */ +FRSH_CPP_END_DECLS + #endif // _FRSH_SHARED_OBJECTS_H_