Documentation/devicetree/bindings/opp/opp.txt

   1 Generic OPP (Operating Performance Points) Bindings
   2 ----------------------------------------------------
   3
   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.
   9
  10 This document contain multiple versions of OPP binding and only one of them
  11 should be used per device.
  12
  13 Binding 1: operating-points
  14 ============================
  15
  16 This binding only supports voltage-frequency pairs.
  17
  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
  23
  24 Examples:
  25
  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 };
  37
  38
  39 Binding 2: operating-points-v2
  40 ============================
  41
  42 * Property: operating-points-v2
  43
  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.
  47
  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.
  52
  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>".
  56
  57 * OPP Table Node
  58
  59 This describes the OPPs belonging to a device. This node can have following
  60 properties:
  61
  62 Required 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
  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.
  77
  78 - status: Marks the OPP table enabled/disabled.
  79
  80
  81 * OPP Node
  82
  83 This defines voltage-current-frequency combinations along with other related
  84 properties.
  85
  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.
  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
  97 Optional 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
 191 Example 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
 245 Example 2: Single cluster, Quad-core Qualcom-krait, switches DVFS states
 246 independently.
 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
 325 Example 3: Dual-cluster, Dual-core per cluster. CPUs within a cluster switch
 326 DVFS 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
 427 Example 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
 485 Example 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
 538 Example 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
 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.
 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 };