| blob | 08b3da4736cf29afa0927ff9706cc23cab0eb5ed |
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. These are mandatory except for the case where the OPP table
69 is present only to indicate dependency between devices using the opp-shared
70 property.
72 Optional properties:
73 - opp-shared: Indicates that device nodes using this OPP Table Node's phandle
74 switch their DVFS state together, i.e. they share clock/voltage/current lines.
75 Missing property means devices have independent clock/voltage/current lines,
76 but they share OPP tables.
78 - status: Marks the OPP table enabled/disabled.
81 * OPP Node
83 This defines voltage-current-frequency combinations along with other related
84 properties.
86 Required properties:
87 - opp-hz: Frequency in Hz, expressed as a 64-bit big-endian integer. This is a
88 required property for all device nodes, unless another "required" property to
89 uniquely identify the OPP nodes exists. Devices like power domains must have
90 another (implementation dependent) property.
92 - opp-peak-kBps: Peak bandwidth in kilobytes per second, expressed as an array
93 of 32-bit big-endian integers. Each element of the array represents the
94 peak bandwidth value of each interconnect path. The number of elements should
95 match the number of interconnect paths.
97 Optional properties:
98 - opp-microvolt: voltage in micro Volts.
100 A single regulator's voltage is specified with an array of size one or three.
101 Single entry is for target voltage and three entries are for <target min max>
102 voltages.
104 Entries for multiple regulators shall be provided in the same field separated
105 by angular brackets <>. The OPP binding doesn't provide any provisions to
106 relate the values to their power supplies or the order in which the supplies
107 need to be configured and that is left for the implementation specific
108 binding.
110 Entries for all regulators shall be of the same size, i.e. either all use a
111 single value or triplets.
113 - opp-microvolt-<name>: Named opp-microvolt property. This is exactly similar to
114 the above opp-microvolt property, but allows multiple voltage ranges to be
115 provided for the same OPP. At runtime, the platform can pick a <name> and
116 matching opp-microvolt-<name> property will be enabled for all OPPs. If the
117 platform doesn't pick a specific <name> or the <name> doesn't match with any
118 opp-microvolt-<name> properties, then opp-microvolt property shall be used, if
119 present.
121 - opp-microamp: The maximum current drawn by the device in microamperes
122 considering system specific parameters (such as transients, process, aging,
123 maximum operating temperature range etc.) as necessary. This may be used to
124 set the most efficient regulator operating mode.
126 Should only be set if opp-microvolt is set for the OPP.
128 Entries for multiple regulators shall be provided in the same field separated
129 by angular brackets <>. If current values aren't required for a regulator,
130 then it shall be filled with 0. If current values aren't required for any of
131 the regulators, then this field is not required. The OPP binding doesn't
132 provide any provisions to relate the values to their power supplies or the
133 order in which the supplies need to be configured and that is left for the
134 implementation specific binding.
136 - opp-microamp-<name>: Named opp-microamp property. Similar to
137 opp-microvolt-<name> property, but for microamp instead.
139 - opp-level: A value representing the performance level of the device,
140 expressed as a 32-bit integer.
142 - opp-avg-kBps: Average bandwidth in kilobytes per second, expressed as an array
143 of 32-bit big-endian integers. Each element of the array represents the
144 average bandwidth value of each interconnect path. The number of elements
145 should match the number of interconnect paths. This property is only
146 meaningful in OPP tables where opp-peak-kBps is present.
148 - clock-latency-ns: Specifies the maximum possible transition latency (in
149 nanoseconds) for switching to this OPP from any other OPP.
151 - turbo-mode: Marks the OPP to be used only for turbo modes. Turbo mode is
152 available on some platforms, where the device can run over its operating
153 frequency for a short duration of time limited by the device's power, current
154 and thermal limits.
156 - opp-suspend: Marks the OPP to be used during device suspend. If multiple OPPs
157 in the table have this, the OPP with highest opp-hz will be used.
159 - opp-supported-hw: This property allows a platform to enable only a subset of
160 the OPPs from the larger set present in the OPP table, based on the current
161 version of the hardware (already known to the operating system).
163 Each block present in the array of blocks in this property, represents a
164 sub-group of hardware versions supported by the OPP. i.e. <sub-group A>,
165 <sub-group B>, etc. The OPP will be enabled if _any_ of these sub-groups match
166 the hardware's version.
168 Each sub-group is a platform defined array representing the hierarchy of
169 hardware versions supported by the platform. For a platform with three
170 hierarchical levels of version (X.Y.Z), this field shall look like
172 opp-supported-hw = <X1 Y1 Z1>, <X2 Y2 Z2>, <X3 Y3 Z3>.
174 Each level (eg. X1) in version hierarchy is represented by a 32 bit value, one
175 bit per version and so there can be maximum 32 versions per level. Logical AND
176 (&) operation is performed for each level with the hardware's level version
177 and a non-zero output for _all_ the levels in a sub-group means the OPP is
178 supported by hardware. A value of 0xFFFFFFFF for each level in the sub-group
179 will enable the OPP for all versions for the hardware.
181 - status: Marks the node enabled/disabled.
183 - required-opps: This contains phandle to an OPP node in another device's OPP
184 table. It may contain an array of phandles, where each phandle points to an
185 OPP of a different device. It should not contain multiple phandles to the OPP
186 nodes in the same OPP table. This specifies the minimum required OPP of the
187 device(s), whose OPP's phandle is present in this property, for the
188 functioning of the current device at the current OPP (where this property is
189 present).
191 Example 1: Single cluster Dual-core ARM cortex A9, switch DVFS states together.
193 / {
194 cpus {
195 #address-cells = <1>;
196 #size-cells = <0>;
198 cpu@0 {
199 compatible = "arm,cortex-a9";
200 reg = <0>;
201 next-level-cache = <&L2>;
202 clocks = <&clk_controller 0>;
203 clock-names = "cpu";
204 cpu-supply = <&cpu_supply0>;
205 operating-points-v2 = <&cpu0_opp_table>;
206 };
208 cpu@1 {
209 compatible = "arm,cortex-a9";
210 reg = <1>;
211 next-level-cache = <&L2>;
212 clocks = <&clk_controller 0>;
213 clock-names = "cpu";
214 cpu-supply = <&cpu_supply0>;
215 operating-points-v2 = <&cpu0_opp_table>;
216 };
217 };
219 cpu0_opp_table: opp_table0 {
220 compatible = "operating-points-v2";
221 opp-shared;
223 opp-1000000000 {
224 opp-hz = /bits/ 64 <1000000000>;
225 opp-microvolt = <975000 970000 985000>;
226 opp-microamp = <70000>;
227 clock-latency-ns = <300000>;
228 opp-suspend;
229 };
230 opp-1100000000 {
231 opp-hz = /bits/ 64 <1100000000>;
232 opp-microvolt = <1000000 980000 1010000>;
233 opp-microamp = <80000>;
234 clock-latency-ns = <310000>;
235 };
236 opp-1200000000 {
237 opp-hz = /bits/ 64 <1200000000>;
238 opp-microvolt = <1025000>;
239 clock-latency-ns = <290000>;
240 turbo-mode;
241 };
242 };
243 };
245 Example 2: Single cluster, Quad-core Qualcom-krait, switches DVFS states
246 independently.
248 / {
249 cpus {
250 #address-cells = <1>;
251 #size-cells = <0>;
253 cpu@0 {
254 compatible = "qcom,krait";
255 reg = <0>;
256 next-level-cache = <&L2>;
257 clocks = <&clk_controller 0>;
258 clock-names = "cpu";
259 cpu-supply = <&cpu_supply0>;
260 operating-points-v2 = <&cpu_opp_table>;
261 };
263 cpu@1 {
264 compatible = "qcom,krait";
265 reg = <1>;
266 next-level-cache = <&L2>;
267 clocks = <&clk_controller 1>;
268 clock-names = "cpu";
269 cpu-supply = <&cpu_supply1>;
270 operating-points-v2 = <&cpu_opp_table>;
271 };
273 cpu@2 {
274 compatible = "qcom,krait";
275 reg = <2>;
276 next-level-cache = <&L2>;
277 clocks = <&clk_controller 2>;
278 clock-names = "cpu";
279 cpu-supply = <&cpu_supply2>;
280 operating-points-v2 = <&cpu_opp_table>;
281 };
283 cpu@3 {
284 compatible = "qcom,krait";
285 reg = <3>;
286 next-level-cache = <&L2>;
287 clocks = <&clk_controller 3>;
288 clock-names = "cpu";
289 cpu-supply = <&cpu_supply3>;
290 operating-points-v2 = <&cpu_opp_table>;
291 };
292 };
294 cpu_opp_table: opp_table {
295 compatible = "operating-points-v2";
297 /*
298 * Missing opp-shared property means CPUs switch DVFS states
299 * independently.
300 */
302 opp-1000000000 {
303 opp-hz = /bits/ 64 <1000000000>;
304 opp-microvolt = <975000 970000 985000>;
305 opp-microamp = <70000>;
306 clock-latency-ns = <300000>;
307 opp-suspend;
308 };
309 opp-1100000000 {
310 opp-hz = /bits/ 64 <1100000000>;
311 opp-microvolt = <1000000 980000 1010000>;
312 opp-microamp = <80000>;
313 clock-latency-ns = <310000>;
314 };
315 opp-1200000000 {
316 opp-hz = /bits/ 64 <1200000000>;
317 opp-microvolt = <1025000>;
318 opp-microamp = <90000;
319 lock-latency-ns = <290000>;
320 turbo-mode;
321 };
322 };
323 };
325 Example 3: Dual-cluster, Dual-core per cluster. CPUs within a cluster switch
326 DVFS state together.
328 / {
329 cpus {
330 #address-cells = <1>;
331 #size-cells = <0>;
333 cpu@0 {
334 compatible = "arm,cortex-a7";
335 reg = <0>;
336 next-level-cache = <&L2>;
337 clocks = <&clk_controller 0>;
338 clock-names = "cpu";
339 cpu-supply = <&cpu_supply0>;
340 operating-points-v2 = <&cluster0_opp>;
341 };
343 cpu@1 {
344 compatible = "arm,cortex-a7";
345 reg = <1>;
346 next-level-cache = <&L2>;
347 clocks = <&clk_controller 0>;
348 clock-names = "cpu";
349 cpu-supply = <&cpu_supply0>;
350 operating-points-v2 = <&cluster0_opp>;
351 };
353 cpu@100 {
354 compatible = "arm,cortex-a15";
355 reg = <100>;
356 next-level-cache = <&L2>;
357 clocks = <&clk_controller 1>;
358 clock-names = "cpu";
359 cpu-supply = <&cpu_supply1>;
360 operating-points-v2 = <&cluster1_opp>;
361 };
363 cpu@101 {
364 compatible = "arm,cortex-a15";
365 reg = <101>;
366 next-level-cache = <&L2>;
367 clocks = <&clk_controller 1>;
368 clock-names = "cpu";
369 cpu-supply = <&cpu_supply1>;
370 operating-points-v2 = <&cluster1_opp>;
371 };
372 };
374 cluster0_opp: opp_table0 {
375 compatible = "operating-points-v2";
376 opp-shared;
378 opp-1000000000 {
379 opp-hz = /bits/ 64 <1000000000>;
380 opp-microvolt = <975000 970000 985000>;
381 opp-microamp = <70000>;
382 clock-latency-ns = <300000>;
383 opp-suspend;
384 };
385 opp-1100000000 {
386 opp-hz = /bits/ 64 <1100000000>;
387 opp-microvolt = <1000000 980000 1010000>;
388 opp-microamp = <80000>;
389 clock-latency-ns = <310000>;
390 };
391 opp-1200000000 {
392 opp-hz = /bits/ 64 <1200000000>;
393 opp-microvolt = <1025000>;
394 opp-microamp = <90000>;
395 clock-latency-ns = <290000>;
396 turbo-mode;
397 };
398 };
400 cluster1_opp: opp_table1 {
401 compatible = "operating-points-v2";
402 opp-shared;
404 opp-1300000000 {
405 opp-hz = /bits/ 64 <1300000000>;
406 opp-microvolt = <1050000 1045000 1055000>;
407 opp-microamp = <95000>;
408 clock-latency-ns = <400000>;
409 opp-suspend;
410 };
411 opp-1400000000 {
412 opp-hz = /bits/ 64 <1400000000>;
413 opp-microvolt = <1075000>;
414 opp-microamp = <100000>;
415 clock-latency-ns = <400000>;
416 };
417 opp-1500000000 {
418 opp-hz = /bits/ 64 <1500000000>;
419 opp-microvolt = <1100000 1010000 1110000>;
420 opp-microamp = <95000>;
421 clock-latency-ns = <400000>;
422 turbo-mode;
423 };
424 };
425 };
427 Example 4: Handling multiple regulators
429 / {
430 cpus {
431 cpu@0 {
432 compatible = "vendor,cpu-type";
433 ...
435 vcc0-supply = <&cpu_supply0>;
436 vcc1-supply = <&cpu_supply1>;
437 vcc2-supply = <&cpu_supply2>;
438 operating-points-v2 = <&cpu0_opp_table>;
439 };
440 };
442 cpu0_opp_table: opp_table0 {
443 compatible = "operating-points-v2";
444 opp-shared;
446 opp-1000000000 {
447 opp-hz = /bits/ 64 <1000000000>;
448 opp-microvolt = <970000>, /* Supply 0 */
449 <960000>, /* Supply 1 */
450 <960000>; /* Supply 2 */
451 opp-microamp = <70000>, /* Supply 0 */
452 <70000>, /* Supply 1 */
453 <70000>; /* Supply 2 */
454 clock-latency-ns = <300000>;
455 };
457 /* OR */
459 opp-1000000000 {
460 opp-hz = /bits/ 64 <1000000000>;
461 opp-microvolt = <975000 970000 985000>, /* Supply 0 */
462 <965000 960000 975000>, /* Supply 1 */
463 <965000 960000 975000>; /* Supply 2 */
464 opp-microamp = <70000>, /* Supply 0 */
465 <70000>, /* Supply 1 */
466 <70000>; /* Supply 2 */
467 clock-latency-ns = <300000>;
468 };
470 /* OR */
472 opp-1000000000 {
473 opp-hz = /bits/ 64 <1000000000>;
474 opp-microvolt = <975000 970000 985000>, /* Supply 0 */
475 <965000 960000 975000>, /* Supply 1 */
476 <965000 960000 975000>; /* Supply 2 */
477 opp-microamp = <70000>, /* Supply 0 */
478 <0>, /* Supply 1 doesn't need this */
479 <70000>; /* Supply 2 */
480 clock-latency-ns = <300000>;
481 };
482 };
483 };
485 Example 5: opp-supported-hw
486 (example: three level hierarchy of versions: cuts, substrate and process)
488 / {
489 cpus {
490 cpu@0 {
491 compatible = "arm,cortex-a7";
492 ...
494 cpu-supply = <&cpu_supply>
495 operating-points-v2 = <&cpu0_opp_table_slow>;
496 };
497 };
499 opp_table {
500 compatible = "operating-points-v2";
501 opp-shared;
503 opp-600000000 {
504 /*
505 * Supports all substrate and process versions for 0xF
506 * cuts, i.e. only first four cuts.
507 */
508 opp-supported-hw = <0xF 0xFFFFFFFF 0xFFFFFFFF>
509 opp-hz = /bits/ 64 <600000000>;
510 ...
511 };
513 opp-800000000 {
514 /*
515 * Supports:
516 * - cuts: only one, 6th cut (represented by 6th bit).
517 * - substrate: supports 16 different substrate versions
518 * - process: supports 9 different process versions
519 */
520 opp-supported-hw = <0x20 0xff0000ff 0x0000f4f0>
521 opp-hz = /bits/ 64 <800000000>;
522 ...
523 };
525 opp-900000000 {
526 /*
527 * Supports:
528 * - All cuts and substrate where process version is 0x2.
529 * - All cuts and process where substrate version is 0x2.
530 */
531 opp-supported-hw = <0xFFFFFFFF 0xFFFFFFFF 0x02>, <0xFFFFFFFF 0x01 0xFFFFFFFF>
532 opp-hz = /bits/ 64 <900000000>;
533 ...
534 };
535 };
536 };
538 Example 6: opp-microvolt-<name>, opp-microamp-<name>:
539 (example: device with two possible microvolt ranges: slow and fast)
541 / {
542 cpus {
543 cpu@0 {
544 compatible = "arm,cortex-a7";
545 ...
547 operating-points-v2 = <&cpu0_opp_table>;
548 };
549 };
551 cpu0_opp_table: opp_table0 {
552 compatible = "operating-points-v2";
553 opp-shared;
555 opp-1000000000 {
556 opp-hz = /bits/ 64 <1000000000>;
557 opp-microvolt-slow = <915000 900000 925000>;
558 opp-microvolt-fast = <975000 970000 985000>;
559 opp-microamp-slow = <70000>;
560 opp-microamp-fast = <71000>;
561 };
563 opp-1200000000 {
564 opp-hz = /bits/ 64 <1200000000>;
565 opp-microvolt-slow = <915000 900000 925000>, /* Supply vcc0 */
566 <925000 910000 935000>; /* Supply vcc1 */
567 opp-microvolt-fast = <975000 970000 985000>, /* Supply vcc0 */
568 <965000 960000 975000>; /* Supply vcc1 */
569 opp-microamp = <70000>; /* Will be used for both slow/fast */
570 };
571 };
572 };
574 Example 7: Single cluster Quad-core ARM cortex A53, OPP points from firmware,
575 distinct clock controls but two sets of clock/voltage/current lines.
577 / {
578 cpus {
579 #address-cells = <2>;
580 #size-cells = <0>;
582 cpu@0 {
583 compatible = "arm,cortex-a53";
584 reg = <0x0 0x100>;
585 next-level-cache = <&A53_L2>;
586 clocks = <&dvfs_controller 0>;
587 operating-points-v2 = <&cpu_opp0_table>;
588 };
589 cpu@1 {
590 compatible = "arm,cortex-a53";
591 reg = <0x0 0x101>;
592 next-level-cache = <&A53_L2>;
593 clocks = <&dvfs_controller 1>;
594 operating-points-v2 = <&cpu_opp0_table>;
595 };
596 cpu@2 {
597 compatible = "arm,cortex-a53";
598 reg = <0x0 0x102>;
599 next-level-cache = <&A53_L2>;
600 clocks = <&dvfs_controller 2>;
601 operating-points-v2 = <&cpu_opp1_table>;
602 };
603 cpu@3 {
604 compatible = "arm,cortex-a53";
605 reg = <0x0 0x103>;
606 next-level-cache = <&A53_L2>;
607 clocks = <&dvfs_controller 3>;
608 operating-points-v2 = <&cpu_opp1_table>;
609 };
611 };
613 cpu_opp0_table: opp0_table {
614 compatible = "operating-points-v2";
615 opp-shared;
616 };
618 cpu_opp1_table: opp1_table {
619 compatible = "operating-points-v2";
620 opp-shared;
621 };
622 };