diff options
Diffstat (limited to 'Documentation/devicetree/bindings/arm/topology.txt')
-rw-r--r-- | Documentation/devicetree/bindings/arm/topology.txt | 474 |
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 | =========================================== | ||
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 ePAPR standard, available from: | ||
33 | |||
34 | http://www.power.org/documentation/epapr-version-1-1/ | ||
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 be | ||
79 | defined within the cpu-map node. | ||
80 | Any other configuration is consider invalid and therefore must be ignored. | ||
81 | |||
82 | =========================================== | ||
83 | 2.1 - cpu-map child nodes naming convention | ||
84 | =========================================== | ||
85 | |||
86 | cpu-map child nodes must follow a naming convention where the node name | ||
87 | must be "clusterN", "coreN", "threadN" depending on the node type (ie | ||
88 | cluster/core/thread) (where N = {0, 1, ...} is the node number; nodes which | ||
89 | are siblings within a single common parent node must be given a unique and | ||
90 | sequential N value, starting from 0). | ||
91 | cpu-map child nodes which do not share a common parent node can have the same | ||
92 | name (ie same number N as other cpu-map child nodes at different device tree | ||
93 | levels) since name uniqueness will be guaranteed by the device tree hierarchy. | ||
94 | |||
95 | =========================================== | ||
96 | 3 - cluster/core/thread node bindings | ||
97 | =========================================== | ||
98 | |||
99 | Bindings 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 | =========================================== | ||
163 | 4 - Example dts | ||
164 | =========================================== | ||
165 | |||
166 | Example 1 (ARM 64-bit, 16-cpu system, two clusters of clusters): | ||
167 | |||
168 | cpus { | ||
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 | |||
385 | Example 2 (ARM 32-bit, dual-cluster, 8-cpu system, no SMT): | ||
386 | |||
387 | cpus { | ||
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 | ||