#include "frsh_energy_management_types.h"
#include "frsh_core_types.h"
+FRSH_CPP_BEGIN_DECLS
#define FRSH_ENERGY_MANAGEMENT_MODULE_SUPPORTED 1
* @defgroup energymgmnt Energy Management Module
*
* This module provides the ability to specify different budgets for
- * different CPU power levels.
+ * different power levels.
*
* We model the situation by specifying budget values per power
* level. Thus switching in the power-level would be done by changing
*
* All global FRSH contract operations (those done with the core
* module without specifying the power level) are considered to be
- * applies to the higest power level.
+ * applied to the higest power level, corresponding to a power_level_t
+ * value of 0.
+ *
+ * @note
+ * For all functions that operate on a contract, the resource is
+ * implicitly identified by the contract core parameters resource_type
+ * and resource_id that are either set through the
+ * frsh_contract_set_resource_and_label() function, or implicitly
+ * defined if no such call is made.
+ *
+ * @note
+ * For the power level management operations, only
+ * implementation for resource_type = FRSH_RT_PROCESSOR is mandatory,
+ * if the energy management module is present.
*
* @{
*
/**
- * frsh_contract_set_min_duration()
+ * frsh_contract_set_min_expiration()
*
- * This function sets the minimum duration that the application must
- * be able to run without finishing battery power. 0 would mean no
+ * This function sets the minimum battery expiration time that the
+ * system must be able to sustain without finishing battery power. A
+ * value of (0,0) would mean that the application does not have such
+ * requirement (this is the default if this parameter is not explicitly
+ * set).
**/
-int frsh_contract_set_min_duration(struct timespec min_duration,
- frsh_contract_t *contract);
+int frsh_contract_set_min_expiration(frsh_contract_t *contract,
+ frsh_rel_time_t min_expiration);
/**
- * frsh_contract_get_min_duration()
+ * frsh_contract_get_min_expiration()
*
* Get version of the previous function.
**/
-int frsh_contract_get_min_duration(const frsh_contract_t *contract,
- struct timespec *min_duration);
+int frsh_contract_get_min_expiration(const frsh_contract_t *contract,
+ frsh_rel_time_t *min_expiration);
/**
* frsh_contract_set_min_budget_pow()
*
- * Here we specify the minimum budget values corresponding to the
- * 3 power levels. The element order of the array goes from highest
- * power level to the lowest.
+ * Here we specify the minimum budget value corresponding to a single
+ * power level.
*
- * @param[in] pow_min_budget Pointer to the first element of the
- * minimum budget array. Elements
- * correspond to [0]->Highest PW,
- * [1]->Medium PW, [2]->Lowest PW.
+ * @param contract The affected contract.
+ * @param power_level The power level for which we are specifying the minimum budget.
+ * @param pow_min_budget The minimum budget requested for the power level.
*
* @return 0 if no error \n
- * FRSH_ERR_BAD_ARGUMENT if any of the pointers is NULL or the
- * budget values don't go in descending order.
+ * FRSH_ERR_BAD_ARGUMENT if power_level is greater than or equal to the value
+ * returned by frsh_get_power_levels budget value is not correct.
+ *
+ * @note
+ * If the minimum budget relative to one or more power levels has not been specified, then
+ * the framework may attempt to perform interpolation of the supplied values in
+ * order to infer them, if an accurate model for such operation is available.
+ * Otherwise, the contract is rejected at frsh_negotiate() time.
**/
-int frsh_contract_set_min_budget_pow(const struct timespec pow_min_budget[],
- frsh_contract_t *contract);
+int frsh_contract_set_min_budget_pow(frsh_contract_t *contract,
+ frsh_power_level_t power_level,
+ const frsh_rel_time_t *pow_min_budget);
/**
* frsh_contract_get_min_budget_pow()
* Get version of the previous function.
**/
int frsh_contract_get_min_budget_pow(const frsh_contract_t *contract,
- struct timespec pow_min_budget[]);
+ frsh_power_level_t power_level,
+ frsh_rel_time_t *pow_min_budget);
/**
* frsh_contract_set_max_budget_pow()
*
- * Here we specify the maximum budget values corresponding to the 3
- * power levels. The element order of the array goes from highest
- * power level to the lowest.
+ * Here we specify the maximum budget for a single power level.
*
- * @param[in] pow_max_budget Pointer to the first element of the
- * maximum budget array. Elements
- * correspond to [0]->Highest PW,
- * [1]->Medium PW, [2]->Lowest PW.
- *
- * @param contract (in/out) Contract
+ * @param contract The affected contract object.
+ * @param power_level The power level for which we are specifying the maximum budget.
+ * @param pow_max_budget The maximum budget requested for the power level.
*
* @return 0 if no error \n
* FRSH_ERR_BAD_ARGUMENT if any of the pointers is NULL or the
* budget values don't go in ascending order.
*
**/
-int frsh_contract_set_max_budget_pow(const struct timespec pow_max_budget[],
- frsh_contract_t *contract);
+int frsh_contract_set_max_budget_pow(frsh_contract_t *contract,
+ frsh_power_level_t power_level,
+ const frsh_rel_time_t *pow_max_budget);
/**
* frsh_contract_get_max_budget_pow()
* Get version of the previous function.
**/
int frsh_contract_get_max_budget_pow(const frsh_contract_t *contract,
- struct timespec pow_max_budget[]);
+ frsh_power_level_t power_level,
+ frsh_rel_time_t *pow_max_budget);
/**
- * frsh_contract_set_utilizations_pow()
+ * frsh_contract_set_utilization_pow()
*
- * Here we specify pairs of
- * [ (budget_pmax, budget_pmedium, budget_plow) , Period ]
+ * This function should be used for contracts with a period of
+ * discrete granularity. Here we specify, for each allowed period,
+ * the budget to be used for each power level.
*
- * for contracts of discrete granularity.
- *
- * param[in] utilization_set Discrete series of utilization values.
- * param contract (in/out) Contract object.
+ * @param contract The affected contract object.
+ * @param power_level The power level for which we specify budget and period.
+ * @param budget The budget to be used for the supplied power level and period.
+ * @param period One of the allowed periods (from the discrete set).
+ * @param period The deadline used with the associated period (from the discrete set).
**/
-int frsh_contract_set_utilizations_pow(const frsh_utilization_set_pow_t *utilization_set_pow,
- frsh_contract_t *contract);
+int frsh_contract_set_utilization_pow(frsh_contract_t *contract,
+ frsh_power_level_t power_level,
+ const frsh_rel_time_t *budget,
+ const frsh_rel_time_t *period,
+ const frsh_rel_time_t *deadline);
/**
- * frsh_contract_get_utilizations_pow()
+ * frsh_contract_get_utilization_pow()
*
* Get version of the previous function.
**/
-int frsh_contract_get_utilizations_pow(const frsh_utilization_set_pow_t *utilization_set_pow,
- frsh_contract_t *contract);
+int frsh_contract_get_utilization_pow(const frsh_contract_t *contract,
+ frsh_power_level_t power_level,
+ frsh_rel_time_t *budget,
+ frsh_rel_time_t *period,
+ frsh_rel_time_t *deadline);
//////////////////////////////////////////////////////////////////////
*
* Get the foreseen expiration time of the system battery(ies).
**/
-int frsh_battery_get_expiration(struct timespec *expiration);
+int frsh_battery_get_expiration(frsh_abs_time_t *expiration);
/*@}*/
+FRSH_CPP_END_DECLS
+
#endif /* _FRSH_ENERGY_MANAGEMENT_H_ */
projects / frescor / frsh-include.git / blobdiff