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 Devices may want to choose OPP tables at runtime and so can provide a list of
  49 phandles here. But only *one* of them should be chosen at runtime. This must be
  50 accompanied by a corresponding "operating-points-names" property, to uniquely
  51 identify the OPP tables.
  52
  53 If required, this can be extended for SoC vendor specfic 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 Optional properties:
  58 - operating-points-names: Names of OPP tables (required if multiple OPP
  59   tables are present), to uniquely identify them. The same list must be present
  60   for all the CPUs which are sharing clock/voltage rails and hence the OPP
  61   tables.
  62
  63 * OPP Table Node
  64
  65 This describes the OPPs belonging to a device. This node can have following
  66 properties:
  67
  68 Required properties:
  69 - compatible: Allow OPPs to express their compatibility. It should be:
  70   "operating-points-v2".
  71
  72 - OPP nodes: One or more OPP nodes describing voltage-current-frequency
  73   combinations. Their name isn't significant but their phandle can be used to
  74   reference an OPP.
  75
  76 Optional properties:
  77 - opp-shared: Indicates that device nodes using this OPP Table Node's phandle
  78   switch their DVFS state together, i.e. they share clock/voltage/current lines.
  79   Missing property means devices have independent clock/voltage/current lines,
  80   but they share OPP tables.
  81
  82 - status: Marks the OPP table enabled/disabled.
  83
  84
  85 * OPP Node
  86
  87 This defines voltage-current-frequency combinations along with other related
  88 properties.
  89
  90 Required properties:
  91 - opp-hz: Frequency in Hz, expressed as a 64-bit big-endian integer.
  92
  93 Optional properties:
  94 - opp-microvolt: voltage in micro Volts.
  95
  96   A single regulator's voltage is specified with an array of size one or three.
  97   Single entry is for target voltage and three entries are for <target min max>
  98   voltages.
  99
 100   Entries for multiple regulators must be present in the same order as
 101   regulators are specified in device's DT node.
 102
 103 - opp-microamp: The maximum current drawn by the device in microamperes
 104   considering system specific parameters (such as transients, process, aging,
 105   maximum operating temperature range etc.) as necessary. This may be used to
 106   set the most efficient regulator operating mode.
 107
 108   Should only be set if opp-microvolt is set for the OPP.
 109
 110   Entries for multiple regulators must be present in the same order as
 111   regulators are specified in device's DT node. If this property isn't required
 112   for few regulators, then this should be marked as zero for them. If it isn't
 113   required for any regulator, then this property need not be present.
 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                 opp00 {
 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                 opp01 {
 188                         opp-hz = /bits/ 64 <1100000000>;
 189                         opp-microvolt = <980000 1000000 1010000>;
 190                         opp-microamp = <80000>;
 191                         clock-latency-ns = <310000>;
 192                 };
 193                 opp02 {
 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                 opp00 {
 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                 opp01 {
 267                         opp-hz = /bits/ 64 <1100000000>;
 268                         opp-microvolt = <980000 1000000 1010000>;
 269                         opp-microamp = <80000>;
 270                         clock-latency-ns = <310000>;
 271                 };
 272                 opp02 {
 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                 opp00 {
 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                 opp01 {
 343                         opp-hz = /bits/ 64 <1100000000>;
 344                         opp-microvolt = <980000 1000000 1010000>;
 345                         opp-microamp = <80000>;
 346                         clock-latency-ns = <310000>;
 347                 };
 348                 opp02 {
 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                 opp10 {
 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                 opp11 {
 369                         opp-hz = /bits/ 64 <1400000000>;
 370                         opp-microvolt = <1075000>;
 371                         opp-microamp = <100000>;
 372                         clock-latency-ns = <400000>;
 373                 };
 374                 opp12 {
 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                 opp00 {
 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                 opp00 {
 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                 opp00 {
 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: Multiple OPP tables
 441
 442 / {
 443         cpus {
 444                 cpu@0 {
 445                         compatible = "arm,cortex-a7";
 446                         ...
 447
 448                         cpu-supply = <&cpu_supply>
 449                         operating-points-v2 = <&cpu0_opp_table_slow>, <&cpu0_opp_table_fast>;
 450                         operating-points-names = "slow", "fast";
 451                 };
 452         };
 453
 454         cpu0_opp_table_slow: opp_table_slow {
 455                 compatible = "operating-points-v2";
 456                 status = "okay";
 457                 opp-shared;
 458
 459                 opp00 {
 460                         opp-hz = /bits/ 64 <600000000>;
 461                         ...
 462                 };
 463
 464                 opp01 {
 465                         opp-hz = /bits/ 64 <800000000>;
 466                         ...
 467                 };
 468         };
 469
 470         cpu0_opp_table_fast: opp_table_fast {
 471                 compatible = "operating-points-v2";
 472                 status = "okay";
 473                 opp-shared;
 474
 475                 opp10 {
 476                         opp-hz = /bits/ 64 <1000000000>;
 477                         ...
 478                 };
 479
 480                 opp11 {
 481                         opp-hz = /bits/ 64 <1100000000>;
 482                         ...
 483                 };
 484         };
 485 };
 486
 487 Example 6: opp-supported-hw
 488 (example: three level hierarchy of versions: cuts, substrate and process)
 489
 490 / {
 491         cpus {
 492                 cpu@0 {
 493                         compatible = "arm,cortex-a7";
 494                         ...
 495
 496                         cpu-supply = <&cpu_supply>
 497                         operating-points-v2 = <&cpu0_opp_table_slow>;
 498                 };
 499         };
 500
 501         opp_table {
 502                 compatible = "operating-points-v2";
 503                 status = "okay";
 504                 opp-shared;
 505
 506                 opp00 {
 507                         /*
 508                          * Supports all substrate and process versions for 0xF
 509                          * cuts, i.e. only first four cuts.
 510                          */
 511                         opp-supported-hw = <0xF 0xFFFFFFFF 0xFFFFFFFF>
 512                         opp-hz = /bits/ 64 <600000000>;
 513                         opp-microvolt = <900000 915000 925000>;
 514                         ...
 515                 };
 516
 517                 opp01 {
 518                         /*
 519                          * Supports:
 520                          * - cuts: only one, 6th cut (represented by 6th bit).
 521                          * - substrate: supports 16 different substrate versions
 522                          * - process: supports 9 different process versions
 523                          */
 524                         opp-supported-hw = <0x20 0xff0000ff 0x0000f4f0>
 525                         opp-hz = /bits/ 64 <800000000>;
 526                         opp-microvolt = <900000 915000 925000>;
 527                         ...
 528                 };
 529         };
 530 };