GNU Linux-libre 4.14.266-gnu1
[releases.git] / 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                 opp-shared;
468
469                 opp-600000000 {
470                         /*
471                          * Supports all substrate and process versions for 0xF
472                          * cuts, i.e. only first four cuts.
473                          */
474                         opp-supported-hw = <0xF 0xFFFFFFFF 0xFFFFFFFF>
475                         opp-hz = /bits/ 64 <600000000>;
476                         opp-microvolt = <915000 900000 925000>;
477                         ...
478                 };
479
480                 opp-800000000 {
481                         /*
482                          * Supports:
483                          * - cuts: only one, 6th cut (represented by 6th bit).
484                          * - substrate: supports 16 different substrate versions
485                          * - process: supports 9 different process versions
486                          */
487                         opp-supported-hw = <0x20 0xff0000ff 0x0000f4f0>
488                         opp-hz = /bits/ 64 <800000000>;
489                         opp-microvolt = <915000 900000 925000>;
490                         ...
491                 };
492         };
493 };
494
495 Example 6: opp-microvolt-<name>, opp-microamp-<name>:
496 (example: device with two possible microvolt ranges: slow and fast)
497
498 / {
499         cpus {
500                 cpu@0 {
501                         compatible = "arm,cortex-a7";
502                         ...
503
504                         operating-points-v2 = <&cpu0_opp_table>;
505                 };
506         };
507
508         cpu0_opp_table: opp_table0 {
509                 compatible = "operating-points-v2";
510                 opp-shared;
511
512                 opp-1000000000 {
513                         opp-hz = /bits/ 64 <1000000000>;
514                         opp-microvolt-slow = <915000 900000 925000>;
515                         opp-microvolt-fast = <975000 970000 985000>;
516                         opp-microamp-slow =  <70000>;
517                         opp-microamp-fast =  <71000>;
518                 };
519
520                 opp-1200000000 {
521                         opp-hz = /bits/ 64 <1200000000>;
522                         opp-microvolt-slow = <915000 900000 925000>, /* Supply vcc0 */
523                                               <925000 910000 935000>; /* Supply vcc1 */
524                         opp-microvolt-fast = <975000 970000 985000>, /* Supply vcc0 */
525                                              <965000 960000 975000>; /* Supply vcc1 */
526                         opp-microamp =  <70000>; /* Will be used for both slow/fast */
527                 };
528         };
529 };