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