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 * @milliwatts: Flag indicating the power values are in milli-Watts
33 * or some other scale.
34 * @cpus: Cpumask covering the CPUs of the domain. It's here
35 * for performance reasons to avoid potential cache
36 * misses during energy calculations in the scheduler
37 * and simplifies allocating/freeing that memory region.
38 *
39 * In case of CPU device, a "performance domain" represents a group of CPUs
40 * whose performance is scaled together. All CPUs of a performance domain
41 * must have the same micro-architecture. Performance domains often have
42 * a 1-to-1 mapping with CPUFreq policies. In case of other devices the @cpus
43 * field is unused.
44 */
45 struct em_perf_domain {
46 struct em_perf_state *table;
47 int nr_perf_states;
48 int milliwatts;
49 unsigned long cpus[];
50 };
51
52 #define em_span_cpus(em) (to_cpumask((em)->cpus))
53
54 #ifdef CONFIG_ENERGY_MODEL
55 #define EM_MAX_POWER 0xFFFF
56
57 /*
58 * Increase resolution of energy estimation calculations for 64-bit
59 * architectures. The extra resolution improves decision made by EAS for the
60 * task placement when two Performance Domains might provide similar energy
61 * estimation values (w/o better resolution the values could be equal).
62 *
63 * We increase resolution only if we have enough bits to allow this increased
64 * resolution (i.e. 64-bit). The costs for increasing resolution when 32-bit
65 * are pretty high and the returns do not justify the increased costs.
66 */
67 #ifdef CONFIG_64BIT
68 #define em_scale_power(p) ((p)*1000)
69 #else
70 #define em_scale_power(p) (p)
71 #endif
72
73 struct em_data_callback {
74 /**
75 * active_power() - Provide power at the next performance state of
76 * a device
77 * @power : Active power at the performance state in mW
78 * (modified)
79 * @freq : Frequency at the performance state in kHz
80 * (modified)
81 * @dev : Device for which we do this operation (can be a CPU)
82 *
83 * active_power() must find the lowest performance state of 'dev' above
84 * 'freq' and update 'power' and 'freq' to the matching active power
85 * and frequency.
86 *
87 * In case of CPUs, the power is the one of a single CPU in the domain,
88 * expressed in milli-watts. It is expected to fit in the
89 * [0, EM_MAX_POWER] range.
90 *
91 * Return 0 on success.
92 */
93 int (*active_power)(unsigned long *power, unsigned long *freq, struct device *dev);
94 };
95 #define EM_DATA_CB(_active_power_cb) \
96 { \
97 .active_power = &_active_power_cb \
98 }
99
100 struct em_perf_domain *em_cpu_get(int cpu);
101 struct em_perf_domain *em_pd_get(struct device *dev);
102 int em_dev_register_perf_domain(struct device *dev, unsigned int nr_states, struct em_data_callback *cb,
103 cpumask_t *span, bool milliwatts);
104 void em_dev_unregister_perf_domain(struct device *dev);
105
106 /**
107 * em_cpu_energy() - Estimates the energy consumed by the CPUs of a
108 performance domain
109 * @pd : performance domain for which energy has to be estimated
110 * @max_util : highest utilization among CPUs of the domain
111 * @sum_util : sum of the utilization of all CPUs in the domain
112 *
113 * This function must be used only for CPU devices. There is no validation,
114 * i.e. if the EM is a CPU type and has cpumask allocated. It is called from
115 * the scheduler code quite frequently and that is why there is not checks.
116 *
117 * Return: the sum of the energy consumed by the CPUs of the domain assuming
118 * a capacity state satisfying the max utilization of the domain.
119 */
em_cpu_energy(struct em_perf_domain * pd,unsigned long max_util,unsigned long sum_util)120 static inline unsigned long em_cpu_energy(struct em_perf_domain *pd, unsigned long max_util, unsigned long sum_util)
121 {
122 unsigned long freq, scale_cpu;
123 struct em_perf_state *ps;
124 int i, cpu;
125
126 if (!sum_util) {
127 return 0;
128 }
129
130 /*
131 * In order to predict the performance state, map the utilization of
132 * the most utilized CPU of the performance domain to a requested
133 * frequency, like schedutil.
134 */
135 cpu = cpumask_first(to_cpumask(pd->cpus));
136 scale_cpu = arch_scale_cpu_capacity(cpu);
137 ps = &pd->table[pd->nr_perf_states - 1];
138 freq = map_util_freq(max_util, ps->frequency, scale_cpu);
139
140 /*
141 * Find the lowest performance state of the Energy Model above the
142 * requested frequency.
143 */
144 for (i = 0; i < pd->nr_perf_states; i++) {
145 ps = &pd->table[i];
146 if (ps->frequency >= freq) {
147 break;
148 }
149 }
150
151 /*
152 * The capacity of a CPU in the domain at the performance state (ps)
153 * can be computed as:
154 *
155 * ps->freq * scale_cpu
156 * ps->cap = -------------------- (1)
157 * cpu_max_freq
158 *
159 * So, ignoring the costs of idle states (which are not available in
160 * the EM), the energy consumed by this CPU at that performance state
161 * is estimated as:
162 *
163 * ps->power * cpu_util
164 * cpu_nrg = -------------------- (2)
165 * ps->cap
166 *
167 * since 'cpu_util / ps->cap' represents its percentage of busy time.
168 *
169 * NOTE: Although the result of this computation actually is in
170 * units of power, it can be manipulated as an energy value
171 * over a scheduling period, since it is assumed to be
172 * constant during that interval.
173 *
174 * By injecting (1) in (2), 'cpu_nrg' can be re-expressed as a product
175 * of two terms:
176 *
177 * ps->power * cpu_max_freq cpu_util
178 * cpu_nrg = ------------------------ * --------- (3)
179 * ps->freq scale_cpu
180 *
181 * The first term is static, and is stored in the em_perf_state struct
182 * as 'ps->cost'.
183 *
184 * Since all CPUs of the domain have the same micro-architecture, they
185 * share the same 'ps->cost', and the same CPU capacity. Hence, the
186 * total energy of the domain (which is the simple sum of the energy of
187 * all of its CPUs) can be factorized as:
188 *
189 * ps->cost * \Sum cpu_util
190 * pd_nrg = ------------------------ (4)
191 * scale_cpu
192 */
193 return ps->cost * sum_util / scale_cpu;
194 }
195
196 /**
197 * em_pd_nr_perf_states() - Get the number of performance states of a perf.
198 * domain
199 * @pd : performance domain for which this must be done
200 *
201 * Return: the number of performance states in the performance domain table
202 */
em_pd_nr_perf_states(struct em_perf_domain * pd)203 static inline int em_pd_nr_perf_states(struct em_perf_domain *pd)
204 {
205 return pd->nr_perf_states;
206 }
207
208 #else
209 struct em_data_callback {
210 };
211 #define EM_DATA_CB(_active_power_cb) \
212 { \
213 }
214
em_dev_register_perf_domain(struct device * dev,unsigned int nr_states,struct em_data_callback * cb,cpumask_t * span,bool milliwatts)215 static inline int em_dev_register_perf_domain(struct device *dev, unsigned int nr_states, struct em_data_callback *cb,
216 cpumask_t *span, bool milliwatts)
217 {
218 return -EINVAL;
219 }
em_dev_unregister_perf_domain(struct device * dev)220 static inline void em_dev_unregister_perf_domain(struct device *dev)
221 {
222 }
em_cpu_get(int cpu)223 static inline struct em_perf_domain *em_cpu_get(int cpu)
224 {
225 return NULL;
226 }
em_pd_get(struct device * dev)227 static inline struct em_perf_domain *em_pd_get(struct device *dev)
228 {
229 return NULL;
230 }
em_cpu_energy(struct em_perf_domain * pd,unsigned long max_util,unsigned long sum_util)231 static inline unsigned long em_cpu_energy(struct em_perf_domain *pd, unsigned long max_util, unsigned long sum_util)
232 {
233 return 0;
234 }
em_pd_nr_perf_states(struct em_perf_domain * pd)235 static inline int em_pd_nr_perf_states(struct em_perf_domain *pd)
236 {
237 return 0;
238 }
239 #endif
240
241 #endif
242