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 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