* 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.
*
- * - Unprotected shared objects are considered only for analysis
- * purposes. They inform FRSH about which shared objects are used
- * in which contracts in order to compute blocking times.
+ * There are also two types of critical sections: time-enforced and
+ * non-time-enforced.
*
- * With unprotected shared objects it is the designer's
- * reponsibility to respect the wcet of the critical section. FRSH
- * does not invoke the critical section, it is run in the
- * application directly.
+ * - 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.
*
- * - Protected shared objects provide not only analysis information
- * but also some means for FRSH to enforce the wcet of the critical
- * sections in a clean way.
+ * Non-time-enforced critical sections are executed directly by the
+ * application and it is the designer's responsibility to respect
+ * the specified wcet.
*
- * The extra parameters allow FRSH to invoke an associated critical
- * section and stop in the middle of it (because it has exceeded
- * his wcet) while preserving the atomicity of the data that
- * manipulates.
+ * 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.
*
- * This is achieved by a backup-rollback mechanism
- * that ensures the atomicity at the price of extra execution (and
- * blocking) time (this extra execution time is calculated
- * automatically by FRSH).
*
* A FRSH shared object is an association of:
* - a mutex with an optional priority celing.
* A FRSH critical section is an association of:
* - a shared object
* - a wcet (which is EXTRA from the allocated budget).
- * and if the shared object is protected, the critical section also
- * has:
- * - An operation pointer.
- * - An attribute operation kind (write or read).
+ * - 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).
*
- *
* This module makes use of the following constants defined in
* frsh_configuration_parameters.h. We list them with our proposed
* default values.
*
* @param[out] obj_handle Placeholder for the shared object handle.
*
- * @param[out] mutex Placeholder for the mutex. NOTE: This
- * placeholder must remain valid for the duration
- * of the mutex life.
+ * @param[out] mutex Placeholder for the mutex. (Ignored for
+ * protected shared objects).
*
* @return
* FRSH_ERR_BAD_ARGUMENT : if obj_id, obj_handle, or mutex are NULL
/**
* 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.
+ * 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
*
* with its kind of operation, a handle
* to its shared object, and the worst-case execution time.
*
- * This function is common to critical sections with a protected or an
- * unprotected shared object.
+ * This function is common to critical sections time-enforced and
+ * non-time-enforced.
*
* @param[in] obj_handle Shared object previously initialised.
*
* Set the read operation in the protected-read critical section
* referenced by cset.
*
- * Only for critical sections with a protected shared object.
- *
* 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
* Set the write operation and the associated memory areas to be backed-up
* in the protected-write critical section referenced by cset
*
- * Only for critical sections with a protected shared object.
+ * 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
*
* Returns the type of operation (read/write) of the critical section
* or FRSH_CSOT_NONE if no operation is currently defined.
-
- * Only for critical section of a protected object. Otherwise the
- * function returns an error.
*
* Get in the variable pointed to by op_kind the kind of
* operation (read or write) stored in the critical section referenced by csect
* Get into the variable pointed to by op the operation pointer stored
* in the critical section referenced by cset.
*
- * If the shared_object of the critical section is not protected it
- * returns an error.
- *
* If the operation is of write type it returns an error.
*
- * If no operation has yet been registered it returns a NULL value.
+ * If the operation has not yet been registered it returns a NULL value.
*
* [@return:
* FRSH_ERR_BAD_ARGUMENT : if cset is NULL or points to a wrong
* Get into the operation pointer and the memory areas associated to a
* write operation in a critical section.
*
- * If the shared object in the critical section is not protected it
- * returns an error.
- *
* If the operation is of read type it returns an error.
*
* @return
* with the write operation stored in the protected-write critical section
* referenced by cset.
*
- * If the shared object in the critical section is not protected it
- * returns an error.
- *
* If the operation is of read type it returns an error.
*
* @return:
projects / frescor / frsh-include.git / commitdiff