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