*
* FRSH_MAX_N_SHARED_OBJECTS 100
* FRSH_MAX_N_CRITICAL_SECTIONS 20
+ * FRSH_MAX_N_MEMORY_AREAS 4
*
* @{
**/
* @{
**/
-
/**
* frsh_init_shared_object()
*
* 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.
+ * exists, the function fails. The object is created according to the
+ * kind of object (protected or unprotected) specified by obj_kind
*
- * [@return:
+ * @return
* 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
* the pthread_mutex_init(), pthread_mutexattr_init(),
* pthread_mutexattr_destroy(), pthread_mutexattr_setprotocol() or
* pthread_mutexattr_setprioceiling() POSIX function calls
- * ]
+ *
**/
int frsh_init_shared_object
(frsh_shared_obj_id_t obj_id,
frsh_shared_obj_handle_t *obj_handle,
- bool protected,
- pthread_mutex_t *mutex);
+ pthread_mutex_t *mutex,
+ frsh_shared_obj_kind_t obj_kind);
+
/**
* pointer to its associated mutex is returned in the variable pointed
* to by mutex. Otherwise, an error code is returned by the function.
*
- * [@return:
+ * @return:
* 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
* 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_remove_shared_obj()
+ *
+ * Allows the implementation to remove a shared object when the last
+ * server 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:
+ * FRSH_ERR_BAD_ARGUMENT : if obj_handle is NULL or obj_handle
+ * is not correct or references 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_remove_shared_obj
+ (frsh_shared_obj_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_init_csect()
+ *
+ * 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
+ *
+ * @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.
+ * 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_init_csect
+ (frsh_critical_section_data_t *cset,
+ frsh_shared_obj_op_kind_t op_kind,
+ frsh_shared_obj_handle_t obj_handle,
+ struct timespec wcet);
+
+/**
+ * frsh_get_csect_op_kind()
+ *
+ * Get in the variable pointed to by op_kind the kind of
+ * operation 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
+ * 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_op_kind
+ (const frsh_critical_section_data_t *cset,
+ frsh_shared_obj_op_kind_t * op_kind);
+
+/**
+ * frsh_get_csect_obj_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
+ * 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_obj_handle
+ (const frsh_critical_section_data_t *cset,
+ frsh_shared_obj_handle_t * obj_handle);
+
+/**
+ * frsh_get_csect_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
+ * 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_wcet
+ (const frsh_critical_section_data_t *cset,
+ struct timespec *wcet);
+
+
+/**
+ * frsh_register_csect_read_op()
+ *
+ * Set the read operation in the protected-read critical section
+ * referenced by cset
+ *
+ * @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
+ * 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_register_csect_read_op
+ (frsh_critical_section_data_t *cset,
+ frsh_shared_obj_op_t op);
+
+
+/**
+ * frsh_get_csect_read_op()
+ *
+ * Get into the variable pointed to by op the read operation stored in
+ * the protected-read critical section referenced by cset
+ *
+ * [@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
+ * 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_read_op
+ (const frsh_critical_section_data_t *cset,
+ frsh_shared_obj_op_t *op);
+
+
+/**
+ * frsh_register_csect_write_op()
+ *
+ * Set the write operation and the associated memory areas to be backed-up
+ * in the protected-write critical section referenced by cset
+ *
+ * @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.
+ * 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_register_csect_write_op
+ (frsh_critical_section_data_t *cset,
+ frsh_shared_obj_op_t op,
+ const frsh_memory_areas_t *areas);
+
+
+/**
+ * frsh_get_csect_write_op()
+ *
+ * Get into the variable pointed to by op the write operation stored in
+ * the protected-write critical section referenced by cset
+ *
+ * @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_write_op
+ (const frsh_critical_section_data_t *cset,
+ frsh_shared_obj_op_t *op);
+
+/**
+ * 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
+ *
+ * @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
+ * to the input and output parameters specified by input_arg and
+ * output arg, setting a budget for the operation and executing the
+ * registered operation.
+ *
+ * For read operations, the mutex is locked, the 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
+ * 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
+ * registered write operation is called, and the mutex is unlocked. If
+ * the 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.
+ *
+ * @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
+ * 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_csect_invoke
+ (const frsh_critical_section_data_t *cset,
+ const void * input_arg,
+ void * output_arg);
+
+/**
+ * frsh_get_csect_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 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
+ * points to a wrong critical section, or to a critical section
+ * that is 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
+ * has been cancelled or it is not valid
+ *
+ **/
+int frsh_csect_get_blocking_time
+ (const frsh_critical_section_data_t *cset,
+ struct timespec *blocking);
+
+
+/*@}*/ /* For so_critical group */
+
+
/////////////////////////////////////////////////////
// CONTRACT PARAMETERS
/////////////////////////////////////////////////////
* The operation updates the specified contract parameters object by
* setting its critical sections to the specified input parameter.
*
- * [@return:
+ * @return
* 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,
* records that are in use in the critical_sections structure are
* copied (according to its size field).
*
- * [@return:
+ * @return:
* FRSH_ERR_BAD_ARGUMENT : if any of the pointers is NULL
- * ]
+ *
**/
int frsh_get_contract_synchronization_parameters
(const frsh_contract_parameters_t *contract,
projects / frescor / frsh-include.git / commitdiff