cpu-topology.txt

Version: - FREEBSD - FREEBSD-13-STABLE - FREEBSD-13-0 - FREEBSD-12-STABLE - FREEBSD-12-0 - FREEBSD-11-STABLE - FREEBSD-11-0 - FREEBSD-10-STABLE - FREEBSD-10-0 - FREEBSD-9-STABLE - FREEBSD-9-0 - FREEBSD-8-STABLE - FREEBSD-8-0 - FREEBSD-7-STABLE - FREEBSD-7-0 - FREEBSD-6-STABLE - FREEBSD-6-0 - FREEBSD-5-STABLE - FREEBSD-5-0 - FREEBSD-4-STABLE - FREEBSD-3-STABLE - FREEBSD22 - l41 - OPENBSD - linux-2.6 - MK84 - PLAN9 - xnu-8792
SearchContext: - none - 3 - 10
    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/
Cache object: 24bce2aa07f68f2eae76d3a4cab60bde
[ source navigation ] [ diff markup ] [ identifier search ] [ freetext search ] [ file search ] [ list types ] [ track identifier ]
This page is part of the FreeBSD/Linux Linux Kernel Cross-Reference, and was automatically generated using a modified version of the LXR engine.
FreeBSD/Linux Kernel Cross Reference sys/contrib/device-tree/Bindings/cpu/cpu-topology.txt

FreeBSD/Linux Kernel Cross Reference
sys/contrib/device-tree/Bindings/cpu/cpu-topology.txt
