@@ -36,8 +36,162 @@ the user. The registration APIs returns the cooling device pointer.
3636 np: pointer to the cooling device device tree node
3737 clip_cpus: cpumask of cpus where the frequency constraints will happen.
3838
39- 1.1.3 void cpufreq_cooling_unregister(struct thermal_cooling_device *cdev)
39+ 1.1.3 struct thermal_cooling_device *cpufreq_power_cooling_register(
40+ const struct cpumask *clip_cpus, u32 capacitance,
41+ get_static_t plat_static_func)
42+
43+ Similar to cpufreq_cooling_register, this function registers a cpufreq
44+ cooling device. Using this function, the cooling device will
45+ implement the power extensions by using a simple cpu power model. The
46+ cpus must have registered their OPPs using the OPP library.
47+
48+ The additional parameters are needed for the power model (See 2. Power
49+ models). "capacitance" is the dynamic power coefficient (See 2.1
50+ Dynamic power). "plat_static_func" is a function to calculate the
51+ static power consumed by these cpus (See 2.2 Static power).
52+
53+ 1.1.4 struct thermal_cooling_device *of_cpufreq_power_cooling_register(
54+ struct device_node *np, const struct cpumask *clip_cpus, u32 capacitance,
55+ get_static_t plat_static_func)
56+
57+ Similar to cpufreq_power_cooling_register, this function register a
58+ cpufreq cooling device with power extensions using the device tree
59+ information supplied by the np parameter.
60+
61+ 1.1.5 void cpufreq_cooling_unregister(struct thermal_cooling_device *cdev)
4062
4163 This interface function unregisters the "thermal-cpufreq-%x" cooling device.
4264
4365 cdev: Cooling device pointer which has to be unregistered.
66+
67+ 2. Power models
68+
69+ The power API registration functions provide a simple power model for
70+ CPUs. The current power is calculated as dynamic + (optionally)
71+ static power. This power model requires that the operating-points of
72+ the CPUs are registered using the kernel's opp library and the
73+ `cpufreq_frequency_table` is assigned to the `struct device` of the
74+ cpu. If you are using CONFIG_CPUFREQ_DT then the
75+ `cpufreq_frequency_table` should already be assigned to the cpu
76+ device.
77+
78+ The `plat_static_func` parameter of `cpufreq_power_cooling_register()`
79+ and `of_cpufreq_power_cooling_register()` is optional. If you don't
80+ provide it, only dynamic power will be considered.
81+
82+ 2.1 Dynamic power
83+
84+ The dynamic power consumption of a processor depends on many factors.
85+ For a given processor implementation the primary factors are:
86+
87+ - The time the processor spends running, consuming dynamic power, as
88+ compared to the time in idle states where dynamic consumption is
89+ negligible. Herein we refer to this as 'utilisation'.
90+ - The voltage and frequency levels as a result of DVFS. The DVFS
91+ level is a dominant factor governing power consumption.
92+ - In running time the 'execution' behaviour (instruction types, memory
93+ access patterns and so forth) causes, in most cases, a second order
94+ variation. In pathological cases this variation can be significant,
95+ but typically it is of a much lesser impact than the factors above.
96+
97+ A high level dynamic power consumption model may then be represented as:
98+
99+ Pdyn = f(run) * Voltage^2 * Frequency * Utilisation
100+
101+ f(run) here represents the described execution behaviour and its
102+ result has a units of Watts/Hz/Volt^2 (this often expressed in
103+ mW/MHz/uVolt^2)
104+
105+ The detailed behaviour for f(run) could be modelled on-line. However,
106+ in practice, such an on-line model has dependencies on a number of
107+ implementation specific processor support and characterisation
108+ factors. Therefore, in initial implementation that contribution is
109+ represented as a constant coefficient. This is a simplification
110+ consistent with the relative contribution to overall power variation.
111+
112+ In this simplified representation our model becomes:
113+
114+ Pdyn = Capacitance * Voltage^2 * Frequency * Utilisation
115+
116+ Where `capacitance` is a constant that represents an indicative
117+ running time dynamic power coefficient in fundamental units of
118+ mW/MHz/uVolt^2. Typical values for mobile CPUs might lie in range
119+ from 100 to 500. For reference, the approximate values for the SoC in
120+ ARM's Juno Development Platform are 530 for the Cortex-A57 cluster and
121+ 140 for the Cortex-A53 cluster.
122+
123+
124+ 2.2 Static power
125+
126+ Static leakage power consumption depends on a number of factors. For a
127+ given circuit implementation the primary factors are:
128+
129+ - Time the circuit spends in each 'power state'
130+ - Temperature
131+ - Operating voltage
132+ - Process grade
133+
134+ The time the circuit spends in each 'power state' for a given
135+ evaluation period at first order means OFF or ON. However,
136+ 'retention' states can also be supported that reduce power during
137+ inactive periods without loss of context.
138+
139+ Note: The visibility of state entries to the OS can vary, according to
140+ platform specifics, and this can then impact the accuracy of a model
141+ based on OS state information alone. It might be possible in some
142+ cases to extract more accurate information from system resources.
143+
144+ The temperature, operating voltage and process 'grade' (slow to fast)
145+ of the circuit are all significant factors in static leakage power
146+ consumption. All of these have complex relationships to static power.
147+
148+ Circuit implementation specific factors include the chosen silicon
149+ process as well as the type, number and size of transistors in both
150+ the logic gates and any RAM elements included.
151+
152+ The static power consumption modelling must take into account the
153+ power managed regions that are implemented. Taking the example of an
154+ ARM processor cluster, the modelling would take into account whether
155+ each CPU can be powered OFF separately or if only a single power
156+ region is implemented for the complete cluster.
157+
158+ In one view, there are others, a static power consumption model can
159+ then start from a set of reference values for each power managed
160+ region (e.g. CPU, Cluster/L2) in each state (e.g. ON, OFF) at an
161+ arbitrary process grade, voltage and temperature point. These values
162+ are then scaled for all of the following: the time in each state, the
163+ process grade, the current temperature and the operating voltage.
164+ However, since both implementation specific and complex relationships
165+ dominate the estimate, the appropriate interface to the model from the
166+ cpu cooling device is to provide a function callback that calculates
167+ the static power in this platform. When registering the cpu cooling
168+ device pass a function pointer that follows the `get_static_t`
169+ prototype:
170+
171+ int plat_get_static(cpumask_t *cpumask, int interval,
172+ unsigned long voltage, u32 &power);
173+
174+ `cpumask` is the cpumask of the cpus involved in the calculation.
175+ `voltage` is the voltage at which they are operating. The function
176+ should calculate the average static power for the last `interval`
177+ milliseconds. It returns 0 on success, -E* on error. If it
178+ succeeds, it should store the static power in `power`. Reading the
179+ temperature of the cpus described by `cpumask` is left for
180+ plat_get_static() to do as the platform knows best which thermal
181+ sensor is closest to the cpu.
182+
183+ If `plat_static_func` is NULL, static power is considered to be
184+ negligible for this platform and only dynamic power is considered.
185+
186+ The platform specific callback can then use any combination of tables
187+ and/or equations to permute the estimated value. Process grade
188+ information is not passed to the model since access to such data, from
189+ on-chip measurement capability or manufacture time data, is platform
190+ specific.
191+
192+ Note: the significance of static power for CPUs in comparison to
193+ dynamic power is highly dependent on implementation. Given the
194+ potential complexity in implementation, the importance and accuracy of
195+ its inclusion when using cpu cooling devices should be assessed on a
196+ case by case basis.
197+
0 commit comments