Documentation/power/energy-model.rst

1 .. SPDX-License-Identifier: GPL-2.0
8 -----------
12 subsystems willing to use that information to make energy-aware decisions.
18 each and every client subsystem to re-implement support for each and every
20 abstraction layer which standardizes the format of power cost tables in the
23 The power values might be expressed in micro-Watts or in an 'abstract scale'.
26 can be found in the Energy-Aware Scheduler documentation
27 Documentation/scheduler/sched-energy.rst. For some subsystems like thermal or
30 thus the real micro-Watts might be needed. An example of these requirements can
32 Documentation/driver-api/thermal/power_allocator.rst.
36 an 'abstract scale' deriving real energy in micro-Joules would not be possible.
38 The figure below depicts an example of drivers (Arm-specific here, but the
42        +---------------+  +-----------------+  +---------------+
44        +---------------+  +-----------------+  +---------------+
47                +---------+         |         +---------+
50                         +---------------------+
53                         +---------------------+
56                 +----------+       |       +---------+
58         +---------------+  +---------------+  +--------------+
59         |  cpufreq-dt   |  |   arm_scmi    |  |    Other     |
60         +---------------+  +---------------+  +--------------+
63         +--------------+   +---------------+  +--------------+
65         +--------------+   +---------------+  +--------------+
67 In case of CPU devices the EM framework manages power cost tables per
70 1-to-1 mapping with CPUFreq policies. All CPUs in a performance domain are
71 required to have the same micro-architecture. CPUs in different performance
72 domains can have different micro-architectures.
83 framework will handle the clean-up when it's possible.
101 ------------
145 "operating-points-v2". Each OPP entry in DT can be extended with a property
146 "opp-microwatt" containing micro-Watts power value. This OPP DT property
156 .get_cost() is optional and provides the 'cost' values used by the EAS.
161 The .get_cost() allows to provide the 'cost' values which reflect the
164 formulas calculating 'cost' values. To register an EM for such platform, the
230 and will be visible to other sub-systems in the kernel (thermal, powercap).
232 or memory allocations at runtime. When pre-computed EMs are available in the
233 device driver, than it should be possible to simply re-use them with low
242 no other sub-system using it, e.g. EAS.
244 To use the power values in other sub-systems (like thermal, powercap) there is
259 There is dedicated API for device drivers to calculate em_perf_state::cost
265 These 'cost' values from EM are used in EAS. The new EM table should be passed
267 of the cost values is done properly the return value from the function is 0.
280 .. kernel-doc:: include/linux/energy_model.h
283 .. kernel-doc:: kernel/power/energy_model.c
288 -----------
302   -> drivers/cpufreq/foo_cpufreq.c
314   11		/* Estimate the power cost for the dev at the relevant freq. */
332   29		cpu_dev = get_cpu_device(cpumask_first(policy->cpus));
338   35     	em_dev_register_perf_domain(cpu_dev, nr_opp, &em_cb, policy->cpus,
354   -> drivers/soc/example/example_em_mod.c
360   05		struct device *dev = ctx->dev;
373   18		new_table = em_table->state;
377   22		for (i = 0; i < pd->nr_perf_states; i++) {
383   28		/* Calculate 'cost' values for EAS */
384   29		ret = em_dev_compute_costs(dev, table, pd->nr_perf_states);
399   44		 * Since it's one-time-update drop the usage counter.
411   56		struct device *dev = ctx->dev;
414   59		ctx->temperature = foo_get_temp(dev, ctx);
415   60		if (ctx->temperature < FOO_EM_UPDATE_TEMP_THRESHOLD)