| blob | 4e4f30288c8bb726667e93c415c79477fc1e9253 |
1 Generic OPP (Operating Performance Points) Bindings
2 ----------------------------------------------------
4 Devices work at voltage-current-frequency combinations and some implementations
5 have the liberty of choosing these. These combinations are called Operating
6 Performance Points aka OPPs. This document defines bindings for these OPPs
7 applicable across wide range of devices. For illustration purpose, this document
8 uses CPU as a device.
10 This document contain multiple versions of OPP binding and only one of them
11 should be used per device.
13 Binding 1: operating-points
14 ============================
16 This binding only supports voltage-frequency pairs.
18 Properties:
19 - operating-points: An array of 2-tuples items, and each item consists
20 of frequency and voltage like <freq-kHz vol-uV>.
21 freq: clock frequency in kHz
22 vol: voltage in microvolt
24 Examples:
26 cpu@0 {
27 compatible = "arm,cortex-a9";
28 reg = <0>;
29 next-level-cache = <&L2>;
30 operating-points = <
31 /* kHz uV */
32 792000 1100000
33 396000 950000
34 198000 850000
35 >;
36 };
39 Binding 2: operating-points-v2
40 ============================
42 * Property: operating-points-v2
44 Devices supporting OPPs must set their "operating-points-v2" property with
45 phandle to a OPP table in their DT node. The OPP core will use this phandle to
46 find the operating points for the device.
48 This can contain more than one phandle for power domain providers that provide
49 multiple power domains. That is, one phandle for each power domain. If only one
50 phandle is available, then the same OPP table will be used for all power domains
51 provided by the power domain provider.
53 If required, this can be extended for SoC vendor specific bindings. Such bindings
54 should be documented as Documentation/devicetree/bindings/power/<vendor>-opp.txt
55 and should have a compatible description like: "operating-points-v2-<vendor>".
57 * OPP Table Node
59 This describes the OPPs belonging to a device. This node can have following
60 properties:
62 Required properties:
63 - compatible: Allow OPPs to express their compatibility. It should be:
64 "operating-points-v2".
66 - OPP nodes: One or more OPP nodes describing voltage-current-frequency
67 combinations. Their name isn't significant but their phandle can be used to
68 reference an OPP.
70 Optional properties:
71 - opp-shared: Indicates that device nodes using this OPP Table Node's phandle
72 switch their DVFS state together, i.e. they share clock/voltage/current lines.
73 Missing property means devices have independent clock/voltage/current lines,
74 but they share OPP tables.
76 - status: Marks the OPP table enabled/disabled.
79 * OPP Node
81 This defines voltage-current-frequency combinations along with other related
82 properties.
84 Required properties:
85 - opp-hz: Frequency in Hz, expressed as a 64-bit big-endian integer.
87 Optional properties:
88 - opp-microvolt: voltage in micro Volts.
90 A single regulator's voltage is specified with an array of size one or three.
91 Single entry is for target voltage and three entries are for <target min max>
92 voltages.
94 Entries for multiple regulators shall be provided in the same field separated
95 by angular brackets <>. The OPP binding doesn't provide any provisions to
96 relate the values to their power supplies or the order in which the supplies
97 need to be configured and that is left for the implementation specific
98 binding.
100 Entries for all regulators shall be of the same size, i.e. either all use a
101 single value or triplets.
103 - opp-microvolt-<name>: Named opp-microvolt property. This is exactly similar to
104 the above opp-microvolt property, but allows multiple voltage ranges to be
105 provided for the same OPP. At runtime, the platform can pick a <name> and
106 matching opp-microvolt-<name> property will be enabled for all OPPs. If the
107 platform doesn't pick a specific <name> or the <name> doesn't match with any
108 opp-microvolt-<name> properties, then opp-microvolt property shall be used, if
109 present.
111 - opp-microamp: The maximum current drawn by the device in microamperes
112 considering system specific parameters (such as transients, process, aging,
113 maximum operating temperature range etc.) as necessary. This may be used to
114 set the most efficient regulator operating mode.
116 Should only be set if opp-microvolt is set for the OPP.
118 Entries for multiple regulators shall be provided in the same field separated
119 by angular brackets <>. If current values aren't required for a regulator,
120 then it shall be filled with 0. If current values aren't required for any of
121 the regulators, then this field is not required. The OPP binding doesn't
122 provide any provisions to relate the values to their power supplies or the
123 order in which the supplies need to be configured and that is left for the
124 implementation specific binding.
126 - opp-microamp-<name>: Named opp-microamp property. Similar to
127 opp-microvolt-<name> property, but for microamp instead.
129 - clock-latency-ns: Specifies the maximum possible transition latency (in
130 nanoseconds) for switching to this OPP from any other OPP.
132 - turbo-mode: Marks the OPP to be used only for turbo modes. Turbo mode is
133 available on some platforms, where the device can run over its operating
134 frequency for a short duration of time limited by the device's power, current
135 and thermal limits.
137 - opp-suspend: Marks the OPP to be used during device suspend. Only one OPP in
138 the table should have this.
140 - opp-supported-hw: This enables us to select only a subset of OPPs from the
141 larger OPP table, based on what version of the hardware we are running on. We
142 still can't have multiple nodes with the same opp-hz value in OPP table.
144 It's a user defined array containing a hierarchy of hardware version numbers,
145 supported by the OPP. For example: a platform with hierarchy of three levels
146 of versions (A, B and C), this field should be like <X Y Z>, where X
147 corresponds to Version hierarchy A, Y corresponds to version hierarchy B and Z
148 corresponds to version hierarchy C.
150 Each level of hierarchy is represented by a 32 bit value, and so there can be
151 only 32 different supported version per hierarchy. i.e. 1 bit per version. A
152 value of 0xFFFFFFFF will enable the OPP for all versions for that hierarchy
153 level. And a value of 0x00000000 will disable the OPP completely, and so we
154 never want that to happen.
156 If 32 values aren't sufficient for a version hierarchy, than that version
157 hierarchy can be contained in multiple 32 bit values. i.e. <X Y Z1 Z2> in the
158 above example, Z1 & Z2 refer to the version hierarchy Z.
160 - status: Marks the node enabled/disabled.
162 - required-opp: This contains phandle to an OPP node in another device's OPP
163 table. It may contain an array of phandles, where each phandle points to an
164 OPP of a different device. It should not contain multiple phandles to the OPP
165 nodes in the same OPP table. This specifies the minimum required OPP of the
166 device(s), whose OPP's phandle is present in this property, for the
167 functioning of the current device at the current OPP (where this property is
168 present).
170 Example 1: Single cluster Dual-core ARM cortex A9, switch DVFS states together.
172 / {
173 cpus {
174 #address-cells = <1>;
175 #size-cells = <0>;
177 cpu@0 {
178 compatible = "arm,cortex-a9";
179 reg = <0>;
180 next-level-cache = <&L2>;
181 clocks = <&clk_controller 0>;
182 clock-names = "cpu";
183 cpu-supply = <&cpu_supply0>;
184 operating-points-v2 = <&cpu0_opp_table>;
185 };
187 cpu@1 {
188 compatible = "arm,cortex-a9";
189 reg = <1>;
190 next-level-cache = <&L2>;
191 clocks = <&clk_controller 0>;
192 clock-names = "cpu";
193 cpu-supply = <&cpu_supply0>;
194 operating-points-v2 = <&cpu0_opp_table>;
195 };
196 };
198 cpu0_opp_table: opp_table0 {
199 compatible = "operating-points-v2";
200 opp-shared;
202 opp-1000000000 {
203 opp-hz = /bits/ 64 <1000000000>;
204 opp-microvolt = <975000 970000 985000>;
205 opp-microamp = <70000>;
206 clock-latency-ns = <300000>;
207 opp-suspend;
208 };
209 opp-1100000000 {
210 opp-hz = /bits/ 64 <1100000000>;
211 opp-microvolt = <1000000 980000 1010000>;
212 opp-microamp = <80000>;
213 clock-latency-ns = <310000>;
214 };
215 opp-1200000000 {
216 opp-hz = /bits/ 64 <1200000000>;
217 opp-microvolt = <1025000>;
218 clock-latency-ns = <290000>;
219 turbo-mode;
220 };
221 };
222 };
224 Example 2: Single cluster, Quad-core Qualcom-krait, switches DVFS states
225 independently.
227 / {
228 cpus {
229 #address-cells = <1>;
230 #size-cells = <0>;
232 cpu@0 {
233 compatible = "qcom,krait";
234 reg = <0>;
235 next-level-cache = <&L2>;
236 clocks = <&clk_controller 0>;
237 clock-names = "cpu";
238 cpu-supply = <&cpu_supply0>;
239 operating-points-v2 = <&cpu_opp_table>;
240 };
242 cpu@1 {
243 compatible = "qcom,krait";
244 reg = <1>;
245 next-level-cache = <&L2>;
246 clocks = <&clk_controller 1>;
247 clock-names = "cpu";
248 cpu-supply = <&cpu_supply1>;
249 operating-points-v2 = <&cpu_opp_table>;
250 };
252 cpu@2 {
253 compatible = "qcom,krait";
254 reg = <2>;
255 next-level-cache = <&L2>;
256 clocks = <&clk_controller 2>;
257 clock-names = "cpu";
258 cpu-supply = <&cpu_supply2>;
259 operating-points-v2 = <&cpu_opp_table>;
260 };
262 cpu@3 {
263 compatible = "qcom,krait";
264 reg = <3>;
265 next-level-cache = <&L2>;
266 clocks = <&clk_controller 3>;
267 clock-names = "cpu";
268 cpu-supply = <&cpu_supply3>;
269 operating-points-v2 = <&cpu_opp_table>;
270 };
271 };
273 cpu_opp_table: opp_table {
274 compatible = "operating-points-v2";
276 /*
277 * Missing opp-shared property means CPUs switch DVFS states
278 * independently.
279 */
281 opp-1000000000 {
282 opp-hz = /bits/ 64 <1000000000>;
283 opp-microvolt = <975000 970000 985000>;
284 opp-microamp = <70000>;
285 clock-latency-ns = <300000>;
286 opp-suspend;
287 };
288 opp-1100000000 {
289 opp-hz = /bits/ 64 <1100000000>;
290 opp-microvolt = <1000000 980000 1010000>;
291 opp-microamp = <80000>;
292 clock-latency-ns = <310000>;
293 };
294 opp-1200000000 {
295 opp-hz = /bits/ 64 <1200000000>;
296 opp-microvolt = <1025000>;
297 opp-microamp = <90000;
298 lock-latency-ns = <290000>;
299 turbo-mode;
300 };
301 };
302 };
304 Example 3: Dual-cluster, Dual-core per cluster. CPUs within a cluster switch
305 DVFS state together.
307 / {
308 cpus {
309 #address-cells = <1>;
310 #size-cells = <0>;
312 cpu@0 {
313 compatible = "arm,cortex-a7";
314 reg = <0>;
315 next-level-cache = <&L2>;
316 clocks = <&clk_controller 0>;
317 clock-names = "cpu";
318 cpu-supply = <&cpu_supply0>;
319 operating-points-v2 = <&cluster0_opp>;
320 };
322 cpu@1 {
323 compatible = "arm,cortex-a7";
324 reg = <1>;
325 next-level-cache = <&L2>;
326 clocks = <&clk_controller 0>;
327 clock-names = "cpu";
328 cpu-supply = <&cpu_supply0>;
329 operating-points-v2 = <&cluster0_opp>;
330 };
332 cpu@100 {
333 compatible = "arm,cortex-a15";
334 reg = <100>;
335 next-level-cache = <&L2>;
336 clocks = <&clk_controller 1>;
337 clock-names = "cpu";
338 cpu-supply = <&cpu_supply1>;
339 operating-points-v2 = <&cluster1_opp>;
340 };
342 cpu@101 {
343 compatible = "arm,cortex-a15";
344 reg = <101>;
345 next-level-cache = <&L2>;
346 clocks = <&clk_controller 1>;
347 clock-names = "cpu";
348 cpu-supply = <&cpu_supply1>;
349 operating-points-v2 = <&cluster1_opp>;
350 };
351 };
353 cluster0_opp: opp_table0 {
354 compatible = "operating-points-v2";
355 opp-shared;
357 opp-1000000000 {
358 opp-hz = /bits/ 64 <1000000000>;
359 opp-microvolt = <975000 970000 985000>;
360 opp-microamp = <70000>;
361 clock-latency-ns = <300000>;
362 opp-suspend;
363 };
364 opp-1100000000 {
365 opp-hz = /bits/ 64 <1100000000>;
366 opp-microvolt = <1000000 980000 1010000>;
367 opp-microamp = <80000>;
368 clock-latency-ns = <310000>;
369 };
370 opp-1200000000 {
371 opp-hz = /bits/ 64 <1200000000>;
372 opp-microvolt = <1025000>;
373 opp-microamp = <90000>;
374 clock-latency-ns = <290000>;
375 turbo-mode;
376 };
377 };
379 cluster1_opp: opp_table1 {
380 compatible = "operating-points-v2";
381 opp-shared;
383 opp-1300000000 {
384 opp-hz = /bits/ 64 <1300000000>;
385 opp-microvolt = <1050000 1045000 1055000>;
386 opp-microamp = <95000>;
387 clock-latency-ns = <400000>;
388 opp-suspend;
389 };
390 opp-1400000000 {
391 opp-hz = /bits/ 64 <1400000000>;
392 opp-microvolt = <1075000>;
393 opp-microamp = <100000>;
394 clock-latency-ns = <400000>;
395 };
396 opp-1500000000 {
397 opp-hz = /bits/ 64 <1500000000>;
398 opp-microvolt = <1100000 1010000 1110000>;
399 opp-microamp = <95000>;
400 clock-latency-ns = <400000>;
401 turbo-mode;
402 };
403 };
404 };
406 Example 4: Handling multiple regulators
408 / {
409 cpus {
410 cpu@0 {
411 compatible = "vendor,cpu-type";
412 ...
414 vcc0-supply = <&cpu_supply0>;
415 vcc1-supply = <&cpu_supply1>;
416 vcc2-supply = <&cpu_supply2>;
417 operating-points-v2 = <&cpu0_opp_table>;
418 };
419 };
421 cpu0_opp_table: opp_table0 {
422 compatible = "operating-points-v2";
423 opp-shared;
425 opp-1000000000 {
426 opp-hz = /bits/ 64 <1000000000>;
427 opp-microvolt = <970000>, /* Supply 0 */
428 <960000>, /* Supply 1 */
429 <960000>; /* Supply 2 */
430 opp-microamp = <70000>, /* Supply 0 */
431 <70000>, /* Supply 1 */
432 <70000>; /* Supply 2 */
433 clock-latency-ns = <300000>;
434 };
436 /* OR */
438 opp-1000000000 {
439 opp-hz = /bits/ 64 <1000000000>;
440 opp-microvolt = <975000 970000 985000>, /* Supply 0 */
441 <965000 960000 975000>, /* Supply 1 */
442 <965000 960000 975000>; /* Supply 2 */
443 opp-microamp = <70000>, /* Supply 0 */
444 <70000>, /* Supply 1 */
445 <70000>; /* Supply 2 */
446 clock-latency-ns = <300000>;
447 };
449 /* OR */
451 opp-1000000000 {
452 opp-hz = /bits/ 64 <1000000000>;
453 opp-microvolt = <975000 970000 985000>, /* Supply 0 */
454 <965000 960000 975000>, /* Supply 1 */
455 <965000 960000 975000>; /* Supply 2 */
456 opp-microamp = <70000>, /* Supply 0 */
457 <0>, /* Supply 1 doesn't need this */
458 <70000>; /* Supply 2 */
459 clock-latency-ns = <300000>;
460 };
461 };
462 };
464 Example 5: opp-supported-hw
465 (example: three level hierarchy of versions: cuts, substrate and process)
467 / {
468 cpus {
469 cpu@0 {
470 compatible = "arm,cortex-a7";
471 ...
473 cpu-supply = <&cpu_supply>
474 operating-points-v2 = <&cpu0_opp_table_slow>;
475 };
476 };
478 opp_table {
479 compatible = "operating-points-v2";
480 opp-shared;
482 opp-600000000 {
483 /*
484 * Supports all substrate and process versions for 0xF
485 * cuts, i.e. only first four cuts.
486 */
487 opp-supported-hw = <0xF 0xFFFFFFFF 0xFFFFFFFF>
488 opp-hz = /bits/ 64 <600000000>;
489 opp-microvolt = <915000 900000 925000>;
490 ...
491 };
493 opp-800000000 {
494 /*
495 * Supports:
496 * - cuts: only one, 6th cut (represented by 6th bit).
497 * - substrate: supports 16 different substrate versions
498 * - process: supports 9 different process versions
499 */
500 opp-supported-hw = <0x20 0xff0000ff 0x0000f4f0>
501 opp-hz = /bits/ 64 <800000000>;
502 opp-microvolt = <915000 900000 925000>;
503 ...
504 };
505 };
506 };
508 Example 6: opp-microvolt-<name>, opp-microamp-<name>:
509 (example: device with two possible microvolt ranges: slow and fast)
511 / {
512 cpus {
513 cpu@0 {
514 compatible = "arm,cortex-a7";
515 ...
517 operating-points-v2 = <&cpu0_opp_table>;
518 };
519 };
521 cpu0_opp_table: opp_table0 {
522 compatible = "operating-points-v2";
523 opp-shared;
525 opp-1000000000 {
526 opp-hz = /bits/ 64 <1000000000>;
527 opp-microvolt-slow = <915000 900000 925000>;
528 opp-microvolt-fast = <975000 970000 985000>;
529 opp-microamp-slow = <70000>;
530 opp-microamp-fast = <71000>;
531 };
533 opp-1200000000 {
534 opp-hz = /bits/ 64 <1200000000>;
535 opp-microvolt-slow = <915000 900000 925000>, /* Supply vcc0 */
536 <925000 910000 935000>; /* Supply vcc1 */
537 opp-microvolt-fast = <975000 970000 985000>, /* Supply vcc0 */
538 <965000 960000 975000>; /* Supply vcc1 */
539 opp-microamp = <70000>; /* Will be used for both slow/fast */
540 };
541 };
542 };