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