1==========================================
2ARM CPUs capacity bindings
3==========================================
4
5==========================================
61 - Introduction
7==========================================
8
9ARM systems may be configured to have cpus with different power/performance
10characteristics within the same chip. In this case, additional information has
11to be made available to the kernel for it to be aware of such differences and
12take decisions accordingly.
13
14==========================================
152 - CPU capacity definition
16==========================================
17
18CPU capacity is a number that provides the scheduler information about CPUs
19heterogeneity. Such heterogeneity can come from micro-architectural differences
20(e.g., ARM big.LITTLE systems) or maximum frequency at which CPUs can run
21(e.g., SMP systems with multiple frequency domains). Heterogeneity in this
22context is about differing performance characteristics; this binding tries to
23capture a first-order approximation of the relative performance of CPUs.
24
25CPU capacities are obtained by running a suitable benchmark. This binding makes
26no guarantees on the validity or suitability of any particular benchmark, the
27final capacity should, however, be:
28
29* A "single-threaded" or CPU affine benchmark
30* Divided by the running frequency of the CPU executing the benchmark
31* Not subject to dynamic frequency scaling of the CPU
32
33For the time being we however advise usage of the Dhrystone benchmark. What
34above thus becomes:
35
36CPU capacities are obtained by running the Dhrystone benchmark on each CPU at
37max frequency (with caches enabled). The obtained DMIPS score is then divided
38by the frequency (in MHz) at which the benchmark has been run, so that
39DMIPS/MHz are obtained.  Such values are then normalized w.r.t. the highest
40score obtained in the system.
41
42==========================================
433 - capacity-dmips-mhz
44==========================================
45
46capacity-dmips-mhz is an optional cpu node [1] property: u32 value
47representing CPU capacity expressed in normalized DMIPS/MHz. At boot time, the
48maximum frequency available to the cpu is then used to calculate the capacity
49value internally used by the kernel.
50
51capacity-dmips-mhz property is all-or-nothing: if it is specified for a cpu
52node, it has to be specified for every other cpu nodes, or the system will
53fall back to the default capacity value for every CPU. If cpufreq is not
54available, final capacities are calculated by directly using capacity-dmips-
55mhz values (normalized w.r.t. the highest value found while parsing the DT).
56
57===========================================
584 - Examples
59===========================================
60
61Example 1 (ARM 64-bit, 6-cpu system, two clusters):
62capacities-dmips-mhz are scaled w.r.t. 1024 (cpu@0 and cpu@1)
63supposing cluster0@max-freq=1100 and custer1@max-freq=850,
64final capacities are 1024 for cluster0 and 446 for cluster1
65
66cpus {
67	#address-cells = <2>;
68	#size-cells = <0>;
69
70	cpu-map {
71		cluster0 {
72			core0 {
73				cpu = <&A57_0>;
74			};
75			core1 {
76				cpu = <&A57_1>;
77			};
78		};
79
80		cluster1 {
81			core0 {
82				cpu = <&A53_0>;
83			};
84			core1 {
85				cpu = <&A53_1>;
86			};
87			core2 {
88				cpu = <&A53_2>;
89			};
90			core3 {
91				cpu = <&A53_3>;
92			};
93		};
94	};
95
96	idle-states {
97		entry-method = "psci";
98
99		CPU_SLEEP_0: cpu-sleep-0 {
100			compatible = "arm,idle-state";
101			arm,psci-suspend-param = <0x0010000>;
102			local-timer-stop;
103			entry-latency-us = <100>;
104			exit-latency-us = <250>;
105			min-residency-us = <150>;
106		};
107
108		CLUSTER_SLEEP_0: cluster-sleep-0 {
109			compatible = "arm,idle-state";
110			arm,psci-suspend-param = <0x1010000>;
111			local-timer-stop;
112			entry-latency-us = <800>;
113			exit-latency-us = <700>;
114			min-residency-us = <2500>;
115		};
116	};
117
118	A57_0: cpu@0 {
119		compatible = "arm,cortex-a57","arm,armv8";
120		reg = <0x0 0x0>;
121		device_type = "cpu";
122		enable-method = "psci";
123		next-level-cache = <&A57_L2>;
124		clocks = <&scpi_dvfs 0>;
125		cpu-idle-states = <&CPU_SLEEP_0 &CLUSTER_SLEEP_0>;
126		capacity-dmips-mhz = <1024>;
127	};
128
129	A57_1: cpu@1 {
130		compatible = "arm,cortex-a57","arm,armv8";
131		reg = <0x0 0x1>;
132		device_type = "cpu";
133		enable-method = "psci";
134		next-level-cache = <&A57_L2>;
135		clocks = <&scpi_dvfs 0>;
136		cpu-idle-states = <&CPU_SLEEP_0 &CLUSTER_SLEEP_0>;
137		capacity-dmips-mhz = <1024>;
138	};
139
140	A53_0: cpu@100 {
141		compatible = "arm,cortex-a53","arm,armv8";
142		reg = <0x0 0x100>;
143		device_type = "cpu";
144		enable-method = "psci";
145		next-level-cache = <&A53_L2>;
146		clocks = <&scpi_dvfs 1>;
147		cpu-idle-states = <&CPU_SLEEP_0 &CLUSTER_SLEEP_0>;
148		capacity-dmips-mhz = <578>;
149	};
150
151	A53_1: cpu@101 {
152		compatible = "arm,cortex-a53","arm,armv8";
153		reg = <0x0 0x101>;
154		device_type = "cpu";
155		enable-method = "psci";
156		next-level-cache = <&A53_L2>;
157		clocks = <&scpi_dvfs 1>;
158		cpu-idle-states = <&CPU_SLEEP_0 &CLUSTER_SLEEP_0>;
159		capacity-dmips-mhz = <578>;
160	};
161
162	A53_2: cpu@102 {
163		compatible = "arm,cortex-a53","arm,armv8";
164		reg = <0x0 0x102>;
165		device_type = "cpu";
166		enable-method = "psci";
167		next-level-cache = <&A53_L2>;
168		clocks = <&scpi_dvfs 1>;
169		cpu-idle-states = <&CPU_SLEEP_0 &CLUSTER_SLEEP_0>;
170		capacity-dmips-mhz = <578>;
171	};
172
173	A53_3: cpu@103 {
174		compatible = "arm,cortex-a53","arm,armv8";
175		reg = <0x0 0x103>;
176		device_type = "cpu";
177		enable-method = "psci";
178		next-level-cache = <&A53_L2>;
179		clocks = <&scpi_dvfs 1>;
180		cpu-idle-states = <&CPU_SLEEP_0 &CLUSTER_SLEEP_0>;
181		capacity-dmips-mhz = <578>;
182	};
183
184	A57_L2: l2-cache0 {
185		compatible = "cache";
186	};
187
188	A53_L2: l2-cache1 {
189		compatible = "cache";
190	};
191};
192
193Example 2 (ARM 32-bit, 4-cpu system, two clusters,
194	   cpus 0,1@1GHz, cpus 2,3@500MHz):
195capacities-dmips-mhz are scaled w.r.t. 2 (cpu@0 and cpu@1), this means that first
196cpu@0 and cpu@1 are twice fast than cpu@2 and cpu@3 (at the same frequency)
197
198cpus {
199	#address-cells = <1>;
200	#size-cells = <0>;
201
202	cpu0: cpu@0 {
203		device_type = "cpu";
204		compatible = "arm,cortex-a15";
205		reg = <0>;
206		capacity-dmips-mhz = <2>;
207	};
208
209	cpu1: cpu@1 {
210		device_type = "cpu";
211		compatible = "arm,cortex-a15";
212		reg = <1>;
213		capacity-dmips-mhz = <2>;
214	};
215
216	cpu2: cpu@2 {
217		device_type = "cpu";
218		compatible = "arm,cortex-a15";
219		reg = <0x100>;
220		capacity-dmips-mhz = <1>;
221	};
222
223	cpu3: cpu@3 {
224		device_type = "cpu";
225		compatible = "arm,cortex-a15";
226		reg = <0x101>;
227		capacity-dmips-mhz = <1>;
228	};
229};
230
231===========================================
2325 - References
233===========================================
234
235[1] ARM Linux Kernel documentation - CPUs bindings
236    Documentation/devicetree/bindings/arm/cpus.txt
237