1Generic OPP (Operating Performance Points) Bindings
2----------------------------------------------------
3
4Devices work at voltage-current-frequency combinations and some implementations
5have the liberty of choosing these. These combinations are called Operating
6Performance Points aka OPPs. This document defines bindings for these OPPs
7applicable across wide range of devices. For illustration purpose, this document
8uses CPU as a device.
9
10This document contain multiple versions of OPP binding and only one of them
11should be used per device.
12
13Binding 1: operating-points
14============================
15
16This binding only supports voltage-frequency pairs.
17
18Properties:
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
24Examples:
25
26cpu@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
39Binding 2: operating-points-v2
40============================
41
42* Property: operating-points-v2
43
44Devices supporting OPPs must set their "operating-points-v2" property with
45phandle to a OPP table in their DT node. The OPP core will use this phandle to
46find the operating points for the device.
47
48Devices may want to choose OPP tables at runtime and so can provide a list of
49phandles here. But only *one* of them should be chosen at runtime. This must be
50accompanied by a corresponding "operating-points-names" property, to uniquely
51identify the OPP tables.
52
53If required, this can be extended for SoC vendor specfic bindings. Such bindings
54should be documented as Documentation/devicetree/bindings/power/<vendor>-opp.txt
55and should have a compatible description like: "operating-points-v2-<vendor>".
56
57Optional 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
65This describes the OPPs belonging to a device. This node can have following
66properties:
67
68Required 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
76Optional 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
87This defines voltage-current-frequency combinations along with other related
88properties.
89
90Required properties:
91- opp-hz: Frequency in Hz, expressed as a 64-bit big-endian integer.
92
93Optional 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
128Example 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
182Example 2: Single cluster, Quad-core Qualcom-krait, switches DVFS states
183independently.
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
262Example 3: Dual-cluster, Dual-core per cluster. CPUs within a cluster switch
263DVFS 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
364Example 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
420Example 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};
466