#ifndef _FRSH_SHARED_OBJECTS_H_
#define _FRSH_SHARED_OBJECTS_H_
-#include "frsh_fosa.h"
#include "frsh_shared_objects_types.h"
#include "frsh_core_types.h"
+FRSH_CPP_BEGIN_DECLS
#define FRSH_SHAREDOBJS_MODULE_SUPPORTED 1
* 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:
- *
- * - UNBOUNDED critical sections:
- * - They are considered in FRSH only for analysis purposes. They
- * inform FRSH about which shared objects are used in which
- * contracts in order to compute blocking times.
- * - These critical sections are executed directly by the
- * application and it is the designer's responsibility to
- * respect the specified wcet.
- * - They can only contain unprotected shared objects because
- * their mutex must be visible to the application.
- *
- * - BOUNDED cricital sections:
- * - They provide not only analysis information but also the
- * needed means for FRSH to enforce the wcet of the critical
- * section in a clean way.
- * - For a bounded critical section FRSH aborts its execution 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.
- * - The application cannot modify directly the memory areas and
- * therefore cannot execute the critical section directly.
- * Instead it executes it indirectly via frsh_csect_invoke()
- * providing a callback to the critical section.
- * - This time protection comes at a penalty of extra blocking
- * blocking time accounted for the backup and the possible need
- * of restoration of the modified memory areas.
- *
- *
- * We allow bounded 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 bounded
- * 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 label (char *) 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 unbounded).
- * - An attribute operation kind (unbounded, write or read).
- * - A list of memory areas modified by the operation (when it is
- * write).
+ *
+ * - <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
- * 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
*
* @{
**/
* 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
+ * 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
* kind of object (protected or unprotected) specified by obj_kind
*
* @param[in] obj_label Label defined by the application. Char * for
- * a string of SHAREDOBJ_LABEL_MAXLENGTH
+ * 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 0 if no error \n
* FRSH_ERR_BAD_ARGUMENT : if obj_label, obj_handle, or mutex are NULL \n
*
* 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_label Defined by the application at object creation
- * time. Char * for a string of SHAREDOBJ_LABEL_MAXLENGTH
- * characters (+ null terminating \0).
+ * 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.
*
*
* 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
frsh_mutex_t **mutex);
/**
- * frsh_sharedobj_get_objkind()
+ * frsh_sharedobj_get_obj_kind()
*
* Get the object kind (protected/unprotected) of the object handle.
*
* has been cancelled or it is not valid
*
**/
-int frsh_sharedobj_get_objkind
+int frsh_sharedobj_get_obj_kind
(frsh_sharedobj_handle_t obj_handle,
frsh_sharedobj_kind_t *obj_kind);
* 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 0 if no error \n
* FRSH_ERR_BAD_ARGUMENT : if obj_handle is NULL or obj_handle
* 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 bounded and unbounded.
+ * 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 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, 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. \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
**/
int frsh_csect_init
(frsh_sharedobj_handle_t obj_handle,
- struct timespec wcet,
+ frsh_rel_time_t wcet,
frsh_csect_t *csect);
* shared object stored in the critical section referenced by csect
*
* @return 0 if no error \n
- * FRSH_ERR_BAD_ARGUMENT : if cset or obj_handle are NULL or cset
+ * 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
*
**/
int frsh_csect_get_sharedobj_handle
- (const frsh_csect_t *cset,
+ (const frsh_csect_t *csect,
frsh_sharedobj_handle_t * obj_handle);
/**
* of the operation stored in the critical section referenced by csect.
*
* @return 0 if no error \n
- * FRSH_ERR_BAD_ARGUMENT : if cset or wcet are NULL or cset
+ * 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
*
**/
int frsh_csect_get_wcet
- (const frsh_csect_t *cset,
- struct timespec *wcet);
+ (const frsh_csect_t *csect,
+ frsh_rel_time_t *wcet);
/**
* 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 0 if no error \n
- * 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 \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
*
**/
int frsh_csect_register_read_op
- (frsh_csect_t *cset,
+ (frsh_csect_t *csect,
frsh_csect_op_t 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.
+ * The function returns an error if the shared_object is unprotected.
*
* @return 0 if no error \n
- * 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 \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
*
**/
int frsh_csect_register_write_op
- (frsh_csect_t *cset,
+ (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) of the critical section
- * or FRSH_CSOT_NONE if no operation is currently defined.
- *
- * Get in the variable pointed to by op_kind the kind of
- * operation (read or write) stored in the critical section referenced by csect
+ * Returns the type of operation (read/write/unchecked) of the critical section.
*
* @return 0 if no error \n
- * FRSH_ERR_BAD_ARGUMENT : if cset or op_kind are NULL or cset
+ * 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
*
**/
int frsh_csect_get_op_kind
- (const frsh_csect_t *cset,
+ (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 cset.
+ * in the critical section referenced by csect.
*
- * If the operation is of write type it returns an error.
- *
- * 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 0 if no error \n
- * FRSH_ERR_BAD_ARGUMENT : if cset is NULL or points to a wrong
+ * 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 \n
+ * 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
*
**/
int frsh_csect_get_read_op
- (const frsh_csect_t *cset,
+ (const frsh_csect_t *csect,
frsh_csect_op_t *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 0 if no error \n
- * FRSH_ERR_BAD_ARGUMENT : if cset is NULL or points to a wrong
+ * 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 \n
+ * 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
*
**/
int frsh_csect_get_write_op
- (const frsh_csect_t *cset,
+ (const frsh_csect_t *csect,
frsh_csect_op_t *op,
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
* 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 0 if no error \n
- * FRSH_ERR_BAD_ARGUMENT : if cset is NULL or points to a wrong
+ * 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 budget expired and the protected
+ * 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
*
**/
int frsh_csect_invoke
- (const frsh_csect_t *cset,
+ (const frsh_csect_t *csect,
const void * input_arg,
void * output_arg);
* 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 0 if no error \n
- * FRSH_ERR_BAD_ARGUMENT : if cset or blocking are NULL or if csect
+ * 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
*
**/
int frsh_csect_get_blocking_time
- (const frsh_csect_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 */
* @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_contract_set_csects
/*@}*/ /* For shared_objects group */
+FRSH_CPP_END_DECLS
+
#endif // _FRSH_SHARED_OBJECTS_H_