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