Shared Objects module

Functions
int	fsf_init_shared_object (fsf_shared_obj_id_t obj_id, fsf_shared_obj_handle_t *obj_handle, pthread_mutex_t *mutex)
int	fsf_get_shared_object_handle (fsf_shared_obj_id_t obj_id, fsf_shared_obj_handle_t *obj_handle)
int	fsf_get_shared_object_mutex (fsf_shared_obj_handle_t obj_handle, pthread_mutex_t **mutex)
int	fsf_set_contract_synchronization_parameters (fsf_contract_parameters_t *contract, const fsf_critical_sections_t *critical_sections)
int	fsf_get_contract_synchronization_parameters (const fsf_contract_parameters_t *contract, fsf_critical_sections_t *critical_sections)

---

Detailed Description

The shared objects module of FSF allows the application to specify in the contract attributes all the information required to do the schedulability analysis.

The set of shared objects present in the system together with the lists of critical sections specified for each contract are used for schedulability analysis purposes only. A run-time mechanism for mutual exclusion is not provided in FSF for two important reasons. One of them is upward compatibility of previous code using regular primitives such as mutexes or protected objects (in Ada); this is a key issue if we want to persuade application developers to switch their systems to the FSF environment. The second reason is that enforcing worst case execution time for critical sections is expensive. The number of critical sections in real pieces of code may be very high, in the tens or in the hundreds per task, and monitoring all of them would require a large amount of system resources.

The FSF application does not depend on any particular synchronization protocol, but there is a requirement that a budget expiration cannot occur inside a critical section, because otherwise the blocking delays could be extremely large. This implies that the application is allowed to overrun its budget for the duration, at most, of the critical section, and this extra budget is taken into account in the schedulability analysis.

---

Function Documentation

int fsf_get_contract_synchronization_parameters (  const fsf_contract_parameters_t *  contract, fsf_critical_sections_t *  critical_sections )

The operation obtains from the specified contract parameters object its critical sections, and copies them to the places pointed to by the specified input parameter. Only those critical_section_data records that are in use in the critical_sections structure are copied (according to its size field). Parameters: in]  contract pointer to a contract out]  critical_sections list of critical sections to be filled Return values: 0  if the operation is succesful FSF_ERR_BAD_ARGUMENT  if any of the pointers is NULL

int fsf_get_shared_object_handle (  fsf_shared_obj_id_t  obj_id, fsf_shared_obj_handle_t *  obj_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. Parameters: [in]  obj_id shared object id [out]  obj_handle pointer to a shared object handle Return values: 0  if the operation is succesful FSF_ERR_BAD_ARGUMENT  if obj_id or obj_handle are NULL FSF_ERR_SHARED_OBJ_NOT_INITIALIZED  if the shared object identified by obj_id does not exist FSF_ERR_NOT_SCHEDULED_CALLING_THREAD  : if the calling thread is not scheduled under the FSF FSF_ERR_INVALID_SCHEDULER_REPLY  the scheduler is wrong or not running FSF_ERR_NOT_CONTRACTED_SERVER  : if the server of the calling thread has been cancelled or it is not valid

int fsf_get_shared_object_mutex (  fsf_shared_obj_handle_t  obj_handle, pthread_mutex_t **  mutex )

Getting the mutex of shared objects. If the object exists, a pointer to its associated mutex is returned in the variable pointed to by mutex. Otherwise, an error code is returned by the function. Parameters: [in]  obj_handle shared object handle [out]  mutex pointer to a pointer to a mutex variable, (remember that the function give back a pointer to a mutex!) Return values: 0  if the operation is succesful FSF_ERR_BAD_ARGUMENT  if obj_handle or mutex are NULL or obj_handle is not correct or reference a wrong shared object FSF_ERR_NOT_SCHEDULED_CALLING_THREAD  : if the calling thread is not scheduled under the FSF FSF_ERR_INVALID_SCHEDULER_REPLY  the scheduler is wrong or not running FSF_ERR_NOT_CONTRACTED_SERVER  if the server of the calling thread has been cancelled or it is not valid

int fsf_init_shared_object (  fsf_shared_obj_id_t  obj_id, fsf_shared_obj_handle_t *  obj_handle, pthread_mutex_t *  mutex )

Initialization of shared objects. If the object identified by obj_id 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. Parameters: [in]  obj_id shared object id [out]  obj_handle pointer to a shared object handle [out]  mutex pointer to a mutex variable Return values: 0  if the operation is succesful FSF_ERR_BAD_ARGUMENT  if obj_id, obj_handle, or mutex are NULL FSF_ERR_SHARED_OBJ_ALREADY_INITIALIZED  if the object identified by obj_id already exists others  It may also return any of the error codes that are returned by the pthread_mutex_init() POSIX function call

int fsf_set_contract_synchronization_parameters (  fsf_contract_parameters_t *  contract, const fsf_critical_sections_t *  critical_sections )

The operation updates the specified contract parameters object by setting its critical sections to the specified input parameter. Parameters: in]  contract the service contract in]  critical_sections list of critical sections accessed by tasks belonging to the contract Return values: 0  if the operation is succesful FSF_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 FSF_MAX_N_CRITICAL_SECTIONS

---