[mirror_ubuntu-hirsute-kernel.git] / Documentation / devicetree / bindings / arm / topology.txt

===========================================
ARM topology binding description
===========================================

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

In an ARM system, the hierarchy of CPUs is defined through three entities that
are used to describe the layout of physical CPUs in the system:

- cluster
- core
- thread

The cpu nodes (bindings defined in [1]) represent the devices that
correspond to physical CPUs and are to be mapped to the hierarchy levels.

The bottom hierarchy level sits at core or thread level depending on whether
symmetric multi-threading (SMT) is supported or not.

For instance in a system where CPUs support SMT, "cpu" nodes represent all
threads existing in the system and map to the hierarchy level "thread" above.
In systems where SMT is not supported "cpu" nodes represent all cores present
in the system and map to the hierarchy level "core" above.

ARM topology bindings allow one to associate cpu nodes with hierarchical groups
corresponding to the system hierarchy; syntactically they are defined as device
tree nodes.

The remainder of this document provides the topology bindings for ARM, based
on the ePAPR standard, available from:

http://www.power.org/documentation/epapr-version-1-1/

If not stated otherwise, whenever a reference to a cpu node phandle is made its
value must point to a cpu node compliant with the cpu node bindings as
documented in [1].
A topology description containing phandles to cpu nodes that are not compliant
with bindings standardized in [1] is therefore considered invalid.

===========================================
2 - cpu-map node
===========================================

The ARM CPU topology is defined within the cpu-map node, which is a direct
child of the cpus node and provides a container where the actual topology
nodes are listed.

- cpu-map node

	Usage: Optional - On ARM SMP systems provide CPUs topology to the OS.
			  ARM uniprocessor systems do not require a topology
			  description and therefore should not define a
			  cpu-map node.

	Description: The cpu-map node is just a container node where its
		     subnodes describe the CPU topology.

	Node name must be "cpu-map".

	The cpu-map node's parent node must be the cpus node.

	The cpu-map node's child nodes can be:

	- one or more cluster nodes

	Any other configuration is considered invalid.

The cpu-map node can only contain three types of child nodes:

- cluster node
- core node
- thread node

whose bindings are described in paragraph 3.

The nodes describing the CPU topology (cluster/core/thread) can only be
defined within the cpu-map node.
Any other configuration is consider invalid and therefore must be ignored.

===========================================
2.1 - cpu-map child nodes naming convention
===========================================

cpu-map child nodes must follow a naming convention where the node name
must be "clusterN", "coreN", "threadN" depending on the node type (ie
cluster/core/thread) (where N = {0, 1, ...} is the node number; nodes which
are siblings within a single common parent node must be given a unique and
sequential N value, starting from 0).
cpu-map child nodes which do not share a common parent node can have the same
name (ie same number N as other cpu-map child nodes at different device tree
levels) since name uniqueness will be guaranteed by the device tree hierarchy.

===========================================
3 - cluster/core/thread node bindings
===========================================

Bindings for cluster/cpu/thread nodes are defined as follows:

- cluster node

	 Description: must be declared within a cpu-map node, one node
		      per cluster. A system can contain several layers of
		      clustering and cluster nodes can be contained in parent
		      cluster nodes.

	The cluster node name must be "clusterN" as described in 2.1 above.
	A cluster node can not be a leaf node.

	A cluster node's child nodes must be:

	- one or more cluster nodes; or
	- one or more core nodes

	Any other configuration is considered invalid.

- core node

	Description: must be declared in a cluster node, one node per core in
		     the cluster. If the system does not support SMT, core
		     nodes are leaf nodes, otherwise they become containers of
		     thread nodes.

	The core node name must be "coreN" as described in 2.1 above.

	A core node must be a leaf node if SMT is not supported.

	Properties for core nodes that are leaf nodes:

	- cpu
		Usage: required
		Value type: <phandle>
		Definition: a phandle to the cpu node that corresponds to the
			    core node.

	If a core node is not a leaf node (CPUs supporting SMT) a core node's
	child nodes can be:

	- one or more thread nodes

	Any other configuration is considered invalid.

- thread node

	Description: must be declared in a core node, one node per thread
		     in the core if the system supports SMT. Thread nodes are
		     always leaf nodes in the device tree.

	The thread node name must be "threadN" as described in 2.1 above.

	A thread node must be a leaf node.

	A thread node must contain the following property:

	- cpu
		Usage: required
		Value type: <phandle>
		Definition: a phandle to the cpu node that corresponds to
			    the thread node.

===========================================
4 - Example dts
===========================================

Example 1 (ARM 64-bit, 16-cpu system, two clusters of clusters):

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

	cpu-map {
		cluster0 {
			cluster0 {
				core0 {
					thread0 {
						cpu = <&CPU0>;
					};
					thread1 {
						cpu = <&CPU1>;
					};
				};

				core1 {
					thread0 {
						cpu = <&CPU2>;
					};
					thread1 {
						cpu = <&CPU3>;
					};
				};
			};

			cluster1 {
				core0 {
					thread0 {
						cpu = <&CPU4>;
					};
					thread1 {
						cpu = <&CPU5>;
					};
				};

				core1 {
					thread0 {
						cpu = <&CPU6>;
					};
					thread1 {
						cpu = <&CPU7>;
					};
				};
			};
		};

		cluster1 {
			cluster0 {
				core0 {
					thread0 {
						cpu = <&CPU8>;
					};
					thread1 {
						cpu = <&CPU9>;
					};
				};
				core1 {
					thread0 {
						cpu = <&CPU10>;
					};
					thread1 {
						cpu = <&CPU11>;
					};
				};
			};

			cluster1 {
				core0 {
					thread0 {
						cpu = <&CPU12>;
					};
					thread1 {
						cpu = <&CPU13>;
					};
				};
				core1 {
					thread0 {
						cpu = <&CPU14>;
					};
					thread1 {
						cpu = <&CPU15>;
					};
				};
			};
		};
	};

	CPU0: cpu@0 {
		device_type = "cpu";
		compatible = "arm,cortex-a57";
		reg = <0x0 0x0>;
		enable-method = "spin-table";
		cpu-release-addr = <0 0x20000000>;
	};

	CPU1: cpu@1 {
		device_type = "cpu";
		compatible = "arm,cortex-a57";
		reg = <0x0 0x1>;
		enable-method = "spin-table";
		cpu-release-addr = <0 0x20000000>;
	};

	CPU2: cpu@100 {
		device_type = "cpu";
		compatible = "arm,cortex-a57";
		reg = <0x0 0x100>;
		enable-method = "spin-table";
		cpu-release-addr = <0 0x20000000>;
	};

	CPU3: cpu@101 {
		device_type = "cpu";
		compatible = "arm,cortex-a57";
		reg = <0x0 0x101>;
		enable-method = "spin-table";
		cpu-release-addr = <0 0x20000000>;
	};

	CPU4: cpu@10000 {
		device_type = "cpu";
		compatible = "arm,cortex-a57";
		reg = <0x0 0x10000>;
		enable-method = "spin-table";
		cpu-release-addr = <0 0x20000000>;
	};

	CPU5: cpu@10001 {
		device_type = "cpu";
		compatible = "arm,cortex-a57";
		reg = <0x0 0x10001>;
		enable-method = "spin-table";
		cpu-release-addr = <0 0x20000000>;
	};

	CPU6: cpu@10100 {
		device_type = "cpu";
		compatible = "arm,cortex-a57";
		reg = <0x0 0x10100>;
		enable-method = "spin-table";
		cpu-release-addr = <0 0x20000000>;
	};

	CPU7: cpu@10101 {
		device_type = "cpu";
		compatible = "arm,cortex-a57";
		reg = <0x0 0x10101>;
		enable-method = "spin-table";
		cpu-release-addr = <0 0x20000000>;
	};

	CPU8: cpu@100000000 {
		device_type = "cpu";
		compatible = "arm,cortex-a57";
		reg = <0x1 0x0>;
		enable-method = "spin-table";
		cpu-release-addr = <0 0x20000000>;
	};

	CPU9: cpu@100000001 {
		device_type = "cpu";
		compatible = "arm,cortex-a57";
		reg = <0x1 0x1>;
		enable-method = "spin-table";
		cpu-release-addr = <0 0x20000000>;
	};

	CPU10: cpu@100000100 {
		device_type = "cpu";
		compatible = "arm,cortex-a57";
		reg = <0x1 0x100>;
		enable-method = "spin-table";
		cpu-release-addr = <0 0x20000000>;
	};

	CPU11: cpu@100000101 {
		device_type = "cpu";
		compatible = "arm,cortex-a57";
		reg = <0x1 0x101>;
		enable-method = "spin-table";
		cpu-release-addr = <0 0x20000000>;
	};

	CPU12: cpu@100010000 {
		device_type = "cpu";
		compatible = "arm,cortex-a57";
		reg = <0x1 0x10000>;
		enable-method = "spin-table";
		cpu-release-addr = <0 0x20000000>;
	};

	CPU13: cpu@100010001 {
		device_type = "cpu";
		compatible = "arm,cortex-a57";
		reg = <0x1 0x10001>;
		enable-method = "spin-table";
		cpu-release-addr = <0 0x20000000>;
	};

	CPU14: cpu@100010100 {
		device_type = "cpu";
		compatible = "arm,cortex-a57";
		reg = <0x1 0x10100>;
		enable-method = "spin-table";
		cpu-release-addr = <0 0x20000000>;
	};

	CPU15: cpu@100010101 {
		device_type = "cpu";
		compatible = "arm,cortex-a57";
		reg = <0x1 0x10101>;
		enable-method = "spin-table";
		cpu-release-addr = <0 0x20000000>;
	};
};

Example 2 (ARM 32-bit, dual-cluster, 8-cpu system, no SMT):

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

	cpu-map {
		cluster0 {
			core0 {
				cpu = <&CPU0>;
			};
			core1 {
				cpu = <&CPU1>;
			};
			core2 {
				cpu = <&CPU2>;
			};
			core3 {
				cpu = <&CPU3>;
			};
		};

		cluster1 {
			core0 {
				cpu = <&CPU4>;
			};
			core1 {
				cpu = <&CPU5>;
			};
			core2 {
				cpu = <&CPU6>;
			};
			core3 {
				cpu = <&CPU7>;
			};
		};
	};

	CPU0: cpu@0 {
		device_type = "cpu";
		compatible = "arm,cortex-a15";
		reg = <0x0>;
	};

	CPU1: cpu@1 {
		device_type = "cpu";
		compatible = "arm,cortex-a15";
		reg = <0x1>;
	};

	CPU2: cpu@2 {
		device_type = "cpu";
		compatible = "arm,cortex-a15";
		reg = <0x2>;
	};

	CPU3: cpu@3 {
		device_type = "cpu";
		compatible = "arm,cortex-a15";
		reg = <0x3>;
	};

	CPU4: cpu@100 {
		device_type = "cpu";
		compatible = "arm,cortex-a7";
		reg = <0x100>;
	};

	CPU5: cpu@101 {
		device_type = "cpu";
		compatible = "arm,cortex-a7";
		reg = <0x101>;
	};

	CPU6: cpu@102 {
		device_type = "cpu";
		compatible = "arm,cortex-a7";
		reg = <0x102>;
	};

	CPU7: cpu@103 {
		device_type = "cpu";
		compatible = "arm,cortex-a7";
		reg = <0x103>;
	};
};

===============================================================================
[1] ARM Linux kernel documentation
    Documentation/devicetree/bindings/arm/cpus.txt
Commit	Line	Data
deeea728 LP	1	===========================================
	2	ARM topology binding description
	3	===========================================
	4
	5	===========================================
	6	1 - Introduction
	7	===========================================
	8
	9	In an ARM system, the hierarchy of CPUs is defined through three entities that
	10	are used to describe the layout of physical CPUs in the system:
	11
	12	- cluster
	13	- core
	14	- thread
	15
	16	The cpu nodes (bindings defined in [1]) represent the devices that
	17	correspond to physical CPUs and are to be mapped to the hierarchy levels.
	18
	19	The bottom hierarchy level sits at core or thread level depending on whether
	20	symmetric multi-threading (SMT) is supported or not.
	21
	22	For instance in a system where CPUs support SMT, "cpu" nodes represent all
	23	threads existing in the system and map to the hierarchy level "thread" above.
	24	In systems where SMT is not supported "cpu" nodes represent all cores present
	25	in the system and map to the hierarchy level "core" above.
	26
	27	ARM topology bindings allow one to associate cpu nodes with hierarchical groups
	28	corresponding to the system hierarchy; syntactically they are defined as device
	29	tree nodes.
	30
	31	The remainder of this document provides the topology bindings for ARM, based
	32	on the ePAPR standard, available from:
	33
	34	http://www.power.org/documentation/epapr-version-1-1/
	35
	36	If not stated otherwise, whenever a reference to a cpu node phandle is made its
	37	value must point to a cpu node compliant with the cpu node bindings as
	38	documented in [1].
	39	A topology description containing phandles to cpu nodes that are not compliant
	40	with bindings standardized in [1] is therefore considered invalid.
	41
	42	===========================================
	43	2 - cpu-map node
	44	===========================================
	45
	46	The ARM CPU topology is defined within the cpu-map node, which is a direct
	47	child of the cpus node and provides a container where the actual topology
	48	nodes are listed.
	49
	50	- cpu-map node
	51
	52	Usage: Optional - On ARM SMP systems provide CPUs topology to the OS.
	53	ARM uniprocessor systems do not require a topology
	54	description and therefore should not define a
	55	cpu-map node.
	56
	57	Description: The cpu-map node is just a container node where its
	58	subnodes describe the CPU topology.
	59
	60	Node name must be "cpu-map".
	61
	62	The cpu-map node's parent node must be the cpus node.
	63
	64	The cpu-map node's child nodes can be:
65
66	- one or more cluster nodes
67
68	Any other configuration is considered invalid.
69
70	The cpu-map node can only contain three types of child nodes:
71
72	- cluster node
73	- core node
74	- thread node
75
76	whose bindings are described in paragraph 3.
77
78	The nodes describing the CPU topology (cluster/core/thread) can only be
79	defined within the cpu-map node.
80	Any other configuration is consider invalid and therefore must be ignored.
81
82	===========================================
83	2.1 - cpu-map child nodes naming convention
84	===========================================
85
86	cpu-map child nodes must follow a naming convention where the node name
87	must be "clusterN", "coreN", "threadN" depending on the node type (ie
88	cluster/core/thread) (where N = {0, 1, ...} is the node number; nodes which
89	are siblings within a single common parent node must be given a unique and
90	sequential N value, starting from 0).
91	cpu-map child nodes which do not share a common parent node can have the same
92	name (ie same number N as other cpu-map child nodes at different device tree
93	levels) since name uniqueness will be guaranteed by the device tree hierarchy.
94
95	===========================================
96	3 - cluster/core/thread node bindings
97	===========================================
98
99	Bindings for cluster/cpu/thread nodes are defined as follows:
100
101	- cluster node
102
103	Description: must be declared within a cpu-map node, one node
104	per cluster. A system can contain several layers of
105	clustering and cluster nodes can be contained in parent
106	cluster nodes.
107
108	The cluster node name must be "clusterN" as described in 2.1 above.
109	A cluster node can not be a leaf node.
110
111	A cluster node's child nodes must be:
112
113	- one or more cluster nodes; or
114	- one or more core nodes
115
116	Any other configuration is considered invalid.
117
118	- core node
119
120	Description: must be declared in a cluster node, one node per core in
121	the cluster. If the system does not support SMT, core
122	nodes are leaf nodes, otherwise they become containers of
123	thread nodes.
124
125	The core node name must be "coreN" as described in 2.1 above.
126
127	A core node must be a leaf node if SMT is not supported.
128
129	Properties for core nodes that are leaf nodes:
130
131	- cpu
132	Usage: required
133	Value type: <phandle>
134	Definition: a phandle to the cpu node that corresponds to the
135	core node.
136
137	If a core node is not a leaf node (CPUs supporting SMT) a core node's
138	child nodes can be:
139
140	- one or more thread nodes
141
142	Any other configuration is considered invalid.
143
144	- thread node
145
146	Description: must be declared in a core node, one node per thread
147	in the core if the system supports SMT. Thread nodes are
148	always leaf nodes in the device tree.
149
150	The thread node name must be "threadN" as described in 2.1 above.
151
152	A thread node must be a leaf node.
153
154	A thread node must contain the following property:
155
156	- cpu
157	Usage: required
158	Value type: <phandle>
159	Definition: a phandle to the cpu node that corresponds to
160	the thread node.
161
162	===========================================
163	4 - Example dts
164	===========================================
165
166	Example 1 (ARM 64-bit, 16-cpu system, two clusters of clusters):
167
168	cpus {
169	#size-cells = <0>;
170	#address-cells = <2>;
171
172	cpu-map {
173	cluster0 {
174	cluster0 {
175	core0 {
176	thread0 {
177	cpu = <&CPU0>;
178	};
179	thread1 {
180	cpu = <&CPU1>;
181	};
182	};
183
184	core1 {
185	thread0 {
186	cpu = <&CPU2>;
187	};
188	thread1 {
189	cpu = <&CPU3>;
190	};
191	};
192	};
193
194	cluster1 {
195	core0 {
196	thread0 {
197	cpu = <&CPU4>;
198	};
199	thread1 {
200	cpu = <&CPU5>;
201	};
202	};
203
204	core1 {
205	thread0 {
206	cpu = <&CPU6>;
207	};
208	thread1 {
209	cpu = <&CPU7>;
210	};
211	};
212	};
213	};
214
215	cluster1 {
216	cluster0 {
217	core0 {
218	thread0 {
219	cpu = <&CPU8>;
220	};
221	thread1 {
222	cpu = <&CPU9>;
223	};
224	};
225	core1 {
226	thread0 {
227	cpu = <&CPU10>;
228	};
229	thread1 {
230	cpu = <&CPU11>;
231	};
232	};
233	};
234
235	cluster1 {
236	core0 {
237	thread0 {
238	cpu = <&CPU12>;
239	};
240	thread1 {
241	cpu = <&CPU13>;
242	};
243	};
244	core1 {
245	thread0 {
246	cpu = <&CPU14>;
247	};
248	thread1 {
249	cpu = <&CPU15>;
250	};
251	};
252	};
253	};
254	};
255
256	CPU0: cpu@0 {
257	device_type = "cpu";
258	compatible = "arm,cortex-a57";
259	reg = <0x0 0x0>;
260	enable-method = "spin-table";
261	cpu-release-addr = <0 0x20000000>;
262	};
263
264	CPU1: cpu@1 {
265	device_type = "cpu";
266	compatible = "arm,cortex-a57";
267	reg = <0x0 0x1>;
268	enable-method = "spin-table";
269	cpu-release-addr = <0 0x20000000>;
270	};
271
272	CPU2: cpu@100 {
273	device_type = "cpu";
274	compatible = "arm,cortex-a57";
275	reg = <0x0 0x100>;
276	enable-method = "spin-table";
277	cpu-release-addr = <0 0x20000000>;
278	};
279
280	CPU3: cpu@101 {
281	device_type = "cpu";
282	compatible = "arm,cortex-a57";
283	reg = <0x0 0x101>;
284	enable-method = "spin-table";
285	cpu-release-addr = <0 0x20000000>;
286	};
287
288	CPU4: cpu@10000 {
289	device_type = "cpu";
290	compatible = "arm,cortex-a57";
291	reg = <0x0 0x10000>;
292	enable-method = "spin-table";
293	cpu-release-addr = <0 0x20000000>;
294	};
295
296	CPU5: cpu@10001 {
297	device_type = "cpu";
298	compatible = "arm,cortex-a57";
299	reg = <0x0 0x10001>;
300	enable-method = "spin-table";
301	cpu-release-addr = <0 0x20000000>;
302	};
303
304	CPU6: cpu@10100 {
305	device_type = "cpu";
306	compatible = "arm,cortex-a57";
307	reg = <0x0 0x10100>;
308	enable-method = "spin-table";
309	cpu-release-addr = <0 0x20000000>;
310	};
311
312	CPU7: cpu@10101 {
313	device_type = "cpu";
314	compatible = "arm,cortex-a57";
315	reg = <0x0 0x10101>;
316	enable-method = "spin-table";
317	cpu-release-addr = <0 0x20000000>;
318	};
319
320	CPU8: cpu@100000000 {
321	device_type = "cpu";
322	compatible = "arm,cortex-a57";
323	reg = <0x1 0x0>;
324	enable-method = "spin-table";
325	cpu-release-addr = <0 0x20000000>;
326	};
327
328	CPU9: cpu@100000001 {
329	device_type = "cpu";
330	compatible = "arm,cortex-a57";
331	reg = <0x1 0x1>;
332	enable-method = "spin-table";
333	cpu-release-addr = <0 0x20000000>;
334	};
335
336	CPU10: cpu@100000100 {
337	device_type = "cpu";
338	compatible = "arm,cortex-a57";
339	reg = <0x1 0x100>;
340	enable-method = "spin-table";
341	cpu-release-addr = <0 0x20000000>;
342	};
343
344	CPU11: cpu@100000101 {
345	device_type = "cpu";
346	compatible = "arm,cortex-a57";
347	reg = <0x1 0x101>;
348	enable-method = "spin-table";
349	cpu-release-addr = <0 0x20000000>;
350	};
351
352	CPU12: cpu@100010000 {
353	device_type = "cpu";
354	compatible = "arm,cortex-a57";
355	reg = <0x1 0x10000>;
356	enable-method = "spin-table";
357	cpu-release-addr = <0 0x20000000>;
358	};
359
360	CPU13: cpu@100010001 {
361	device_type = "cpu";
362	compatible = "arm,cortex-a57";
363	reg = <0x1 0x10001>;
364	enable-method = "spin-table";
365	cpu-release-addr = <0 0x20000000>;
366	};
367
368	CPU14: cpu@100010100 {
369	device_type = "cpu";
370	compatible = "arm,cortex-a57";
371	reg = <0x1 0x10100>;
372	enable-method = "spin-table";
373	cpu-release-addr = <0 0x20000000>;
374	};
375
376	CPU15: cpu@100010101 {
377	device_type = "cpu";
378	compatible = "arm,cortex-a57";
379	reg = <0x1 0x10101>;
380	enable-method = "spin-table";
381	cpu-release-addr = <0 0x20000000>;
382	};
383	};
384
385	Example 2 (ARM 32-bit, dual-cluster, 8-cpu system, no SMT):
386
387	cpus {
388	#size-cells = <0>;
389	#address-cells = <1>;
390
391	cpu-map {
392	cluster0 {
393	core0 {
394	cpu = <&CPU0>;
395	};
396	core1 {
397	cpu = <&CPU1>;
398	};
399	core2 {
400	cpu = <&CPU2>;
401	};
402	core3 {
403	cpu = <&CPU3>;
404	};
405	};
406
407	cluster1 {
408	core0 {
409	cpu = <&CPU4>;
410	};
411	core1 {
412	cpu = <&CPU5>;
413	};
414	core2 {
415	cpu = <&CPU6>;
416	};
417	core3 {
418	cpu = <&CPU7>;
419	};
420	};
421	};
422
423	CPU0: cpu@0 {
424	device_type = "cpu";
425	compatible = "arm,cortex-a15";
426	reg = <0x0>;
427	};
428
429	CPU1: cpu@1 {
430	device_type = "cpu";
431	compatible = "arm,cortex-a15";
432	reg = <0x1>;
433	};
434
435	CPU2: cpu@2 {
436	device_type = "cpu";
437	compatible = "arm,cortex-a15";
438	reg = <0x2>;
439	};
440
441	CPU3: cpu@3 {
442	device_type = "cpu";
443	compatible = "arm,cortex-a15";
444	reg = <0x3>;
445	};
446
447	CPU4: cpu@100 {
448	device_type = "cpu";
449	compatible = "arm,cortex-a7";
450	reg = <0x100>;
451	};
452
453	CPU5: cpu@101 {
454	device_type = "cpu";
455	compatible = "arm,cortex-a7";
456	reg = <0x101>;
457	};
458
459	CPU6: cpu@102 {
460	device_type = "cpu";
461	compatible = "arm,cortex-a7";
462	reg = <0x102>;
463	};
464
465	CPU7: cpu@103 {
466	device_type = "cpu";
467	compatible = "arm,cortex-a7";
468	reg = <0x103>;
469	};
470	};
471
472	===============================================================================
473	[1] ARM Linux kernel documentation
474	Documentation/devicetree/bindings/arm/cpus.txt