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 - status: Marks the node enabled/disabled.
 127
 128 Example 1: Single cluster Dual-core ARM cortex A9, switch DVFS states together.
 129
 130 / {
 131         cpus {
 132                 #address-cells = <1>;
 133                 #size-cells = <0>;
 134
 135                 cpu@0 {
 136                         compatible = "arm,cortex-a9";
 137                         reg = <0>;
 138                         next-level-cache = <&L2>;
 139                         clocks = <&clk_controller 0>;
 140                         clock-names = "cpu";
 141                         cpu-supply = <&cpu_supply0>;
 142                         operating-points-v2 = <&cpu0_opp_table>;
 143                 };
 144
 145                 cpu@1 {
 146                         compatible = "arm,cortex-a9";
 147                         reg = <1>;
 148                         next-level-cache = <&L2>;
 149                         clocks = <&clk_controller 0>;
 150                         clock-names = "cpu";
 151                         cpu-supply = <&cpu_supply0>;
 152                         operating-points-v2 = <&cpu0_opp_table>;
 153                 };
 154         };
 155
 156         cpu0_opp_table: opp_table0 {
 157                 compatible = "operating-points-v2";
 158                 opp-shared;
 159
 160                 opp00 {
 161                         opp-hz = /bits/ 64 <1000000000>;
 162                         opp-microvolt = <970000 975000 985000>;
 163                         opp-microamp = <70000>;
 164                         clock-latency-ns = <300000>;
 165                         opp-suspend;
 166                 };
 167                 opp01 {
 168                         opp-hz = /bits/ 64 <1100000000>;
 169                         opp-microvolt = <980000 1000000 1010000>;
 170                         opp-microamp = <80000>;
 171                         clock-latency-ns = <310000>;
 172                 };
 173                 opp02 {
 174                         opp-hz = /bits/ 64 <1200000000>;
 175                         opp-microvolt = <1025000>;
 176                         clock-latency-ns = <290000>;
 177                         turbo-mode;
 178                 };
 179         };
 180 };
 181
 182 Example 2: Single cluster, Quad-core Qualcom-krait, switches DVFS states
 183 independently.
 184
 185 / {
 186         cpus {
 187                 #address-cells = <1>;
 188                 #size-cells = <0>;
 189
 190                 cpu@0 {
 191                         compatible = "qcom,krait";
 192                         reg = <0>;
 193                         next-level-cache = <&L2>;
 194                         clocks = <&clk_controller 0>;
 195                         clock-names = "cpu";
 196                         cpu-supply = <&cpu_supply0>;
 197                         operating-points-v2 = <&cpu_opp_table>;
 198                 };
 199
 200                 cpu@1 {
 201                         compatible = "qcom,krait";
 202                         reg = <1>;
 203                         next-level-cache = <&L2>;
 204                         clocks = <&clk_controller 1>;
 205                         clock-names = "cpu";
 206                         cpu-supply = <&cpu_supply1>;
 207                         operating-points-v2 = <&cpu_opp_table>;
 208                 };
 209
 210                 cpu@2 {
 211                         compatible = "qcom,krait";
 212                         reg = <2>;
 213                         next-level-cache = <&L2>;
 214                         clocks = <&clk_controller 2>;
 215                         clock-names = "cpu";
 216                         cpu-supply = <&cpu_supply2>;
 217                         operating-points-v2 = <&cpu_opp_table>;
 218                 };
 219
 220                 cpu@3 {
 221                         compatible = "qcom,krait";
 222                         reg = <3>;
 223                         next-level-cache = <&L2>;
 224                         clocks = <&clk_controller 3>;
 225                         clock-names = "cpu";
 226                         cpu-supply = <&cpu_supply3>;
 227                         operating-points-v2 = <&cpu_opp_table>;
 228                 };
 229         };
 230
 231         cpu_opp_table: opp_table {
 232                 compatible = "operating-points-v2";
 233
 234                 /*
 235                  * Missing opp-shared property means CPUs switch DVFS states
 236                  * independently.
 237                  */
 238
 239                 opp00 {
 240                         opp-hz = /bits/ 64 <1000000000>;
 241                         opp-microvolt = <970000 975000 985000>;
 242                         opp-microamp = <70000>;
 243                         clock-latency-ns = <300000>;
 244                         opp-suspend;
 245                 };
 246                 opp01 {
 247                         opp-hz = /bits/ 64 <1100000000>;
 248                         opp-microvolt = <980000 1000000 1010000>;
 249                         opp-microamp = <80000>;
 250                         clock-latency-ns = <310000>;
 251                 };
 252                 opp02 {
 253                         opp-hz = /bits/ 64 <1200000000>;
 254                         opp-microvolt = <1025000>;
 255                         opp-microamp = <90000;
 256                         lock-latency-ns = <290000>;
 257                         turbo-mode;
 258                 };
 259         };
 260 };
 261
 262 Example 3: Dual-cluster, Dual-core per cluster. CPUs within a cluster switch
 263 DVFS state together.
 264
 265 / {
 266         cpus {
 267                 #address-cells = <1>;
 268                 #size-cells = <0>;
 269
 270                 cpu@0 {
 271                         compatible = "arm,cortex-a7";
 272                         reg = <0>;
 273                         next-level-cache = <&L2>;
 274                         clocks = <&clk_controller 0>;
 275                         clock-names = "cpu";
 276                         cpu-supply = <&cpu_supply0>;
 277                         operating-points-v2 = <&cluster0_opp>;
 278                 };
 279
 280                 cpu@1 {
 281                         compatible = "arm,cortex-a7";
 282                         reg = <1>;
 283                         next-level-cache = <&L2>;
 284                         clocks = <&clk_controller 0>;
 285                         clock-names = "cpu";
 286                         cpu-supply = <&cpu_supply0>;
 287                         operating-points-v2 = <&cluster0_opp>;
 288                 };
 289
 290                 cpu@100 {
 291                         compatible = "arm,cortex-a15";
 292                         reg = <100>;
 293                         next-level-cache = <&L2>;
 294                         clocks = <&clk_controller 1>;
 295                         clock-names = "cpu";
 296                         cpu-supply = <&cpu_supply1>;
 297                         operating-points-v2 = <&cluster1_opp>;
 298                 };
 299
 300                 cpu@101 {
 301                         compatible = "arm,cortex-a15";
 302                         reg = <101>;
 303                         next-level-cache = <&L2>;
 304                         clocks = <&clk_controller 1>;
 305                         clock-names = "cpu";
 306                         cpu-supply = <&cpu_supply1>;
 307                         operating-points-v2 = <&cluster1_opp>;
 308                 };
 309         };
 310
 311         cluster0_opp: opp_table0 {
 312                 compatible = "operating-points-v2";
 313                 opp-shared;
 314
 315                 opp00 {
 316                         opp-hz = /bits/ 64 <1000000000>;
 317                         opp-microvolt = <970000 975000 985000>;
 318                         opp-microamp = <70000>;
 319                         clock-latency-ns = <300000>;
 320                         opp-suspend;
 321                 };
 322                 opp01 {
 323                         opp-hz = /bits/ 64 <1100000000>;
 324                         opp-microvolt = <980000 1000000 1010000>;
 325                         opp-microamp = <80000>;
 326                         clock-latency-ns = <310000>;
 327                 };
 328                 opp02 {
 329                         opp-hz = /bits/ 64 <1200000000>;
 330                         opp-microvolt = <1025000>;
 331                         opp-microamp = <90000>;
 332                         clock-latency-ns = <290000>;
 333                         turbo-mode;
 334                 };
 335         };
 336
 337         cluster1_opp: opp_table1 {
 338                 compatible = "operating-points-v2";
 339                 opp-shared;
 340
 341                 opp10 {
 342                         opp-hz = /bits/ 64 <1300000000>;
 343                         opp-microvolt = <1045000 1050000 1055000>;
 344                         opp-microamp = <95000>;
 345                         clock-latency-ns = <400000>;
 346                         opp-suspend;
 347                 };
 348                 opp11 {
 349                         opp-hz = /bits/ 64 <1400000000>;
 350                         opp-microvolt = <1075000>;
 351                         opp-microamp = <100000>;
 352                         clock-latency-ns = <400000>;
 353                 };
 354                 opp12 {
 355                         opp-hz = /bits/ 64 <1500000000>;
 356                         opp-microvolt = <1010000 1100000 1110000>;
 357                         opp-microamp = <95000>;
 358                         clock-latency-ns = <400000>;
 359                         turbo-mode;
 360                 };
 361         };
 362 };
 363
 364 Example 4: Handling multiple regulators
 365
 366 / {
 367         cpus {
 368                 cpu@0 {
 369                         compatible = "arm,cortex-a7";
 370                         ...
 371
 372                         cpu-supply = <&cpu_supply0>, <&cpu_supply1>, <&cpu_supply2>;
 373                         operating-points-v2 = <&cpu0_opp_table>;
 374                 };
 375         };
 376
 377         cpu0_opp_table: opp_table0 {
 378                 compatible = "operating-points-v2";
 379                 opp-shared;
 380
 381                 opp00 {
 382                         opp-hz = /bits/ 64 <1000000000>;
 383                         opp-microvolt = <970000>, /* Supply 0 */
 384                                         <960000>, /* Supply 1 */
 385                                         <960000>; /* Supply 2 */
 386                         opp-microamp =  <70000>,  /* Supply 0 */
 387                                         <70000>,  /* Supply 1 */
 388                                         <70000>;  /* Supply 2 */
 389                         clock-latency-ns = <300000>;
 390                 };
 391
 392                 /* OR */
 393
 394                 opp00 {
 395                         opp-hz = /bits/ 64 <1000000000>;
 396                         opp-microvolt = <970000 975000 985000>, /* Supply 0 */
 397                                         <960000 965000 975000>, /* Supply 1 */
 398                                         <960000 965000 975000>; /* Supply 2 */
 399                         opp-microamp =  <70000>,                /* Supply 0 */
 400                                         <70000>,                /* Supply 1 */
 401                                         <70000>;                /* Supply 2 */
 402                         clock-latency-ns = <300000>;
 403                 };
 404
 405                 /* OR */
 406
 407                 opp00 {
 408                         opp-hz = /bits/ 64 <1000000000>;
 409                         opp-microvolt = <970000 975000 985000>, /* Supply 0 */
 410                                         <960000 965000 975000>, /* Supply 1 */
 411                                         <960000 965000 975000>; /* Supply 2 */
 412                         opp-microamp =  <70000>,                /* Supply 0 */
 413                                         <0>,                    /* Supply 1 doesn't need this */
 414                                         <70000>;                /* Supply 2 */
 415                         clock-latency-ns = <300000>;
 416                 };
 417         };
 418 };
 419
 420 Example 5: Multiple OPP tables
 421
 422 / {
 423         cpus {
 424                 cpu@0 {
 425                         compatible = "arm,cortex-a7";
 426                         ...
 427
 428                         cpu-supply = <&cpu_supply>
 429                         operating-points-v2 = <&cpu0_opp_table_slow>, <&cpu0_opp_table_fast>;
 430                         operating-points-names = "slow", "fast";
 431                 };
 432         };
 433
 434         cpu0_opp_table_slow: opp_table_slow {
 435                 compatible = "operating-points-v2";
 436                 status = "okay";
 437                 opp-shared;
 438
 439                 opp00 {
 440                         opp-hz = /bits/ 64 <600000000>;
 441                         ...
 442                 };
 443
 444                 opp01 {
 445                         opp-hz = /bits/ 64 <800000000>;
 446                         ...
 447                 };
 448         };
 449
 450         cpu0_opp_table_fast: opp_table_fast {
 451                 compatible = "operating-points-v2";
 452                 status = "okay";
 453                 opp-shared;
 454
 455                 opp10 {
 456                         opp-hz = /bits/ 64 <1000000000>;
 457                         ...
 458                 };
 459
 460                 opp11 {
 461                         opp-hz = /bits/ 64 <1100000000>;
 462                         ...
 463                 };
 464         };
 465 };