Documentation/devicetree/bindings/numa.txt

   1 ==============================================================================
   2 NUMA binding description.
   3 ==============================================================================
   4
   5 ==============================================================================
   6 1 - Introduction
   7 ==============================================================================
   8
   9 Systems employing a Non Uniform Memory Access (NUMA) architecture contain
  10 collections of hardware resources including processors, memory, and I/O buses,
  11 that comprise what is commonly known as a NUMA node.
  12 Processor accesses to memory within the local NUMA node is generally faster
  13 than processor accesses to memory outside of the local NUMA node.
  14 DT defines interfaces that allow the platform to convey NUMA node
  15 topology information to OS.
  16
  17 ==============================================================================
  18 2 - numa-node-id
  19 ==============================================================================
  20
  21 For the purpose of identification, each NUMA node is associated with a unique
  22 token known as a node id. For the purpose of this binding
  23 a node id is a 32-bit integer.
  24
  25 A device node is associated with a NUMA node by the presence of a
  26 numa-node-id property which contains the node id of the device.
  27
  28 Example:
  29         /* numa node 0 */
  30         numa-node-id = <0>;
  31
  32         /* numa node 1 */
  33         numa-node-id = <1>;
  34
  35 ==============================================================================
  36 3 - distance-map
  37 ==============================================================================
  38
  39 The optional device tree node distance-map describes the relative
  40 distance (memory latency) between all numa nodes.
  41
  42 - compatible : Should at least contain "numa-distance-map-v1".
  43
  44 - distance-matrix
  45   This property defines a matrix to describe the relative distances
  46   between all numa nodes.
  47   It is represented as a list of node pairs and their relative distance.
  48
  49   Note:
  50         1. Each entry represents distance from first node to second node.
  51         The distances are equal in either direction.
  52         2. The distance from a node to self (local distance) is represented
  53         with value 10 and all internode distance should be represented with
  54         a value greater than 10.
  55         3. distance-matrix should have entries in lexicographical ascending
  56         order of nodes.
  57         4. There must be only one device node distance-map which must
  58         reside in the root node.
  59         5. If the distance-map node is not present, a default
  60         distance-matrix is used.
  61
  62 Example:
  63         4 nodes connected in mesh/ring topology as below,
  64
  65                 0_______20______1
  66                 |               |
  67                 |               |
  68                 20             20
  69                 |               |
  70                 |               |
  71                 |_______________|
  72                 3       20      2
  73
  74         if relative distance for each hop is 20,
  75         then internode distance would be,
  76               0 -> 1 = 20
  77               1 -> 2 = 20
  78               2 -> 3 = 20
  79               3 -> 0 = 20
  80               0 -> 2 = 40
  81               1 -> 3 = 40
  82
  83      and dt presentation for this distance matrix is,
  84
  85                 distance-map {
  86                          compatible = "numa-distance-map-v1";
  87                          distance-matrix = <0 0  10>,
  88                                            <0 1  20>,
  89                                            <0 2  40>,
  90                                            <0 3  20>,
  91                                            <1 0  20>,
  92                                            <1 1  10>,
  93                                            <1 2  20>,
  94                                            <1 3  40>,
  95                                            <2 0  40>,
  96                                            <2 1  20>,
  97                                            <2 2  10>,
  98                                            <2 3  20>,
  99                                            <3 0  20>,
 100                                            <3 1  40>,
 101                                            <3 2  20>,
 102                                            <3 3  10>;
 103                 };
 104
 105 ==============================================================================
 106 4 - Empty memory nodes
 107 ==============================================================================
 108
 109 Empty memory nodes, which no memory resides in, are allowed. There are no
 110 device nodes for these empty memory nodes. However, the NUMA node IDs and
 111 distance maps are still valid and memory may be added into them through
 112 hotplug afterwards.
 113
 114 Example:
 115
 116         memory@0 {
 117                 device_type = "memory";
 118                 reg = <0x0 0x0 0x0 0x80000000>;
 119                 numa-node-id = <0>;
 120         };
 121
 122         memory@80000000 {
 123                 device_type = "memory";
 124                 reg = <0x0 0x80000000 0x0 0x80000000>;
 125                 numa-node-id = <1>;
 126         };
 127
 128         /* Empty memory node 2 and 3 */
 129         distance-map {
 130                 compatible = "numa-distance-map-v1";
 131                 distance-matrix = <0 0  10>,
 132                                   <0 1  20>,
 133                                   <0 2  40>,
 134                                   <0 3  20>,
 135                                   <1 0  20>,
 136                                   <1 1  10>,
 137                                   <1 2  20>,
 138                                   <1 3  40>,
 139                                   <2 0  40>,
 140                                   <2 1  20>,
 141                                   <2 2  10>,
 142                                   <2 3  20>,
 143                                   <3 0  20>,
 144                                   <3 1  40>,
 145                                   <3 2  20>,
 146                                   <3 3  10>;
 147         };
 148
 149 ==============================================================================
 150 5 - Example dts
 151 ==============================================================================
 152
 153 Dual socket system consists of 2 boards connected through ccn bus and
 154 each board having one socket/soc of 8 cpus, memory and pci bus.
 155
 156         memory@c00000 {
 157                 device_type = "memory";
 158                 reg = <0x0 0xc00000 0x0 0x80000000>;
 159                 /* node 0 */
 160                 numa-node-id = <0>;
 161         };
 162
 163         memory@10000000000 {
 164                 device_type = "memory";
 165                 reg = <0x100 0x0 0x0 0x80000000>;
 166                 /* node 1 */
 167                 numa-node-id = <1>;
 168         };
 169
 170         cpus {
 171                 #address-cells = <2>;
 172                 #size-cells = <0>;
 173
 174                 cpu@0 {
 175                         device_type = "cpu";
 176                         compatible =  "arm,armv8";
 177                         reg = <0x0 0x0>;
 178                         enable-method = "psci";
 179                         /* node 0 */
 180                         numa-node-id = <0>;
 181                 };
 182                 cpu@1 {
 183                         device_type = "cpu";
 184                         compatible =  "arm,armv8";
 185                         reg = <0x0 0x1>;
 186                         enable-method = "psci";
 187                         numa-node-id = <0>;
 188                 };
 189                 cpu@2 {
 190                         device_type = "cpu";
 191                         compatible =  "arm,armv8";
 192                         reg = <0x0 0x2>;
 193                         enable-method = "psci";
 194                         numa-node-id = <0>;
 195                 };
 196                 cpu@3 {
 197                         device_type = "cpu";
 198                         compatible =  "arm,armv8";
 199                         reg = <0x0 0x3>;
 200                         enable-method = "psci";
 201                         numa-node-id = <0>;
 202                 };
 203                 cpu@4 {
 204                         device_type = "cpu";
 205                         compatible =  "arm,armv8";
 206                         reg = <0x0 0x4>;
 207                         enable-method = "psci";
 208                         numa-node-id = <0>;
 209                 };
 210                 cpu@5 {
 211                         device_type = "cpu";
 212                         compatible =  "arm,armv8";
 213                         reg = <0x0 0x5>;
 214                         enable-method = "psci";
 215                         numa-node-id = <0>;
 216                 };
 217                 cpu@6 {
 218                         device_type = "cpu";
 219                         compatible =  "arm,armv8";
 220                         reg = <0x0 0x6>;
 221                         enable-method = "psci";
 222                         numa-node-id = <0>;
 223                 };
 224                 cpu@7 {
 225                         device_type = "cpu";
 226                         compatible =  "arm,armv8";
 227                         reg = <0x0 0x7>;
 228                         enable-method = "psci";
 229                         numa-node-id = <0>;
 230                 };
 231                 cpu@8 {
 232                         device_type = "cpu";
 233                         compatible =  "arm,armv8";
 234                         reg = <0x0 0x8>;
 235                         enable-method = "psci";
 236                         /* node 1 */
 237                         numa-node-id = <1>;
 238                 };
 239                 cpu@9 {
 240                         device_type = "cpu";
 241                         compatible =  "arm,armv8";
 242                         reg = <0x0 0x9>;
 243                         enable-method = "psci";
 244                         numa-node-id = <1>;
 245                 };
 246                 cpu@a {
 247                         device_type = "cpu";
 248                         compatible =  "arm,armv8";
 249                         reg = <0x0 0xa>;
 250                         enable-method = "psci";
 251                         numa-node-id = <1>;
 252                 };
 253                 cpu@b {
 254                         device_type = "cpu";
 255                         compatible =  "arm,armv8";
 256                         reg = <0x0 0xb>;
 257                         enable-method = "psci";
 258                         numa-node-id = <1>;
 259                 };
 260                 cpu@c {
 261                         device_type = "cpu";
 262                         compatible =  "arm,armv8";
 263                         reg = <0x0 0xc>;
 264                         enable-method = "psci";
 265                         numa-node-id = <1>;
 266                 };
 267                 cpu@d {
 268                         device_type = "cpu";
 269                         compatible =  "arm,armv8";
 270                         reg = <0x0 0xd>;
 271                         enable-method = "psci";
 272                         numa-node-id = <1>;
 273                 };
 274                 cpu@e {
 275                         device_type = "cpu";
 276                         compatible =  "arm,armv8";
 277                         reg = <0x0 0xe>;
 278                         enable-method = "psci";
 279                         numa-node-id = <1>;
 280                 };
 281                 cpu@f {
 282                         device_type = "cpu";
 283                         compatible =  "arm,armv8";
 284                         reg = <0x0 0xf>;
 285                         enable-method = "psci";
 286                         numa-node-id = <1>;
 287                 };
 288         };
 289
 290         pcie0: pcie0@848000000000 {
 291                 compatible = "arm,armv8";
 292                 device_type = "pci";
 293                 bus-range = <0 255>;
 294                 #size-cells = <2>;
 295                 #address-cells = <3>;
 296                 reg = <0x8480 0x00000000 0 0x10000000>;  /* Configuration space */
 297                 ranges = <0x03000000 0x8010 0x00000000 0x8010 0x00000000 0x70 0x00000000>;
 298                 /* node 0 */
 299                 numa-node-id = <0>;
 300         };
 301
 302         pcie1: pcie1@948000000000 {
 303                 compatible = "arm,armv8";
 304                 device_type = "pci";
 305                 bus-range = <0 255>;
 306                 #size-cells = <2>;
 307                 #address-cells = <3>;
 308                 reg = <0x9480 0x00000000 0 0x10000000>;  /* Configuration space */
 309                 ranges = <0x03000000 0x9010 0x00000000 0x9010 0x00000000 0x70 0x00000000>;
 310                 /* node 1 */
 311                 numa-node-id = <1>;
 312         };
 313
 314         distance-map {
 315                 compatible = "numa-distance-map-v1";
 316                 distance-matrix = <0 0 10>,
 317                                   <0 1 20>,
 318                                   <1 1 10>;
 319         };