GNU Linux-libre 4.14.266-gnu1
[releases.git] / Documentation / devicetree / bindings / arm / topology.txt
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 Devicetree Specification, available from:
33
34 https://www.devicetree.org/specifications/
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
79 be defined within the cpu-map node and every core/thread in the system
80 must be defined within the topology.  Any other configuration is
81 invalid and therefore must be ignored.
82
83 ===========================================
84 2.1 - cpu-map child nodes naming convention
85 ===========================================
86
87 cpu-map child nodes must follow a naming convention where the node name
88 must be "clusterN", "coreN", "threadN" depending on the node type (ie
89 cluster/core/thread) (where N = {0, 1, ...} is the node number; nodes which
90 are siblings within a single common parent node must be given a unique and
91 sequential N value, starting from 0).
92 cpu-map child nodes which do not share a common parent node can have the same
93 name (ie same number N as other cpu-map child nodes at different device tree
94 levels) since name uniqueness will be guaranteed by the device tree hierarchy.
95
96 ===========================================
97 3 - cluster/core/thread node bindings
98 ===========================================
99
100 Bindings for cluster/cpu/thread nodes are defined as follows:
101
102 - cluster node
103
104          Description: must be declared within a cpu-map node, one node
105                       per cluster. A system can contain several layers of
106                       clustering and cluster nodes can be contained in parent
107                       cluster nodes.
108
109         The cluster node name must be "clusterN" as described in 2.1 above.
110         A cluster node can not be a leaf node.
111
112         A cluster node's child nodes must be:
113
114         - one or more cluster nodes; or
115         - one or more core nodes
116
117         Any other configuration is considered invalid.
118
119 - core node
120
121         Description: must be declared in a cluster node, one node per core in
122                      the cluster. If the system does not support SMT, core
123                      nodes are leaf nodes, otherwise they become containers of
124                      thread nodes.
125
126         The core node name must be "coreN" as described in 2.1 above.
127
128         A core node must be a leaf node if SMT is not supported.
129
130         Properties for core nodes that are leaf nodes:
131
132         - cpu
133                 Usage: required
134                 Value type: <phandle>
135                 Definition: a phandle to the cpu node that corresponds to the
136                             core node.
137
138         If a core node is not a leaf node (CPUs supporting SMT) a core node's
139         child nodes can be:
140
141         - one or more thread nodes
142
143         Any other configuration is considered invalid.
144
145 - thread node
146
147         Description: must be declared in a core node, one node per thread
148                      in the core if the system supports SMT. Thread nodes are
149                      always leaf nodes in the device tree.
150
151         The thread node name must be "threadN" as described in 2.1 above.
152
153         A thread node must be a leaf node.
154
155         A thread node must contain the following property:
156
157         - cpu
158                 Usage: required
159                 Value type: <phandle>
160                 Definition: a phandle to the cpu node that corresponds to
161                             the thread node.
162
163 ===========================================
164 4 - Example dts
165 ===========================================
166
167 Example 1 (ARM 64-bit, 16-cpu system, two clusters of clusters):
168
169 cpus {
170         #size-cells = <0>;
171         #address-cells = <2>;
172
173         cpu-map {
174                 cluster0 {
175                         cluster0 {
176                                 core0 {
177                                         thread0 {
178                                                 cpu = <&CPU0>;
179                                         };
180                                         thread1 {
181                                                 cpu = <&CPU1>;
182                                         };
183                                 };
184
185                                 core1 {
186                                         thread0 {
187                                                 cpu = <&CPU2>;
188                                         };
189                                         thread1 {
190                                                 cpu = <&CPU3>;
191                                         };
192                                 };
193                         };
194
195                         cluster1 {
196                                 core0 {
197                                         thread0 {
198                                                 cpu = <&CPU4>;
199                                         };
200                                         thread1 {
201                                                 cpu = <&CPU5>;
202                                         };
203                                 };
204
205                                 core1 {
206                                         thread0 {
207                                                 cpu = <&CPU6>;
208                                         };
209                                         thread1 {
210                                                 cpu = <&CPU7>;
211                                         };
212                                 };
213                         };
214                 };
215
216                 cluster1 {
217                         cluster0 {
218                                 core0 {
219                                         thread0 {
220                                                 cpu = <&CPU8>;
221                                         };
222                                         thread1 {
223                                                 cpu = <&CPU9>;
224                                         };
225                                 };
226                                 core1 {
227                                         thread0 {
228                                                 cpu = <&CPU10>;
229                                         };
230                                         thread1 {
231                                                 cpu = <&CPU11>;
232                                         };
233                                 };
234                         };
235
236                         cluster1 {
237                                 core0 {
238                                         thread0 {
239                                                 cpu = <&CPU12>;
240                                         };
241                                         thread1 {
242                                                 cpu = <&CPU13>;
243                                         };
244                                 };
245                                 core1 {
246                                         thread0 {
247                                                 cpu = <&CPU14>;
248                                         };
249                                         thread1 {
250                                                 cpu = <&CPU15>;
251                                         };
252                                 };
253                         };
254                 };
255         };
256
257         CPU0: cpu@0 {
258                 device_type = "cpu";
259                 compatible = "arm,cortex-a57";
260                 reg = <0x0 0x0>;
261                 enable-method = "spin-table";
262                 cpu-release-addr = <0 0x20000000>;
263         };
264
265         CPU1: cpu@1 {
266                 device_type = "cpu";
267                 compatible = "arm,cortex-a57";
268                 reg = <0x0 0x1>;
269                 enable-method = "spin-table";
270                 cpu-release-addr = <0 0x20000000>;
271         };
272
273         CPU2: cpu@100 {
274                 device_type = "cpu";
275                 compatible = "arm,cortex-a57";
276                 reg = <0x0 0x100>;
277                 enable-method = "spin-table";
278                 cpu-release-addr = <0 0x20000000>;
279         };
280
281         CPU3: cpu@101 {
282                 device_type = "cpu";
283                 compatible = "arm,cortex-a57";
284                 reg = <0x0 0x101>;
285                 enable-method = "spin-table";
286                 cpu-release-addr = <0 0x20000000>;
287         };
288
289         CPU4: cpu@10000 {
290                 device_type = "cpu";
291                 compatible = "arm,cortex-a57";
292                 reg = <0x0 0x10000>;
293                 enable-method = "spin-table";
294                 cpu-release-addr = <0 0x20000000>;
295         };
296
297         CPU5: cpu@10001 {
298                 device_type = "cpu";
299                 compatible = "arm,cortex-a57";
300                 reg = <0x0 0x10001>;
301                 enable-method = "spin-table";
302                 cpu-release-addr = <0 0x20000000>;
303         };
304
305         CPU6: cpu@10100 {
306                 device_type = "cpu";
307                 compatible = "arm,cortex-a57";
308                 reg = <0x0 0x10100>;
309                 enable-method = "spin-table";
310                 cpu-release-addr = <0 0x20000000>;
311         };
312
313         CPU7: cpu@10101 {
314                 device_type = "cpu";
315                 compatible = "arm,cortex-a57";
316                 reg = <0x0 0x10101>;
317                 enable-method = "spin-table";
318                 cpu-release-addr = <0 0x20000000>;
319         };
320
321         CPU8: cpu@100000000 {
322                 device_type = "cpu";
323                 compatible = "arm,cortex-a57";
324                 reg = <0x1 0x0>;
325                 enable-method = "spin-table";
326                 cpu-release-addr = <0 0x20000000>;
327         };
328
329         CPU9: cpu@100000001 {
330                 device_type = "cpu";
331                 compatible = "arm,cortex-a57";
332                 reg = <0x1 0x1>;
333                 enable-method = "spin-table";
334                 cpu-release-addr = <0 0x20000000>;
335         };
336
337         CPU10: cpu@100000100 {
338                 device_type = "cpu";
339                 compatible = "arm,cortex-a57";
340                 reg = <0x1 0x100>;
341                 enable-method = "spin-table";
342                 cpu-release-addr = <0 0x20000000>;
343         };
344
345         CPU11: cpu@100000101 {
346                 device_type = "cpu";
347                 compatible = "arm,cortex-a57";
348                 reg = <0x1 0x101>;
349                 enable-method = "spin-table";
350                 cpu-release-addr = <0 0x20000000>;
351         };
352
353         CPU12: cpu@100010000 {
354                 device_type = "cpu";
355                 compatible = "arm,cortex-a57";
356                 reg = <0x1 0x10000>;
357                 enable-method = "spin-table";
358                 cpu-release-addr = <0 0x20000000>;
359         };
360
361         CPU13: cpu@100010001 {
362                 device_type = "cpu";
363                 compatible = "arm,cortex-a57";
364                 reg = <0x1 0x10001>;
365                 enable-method = "spin-table";
366                 cpu-release-addr = <0 0x20000000>;
367         };
368
369         CPU14: cpu@100010100 {
370                 device_type = "cpu";
371                 compatible = "arm,cortex-a57";
372                 reg = <0x1 0x10100>;
373                 enable-method = "spin-table";
374                 cpu-release-addr = <0 0x20000000>;
375         };
376
377         CPU15: cpu@100010101 {
378                 device_type = "cpu";
379                 compatible = "arm,cortex-a57";
380                 reg = <0x1 0x10101>;
381                 enable-method = "spin-table";
382                 cpu-release-addr = <0 0x20000000>;
383         };
384 };
385
386 Example 2 (ARM 32-bit, dual-cluster, 8-cpu system, no SMT):
387
388 cpus {
389         #size-cells = <0>;
390         #address-cells = <1>;
391
392         cpu-map {
393                 cluster0 {
394                         core0 {
395                                 cpu = <&CPU0>;
396                         };
397                         core1 {
398                                 cpu = <&CPU1>;
399                         };
400                         core2 {
401                                 cpu = <&CPU2>;
402                         };
403                         core3 {
404                                 cpu = <&CPU3>;
405                         };
406                 };
407
408                 cluster1 {
409                         core0 {
410                                 cpu = <&CPU4>;
411                         };
412                         core1 {
413                                 cpu = <&CPU5>;
414                         };
415                         core2 {
416                                 cpu = <&CPU6>;
417                         };
418                         core3 {
419                                 cpu = <&CPU7>;
420                         };
421                 };
422         };
423
424         CPU0: cpu@0 {
425                 device_type = "cpu";
426                 compatible = "arm,cortex-a15";
427                 reg = <0x0>;
428         };
429
430         CPU1: cpu@1 {
431                 device_type = "cpu";
432                 compatible = "arm,cortex-a15";
433                 reg = <0x1>;
434         };
435
436         CPU2: cpu@2 {
437                 device_type = "cpu";
438                 compatible = "arm,cortex-a15";
439                 reg = <0x2>;
440         };
441
442         CPU3: cpu@3 {
443                 device_type = "cpu";
444                 compatible = "arm,cortex-a15";
445                 reg = <0x3>;
446         };
447
448         CPU4: cpu@100 {
449                 device_type = "cpu";
450                 compatible = "arm,cortex-a7";
451                 reg = <0x100>;
452         };
453
454         CPU5: cpu@101 {
455                 device_type = "cpu";
456                 compatible = "arm,cortex-a7";
457                 reg = <0x101>;
458         };
459
460         CPU6: cpu@102 {
461                 device_type = "cpu";
462                 compatible = "arm,cortex-a7";
463                 reg = <0x102>;
464         };
465
466         CPU7: cpu@103 {
467                 device_type = "cpu";
468                 compatible = "arm,cortex-a7";
469                 reg = <0x103>;
470         };
471 };
472
473 ===============================================================================
474 [1] ARM Linux kernel documentation
475     Documentation/devicetree/bindings/arm/cpus.txt