// -----------------------------------------------------------------------
-// Copyright (C) 2005 Mälardalen University, SWEDEN
+// Copyright (C) 2006 - 2007 FRESCOR consortium partners:
+//
+// Universidad de Cantabria, SPAIN
+// University of York, UK
+// Scuola Superiore Sant'Anna, ITALY
+// Kaiserslautern University, GERMANY
+// Univ. Politécnica Valencia, SPAIN
+// Czech Technical University in Prague, CZECH REPUBLIC
+// ENEA SWEDEN
+// Thales Communication S.A. FRANCE
+// 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
+// in part by the European Union Sixth Framework Programme
+// The European Union is not liable of any use that may be
+// made of this code.
+//
+//
+// 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
// University of York, UK
//
-// FRSH API web pages: http://marte.unican.es/frsh/docs/
+// FSF API web pages: http://marte.unican.es/fsf/docs
// http://shark.sssup.it/contrib/first/docs/
//
// This file is part of FRSH API
// Public License.
// -----------------------------------------------------------------------
//frsh_shared_objects.h
-//==================================================
-// FFFFFFIII RRRRR SSTTTTTTT
-// FF IIR RR SS
-// FF IR SS
-// FFFFFF RRRR SSSSST
-// FF FI RRR SS
-// FF II RRR SS
-// FF IIIIIR RS
-//
-// FRSH(FIRST Scheduling Framework)
-// shared objects functionality
-//====================================================
-#include <pthread.h>
-#include "frsh_basic_types.h"
-#include "frsh_core.h"
+//==============================================
+// ******** ******* ******** ** **
+// **///// /**////** **////// /** /**
+// ** /** /** /** /** /**
+// ******* /******* /********* /**********
+// **//// /**///** ////////** /**//////**
+// ** /** //** /** /** /**
+// ** /** //** ******** /** /**
+// // // // //////// // //
+//
+// FRSH(FRescor ScHeduler), pronounced "fresh"
+//==============================================
#ifndef _FRSH_SHARED_OBJECTS_H_
#define _FRSH_SHARED_OBJECTS_H_
-#define FRSH_SHARED_OBJECTS_MODULE_SUPPORTED 1
+#include "frsh_shared_objects_types.h"
+#include "frsh_core_types.h"
+FRSH_CPP_BEGIN_DECLS
-// These constants are defined in the frsh_configuration_parameters.h
-// file:
+#define FRSH_SHAREDOBJS_MODULE_SUPPORTED 1
-//#define FRSH_MAX_N_SHARED_OBJECTS 100
-//#define FRSH_MAX_N_CRITICAL_SECTIONS 20
+/**
+ * @file frsh_shared_objects.h
+ **/
+/**
+ * @defgroup sharedobj Shared Objects module
+ *
+ * This module includes the functions to declare and use shared
+ * objects in different critical sections.
+ *
+ * A shared object is an abstraction of a mutex giving it a name and a
+ * possible priority ceiling.
+ *
+ * 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.
+ *
+ * - <b>UNPROTECTED shared objects</b>. 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.
+ *
+ * - <b>PROTECTED shared objects</b>. 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.
+ *
+ * - <b>UNCHECKED critical sections</b>. These critical sections are
+ * not monitored by FRSH for wcet compliance. Their wcet value is
+ * used only for analysis purposes (calculation of blocking times).
+ *
+ * - <b>READ critical sections</b>. These critical sections have
+ * their wcet enforced but they don't have any rollback action
+ * applied when their wcet is exceeded.
+ *
+ * - <b>WRITE critical sections</b>. 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 \n
+ * FRSH_MAX_N_CRITICAL_SECTIONS 20\n
+ * FRSH_MAX_N_MEMORY_AREAS 4\n
+ *
+ * @{
+ **/
-//// The definition of this types is in frsh_basic_types.h
-//
-//// Shared object identifier (null character terminated string)
-//typedef char * frsh_shared_obj_id_t;
-//
-//// Shared object handle (opaque type)
-//typedef FRSH_SHARED_OBJ_HANDLE_T_OPAQUE frsh_shared_obj_handle_t;
-//
-//// Critical section data
-//typedef struct {
-// frsh_shared_obj_handle_t obj_handle;
-// struct timespec wcet; //Execution time
-//} frsh_critical_section_data_t;
-//
-//// List of critical sections
-//typedef struct {
-// int size; // = 0
-// frsh_critical_section_data_t
-// section[FRSH_MAX_N_CRITICAL_SECTIONS];
-//} frsh_critical_sections_t;
-//
/////////////////////////////////////////////////////
// SHARED OBJECTS & OPERATIONS MANAGEMENT
/////////////////////////////////////////////////////
+/**
+ * @defgroup so_opp_mgmnt Shared Objects & Operations
+ * @ingroup sharedobj
+ *
+ * These functions are used to declare shared objects and link them
+ * with a mutex.
+ *
+ * @{
+ **/
+
+/**
+ * frsh_sharedobj_init()
+ *
+ * Initialization of shared objects. If the object identified by
+ * 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_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.
+ *
+ * @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 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. \n
+ * .
+ * It may also return any of the error codes that are returned by
+ * fosa_mutex_init() and fosa_mutex_set_prioceiling().
+ *
+ **/
+int frsh_sharedobj_init
+ (char *obj_label,
+ frsh_sharedobj_kind_t obj_kind,
+ frsh_sharedobj_handle_t *obj_handle,
+ frsh_mutex_t *mutex);
+
+
+
+/**
+ * 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.
+ *
+ * @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 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_label does not exist \n
+ * FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
+ * 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
+ * fosa_mutex_init() function call
+ *
+ **/
+int frsh_sharedobj_get_handle
+ (char *obj_label,
+ frsh_sharedobj_handle_t *obj_handle);
+
+
+/**
+ * frsh_sharedobj_get_mutex()
+ *
+ * Getting the mutex of shared objects.
+ *
+ * @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 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 \n
+ * FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
+ * 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_sharedobj_get_mutex
+ (frsh_sharedobj_handle_t obj_handle,
+ frsh_mutex_t **mutex);
+
+/**
+ * frsh_sharedobj_get_obj_kind()
+ *
+ * Get the object kind (protected/unprotected) of the object handle.
+ *
+ * @param[in] obj_handle Handle of the shared object
+ *
+ * @param[out] obj_kind Placeholder for an enumeration variable of
+ * protected / unprotected.
+ *
+ * @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 \n
+ * FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
+ * 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_sharedobj_get_obj_kind
+ (frsh_sharedobj_handle_t obj_handle,
+ frsh_sharedobj_kind_t *obj_kind);
+
+/**
+ * frsh_sharedobj_remove()
+ *
+ * Allows the implementation to remove a shared object when the last
+ * 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.
+ *
+ * @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 \n
+ * FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
+ * 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_sharedobj_remove
+ (frsh_sharedobj_handle_t obj_handle);
+
+
+
+/*@}*/
+
+/////////////////////////////////////////////////////
+// CRITICAL SECTIONS
+/////////////////////////////////////////////////////
+/**
+ * @defgroup so_critical Critical Sections
+ * @ingroup sharedobj
+ *
+ * These functions are used to create and manage the parameters
+ * of critical sections. Critical sections are operations that
+ * make use of a shared object in a mutually exclusive way.
+ *
+ * @{
+ **/
+
+/**
+ * frsh_csect_init()
+ *
+ * Initialize the critical section pointed to by csect
+ * with a handle to its shared object, and the worst-case execution
+ * time.
+ *
+ * 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. This
+ * budget is consumed in parallel with the vres budget.
+ *
+ * @param[out] csect Critical section memory placeholder.
+ *
+ * @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 \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_init
+ (frsh_sharedobj_handle_t obj_handle,
+ frsh_rel_time_t wcet,
+ frsh_csect_t *csect);
-// frsh_init_shared_object: 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.
-/*
- [ERR@RETURNED:
- FRSH_ERR_BAD_ARGUMENT : if obj_id, obj_handle, or mutex are NULL
- FRSH_ERR_SHARED_OBJ_ALREADY_INITIALIZED : if the object identified
- by obj_id already exists
- It may also return any of the error codes that are returned by the
- pthread_mutex_init() POSIX function call
- ]
-*/
-int frsh_init_shared_object
- (frsh_shared_obj_id_t obj_id,
- frsh_shared_obj_handle_t *obj_handle,
- pthread_mutex_t *mutex);
-
-
-// frsh_get_shared_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.
-/*
- [ERR@RETURNED:
- FRSH_ERR_BAD_ARGUMENT : if obj_id or obj_handle are NULL
- FRSH_ERR_SHARED_OBJ_NOT_INITIALIZED : if the shared object identified
- by obj_id does not exist
- 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_shared_obj_handle
- (frsh_shared_obj_id_t obj_id,
- frsh_shared_obj_handle_t *obj_handle);
-
-// frsh_get_shared_obj_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.
-/*
- [ERR@RETURNED:
- FRSH_ERR_BAD_ARGUMENT : if obj_handle or mutex are NULL or obj_handle
- is not correct or reference a wrong shared object
- 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_shared_obj_mutex
- (frsh_shared_obj_handle_t obj_handle,
- pthread_mutex_t **mutex);
+
+/**
+ * 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 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 \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_sharedobj_handle
+ (const frsh_csect_t *csect,
+ frsh_sharedobj_handle_t * obj_handle);
+
+/**
+ * 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 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 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_wcet
+ (const frsh_csect_t *csect,
+ frsh_rel_time_t *wcet);
+
+
+/**
+ * frsh_csect_register_read_op()
+ *
+ * Register the given operation with the critical section and set
+ * op_kind to FRSH_CSOK_READ.
+ *
+ * The function returns an error if the shared_object is unprotected.
+ *
+ * @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 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_register_read_op
+ (frsh_csect_t *csect,
+ frsh_csect_op_t op);
+
+/**
+ * frsh_csect_register_write_op()
+ *
+ * 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.
+ *
+ * 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 \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_register_write_op
+ (frsh_csect_t *csect,
+ frsh_csect_op_t op,
+ const frsh_memory_areas_t *areas);
+
+
+/**
+ * frsh_csect_get_op_kind()
+ *
+ * Returns the type of operation (read/write/unchecked) of the critical section.
+ *
+ * @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 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_op_kind
+ (const frsh_csect_t *csect,
+ frsh_csect_op_kind_t *op_kind);
+
+
+/**
+ * frsh_csect_get_read_op()
+ *
+ * Get into the variable pointed to by op the operation pointer stored
+ * in the critical section referenced by csect.
+ *
+ * If the csect is of type write or unchecked it returns an error.
+ *
+ * @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_CSOK_READ kind \n
+ * FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
+ * 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_read_op
+ (const frsh_csect_t *csect,
+ frsh_csect_op_t *op);
+
+
+
+/**
+ * frsh_csect_get_write_op()
+ *
+ * Get the operation pointer and the memory areas stored in the csect.
+ *
+ * If the csect is of type read or unchecked.
+ *
+ * @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_CSOK_WRITE kind \n
+ * FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
+ * 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_csect_get_write_op
+ (const frsh_csect_t *csect,
+ frsh_csect_op_t *op,
+ frsh_memory_areas_t *areas);
+
+
+/**
+ * frsh_csect_invoke()
+ *
+ * Invoke the registered operation in the critical section, with the pointers
+ * to the input and output parameters specified by input_arg and
+ * output arg.
+ *
+ * If the section is of type FRSH_CSOK_UNCHECKED, the function returns
+ * an error.
+ *
+ * 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 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, the csect budget is set equal to the wcet, the
+ * registered write operation is called, and the mutex is unlocked. If
+ * 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
+ * time plus the recovery time.
+ *
+ * If the shared object in the critical section is not protected it
+ * returns an error.
+ *
+ * @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 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_csect_t *csect,
+ const void * input_arg,
+ void * output_arg);
+
+/**
+ * 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 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 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 \n
+ * FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not
+ * 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_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 */
/////////////////////////////////////////////////////
// CONTRACT PARAMETERS
/////////////////////////////////////////////////////
+/**
+ * @defgroup so_contract Shared Objects & Contract Parameters
+ * @ingroup sharedobj
+ *
+ * These functions are used to link shared objects to contracts via
+ * critical sections.
+ *
+ * @{
+ **/
+
+
+/**
+ * frsh_contract_set_csects()
+ *
+ * The operation updates the specified contract parameters object by
+ * setting its critical sections to the specified input parameter.
+ *
+ * @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 greater than FRSH_MAX_N_CRITICAL_SECTIONS
+ *
+ **/
+int frsh_contract_set_csects
+ (frsh_contract_t *contract,
+ const frsh_csects_group_t *critical_sections);
+
+/**
+ * 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
+ * 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).
+ *
+ * @return 0 if no error \n
+ * FRSH_ERR_BAD_ARGUMENT : if any of the pointers is NULL
+ *
+ **/
+int frsh_contract_get_csects
+ (const frsh_contract_t *contract,
+ frsh_csects_group_t *critical_sections);
+
+/*@}*/ /* For so_contract group */
-//frsh_set_contract_synchronization_parameters: The operation updates
-//the specified contract parameters object by setting its critical
-//sections to the specified input parameter.
-/*
- [ERR@RETURNED:
- 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
- ]
-*/
-int
-frsh_set_contract_synchronization_parameters
- (frsh_contract_parameters_t *contract,
- const frsh_critical_sections_t *critical_sections);
-
-
-//frsh_get_contract_synchronization_parameters: 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).
-/*
- [ERR@RETURNED:
- 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);
+/*@}*/ /* For shared_objects group */
+FRSH_CPP_END_DECLS
#endif // _FRSH_SHARED_OBJECTS_H_