xref: /freebsd/sys/contrib/device-tree/Bindings/numa.txt (revision d5b0e70f7e04d971691517ce1304d86a1e367e2e) 
1==============================================================================
2NUMA binding description.
3==============================================================================
4
5==============================================================================
61 - Introduction
7==============================================================================
8
9Systems employing a Non Uniform Memory Access (NUMA) architecture contain
10collections of hardware resources including processors, memory, and I/O buses,
11that comprise what is commonly known as a NUMA node.
12Processor accesses to memory within the local NUMA node is generally faster
13than processor accesses to memory outside of the local NUMA node.
14DT defines interfaces that allow the platform to convey NUMA node
15topology information to OS.
16
17==============================================================================
182 - numa-node-id
19==============================================================================
20
21For the purpose of identification, each NUMA node is associated with a unique
22token known as a node id. For the purpose of this binding
23a node id is a 32-bit integer.
24
25A device node is associated with a NUMA node by the presence of a
26numa-node-id property which contains the node id of the device.
27
28Example:
29	/* numa node 0 */
30	numa-node-id = <0>;
31
32	/* numa node 1 */
33	numa-node-id = <1>;
34
35==============================================================================
363 - distance-map
37==============================================================================
38
39The optional device tree node distance-map describes the relative
40distance (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
62Example:
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==============================================================================
1064 - Empty memory nodes
107==============================================================================
108
109Empty memory nodes, which no memory resides in, are allowed. There are no
110device nodes for these empty memory nodes. However, the NUMA node IDs and
111distance maps are still valid and memory may be added into them through
112hotplug afterwards.
113
114Example:
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==============================================================================
1505 - Example dts
151==============================================================================
152
153Dual socket system consists of 2 boards connected through ccn bus and
154each 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	};
320