src_frescan/frescan_bwres_analysis.h

   1 /*!
   2  * @file frescan_bwres_analysis.h
   3  *
   4  * @brief FRESCAN bandwith reservation layer: sched analysis
   5  *
   6  * This module contains the scheduling analysis data and functions for the
   7  * admission tests and spare capacity distribution of the negotiation layer.
   8  * It provides an easy API easy to understand and in the implementation part
   9  * it makes call to the general sched analysis module of FRSH which is shared
  10  * with the CPU contracts layer in FRSH.
  11  *
  12  * EXAMPLE of utilization:
  13  *
  14  * INITIALIZATION
  15  * --------------
  16  * params.min_prio = 0;
  17  * params.max_prio = 16;
  18  * params.overhead = ...;
  19  * frescan_sa_init(&scenario, &params);
  20  *
  21  * NEGOTIATE
  22  * ---------
  23  * fadt_freelist_alloc(&freelist_contracts, &id);
  24  * frescan_sa_add_contract(&scenario, &contracts[id], id);
  25  * frescan_sa_sched_test(&scenario, &success);
  26  *
  27  * if (!success) {
  28  *      frescan_sa_remove_contract(&scenario, id);
  29  * } else {
  30  *      frescan_sa_spare_capacity(&scenario);
  31  *      vres_id = to_vres(resource_type, resource_id, id);
  32  *      create vres runtime structures;
  33  *
  34  *      for vres_id in active_vres_id {
  35  *                frescan_sa_get_final_values(&scenario,
  36  *                                            to_index(vres_id),
  37  *                                            &final_values);
  38  *                update vres runtime structures if necessary;
  39  *      }
  40  * }
  41  *
  42  * RENEGOTIATE
  43  * -----------
  44  * copy old_contract
  45  * frescan_sa_update_contract(&scenario, to_index(vres_id), &contract);
  46  * frescan_sa_sched_test(&scenario, &success);
  47  *
  48  * if (!success) {
  49  *         frescan_sa_update_contract(&sa_data,
  50  *                                    to_index(vres_id),
  51  *                                    &old_contract);
  52  * } else {
  53  *      frescan_sa_spare_capacity(&scenario);
  54  *      for vres_id in active_vres_id {
  55  *              frescan_sa_get_final_values(&scenario,
  56  *                                          to_index(vres_id),
  57  *                                          &final_values);
  58  *              update vres runtime structures if necessary;
  59  *      }
  60  * }
  61  *
  62  * CANCEL
  63  * ------
  64  * frescan_sa_remove_contract(&scenario, to_index(vres_id));
  65  * frescan_sa_spare_capacity(&scenario);
  66  *
  67  * @version 0.01
  68  *
  69  * @date 15-Apr-2008
  70  *
  71  * @author Daniel Sangorrin <daniel.sangorrin@unican.es>
  72  *
  73  */
  74
  75 #ifndef _FRESCAN_BWRES_ANALYSIS_H_
  76 #define _FRESCAN_BWRES_ANALYSIS_H_
  77
  78 #include "frescan.h"
  79 #include "frescan_data.h"
  80
  81 /**
  82  * frescan_sa_init() - init the scenario
  83  *
  84  * @scenario: the scenario (in out)
  85  * @params: init params (in)
  86  */
  87
  88 extern int frescan_sa_init(frescan_sa_scenario_t *scenario,
  89                            const frescan_sa_init_params_t *params);
  90
  91 /**
  92  * frescan_sa_add_contract() - add a contract to the scenario
  93  *
  94  * @scenario: the scenario (in out)
  95  * @contract: the new contract (in)
  96  * @ss: the preallocated ss identificator (in)
  97  * @node: the node this contract belongs to (in)
  98  */
  99
 100 extern int frescan_sa_add_contract(frescan_sa_scenario_t    *scenario,
 101                                    const frescan_contract_t *contract,
 102                                    frescan_ss_t             ss,
 103                                    frescan_node_t           node);
 104
 105 /**
 106  * frescan_sa_update_contract() - update a contract in the scenario
 107  *
 108  * @scenario: the scenario (in out)
 109  * @ss: the ss identificator (in)
 110  * @node: the node this contract belongs to (in)
 111  * @contract: the values to update the contract (in)
 112  * @old_contract: the values of the previous contract. Can be NULL (out)
 113  */
 114
 115 extern int frescan_sa_update_contract(frescan_sa_scenario_t   *scenario,
 116                                       frescan_ss_t             ss,
 117                                       frescan_node_t           node,
 118                                       const frescan_contract_t *contract,
 119                                       frescan_contract_t       *old_contract);
 120
 121 /**
 122  * frescan_sa_remove_contract() - remove a contract from the scenario
 123  *
 124  * @scenario: the scenario (in out)
 125  * @ss: the ss to remove (in)
 126  * @node: the node this contract belongs to (in)
 127  */
 128
 129 extern int frescan_sa_remove_contract(frescan_sa_scenario_t *scenario,
 130                                       frescan_ss_t          ss,
 131                                       frescan_node_t        node);
 132
 133 /**
 134  * frescan_sa_sched_test() - perform a scheduling test on the scenario
 135  *
 136  * @scenario: the scenario (in out)
 137  * @success: if the scenario is schedulable or not (out)
 138  */
 139
 140 extern int frescan_sa_sched_test(frescan_sa_scenario_t *scenario,
 141                                  bool *success);
 142
 143 /**
 144  * frescan_sa_spare_capacity() - distribute the remaining spare capacity
 145  *
 146  * @scenario: the scenario (in out)
 147  */
 148
 149 extern int frescan_sa_spare_capacity(frescan_sa_scenario_t *scenario);
 150
 151 /**
 152  * frescan_sa_get_final_values() - get the final values
 153  *
 154  * @scenario: the scenario (in)
 155  * @ss: the ss from which we want the final values (in)
 156  * @node: the node this contract belongs to (in)
 157  * @final_values: the final values (out)
 158  */
 159
 160 extern int frescan_sa_get_final_values(const frescan_sa_scenario_t *scenario,
 161                                        frescan_ss_t              ss,
 162                                        frescan_node_t            node,
 163                                        frescan_sa_final_values_t *final_values);
 164
 165 #endif // _FRESCAN_BWRES_ANALYSIS_H_