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