include/linux/energy_model.h

   1 /* SPDX-License-Identifier: GPL-2.0 */
   2 #ifndef _LINUX_ENERGY_MODEL_H
   3 #define _LINUX_ENERGY_MODEL_H
   4 #include <linux/cpumask.h>
   5 #include <linux/device.h>
   6 #include <linux/jump_label.h>
   7 #include <linux/kobject.h>
   8 #include <linux/rcupdate.h>
   9 #include <linux/sched/cpufreq.h>
  10 #include <linux/sched/topology.h>
  11 #include <linux/types.h>
  12
  13 /**
  14  * em_perf_state - Performance state of a performance domain
  15  * @frequency:  The frequency in KHz, for consistency with CPUFreq
  16  * @power:      The power consumed at this level, in milli-watts (by 1 CPU or
  17                 by a registered device). It can be a total power: static and
  18                 dynamic.
  19  * @cost:       The cost coefficient associated with this level, used during
  20  *              energy calculation. Equal to: power * max_frequency / frequency
  21  */
  22 struct em_perf_state {
  23         unsigned long frequency;
  24         unsigned long power;
  25         unsigned long cost;
  26 };
  27
  28 /**
  29  * em_perf_domain - Performance domain
  30  * @table:              List of performance states, in ascending order
  31  * @nr_perf_states:     Number of performance states
  32  * @cpus:               Cpumask covering the CPUs of the domain. It's here
  33  *                      for performance reasons to avoid potential cache
  34  *                      misses during energy calculations in the scheduler
  35  *                      and simplifies allocating/freeing that memory region.
  36  *
  37  * In case of CPU device, a "performance domain" represents a group of CPUs
  38  * whose performance is scaled together. All CPUs of a performance domain
  39  * must have the same micro-architecture. Performance domains often have
  40  * a 1-to-1 mapping with CPUFreq policies. In case of other devices the @cpus
  41  * field is unused.
  42  */
  43 struct em_perf_domain {
  44         struct em_perf_state *table;
  45         int nr_perf_states;
  46         unsigned long cpus[];
  47 };
  48
  49 #define em_span_cpus(em) (to_cpumask((em)->cpus))
  50
  51 #ifdef CONFIG_ENERGY_MODEL
  52 #define EM_MAX_POWER 0xFFFF
  53
  54 struct em_data_callback {
  55         /**
  56          * active_power() - Provide power at the next performance state of
  57          *              a device
  58          * @power       : Active power at the performance state in mW
  59          *              (modified)
  60          * @freq        : Frequency at the performance state in kHz
  61          *              (modified)
  62          * @dev         : Device for which we do this operation (can be a CPU)
  63          *
  64          * active_power() must find the lowest performance state of 'dev' above
  65          * 'freq' and update 'power' and 'freq' to the matching active power
  66          * and frequency.
  67          *
  68          * In case of CPUs, the power is the one of a single CPU in the domain,
  69          * expressed in milli-watts. It is expected to fit in the
  70          * [0, EM_MAX_POWER] range.
  71          *
  72          * Return 0 on success.
  73          */
  74         int (*active_power)(unsigned long *power, unsigned long *freq,
  75                             struct device *dev);
  76 };
  77 #define EM_DATA_CB(_active_power_cb) { .active_power = &_active_power_cb }
  78
  79 struct em_perf_domain *em_cpu_get(int cpu);
  80 struct em_perf_domain *em_pd_get(struct device *dev);
  81 int em_dev_register_perf_domain(struct device *dev, unsigned int nr_states,
  82                                 struct em_data_callback *cb, cpumask_t *span);
  83 void em_dev_unregister_perf_domain(struct device *dev);
  84
  85 /**
  86  * em_cpu_energy() - Estimates the energy consumed by the CPUs of a
  87                 performance domain
  88  * @pd          : performance domain for which energy has to be estimated
  89  * @max_util    : highest utilization among CPUs of the domain
  90  * @sum_util    : sum of the utilization of all CPUs in the domain
  91  *
  92  * This function must be used only for CPU devices. There is no validation,
  93  * i.e. if the EM is a CPU type and has cpumask allocated. It is called from
  94  * the scheduler code quite frequently and that is why there is not checks.
  95  *
  96  * Return: the sum of the energy consumed by the CPUs of the domain assuming
  97  * a capacity state satisfying the max utilization of the domain.
  98  */
  99 static inline unsigned long em_cpu_energy(struct em_perf_domain *pd,
 100                                 unsigned long max_util, unsigned long sum_util)
 101 {
 102         unsigned long freq, scale_cpu;
 103         struct em_perf_state *ps;
 104         int i, cpu;
 105
 106         /*
 107          * In order to predict the performance state, map the utilization of
 108          * the most utilized CPU of the performance domain to a requested
 109          * frequency, like schedutil.
 110          */
 111         cpu = cpumask_first(to_cpumask(pd->cpus));
 112         scale_cpu = arch_scale_cpu_capacity(cpu);
 113         ps = &pd->table[pd->nr_perf_states - 1];
 114         freq = map_util_freq(max_util, ps->frequency, scale_cpu);
 115
 116         /*
 117          * Find the lowest performance state of the Energy Model above the
 118          * requested frequency.
 119          */
 120         for (i = 0; i < pd->nr_perf_states; i++) {
 121                 ps = &pd->table[i];
 122                 if (ps->frequency >= freq)
 123                         break;
 124         }
 125
 126         /*
 127          * The capacity of a CPU in the domain at the performance state (ps)
 128          * can be computed as:
 129          *
 130          *             ps->freq * scale_cpu
 131          *   ps->cap = --------------------                          (1)
 132          *                 cpu_max_freq
 133          *
 134          * So, ignoring the costs of idle states (which are not available in
 135          * the EM), the energy consumed by this CPU at that performance state
 136          * is estimated as:
 137          *
 138          *             ps->power * cpu_util
 139          *   cpu_nrg = --------------------                          (2)
 140          *                   ps->cap
 141          *
 142          * since 'cpu_util / ps->cap' represents its percentage of busy time.
 143          *
 144          *   NOTE: Although the result of this computation actually is in
 145          *         units of power, it can be manipulated as an energy value
 146          *         over a scheduling period, since it is assumed to be
 147          *         constant during that interval.
 148          *
 149          * By injecting (1) in (2), 'cpu_nrg' can be re-expressed as a product
 150          * of two terms:
 151          *
 152          *             ps->power * cpu_max_freq   cpu_util
 153          *   cpu_nrg = ------------------------ * ---------          (3)
 154          *                    ps->freq            scale_cpu
 155          *
 156          * The first term is static, and is stored in the em_perf_state struct
 157          * as 'ps->cost'.
 158          *
 159          * Since all CPUs of the domain have the same micro-architecture, they
 160          * share the same 'ps->cost', and the same CPU capacity. Hence, the
 161          * total energy of the domain (which is the simple sum of the energy of
 162          * all of its CPUs) can be factorized as:
 163          *
 164          *            ps->cost * \Sum cpu_util
 165          *   pd_nrg = ------------------------                       (4)
 166          *                  scale_cpu
 167          */
 168         return ps->cost * sum_util / scale_cpu;
 169 }
 170
 171 /**
 172  * em_pd_nr_perf_states() - Get the number of performance states of a perf.
 173  *                              domain
 174  * @pd          : performance domain for which this must be done
 175  *
 176  * Return: the number of performance states in the performance domain table
 177  */
 178 static inline int em_pd_nr_perf_states(struct em_perf_domain *pd)
 179 {
 180         return pd->nr_perf_states;
 181 }
 182
 183 #else
 184 struct em_data_callback {};
 185 #define EM_DATA_CB(_active_power_cb) { }
 186
 187 static inline
 188 int em_dev_register_perf_domain(struct device *dev, unsigned int nr_states,
 189                                 struct em_data_callback *cb, cpumask_t *span)
 190 {
 191         return -EINVAL;
 192 }
 193 static inline void em_dev_unregister_perf_domain(struct device *dev)
 194 {
 195 }
 196 static inline struct em_perf_domain *em_cpu_get(int cpu)
 197 {
 198         return NULL;
 199 }
 200 static inline struct em_perf_domain *em_pd_get(struct device *dev)
 201 {
 202         return NULL;
 203 }
 204 static inline unsigned long em_cpu_energy(struct em_perf_domain *pd,
 205                         unsigned long max_util, unsigned long sum_util)
 206 {
 207         return 0;
 208 }
 209 static inline int em_pd_nr_perf_states(struct em_perf_domain *pd)
 210 {
 211         return 0;
 212 }
 213 #endif
 214
 215 #endif