1====================
2Energy Model of CPUs
3====================
4
51. Overview
6-----------
7
8The Energy Model (EM) framework serves as an interface between drivers knowing
9the power consumed by CPUs at various performance levels, and the kernel
10subsystems willing to use that information to make energy-aware decisions.
11
12The source of the information about the power consumed by CPUs can vary greatly
13from one platform to another. These power costs can be estimated using
14devicetree data in some cases. In others, the firmware will know better.
15Alternatively, userspace might be best positioned. And so on. In order to avoid
16each and every client subsystem to re-implement support for each and every
17possible source of information on its own, the EM framework intervenes as an
18abstraction layer which standardizes the format of power cost tables in the
19kernel, hence enabling to avoid redundant work.
20
21The figure below depicts an example of drivers (Arm-specific here, but the
22approach is applicable to any architecture) providing power costs to the EM
23framework, and interested clients reading the data from it::
24
25       +---------------+  +-----------------+  +---------------+
26       | Thermal (IPA) |  | Scheduler (EAS) |  |     Other     |
27       +---------------+  +-----------------+  +---------------+
28               |                   | em_pd_energy()    |
29               |                   | em_cpu_get()      |
30               +---------+         |         +---------+
31                         |         |         |
32                         v         v         v
33                        +---------------------+
34                        |    Energy Model     |
35                        |     Framework       |
36                        +---------------------+
37                           ^       ^       ^
38                           |       |       | em_register_perf_domain()
39                +----------+       |       +---------+
40                |                  |                 |
41        +---------------+  +---------------+  +--------------+
42        |  cpufreq-dt   |  |   arm_scmi    |  |    Other     |
43        +---------------+  +---------------+  +--------------+
44                ^                  ^                 ^
45                |                  |                 |
46        +--------------+   +---------------+  +--------------+
47        | Device Tree  |   |   Firmware    |  |      ?       |
48        +--------------+   +---------------+  +--------------+
49
50The EM framework manages power cost tables per 'performance domain' in the
51system. A performance domain is a group of CPUs whose performance is scaled
52together. Performance domains generally have a 1-to-1 mapping with CPUFreq
53policies. All CPUs in a performance domain are required to have the same
54micro-architecture. CPUs in different performance domains can have different
55micro-architectures.
56
57
582. Core APIs
59------------
60
612.1 Config options
62^^^^^^^^^^^^^^^^^^
63
64CONFIG_ENERGY_MODEL must be enabled to use the EM framework.
65
66
672.2 Registration of performance domains
68^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
69
70Drivers are expected to register performance domains into the EM framework by
71calling the following API::
72
73  int em_register_perf_domain(cpumask_t *span, unsigned int nr_states,
74			      struct em_data_callback *cb);
75
76Drivers must specify the CPUs of the performance domains using the cpumask
77argument, and provide a callback function returning <frequency, power> tuples
78for each capacity state. The callback function provided by the driver is free
79to fetch data from any relevant location (DT, firmware, ...), and by any mean
80deemed necessary. See Section 3. for an example of driver implementing this
81callback, and kernel/power/energy_model.c for further documentation on this
82API.
83
84
852.3 Accessing performance domains
86^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
87
88Subsystems interested in the energy model of a CPU can retrieve it using the
89em_cpu_get() API. The energy model tables are allocated once upon creation of
90the performance domains, and kept in memory untouched.
91
92The energy consumed by a performance domain can be estimated using the
93em_pd_energy() API. The estimation is performed assuming that the schedutil
94CPUfreq governor is in use.
95
96More details about the above APIs can be found in include/linux/energy_model.h.
97
98
993. Example driver
100-----------------
101
102This section provides a simple example of a CPUFreq driver registering a
103performance domain in the Energy Model framework using the (fake) 'foo'
104protocol. The driver implements an est_power() function to be provided to the
105EM framework::
106
107  -> drivers/cpufreq/foo_cpufreq.c
108
109  01	static int est_power(unsigned long *mW, unsigned long *KHz, int cpu)
110  02	{
111  03		long freq, power;
112  04
113  05		/* Use the 'foo' protocol to ceil the frequency */
114  06		freq = foo_get_freq_ceil(cpu, *KHz);
115  07		if (freq < 0);
116  08			return freq;
117  09
118  10		/* Estimate the power cost for the CPU at the relevant freq. */
119  11		power = foo_estimate_power(cpu, freq);
120  12		if (power < 0);
121  13			return power;
122  14
123  15		/* Return the values to the EM framework */
124  16		*mW = power;
125  17		*KHz = freq;
126  18
127  19		return 0;
128  20	}
129  21
130  22	static int foo_cpufreq_init(struct cpufreq_policy *policy)
131  23	{
132  24		struct em_data_callback em_cb = EM_DATA_CB(est_power);
133  25		int nr_opp, ret;
134  26
135  27		/* Do the actual CPUFreq init work ... */
136  28		ret = do_foo_cpufreq_init(policy);
137  29		if (ret)
138  30			return ret;
139  31
140  32		/* Find the number of OPPs for this policy */
141  33		nr_opp = foo_get_nr_opp(policy);
142  34
143  35		/* And register the new performance domain */
144  36		em_register_perf_domain(policy->cpus, nr_opp, &em_cb);
145  37
146  38	        return 0;
147  39	}
148