1 ===========================================
2 CPU topology binding description
3 ===========================================
4
5 ===========================================
6 1 - Introduction
7 ===========================================
8
9 In a SMP 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 - socket
13 - cluster
14 - core
15 - thread
16
17 The bottom hierarchy level sits at core or thread level depending on whether
18 symmetric multi-threading (SMT) is supported or not.
19
20 For instance in a system where CPUs support SMT, "cpu" nodes represent all
21 threads existing in the system and map to the hierarchy level "thread" above.
22 In systems where SMT is not supported "cpu" nodes represent all cores present
23 in the system and map to the hierarchy level "core" above.
24
25 CPU topology bindings allow one to associate cpu nodes with hierarchical groups
26 corresponding to the system hierarchy; syntactically they are defined as device
27 tree nodes.
28
29 Currently, only ARM/RISC-V intend to use this cpu topology binding but it may be
30 used for any other architecture as well.
31
32 The cpu nodes, as per bindings defined in [4], represent the devices that
33 correspond to physical CPUs and are to be mapped to the hierarchy levels.
34
35 A topology description containing phandles to cpu nodes that are not compliant
36 with bindings standardized in [4] is therefore considered invalid.
37
38 ===========================================
39 2 - cpu-map node
40 ===========================================
41
42 The ARM/RISC-V CPU topology is defined within the cpu-map node, which is a direct
43 child of the cpus node and provides a container where the actual topology
44 nodes 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
67 The 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
74 whose bindings are described in paragraph 3.
75
76 The nodes describing the CPU topology (socket/cluster/core/thread) can
77 only be defined within the cpu-map node and every core/thread in the
78 system must be defined within the topology. Any other configuration is
79 invalid and therefore must be ignored.
80
81 ===========================================
82 2.1 - cpu-map child nodes naming convention
83 ===========================================
84
85 cpu-map child nodes must follow a naming convention where the node name
86 must 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
88 which are siblings within a single common parent node must be given a unique and
89 sequential N value, starting from 0).
90 cpu-map child nodes which do not share a common parent node can have the same
91 name (ie same number N as other cpu-map child nodes at different device tree
92 levels) since name uniqueness will be guaranteed by the device tree hierarchy.
93
94 ===========================================
95 3 - socket/cluster/core/thread node bindings
96 ===========================================
97
98 Bindings 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 ===========================================
180 4 - Example dts
181 ===========================================
182
183 Example 1 (ARM 64-bit, 16-cpu system, two clusters of clusters in a single
184 physical socket):
185
186 cpus {
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
405 Example 2 (ARM 32-bit, dual-cluster, 8-cpu system, no SMT):
406
407 cpus {
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
492 Example 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/
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.