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