// -----------------------------------------------------------------------
-// Copyright (C) 2006 - 2008 FRESCOR consortium partners:
+// Copyright (C) 2006 - 2009 FRESCOR consortium partners:
//
// Universidad de Cantabria, SPAIN
// University of York, UK
**/
int frsh_init();
+/**
+ * frsh_destroy()
+ *
+ * Reverts the efect of frsh_init().
+ */
+void frsh_destroy();
+
/*@}*/
int frsh_contract_init(frsh_contract_t *contract);
+/**
+ * frsh_contract_destroy()
+ *
+ * The operation deallocates all memory which might be allocated for
+ * the contract.
+ *
+ * @param contract the pointer to the contract variable.
+ **/
+void frsh_contract_destroy(frsh_contract_t *contract);
+
+
/**
* frsh_contract_set_basic_params()
*
* this parameter is ignored (the contract value
* will be NULL_DEADLINE internally). Otherwise, it
* contains the desired deadline value.
- * @param [in] budget_overrun_signal contains the number of the signal
- * that must be raised if the budget of the vres is overrun.
- * If the value of this parameter is FRSH_NULL_SIGNAL, no signal will
- * be raised.
- * @param [in] budget_overrun_siginfo contains the value that will be
- * passed to the signal "catcher" when the signal is raised.
- * This parameters is not used if the budget_overrun_signal
- * parameter is set to FRSH_NULL_SIGNAL.
- * @param [in] deadline_miss_signal contains the number of the
- * signal that must be raised if the deadline of the
- * vres is missed. If the value of this parameter is
- * FRSH_NULL_SIGNAL, no signal is raised.
- * @param [in] deadline_miss_siginfo contains the value that will be
- * passed to the signal "catcher" when the signal is
- * raised. This parameter is not used if the
- * deadline_signal parameter is set to NULL_SIGNAL
*
* @return 0 if successful\n
* FRSH_ERR_BAD_ARGUMENT : if contract is NULL \b or \n
int frsh_contract_set_timing_reqs
(frsh_contract_t *contract,
const bool d_equals_t,
- const frsh_rel_time_t *deadline,
- const frsh_signal_t budget_overrun_signal,
- const frsh_signal_info_t budget_overrun_siginfo,
- const frsh_signal_t deadline_miss_signal,
- const frsh_signal_info_t deadline_miss_siginfo);
+ const frsh_rel_time_t *deadline);
/**
* frsh_contract_get_timing_reqs()
int frsh_contract_get_timing_reqs
(const frsh_contract_t *contract,
bool *d_equals_t,
- frsh_rel_time_t *deadline,
- frsh_signal_t *budget_overrun_signal,
- frsh_signal_info_t *budget_overrun_siginfo,
- frsh_signal_t *deadline_miss_signal,
- frsh_signal_info_t *deadline_miss_siginfo);
+ frsh_rel_time_t *deadline);
/*@}*/
/**
* frsh_vresperiod_wait()
- *
+ *
* Suspend the calling thread until the start of the specified virtual
- * resource period, for a synchronized workload.
- *
+ * resource period of a vres_id, for a synchronized workload.
+ *
* Virtual resource periods are numbered. The number of the current
* period can be obtained through the frsh_vres_get_period_number()
- * operation.
+ * operation.
**/
-int frsh_vresperiod_wait
- (const frsh_vres_id_t vres,
- long period_num);
+int frsh_vresperiod_wait(unsigned long period_num,
+ frsh_rel_time_t *next_budget,
+ frsh_rel_time_t *next_period,
+ bool *was_deadline_missed,
+ bool *was_budget_overran);
/**
* frsh_vres_get_period()
- *
+ *
* Return the current period number, for a virtual resource of
* synchronized workload.
**/
frsh_vres_id_t *vres_id);
+
+/**
+ * frsh_thread_join_in_background()
+ *
+ * This function is aimed for external threads to join FRSH in the
+ * least disturbing possible mode.
+ *
+ * Upon calling this function by a thread which has been created
+ * natively in the OS, it joins the framework and gets inmediately
+ * bound to an on-the-fly generated background contract.
+ *
+ * In order to gain a higher priority then it can renegotiate a
+ * contract for its vres with the needed parameters.
+ *
+ * @param[in] resource_id: Resource (CPU) in which the vres will
+ * be associated.
+ *
+ * @param[in] resource_type: Resource type (should be CPU) for the
+ * contract.
+ *
+ * @param[in] label: Label to be added to the contract.
+ *
+ * @param[out] vres_id: Resulting vres_id from the on-the-fly
+ * generated background contract.
+ *
+ * @return 0 if successful\n
+ * FRSH_ERR_NOT_CONTRACTED_VRES if the thread is already
+ * bound to a vres.
+ **/
int frsh_thread_join_in_background(frsh_resource_id_t resource_id,
frsh_resource_type_t resource_type,
const char *label,
**/
int frsh_thread_unbind(const frsh_thread_id_t thread);
+/**
+ * frsh_vres_set_notification()
+ *
+ * This function setups notification signals for CPU vres. It is
+ * necessary to call this function before bounding the thread to the
+ * vres.
+ *
+ * @param [in] budget_overrun_signal contains the number of the signal
+ * that must be raised if the budget of the vres is
+ * overrun by the thread.
+ * If the value of this parameter is FRSH_NULL_SIGNAL, no signal will
+ * be raised.
+ * @param [in] budget_overrun_siginfo contains the value that will be
+ * passed to the signal "catcher" when the signal is raised.
+ * This parameters is not used if the budget_overrun_signal
+ * parameter is set to FRSH_NULL_SIGNAL.
+ * @param [in] deadline_miss_signal contains the number of the
+ * signal that must be raised if the deadline of the
+ * vres is missed. If the value of this parameter is
+ * FRSH_NULL_SIGNAL, no signal is raised.
+ * @param [in] deadline_miss_siginfo contains the value that will be
+ * passed to the signal "catcher" when the signal is
+ * raised. This parameter is not used if the
+ * deadline_signal parameter is set to NULL_SIGNAL
+ **/
+int frsh_vres_set_notification(
+ frsh_vres_id_t vres,
+ const frsh_signal_t budget_overrun_signal,
+ const frsh_signal_info_t budget_overrun_siginfo,
+ const frsh_signal_t deadline_miss_signal,
+ const frsh_signal_info_t deadline_miss_siginfo);
+
/**
* frsh_thread_get_vres_id()
*
* running \n
* FRSH_ERR_NOT_CONTRACTED_VRES : if the vres of the calling thread
* has been cancelled or it is not valid \n
- * FRSH_ERR_REJECTED_CONTRACT : if the renegotiation fails
+ * FRSH_ERR_CONTRACT_REJECTED : if the renegotiation fails
*
**/
int frsh_contract_renegotiate_sync
* @{
**/
-/**
- * frsh_group_negotiate()
- *
- * This function negotiates atomically a group of new contracts
- * while giving the possibility of cancellling others.
- *
- * If the on-line admission test is enabled, FRSH analizes the
- * schedulability of the context that results in the new contract
- * situation with removed and added contracts.
- *
- * If the overall negotiation is successful, all actions will be taken
- * inmediatly: the creation of new vres for the contract_up list
- * and the cancellation of the designated ones.
- *
- * If for any reason one of the contracts is not accepted, a
- * corresponding error will be returned and no actions will be taken,
- * the previous context will be preserved.
- *
- * This call is a synchronous, potentially blocking operation. It
- * returns when the system has rejected the contracts or accepted them
- * and made them effective.
- *
- * @param[in] contracts_up List of new proposed contracts
- *
- * @param[in] vres_down List of vres_id to be canceled
- *
- * @param[out] vres_up vres_id assigned by the system to the
- * corresponding contracts_up.
- *
- * @return 0 if no error \n
- * .
- * FRSH_ERR_INVALID_SCHEDULER_REPLY : the scheduler is wrong or not
- * running \n
- * FRSH_ERR_INTERNAL_ERROR : erroneous binding or malfunction of the FRSH
- * main scheduler \n
- * FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD : if the calling thread is not scheduled
- * under FRSH \n
- * FRSH_ERR_BAD_ARGUMENT : if any of the vres_up or accepted arguments
- * is NULL, if the contracts_up and vres_down arguments are both NULL,
- * or any of them has erroneous size or its elements are NULL or not in the
- * valid range respectively
- **/
-int frsh_group_negotiate
- (const frsh_contracts_group_t *contracts_up,
- const frsh_vres_group_t *vres_down,
- frsh_vres_group_t *vres_up);
-
-
-
/**
* frsh_group_change_mode_sync()
*
- * An extension of frsh_group_negotiate() by adding the possibility of
- * specifying also group contract renegotiation and removal.
+ * This function performs a set of negotiation operations which can
+ * include: adding new contracts (neg), modifying existing vres (reneg)
+ * or cancelling existing vres (cancel).
*
- * NOTE: This function will be implemented in a second phase after
- * having fully implemented frsh_group_negotiate() in order to
- * better grasp possible issues that the problems it may raise.
+ * If one of the group operations has a NULL value, unless it causes an
+ * inconsistency the system will suppose that no operation of that
+ * type (neg, reneg or cancel) should be done.
*
- * This is a draft of the specification, it is yet subject to
- * change.
- *
- * This operation performs a global (re)negotiation of a group of
- * contracts in an atomic way. Contracts can be added, canceled or
- * renegotiated. Note that any of the groups can be empty.
+ * The virtual resources resulting from negotiations of new contracts are
+ * returned in the parameter 'new_vres' which must be provided by the user.
*
* If the on-line admission test is enabled, FRSH analizes the
* schedulability of the context that would result in the new
* update of vres) have been carried out to reach the new running
* context.
*
- * If for any reason one of the contracts is not accepted a
- * corresponding error shall be returned and no changes will be made
- * to the previously running context.
+ * If any of the contracts is not accepted a corresponding error shall be
+ * returned and no changes will be made to the previously running context.
*
* This call is a synchronous, potentially blocking operation. It
- * returns when the system has rejected the contracts or accepted them
- * and made them effective. There is also an asynchronous
- * (non-blocking) version of this function below.
- *
- * @param[in] contracts_new_vres Contracts to be added.
- * @param[out] vres_id_new vres_id's corresponding to the new
- * contracts.
- * @param[in] contracts_update_vres New contracts for vres to
- * be updated.
- * @param[in] vres_update vres_id's corresponding to the
- * contracts that have to be updated.
- * @param[in] vres_removed Vres_id's to be removed.
+ * returns when the system has rejected the contracts or accepted
+ * and made them effective.
+ *
+ * @param[in] contracts_to_neg List of new contracts to negotiate
+ * @param[in] contracts_to_reneg List of contracts to renegotiate
+ * @param[in] vres_to_reneg List of vres to renegotiate
+ * @param[in] vres_to_cancel List of vres to cancel
+ * @param[out] new_vres List of vres of new contracts.
*
* @return 0 if no error \n
- * FRSH_ERR_BAD_ARGUMENT Invalid pointer or vres_id ranges. \n
+ * FRSH_ERR_BAD_ARGUMENT Invalid pointer or group identifier. \n
* FRSH_ERR_CONTRACT_LABEL_ALREADY_EXISTS contract_label not unique. \n
- * FRSH_ERR_NOT_CONTRACTED_VRES: One of the provided
- * vres_ids is not recognised. \n
+ * FRSH_ERR_NOT_CONTRACTED_VRES: One of the provided vres_ids
+ * is not recognised. \n
* FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD The calling thread
- * is not scheduled under FRSH. \n
- * FRSH_ERR_INVALID_SCHEDULER_REPLY: The scheduler is wrong
- * or not running. \n
+ * is not scheduled under FRSH. \n
+ * FRSH_ERR_INVALID_SCHEDULER_REPLY: The scheduler is wrong or
+ * not running. \n
* FRSH_ERR_INTERNAL_ERROR: Erroneous binding or malfunction of
- * FRSH main scheduler. \n
+ * FRSH main scheduler. \n
* FRSH_ERR_REJECTED_CONTRACT: The negotiation of one of the
- * proposed contracts has failed.
- *
+ * proposed contracts has failed.
**/
int frsh_group_change_mode_sync
- (const frsh_contracts_group_t *contracts_new_vres,
- frsh_vres_group_t *vres_id_new,
- const frsh_contracts_group_t *contracts_update_vres,
- const frsh_vres_group_t *vres_update,
- const frsh_vres_group_t *vres_removed);
-
+ (const frsh_contracts_group_t *contracts_to_neg,
+ const frsh_contracts_group_t *contracts_to_reneg,
+ const frsh_vres_group_t *vres_to_reneg,
+ const frsh_vres_group_t *vres_to_cancel,
+ frsh_vres_group_t *new_vres);
/**
* frsh_group_change_mode_async()
*
- * This operation enqueues a global renegotiation of a group of
- * contracts (with a possible addition of new vres) and returns
- * immediately. The renegotiation is performed asynchronously as soon
- * as it is practical.
- *
- * NOTE: This function will be implemented in a second phase after
- * having fully implemented frsh_group_negotiate() in order to
- * better grasp possible issues that the problem may raise.
- *
- * This is a draft of the specification, it is yet subject to
- * change.
- *
- * This is an asynchronous (non-blocking) version of
- * frsh_group_change_mode_sync(). Note however that there must
- * be at least one existing thread involved in the operation (to be
- * canceled or have its contract updated). An operation of puring
- * adding a group of new contracts can only be done synchronously.
- *
- * The status of the operation (in progress, admitted or rejected) can
- * be queried via frsh_vres_get_renegotiation_status() invoked for any of
- * the vres involved in the renegotiation (updated or to be
- * removed). As an option, a signal can be sent to the caller to
- * notify the end-result of the operation.
- *
- * @param[in] contracts_new_vres Contracts for new vres to be
- * added.
- * @param[in] contract_labels Contract labels for the corresponding new
- * vres to be added.
- * @param[out] vres_id_new vres_id's corresponding to the new
- * contracts.
- * @param[in] contracts_update_vres New contracts for vres to
- * be updated.
- * @param[in] vres_update vres_id's corresponding to the
- * contracts that have to be updated.
- * @param[in] vres_removed vres_id's to be removed.
- *
- * @param[in] sig_notify Signal number where the coller expects to
- * receive the information.
- * @param[in] sig_value Signal data associated with that signal.
+ * This is an asynchronous (non-blocking) version of the previous function,
+ * frsh_group_change_mode_sync() and thus, it returns inmediately.
+ *
+ * The status of the change of mode and the identifiers for new virtual
+ * resources must be requested with the function 'frsh_group_get_status'
+ * by using the return parameter 'group'.
+ *
+ * As in the asynchronous renegotiations, when the operation is completed,
+ * the user is notified with a signal so he can check the final result with
+ * 'frsh_group_get_status'. In case that FRSH_NULL_SIGNAL is used, no
+ * signal will be sent to the user.
+ *
+ * @param[in] contracts_to_neg List of new contracts to negotiate
+ * @param[in] contracts_to_reneg List of contracts to renegotiate
+ * @param[in] vres_to_reneg List of vres to renegotiate
+ * @param[in] vres_to_cancel List of vres to cancel
+ * @param[in] signal Signal number to notify completion of
+ * the change of mode. If FRSH_NULL_SIGNAL,
+ * no signal will be raised.
+ * @param[in] signal_info Data associated to the signal
+ * @param[out] group The group identifier to get the status
*
* @return 0 if no error \n
- * FRSH_ERR_BAD_ARGUMENT Invalid pointer or vres_id ranges. Also
- * when the request is for adding only new contracts. \n
+ * FRSH_ERR_BAD_ARGUMENT Invalid pointer, signal or group identifier. \n
* FRSH_ERR_CONTRACT_LABEL_ALREADY_EXISTS contract_label not unique. \n
- * FRSH_ERR_NOT_CONTRACTED_VRES: One of the provided
- * vres_id's is not recognised. \n
+ * FRSH_ERR_NOT_CONTRACTED_VRES: One of the provided vres_ids
+ * is not recognised. \n
* FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD The calling thread
- * is not scheduled under FRSH. \n
- * FRSH_ERR_INVALID_SCHEDULER_REPLY: The scheduler is wrong
- * or not running. \n
+ * is not scheduled under FRSH. \n
+ * FRSH_ERR_INVALID_SCHEDULER_REPLY: The scheduler is wrong or
+ * not running. \n
* FRSH_ERR_INTERNAL_ERROR: Erroneous binding or malfunction of
- * FRSH main scheduler. \n
- * FRSH_ERR_REJECTED_CONTRACT: The negotiation of one of the
- * proposed contracts has failed.
+ * FRSH main scheduler.
**/
int frsh_group_change_mode_async
- (const frsh_contracts_group_t *contracts_new_vres,
- frsh_vres_group_t *vres_id_new,
- const frsh_contracts_group_t *contracts_update_vres,
- const frsh_vres_group_t *vres_update,
- const frsh_vres_group_t *vres_removed,
- const frsh_signal_t signal_notify,
- const frsh_signal_info_t signal_info);
+ (const frsh_contracts_group_t *contracts_to_neg,
+ const frsh_contracts_group_t *contracts_to_reneg,
+ const frsh_vres_group_t *vres_to_reneg,
+ const frsh_vres_group_t *vres_to_cancel,
+ const frsh_signal_t signal,
+ const frsh_signal_info_t signal_info,
+ frsh_group_id_t *group);
+
+/**
+ * frsh_group_get_status()
+ *
+ * This function is similar to 'frsh_vres_get_renegotiation_status' but it
+ * is intented for group negotiations (changes of mode).
+ *
+ * The operation reports on the status of the last negotiation
+ * operation enqueued for the specified group identifier.
+ *
+ * The status value can be one of the following values:
+ *
+ * - FRSH_RS_IN_PROGRESS: the change of mode is in progress
+ * - FRSH_RS_REJECTED: the change of mode was not accepted
+ * - FRSH_RS_ADMITTED: the change of mode was accepted
+ * - FRSH_RS_NOT_REQUESTED: no change of mode has been requested yet
+ *
+ * When status returns 'FRSH_RS_ADMITTED', the array 'new_vres' contains
+ * the values for the new virtual resources (if there was any).
+ *
+ * This function frees the group identifier when status returns something
+ * different than FRSH_RS_IN_PROGRESS so further calls to this function may
+ * return inconsistent values.
+ *
+ * @param[in] group The group identifier
+ * @param[out] status The status of the change of mode
+ * @param[out] new_vres List of vres for the negotiation of new contracts.
+ *
+ * @return 0 if no error \n
+ * FRSH_ERR_BAD_ARGUMENT Invalid pointer, signal or group identifier. \n
+ * FRSH_ERR_CONTRACT_LABEL_ALREADY_EXISTS contract_label not unique. \n
+ * FRSH_ERR_NOT_CONTRACTED_VRES: One of the provided vres_ids
+ * is not recognised. \n
+ * FRSH_ERR_NOT_SCHEDULED_CALLING_THREAD The calling thread
+ * is not scheduled under FRSH. \n
+ * FRSH_ERR_INVALID_SCHEDULER_REPLY: The scheduler is wrong or
+ * not running. \n
+ * FRSH_ERR_INTERNAL_ERROR: Erroneous binding or malfunction of
+ * FRSH main scheduler.
+ **/
+int frsh_group_get_status(const frsh_group_id_t group,
+ frsh_renegotiation_status_t *status,
+ frsh_vres_group_t *new_vres);
-/*@}*/
+/*@}*/
////////////////////////////////////////////////////
//threads
+////////////////////////////////////////////////////////////////////////
+// OTHER
+////////////////////////////////////////////////////////////////////////
+
+/**
+ * Returns resource id of local CPU.
+ *
+ * The ID is determined from environment variable FRSH_CPU_ID or, if
+ * that is not defined, the compile time default (defined in
+ * config.target/omk).
+ */
+frsh_resource_id_t frsh_get_local_cpu_id(void);
+
FRSH_CPP_END_DECLS
#endif // _FRSH_CORE_H_