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  * @contract: the values to update the contract (in)
 111  * @node: the node this contract belongs to (in)
 112  */
 113
 114 extern int frescan_sa_update_contract(frescan_sa_scenario_t *scenario,
 115                                       frescan_ss_t          ss,
 116                                       const frescan_contract_t *contract,
 117                                       frescan_node_t           node);
 118
 119 /**
 120  * frescan_sa_remove_contract() - remove a contract from the scenario
 121  *
 122  * @scenario: the scenario (in out)
 123  * @ss: the ss to remove (in)
 124  * @node: the node this contract belongs to (in)
 125  */
 126
 127 extern int frescan_sa_remove_contract(frescan_sa_scenario_t *scenario,
 128                                       frescan_ss_t          ss,
 129                                       frescan_node_t        node);
 130
 131 /**
 132  * frescan_sa_sched_test() - perform a scheduling test on the scenario
 133  *
 134  * @scenario: the scenario (in out)
 135  * @success: if the scenario is schedulable or not (out)
 136  */
 137
 138 extern int frescan_sa_sched_test(frescan_sa_scenario_t *scenario,
 139                                  bool *success);
 140
 141 /**
 142  * frescan_sa_spare_capacity() - distribute the remaining spare capacity
 143  *
 144  * @scenario: the scenario (in out)
 145  */
 146
 147 extern int frescan_sa_spare_capacity(frescan_sa_scenario_t *scenario);
 148
 149 /**
 150  * frescan_sa_get_final_values() - get the final values
 151  *
 152  * @scenario: the scenario (in)
 153  * @ss: the ss from which we want the final values (in)
 154  * @node: the node this contract belongs to (in)
 155  * @final_values: the final values (out)
 156  */
 157
 158 extern int frescan_sa_get_final_values(const frescan_sa_scenario_t *scenario,
 159                                        frescan_ss_t              ss,
 160                                        frescan_node_t            node,
 161                                        frescan_sa_final_values_t *final_values);
 162
 163 #endif // _FRESCAN_BWRES_ANALYSIS_H_