bindings/cpu/cpu-topology.txt

6 1 - Introduction
9 In a SMP system, the hierarchy of CPUs is defined through three entities that
12 - socket
13 - cluster
14 - core
15 - thread
18 symmetric multi-threading (SMT) is supported or not.
20 For instance in a system where CPUs support SMT, "cpu" nodes represent all
29 Currently, only ARM/RISC-V intend to use this cpu topology binding but it may be
35 A topology description containing phandles to cpu nodes that are not compliant
39 2 - cpu-map node
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
46 - cpu-map node
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.
53 	Description: The cpu-map node is just a container node where its
56 	Node name must be "cpu-map".
58 	The cpu-map node's parent node must be the cpus node.
60 	The cpu-map node's child nodes can be:
62 	- one or more cluster nodes or
63 	- one or more socket nodes in a multi-socket system
67 The cpu-map node can only contain 4 types of child nodes:
69 - socket node
70 - cluster node
71 - core node
72 - thread node
77 only be defined within the cpu-map node and every core/thread in the
82 2.1 - cpu-map child nodes naming convention
85 cpu-map child nodes must follow a naming convention where the node name
88 which are siblings within a single common parent node must be given a unique and
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
95 3 - socket/cluster/core/thread node bindings
100 - socket node
102 	 Description: must be declared within a cpu-map node, one node
103 		      per physical socket in the system. A system can
109 	This node is optional for a single socket system.
112 	A socket node can not be a leaf node.
114 	A socket node's child nodes must be one or more cluster nodes.
118 - cluster node
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
126 	A cluster node can not be a leaf node.
128 	A cluster node's child nodes must be:
130 	- one or more cluster nodes; or
131 	- one or more core nodes
135 - core node
137 	Description: must be declared in a cluster node, one node per core in
144 	A core node must be a leaf node if SMT is not supported.
148 	- cpu
151 		Definition: a phandle to the cpu node that corresponds to the
154 	If a core node is not a leaf node (CPUs supporting SMT) a core node's
157 	- one or more thread nodes
161 - thread node
163 	Description: must be declared in a core node, one node per thread
169 	A thread node must be a leaf node.
171 	A thread node must contain the following property:
173 	- cpu
176 		Definition: a phandle to the cpu node that corresponds to
180 4 - Example dts
183 Example 1 (ARM 64-bit, 16-cpu system, two clusters of clusters in a single
187 	#size-cells = <0>;
188 	#address-cells = <2>;
190 	cpu-map {
278 		compatible = "arm,cortex-a57";
280 		enable-method = "spin-table";
281 		cpu-release-addr = <0 0x20000000>;
286 		compatible = "arm,cortex-a57";
288 		enable-method = "spin-table";
289 		cpu-release-addr = <0 0x20000000>;
294 		compatible = "arm,cortex-a57";
296 		enable-method = "spin-table";
297 		cpu-release-addr = <0 0x20000000>;
302 		compatible = "arm,cortex-a57";
304 		enable-method = "spin-table";
305 		cpu-release-addr = <0 0x20000000>;
310 		compatible = "arm,cortex-a57";
312 		enable-method = "spin-table";
313 		cpu-release-addr = <0 0x20000000>;
318 		compatible = "arm,cortex-a57";
320 		enable-method = "spin-table";
321 		cpu-release-addr = <0 0x20000000>;
326 		compatible = "arm,cortex-a57";
328 		enable-method = "spin-table";
329 		cpu-release-addr = <0 0x20000000>;
334 		compatible = "arm,cortex-a57";
336 		enable-method = "spin-table";
337 		cpu-release-addr = <0 0x20000000>;
342 		compatible = "arm,cortex-a57";
344 		enable-method = "spin-table";
345 		cpu-release-addr = <0 0x20000000>;
350 		compatible = "arm,cortex-a57";
352 		enable-method = "spin-table";
353 		cpu-release-addr = <0 0x20000000>;
358 		compatible = "arm,cortex-a57";
360 		enable-method = "spin-table";
361 		cpu-release-addr = <0 0x20000000>;
366 		compatible = "arm,cortex-a57";
368 		enable-method = "spin-table";
369 		cpu-release-addr = <0 0x20000000>;
374 		compatible = "arm,cortex-a57";
376 		enable-method = "spin-table";
377 		cpu-release-addr = <0 0x20000000>;
382 		compatible = "arm,cortex-a57";
384 		enable-method = "spin-table";
385 		cpu-release-addr = <0 0x20000000>;
390 		compatible = "arm,cortex-a57";
392 		enable-method = "spin-table";
393 		cpu-release-addr = <0 0x20000000>;
398 		compatible = "arm,cortex-a57";
400 		enable-method = "spin-table";
401 		cpu-release-addr = <0 0x20000000>;
405 Example 2 (ARM 32-bit, dual-cluster, 8-cpu system, no SMT):
408 	#size-cells = <0>;
409 	#address-cells = <1>;
411 	cpu-map {
445 		compatible = "arm,cortex-a15";
451 		compatible = "arm,cortex-a15";
457 		compatible = "arm,cortex-a15";
463 		compatible = "arm,cortex-a15";
469 		compatible = "arm,cortex-a7";
475 		compatible = "arm,cortex-a7";
481 		compatible = "arm,cortex-a7";
487 		compatible = "arm,cortex-a7";
492 Example 3: HiFive Unleashed (RISC-V 64 bit, 4 core system)
495 	#address-cells = <2>;
496 	#size-cells = <2>;
498 	model = "sifive,hifive-unleashed-a00";
502 		#address-cells = <1>;
503 		#size-cells = <0>;
504 		cpu-map {
551 [3] RISC-V Linux kernel documentation