1Generic OPP (Operating Performance Points) Bindings 2---------------------------------------------------- 3 4Devices work at voltage-current-frequency combinations and some implementations 5have the liberty of choosing these. These combinations are called Operating 6Performance Points aka OPPs. This document defines bindings for these OPPs 7applicable across wide range of devices. For illustration purpose, this document 8uses CPU as a device. 9 10This document contain multiple versions of OPP binding and only one of them 11should be used per device. 12 13Binding 1: operating-points 14============================ 15 16This binding only supports voltage-frequency pairs. 17 18Properties: 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 23 24Examples: 25 26cpu@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}; 37 38 39Binding 2: operating-points-v2 40============================ 41 42* Property: operating-points-v2 43 44Devices supporting OPPs must set their "operating-points-v2" property with 45phandle to a OPP table in their DT node. The OPP core will use this phandle to 46find the operating points for the device. 47 48This can contain more than one phandle for power domain providers that provide 49multiple power domains. That is, one phandle for each power domain. If only one 50phandle is available, then the same OPP table will be used for all power domains 51provided by the power domain provider. 52 53If required, this can be extended for SoC vendor specific bindings. Such bindings 54should be documented as Documentation/devicetree/bindings/power/<vendor>-opp.txt 55and should have a compatible description like: "operating-points-v2-<vendor>". 56 57* OPP Table Node 58 59This describes the OPPs belonging to a device. This node can have following 60properties: 61 62Required properties: 63- compatible: Allow OPPs to express their compatibility. It should be: 64 "operating-points-v2". 65 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. 71 72Optional 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. 77 78- status: Marks the OPP table enabled/disabled. 79 80 81* OPP Node 82 83This defines voltage-current-frequency combinations along with other related 84properties. 85 86Required 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. 91 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. 96 97Optional properties: 98- opp-microvolt: voltage in micro Volts. 99 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. 103 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. 109 110 Entries for all regulators shall be of the same size, i.e. either all use a 111 single value or triplets. 112 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. 120 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. 125 126 Should only be set if opp-microvolt is set for the OPP. 127 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. 135 136- opp-microamp-<name>: Named opp-microamp property. Similar to 137 opp-microvolt-<name> property, but for microamp instead. 138 139- opp-level: A value representing the performance level of the device, 140 expressed as a 32-bit integer. 141 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. 147 148- clock-latency-ns: Specifies the maximum possible transition latency (in 149 nanoseconds) for switching to this OPP from any other OPP. 150 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. 155 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. 158 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). 162 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. 167 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 171 172 opp-supported-hw = <X1 Y1 Z1>, <X2 Y2 Z2>, <X3 Y3 Z3>. 173 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. 180 181- status: Marks the node enabled/disabled. 182 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). 190 191Example 1: Single cluster Dual-core ARM cortex A9, switch DVFS states together. 192 193/ { 194 cpus { 195 #address-cells = <1>; 196 #size-cells = <0>; 197 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 }; 207 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 }; 218 219 cpu0_opp_table: opp_table0 { 220 compatible = "operating-points-v2"; 221 opp-shared; 222 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}; 244 245Example 2: Single cluster, Quad-core Qualcom-krait, switches DVFS states 246independently. 247 248/ { 249 cpus { 250 #address-cells = <1>; 251 #size-cells = <0>; 252 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 }; 262 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 }; 272 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 }; 282 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 }; 293 294 cpu_opp_table: opp_table { 295 compatible = "operating-points-v2"; 296 297 /* 298 * Missing opp-shared property means CPUs switch DVFS states 299 * independently. 300 */ 301 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}; 324 325Example 3: Dual-cluster, Dual-core per cluster. CPUs within a cluster switch 326DVFS state together. 327 328/ { 329 cpus { 330 #address-cells = <1>; 331 #size-cells = <0>; 332 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 }; 342 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 }; 352 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 }; 362 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 }; 373 374 cluster0_opp: opp_table0 { 375 compatible = "operating-points-v2"; 376 opp-shared; 377 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 }; 399 400 cluster1_opp: opp_table1 { 401 compatible = "operating-points-v2"; 402 opp-shared; 403 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}; 426 427Example 4: Handling multiple regulators 428 429/ { 430 cpus { 431 cpu@0 { 432 compatible = "vendor,cpu-type"; 433 ... 434 435 vcc0-supply = <&cpu_supply0>; 436 vcc1-supply = <&cpu_supply1>; 437 vcc2-supply = <&cpu_supply2>; 438 operating-points-v2 = <&cpu0_opp_table>; 439 }; 440 }; 441 442 cpu0_opp_table: opp_table0 { 443 compatible = "operating-points-v2"; 444 opp-shared; 445 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 }; 456 457 /* OR */ 458 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 }; 469 470 /* OR */ 471 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}; 484 485Example 5: opp-supported-hw 486(example: three level hierarchy of versions: cuts, substrate and process) 487 488/ { 489 cpus { 490 cpu@0 { 491 compatible = "arm,cortex-a7"; 492 ... 493 494 cpu-supply = <&cpu_supply> 495 operating-points-v2 = <&cpu0_opp_table_slow>; 496 }; 497 }; 498 499 opp_table { 500 compatible = "operating-points-v2"; 501 opp-shared; 502 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 }; 512 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 }; 524 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}; 537 538Example 6: opp-microvolt-<name>, opp-microamp-<name>: 539(example: device with two possible microvolt ranges: slow and fast) 540 541/ { 542 cpus { 543 cpu@0 { 544 compatible = "arm,cortex-a7"; 545 ... 546 547 operating-points-v2 = <&cpu0_opp_table>; 548 }; 549 }; 550 551 cpu0_opp_table: opp_table0 { 552 compatible = "operating-points-v2"; 553 opp-shared; 554 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 }; 562 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}; 573 574Example 7: Single cluster Quad-core ARM cortex A53, OPP points from firmware, 575distinct clock controls but two sets of clock/voltage/current lines. 576 577/ { 578 cpus { 579 #address-cells = <2>; 580 #size-cells = <0>; 581 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 }; 610 611 }; 612 613 cpu_opp0_table: opp0_table { 614 compatible = "operating-points-v2"; 615 opp-shared; 616 }; 617 618 cpu_opp1_table: opp1_table { 619 compatible = "operating-points-v2"; 620 opp-shared; 621 }; 622}; 623