[mirror_ubuntu-eoan-kernel.git] / Documentation / devicetree / bindings / arm / cpu-capacity.txt

==========================================
ARM CPUs capacity bindings
==========================================

==========================================
1 - Introduction
==========================================

ARM systems may be configured to have cpus with different power/performance
characteristics within the same chip. In this case, additional information has
to be made available to the kernel for it to be aware of such differences and
take decisions accordingly.

==========================================
2 - CPU capacity definition
==========================================

CPU capacity is a number that provides the scheduler information about CPUs
heterogeneity. Such heterogeneity can come from micro-architectural differences
(e.g., ARM big.LITTLE systems) or maximum frequency at which CPUs can run
(e.g., SMP systems with multiple frequency domains). Heterogeneity in this
context is about differing performance characteristics; this binding tries to
capture a first-order approximation of the relative performance of CPUs.

CPU capacities are obtained by running a suitable benchmark. This binding makes
no guarantees on the validity or suitability of any particular benchmark, the
final capacity should, however, be:

* A "single-threaded" or CPU affine benchmark
* Divided by the running frequency of the CPU executing the benchmark
* Not subject to dynamic frequency scaling of the CPU

For the time being we however advise usage of the Dhrystone benchmark. What
above thus becomes:

CPU capacities are obtained by running the Dhrystone benchmark on each CPU at
max frequency (with caches enabled). The obtained DMIPS score is then divided
by the frequency (in MHz) at which the benchmark has been run, so that
DMIPS/MHz are obtained.  Such values are then normalized w.r.t. the highest
score obtained in the system.

==========================================
3 - capacity-dmips-mhz
==========================================

capacity-dmips-mhz is an optional cpu node [1] property: u32 value
representing CPU capacity expressed in normalized DMIPS/MHz. At boot time, the
maximum frequency available to the cpu is then used to calculate the capacity
value internally used by the kernel.

capacity-dmips-mhz property is all-or-nothing: if it is specified for a cpu
node, it has to be specified for every other cpu nodes, or the system will
fall back to the default capacity value for every CPU. If cpufreq is not
available, final capacities are calculated by directly using capacity-dmips-
mhz values (normalized w.r.t. the highest value found while parsing the DT).

===========================================
4 - Examples
===========================================

Example 1 (ARM 64-bit, 6-cpu system, two clusters):
capacities-dmips-mhz are scaled w.r.t. 1024 (cpu@0 and cpu@1)
supposing cluster0@max-freq=1100 and custer1@max-freq=850,
final capacities are 1024 for cluster0 and 446 for cluster1

cpus {
	#address-cells = <2>;
	#size-cells = <0>;

	cpu-map {
		cluster0 {
			core0 {
				cpu = <&A57_0>;
			};
			core1 {
				cpu = <&A57_1>;
			};
		};

		cluster1 {
			core0 {
				cpu = <&A53_0>;
			};
			core1 {
				cpu = <&A53_1>;
			};
			core2 {
				cpu = <&A53_2>;
			};
			core3 {
				cpu = <&A53_3>;
			};
		};
	};

	idle-states {
		entry-method = "psci";

		CPU_SLEEP_0: cpu-sleep-0 {
			compatible = "arm,idle-state";
			arm,psci-suspend-param = <0x0010000>;
			local-timer-stop;
			entry-latency-us = <100>;
			exit-latency-us = <250>;
			min-residency-us = <150>;
		};

		CLUSTER_SLEEP_0: cluster-sleep-0 {
			compatible = "arm,idle-state";
			arm,psci-suspend-param = <0x1010000>;
			local-timer-stop;
			entry-latency-us = <800>;
			exit-latency-us = <700>;
			min-residency-us = <2500>;
		};
	};

	A57_0: cpu@0 {
		compatible = "arm,cortex-a57","arm,armv8";
		reg = <0x0 0x0>;
		device_type = "cpu";
		enable-method = "psci";
		next-level-cache = <&A57_L2>;
		clocks = <&scpi_dvfs 0>;
		cpu-idle-states = <&CPU_SLEEP_0 &CLUSTER_SLEEP_0>;
		capacity-dmips-mhz = <1024>;
	};

	A57_1: cpu@1 {
		compatible = "arm,cortex-a57","arm,armv8";
		reg = <0x0 0x1>;
		device_type = "cpu";
		enable-method = "psci";
		next-level-cache = <&A57_L2>;
		clocks = <&scpi_dvfs 0>;
		cpu-idle-states = <&CPU_SLEEP_0 &CLUSTER_SLEEP_0>;
		capacity-dmips-mhz = <1024>;
	};

	A53_0: cpu@100 {
		compatible = "arm,cortex-a53","arm,armv8";
		reg = <0x0 0x100>;
		device_type = "cpu";
		enable-method = "psci";
		next-level-cache = <&A53_L2>;
		clocks = <&scpi_dvfs 1>;
		cpu-idle-states = <&CPU_SLEEP_0 &CLUSTER_SLEEP_0>;
		capacity-dmips-mhz = <578>;
	};

	A53_1: cpu@101 {
		compatible = "arm,cortex-a53","arm,armv8";
		reg = <0x0 0x101>;
		device_type = "cpu";
		enable-method = "psci";
		next-level-cache = <&A53_L2>;
		clocks = <&scpi_dvfs 1>;
		cpu-idle-states = <&CPU_SLEEP_0 &CLUSTER_SLEEP_0>;
		capacity-dmips-mhz = <578>;
	};

	A53_2: cpu@102 {
		compatible = "arm,cortex-a53","arm,armv8";
		reg = <0x0 0x102>;
		device_type = "cpu";
		enable-method = "psci";
		next-level-cache = <&A53_L2>;
		clocks = <&scpi_dvfs 1>;
		cpu-idle-states = <&CPU_SLEEP_0 &CLUSTER_SLEEP_0>;
		capacity-dmips-mhz = <578>;
	};

	A53_3: cpu@103 {
		compatible = "arm,cortex-a53","arm,armv8";
		reg = <0x0 0x103>;
		device_type = "cpu";
		enable-method = "psci";
		next-level-cache = <&A53_L2>;
		clocks = <&scpi_dvfs 1>;
		cpu-idle-states = <&CPU_SLEEP_0 &CLUSTER_SLEEP_0>;
		capacity-dmips-mhz = <578>;
	};

	A57_L2: l2-cache0 {
		compatible = "cache";
	};

	A53_L2: l2-cache1 {
		compatible = "cache";
	};
};

Example 2 (ARM 32-bit, 4-cpu system, two clusters,
	   cpus 0,1@1GHz, cpus 2,3@500MHz):
capacities-dmips-mhz are scaled w.r.t. 2 (cpu@0 and cpu@1), this means that first
cpu@0 and cpu@1 are twice fast than cpu@2 and cpu@3 (at the same frequency)

cpus {
	#address-cells = <1>;
	#size-cells = <0>;

	cpu0: cpu@0 {
		device_type = "cpu";
		compatible = "arm,cortex-a15";
		reg = <0>;
		capacity-dmips-mhz = <2>;
	};

	cpu1: cpu@1 {
		device_type = "cpu";
		compatible = "arm,cortex-a15";
		reg = <1>;
		capacity-dmips-mhz = <2>;
	};

	cpu2: cpu@2 {
		device_type = "cpu";
		compatible = "arm,cortex-a15";
		reg = <0x100>;
		capacity-dmips-mhz = <1>;
	};

	cpu3: cpu@3 {
		device_type = "cpu";
		compatible = "arm,cortex-a15";
		reg = <0x101>;
		capacity-dmips-mhz = <1>;
	};
};

===========================================
5 - References
===========================================

[1] ARM Linux Kernel documentation - CPUs bindings
    Documentation/devicetree/bindings/arm/cpus.txt
Commit	Line	Data
de42fe11 JL	1	==========================================
	2	ARM CPUs capacity bindings
	3	==========================================
	4
	5	==========================================
	6	1 - Introduction
	7	==========================================
	8
	9	ARM systems may be configured to have cpus with different power/performance
	10	characteristics within the same chip. In this case, additional information has
	11	to be made available to the kernel for it to be aware of such differences and
	12	take decisions accordingly.
	13
	14	==========================================
	15	2 - CPU capacity definition
	16	==========================================
	17
	18	CPU capacity is a number that provides the scheduler information about CPUs
	19	heterogeneity. 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
	22	context is about differing performance characteristics; this binding tries to
	23	capture a first-order approximation of the relative performance of CPUs.
	24
	25	CPU capacities are obtained by running a suitable benchmark. This binding makes
	26	no guarantees on the validity or suitability of any particular benchmark, the
	27	final 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
	33	For the time being we however advise usage of the Dhrystone benchmark. What
	34	above thus becomes:
	35
	36	CPU capacities are obtained by running the Dhrystone benchmark on each CPU at
	37	max frequency (with caches enabled). The obtained DMIPS score is then divided
	38	by the frequency (in MHz) at which the benchmark has been run, so that
	39	DMIPS/MHz are obtained. Such values are then normalized w.r.t. the highest
	40	score obtained in the system.
	41
	42	==========================================
	43	3 - capacity-dmips-mhz
	44	==========================================
	45
	46	capacity-dmips-mhz is an optional cpu node [1] property: u32 value
	47	representing CPU capacity expressed in normalized DMIPS/MHz. At boot time, the
	48	maximum frequency available to the cpu is then used to calculate the capacity
	49	value internally used by the kernel.
	50
	51	capacity-dmips-mhz property is all-or-nothing: if it is specified for a cpu
	52	node, it has to be specified for every other cpu nodes, or the system will
	53	fall back to the default capacity value for every CPU. If cpufreq is not
	54	available, final capacities are calculated by directly using capacity-dmips-
	55	mhz values (normalized w.r.t. the highest value found while parsing the DT).
	56
	57	===========================================
	58	4 - Examples
	59	===========================================
	60
	61	Example 1 (ARM 64-bit, 6-cpu system, two clusters):
	62	capacities-dmips-mhz are scaled w.r.t. 1024 (cpu@0 and cpu@1)
	63	supposing cluster0@max-freq=1100 and custer1@max-freq=850,
	64	final capacities are 1024 for cluster0 and 446 for cluster1
65
66	cpus {
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 {
e9880240	97	entry-method = "psci";
de42fe11 JL	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
193	Example 2 (ARM 32-bit, 4-cpu system, two clusters,
194	cpus 0,1@1GHz, cpus 2,3@500MHz):
195	capacities-dmips-mhz are scaled w.r.t. 2 (cpu@0 and cpu@1), this means that first
196	cpu@0 and cpu@1 are twice fast than cpu@2 and cpu@3 (at the same frequency)
197
198	cpus {
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	===========================================
232	5 - References
233	===========================================
234
235	[1] ARM Linux Kernel documentation - CPUs bindings
236	Documentation/devicetree/bindings/arm/cpus.txt