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