Documentation/devicetree/bindings/power/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
  72 * OPP Node
  73
  74 This defines voltage-current-frequency combinations along with other related
  75 properties.
  76
  77 Required properties:
  78 - opp-hz: Frequency in Hz
  79
  80 Optional properties:
  81 - opp-microvolt: voltage in micro Volts.
  82
  83   A single regulator's voltage is specified with an array of size one or three.
  84   Single entry is for target voltage and three entries are for <target min max>
  85   voltages.
  86
  87   Entries for multiple regulators must be present in the same order as
  88   regulators are specified in device's DT node.
  89
  90 - opp-microamp: The maximum current drawn by the device in microamperes
  91   considering system specific parameters (such as transients, process, aging,
  92   maximum operating temperature range etc.) as necessary. This may be used to
  93   set the most efficient regulator operating mode.
  94
  95   Should only be set if opp-microvolt is set for the OPP.
  96
  97   Entries for multiple regulators must be present in the same order as
  98   regulators are specified in device's DT node. If this property isn't required
  99   for few regulators, then this should be marked as zero for them. If it isn't
 100   required for any regulator, then this property need not be present.
 101
 102 - clock-latency-ns: Specifies the maximum possible transition latency (in
 103   nanoseconds) for switching to this OPP from any other OPP.
 104
 105 - turbo-mode: Marks the OPP to be used only for turbo modes. Turbo mode is
 106   available on some platforms, where the device can run over its operating
 107   frequency for a short duration of time limited by the device's power, current
 108   and thermal limits.
 109
 110 - status: Marks the node enabled/disabled.
 111
 112 Example 1: Single cluster Dual-core ARM cortex A9, switch DVFS states together.
 113
 114 / {
 115         cpus {
 116                 #address-cells = <1>;
 117                 #size-cells = <0>;
 118
 119                 cpu@0 {
 120                         compatible = "arm,cortex-a9";
 121                         reg = <0>;
 122                         next-level-cache = <&L2>;
 123                         clocks = <&clk_controller 0>;
 124                         clock-names = "cpu";
 125                         cpu-supply = <&cpu_supply0>;
 126                         operating-points-v2 = <&cpu0_opp_table>;
 127                 };
 128
 129                 cpu@1 {
 130                         compatible = "arm,cortex-a9";
 131                         reg = <1>;
 132                         next-level-cache = <&L2>;
 133                         clocks = <&clk_controller 0>;
 134                         clock-names = "cpu";
 135                         cpu-supply = <&cpu_supply0>;
 136                         operating-points-v2 = <&cpu0_opp_table>;
 137                 };
 138         };
 139
 140         cpu0_opp_table: opp_table0 {
 141                 compatible = "operating-points-v2";
 142                 opp-shared;
 143
 144                 opp00 {
 145                         opp-hz = <1000000000>;
 146                         opp-microvolt = <970000 975000 985000>;
 147                         opp-microamp = <70000>;
 148                         clock-latency-ns = <300000>;
 149                 };
 150                 opp01 {
 151                         opp-hz = <1100000000>;
 152                         opp-microvolt = <980000 1000000 1010000>;
 153                         opp-microamp = <80000>;
 154                         clock-latency-ns = <310000>;
 155                 };
 156                 opp02 {
 157                         opp-hz = <1200000000>;
 158                         opp-microvolt = <1025000>;
 159                         clock-latency-ns = <290000>;
 160                         turbo-mode;
 161                 };
 162         };
 163 };
 164
 165 Example 2: Single cluster, Quad-core Qualcom-krait, switches DVFS states
 166 independently.
 167
 168 / {
 169         cpus {
 170                 #address-cells = <1>;
 171                 #size-cells = <0>;
 172
 173                 cpu@0 {
 174                         compatible = "qcom,krait";
 175                         reg = <0>;
 176                         next-level-cache = <&L2>;
 177                         clocks = <&clk_controller 0>;
 178                         clock-names = "cpu";
 179                         cpu-supply = <&cpu_supply0>;
 180                         operating-points-v2 = <&cpu_opp_table>;
 181                 };
 182
 183                 cpu@1 {
 184                         compatible = "qcom,krait";
 185                         reg = <1>;
 186                         next-level-cache = <&L2>;
 187                         clocks = <&clk_controller 1>;
 188                         clock-names = "cpu";
 189                         cpu-supply = <&cpu_supply1>;
 190                         operating-points-v2 = <&cpu_opp_table>;
 191                 };
 192
 193                 cpu@2 {
 194                         compatible = "qcom,krait";
 195                         reg = <2>;
 196                         next-level-cache = <&L2>;
 197                         clocks = <&clk_controller 2>;
 198                         clock-names = "cpu";
 199                         cpu-supply = <&cpu_supply2>;
 200                         operating-points-v2 = <&cpu_opp_table>;
 201                 };
 202
 203                 cpu@3 {
 204                         compatible = "qcom,krait";
 205                         reg = <3>;
 206                         next-level-cache = <&L2>;
 207                         clocks = <&clk_controller 3>;
 208                         clock-names = "cpu";
 209                         cpu-supply = <&cpu_supply3>;
 210                         operating-points-v2 = <&cpu_opp_table>;
 211                 };
 212         };
 213
 214         cpu_opp_table: opp_table {
 215                 compatible = "operating-points-v2";
 216
 217                 /*
 218                  * Missing opp-shared property means CPUs switch DVFS states
 219                  * independently.
 220                  */
 221
 222                 opp00 {
 223                         opp-hz = <1000000000>;
 224                         opp-microvolt = <970000 975000 985000>;
 225                         opp-microamp = <70000>;
 226                         clock-latency-ns = <300000>;
 227                 };
 228                 opp01 {
 229                         opp-hz = <1100000000>;
 230                         opp-microvolt = <980000 1000000 1010000>;
 231                         opp-microamp = <80000>;
 232                         clock-latency-ns = <310000>;
 233                 };
 234                 opp02 {
 235                         opp-hz = <1200000000>;
 236                         opp-microvolt = <1025000>;
 237                         opp-microamp = <90000;
 238                         lock-latency-ns = <290000>;
 239                         turbo-mode;
 240                 };
 241         };
 242 };
 243
 244 Example 3: Dual-cluster, Dual-core per cluster. CPUs within a cluster switch
 245 DVFS state together.
 246
 247 / {
 248         cpus {
 249                 #address-cells = <1>;
 250                 #size-cells = <0>;
 251
 252                 cpu@0 {
 253                         compatible = "arm,cortex-a7";
 254                         reg = <0>;
 255                         next-level-cache = <&L2>;
 256                         clocks = <&clk_controller 0>;
 257                         clock-names = "cpu";
 258                         cpu-supply = <&cpu_supply0>;
 259                         operating-points-v2 = <&cluster0_opp>;
 260                 };
 261
 262                 cpu@1 {
 263                         compatible = "arm,cortex-a7";
 264                         reg = <1>;
 265                         next-level-cache = <&L2>;
 266                         clocks = <&clk_controller 0>;
 267                         clock-names = "cpu";
 268                         cpu-supply = <&cpu_supply0>;
 269                         operating-points-v2 = <&cluster0_opp>;
 270                 };
 271
 272                 cpu@100 {
 273                         compatible = "arm,cortex-a15";
 274                         reg = <100>;
 275                         next-level-cache = <&L2>;
 276                         clocks = <&clk_controller 1>;
 277                         clock-names = "cpu";
 278                         cpu-supply = <&cpu_supply1>;
 279                         operating-points-v2 = <&cluster1_opp>;
 280                 };
 281
 282                 cpu@101 {
 283                         compatible = "arm,cortex-a15";
 284                         reg = <101>;
 285                         next-level-cache = <&L2>;
 286                         clocks = <&clk_controller 1>;
 287                         clock-names = "cpu";
 288                         cpu-supply = <&cpu_supply1>;
 289                         operating-points-v2 = <&cluster1_opp>;
 290                 };
 291         };
 292
 293         cluster0_opp: opp_table0 {
 294                 compatible = "operating-points-v2";
 295                 opp-shared;
 296
 297                 opp00 {
 298                         opp-hz = <1000000000>;
 299                         opp-microvolt = <970000 975000 985000>;
 300                         opp-microamp = <70000>;
 301                         clock-latency-ns = <300000>;
 302                 };
 303                 opp01 {
 304                         opp-hz = <1100000000>;
 305                         opp-microvolt = <980000 1000000 1010000>;
 306                         opp-microamp = <80000>;
 307                         clock-latency-ns = <310000>;
 308                 };
 309                 opp02 {
 310                         opp-hz = <1200000000>;
 311                         opp-microvolt = <1025000>;
 312                         opp-microamp = <90000>;
 313                         clock-latency-ns = <290000>;
 314                         turbo-mode;
 315                 };
 316         };
 317
 318         cluster1_opp: opp_table1 {
 319                 compatible = "operating-points-v2";
 320                 opp-shared;
 321
 322                 opp10 {
 323                         opp-hz = <1300000000>;
 324                         opp-microvolt = <1045000 1050000 1055000>;
 325                         opp-microamp = <95000>;
 326                         clock-latency-ns = <400000>;
 327                 };
 328                 opp11 {
 329                         opp-hz = <1400000000>;
 330                         opp-microvolt = <1075000>;
 331                         opp-microamp = <100000>;
 332                         clock-latency-ns = <400000>;
 333                 };
 334                 opp12 {
 335                         opp-hz = <1500000000>;
 336                         opp-microvolt = <1010000 1100000 1110000>;
 337                         opp-microamp = <95000>;
 338                         clock-latency-ns = <400000>;
 339                         turbo-mode;
 340                 };
 341         };
 342 };
 343
 344 Example 4: Handling multiple regulators
 345
 346 / {
 347         cpus {
 348                 cpu@0 {
 349                         compatible = "arm,cortex-a7";
 350                         ...
 351
 352                         cpu-supply = <&cpu_supply0>, <&cpu_supply1>, <&cpu_supply2>;
 353                         operating-points-v2 = <&cpu0_opp_table>;
 354                 };
 355         };
 356
 357         cpu0_opp_table: opp_table0 {
 358                 compatible = "operating-points-v2";
 359                 opp-shared;
 360
 361                 opp00 {
 362                         opp-hz = <1000000000>;
 363                         opp-microvolt = <970000>, /* Supply 0 */
 364                                         <960000>, /* Supply 1 */
 365                                         <960000>; /* Supply 2 */
 366                         opp-microamp =  <70000>,  /* Supply 0 */
 367                                         <70000>,  /* Supply 1 */
 368                                         <70000>;  /* Supply 2 */
 369                         clock-latency-ns = <300000>;
 370                 };
 371
 372                 /* OR */
 373
 374                 opp00 {
 375                         opp-hz = <1000000000>;
 376                         opp-microvolt = <970000 975000 985000>, /* Supply 0 */
 377                                         <960000 965000 975000>, /* Supply 1 */
 378                                         <960000 965000 975000>; /* Supply 2 */
 379                         opp-microamp =  <70000>,                /* Supply 0 */
 380                                         <70000>,                /* Supply 1 */
 381                                         <70000>;                /* Supply 2 */
 382                         clock-latency-ns = <300000>;
 383                 };
 384
 385                 /* OR */
 386
 387                 opp00 {
 388                         opp-hz = <1000000000>;
 389                         opp-microvolt = <970000 975000 985000>, /* Supply 0 */
 390                                         <960000 965000 975000>, /* Supply 1 */
 391                                         <960000 965000 975000>; /* Supply 2 */
 392                         opp-microamp =  <70000>,                /* Supply 0 */
 393                                         <0>,                    /* Supply 1 doesn't need this */
 394                                         <70000>;                /* Supply 2 */
 395                         clock-latency-ns = <300000>;
 396                 };
 397         };
 398 };