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