Documentation/devicetree/bindings/cpu/cpu-topology.txt

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