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