aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/devicetree/bindings/arm/topology.txt
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/devicetree/bindings/arm/topology.txt')
-rw-r--r--Documentation/devicetree/bindings/arm/topology.txt474
1 files changed, 474 insertions, 0 deletions
diff --git a/Documentation/devicetree/bindings/arm/topology.txt b/Documentation/devicetree/bindings/arm/topology.txt
new file mode 100644
index 000000000000..4aa20e7a424e
--- /dev/null
+++ b/Documentation/devicetree/bindings/arm/topology.txt
@@ -0,0 +1,474 @@
1===========================================
2ARM topology binding description
3===========================================
4
5===========================================
61 - Introduction
7===========================================
8
9In an ARM 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- cluster
13- core
14- thread
15
16The cpu nodes (bindings defined in [1]) represent the devices that
17correspond to physical CPUs and are to be mapped to the hierarchy levels.
18
19The bottom hierarchy level sits at core or thread level depending on whether
20symmetric multi-threading (SMT) is supported or not.
21
22For instance in a system where CPUs support SMT, "cpu" nodes represent all
23threads existing in the system and map to the hierarchy level "thread" above.
24In systems where SMT is not supported "cpu" nodes represent all cores present
25in the system and map to the hierarchy level "core" above.
26
27ARM topology bindings allow one to associate cpu nodes with hierarchical groups
28corresponding to the system hierarchy; syntactically they are defined as device
29tree nodes.
30
31The remainder of this document provides the topology bindings for ARM, based
32on the ePAPR standard, available from:
33
34http://www.power.org/documentation/epapr-version-1-1/
35
36If not stated otherwise, whenever a reference to a cpu node phandle is made its
37value must point to a cpu node compliant with the cpu node bindings as
38documented in [1].
39A topology description containing phandles to cpu nodes that are not compliant
40with bindings standardized in [1] is therefore considered invalid.
41
42===========================================
432 - cpu-map node
44===========================================
45
46The ARM CPU topology is defined within the cpu-map node, which is a direct
47child of the cpus node and provides a container where the actual topology
48nodes 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
70The cpu-map node can only contain three types of child nodes:
71
72- cluster node
73- core node
74- thread node
75
76whose bindings are described in paragraph 3.
77
78The nodes describing the CPU topology (cluster/core/thread) can only be
79defined within the cpu-map node.
80Any other configuration is consider invalid and therefore must be ignored.
81
82===========================================
832.1 - cpu-map child nodes naming convention
84===========================================
85
86cpu-map child nodes must follow a naming convention where the node name
87must be "clusterN", "coreN", "threadN" depending on the node type (ie
88cluster/core/thread) (where N = {0, 1, ...} is the node number; nodes which
89are siblings within a single common parent node must be given a unique and
90sequential N value, starting from 0).
91cpu-map child nodes which do not share a common parent node can have the same
92name (ie same number N as other cpu-map child nodes at different device tree
93levels) since name uniqueness will be guaranteed by the device tree hierarchy.
94
95===========================================
963 - cluster/core/thread node bindings
97===========================================
98
99Bindings 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===========================================
1634 - Example dts
164===========================================
165
166Example 1 (ARM 64-bit, 16-cpu system, two clusters of clusters):
167
168cpus {
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
385Example 2 (ARM 32-bit, dual-cluster, 8-cpu system, no SMT):
386
387cpus {
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