src_frescan/frescan_sched_analysis.h

   1 /*!
   2  * @file frescan_sched_analysis.h
   3  *
   4  * @brief FRESCAN sched analysis queue
   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_SCHED_ANALYSIS_H_
  76 #define _FRESCAN_SCHED_ANALYSIS_H_
  77
  78 #include "frsh.h"
  79
  80 // #include "frsh_sa_scenario.h"
  81 typedef int frsh_sa_scenario_t;
  82 typedef int frsh_sa_init_params_t;
  83 typedef int frsh_vres_index_t;
  84 typedef int frescan_sa_final_values_t;
  85
  86 /**
  87  * frescan_sa_init() - init the scenario
  88  */
  89
  90 extern int frescan_sa_init(frsh_sa_scenario_t *scenario,         // in out
  91                            const frsh_sa_init_params_t *params); // in
  92
  93 /**
  94  * frescan_sa_add_contract() - add a contract to the scenario
  95  */
  96
  97 extern int frescan_sa_add_contract(frsh_sa_scenario_t    *scenario, // in out
  98                                    const frsh_contract_t *contract, // in
  99                                    frsh_vres_index_t     id);       // in
 100
 101 /**
 102  * frescan_sa_update_contract() - update a contract in the scenario
 103  */
 104
 105 extern int frescan_sa_update_contract(frsh_sa_scenario_t    *scenario, // in out
 106                                       frsh_vres_index_t     id,        // in
 107                                       const frsh_contract_t *contract);// in
 108
 109 /**
 110  * frescan_sa_remove_contract() - remove a contract from the scenario
 111  */
 112
 113 extern int frescan_sa_remove_contract(frsh_sa_scenario_t *scenario,  // in out
 114                                       frsh_vres_index_t id);         // in
 115
 116 /**
 117  * frescan_sa_sched_test() - perform a scheduling test on the scenario
 118  */
 119
 120 extern int frescan_sa_sched_test(frsh_sa_scenario_t *scenario,  // in out
 121                                  bool *success);                // out
 122
 123 /**
 124  * frescan_sa_spare_capacity() - distribute the remaining spare capacity
 125  */
 126
 127 extern int frescan_sa_spare_capacity(frsh_sa_scenario_t *scenario); // in out
 128
 129 /**
 130  * sa_get_final_values() - get the final values
 131  */
 132
 133 extern int sa_get_final_values(const frsh_sa_scenario_t *scenario,       // in
 134                                frsh_vres_index_t id,                     // in
 135                                frescan_sa_final_values_t *final_values); // out
 136
 137 #endif // _FRESCAN_REQUESTS_QUEUE_H_