admin-guide/mm/numa_memory_policy.rst

10 supported platforms with Non-Uniform Memory Access architectures since 2.4.?.
16 (``Documentation/admin-guide/cgroup-v1/cpusets.rst``)
19 programming interface that a NUMA-aware application can take advantage of.  When
28 ------------------------
41 	not to overload the initial boot node with boot-time
45 	this is an optional, per-task policy.  When defined for a
61 	In a multi-threaded task, task policies apply only to the thread
75 	A "VMA" or "Virtual Memory Area" refers to a range of a task's
83 	this region of the address space.  Any regions of the task's
98 	  mapping-- i.e., at Copy-On-Write.
101 	  virtual address space--a.k.a. threads--independent of when
104 	  region of a task's address space, and because the address
106 	  are NOT inheritable across exec().  Thus, only NUMA-aware
109 	* A task may install a new VMA policy on a sub-range of a
126 	policies--using the mbind() system call specifying a range of
129 	range of a task's address space, shared policies apply
138 	support allocation at fault time--a.k.a lazy allocation--so hugetlbfs
161 -----------------------------
163 A NUMA memory policy consists of a "mode", optional mode flags, and
164 an optional set of nodes.  The mode determines the behavior of the
165 policy, the optional mode flags determine the behavior of the mode,
175 Default Mode--MPOL_DEFAULT
176 	This mode is only used in the memory policy APIs.  Internally,
178 	policy scopes.  Any existing non-default policy will simply be
187 	When specified in one of the memory policy APIs, the Default mode
191 	be non-empty.
194 	This mode specifies that memory must come from the set of
200 	This mode specifies that the allocation should be attempted
206 	Internally, the Preferred policy uses a single node--the
208 	mode flag MPOL_F_LOCAL is set, the preferred_node is ignored
216 	mode.  If an empty nodemask is passed, the policy cannot use
221 	This mode specifies that page allocations be interleaved, on a
223 	This mode also behaves slightly differently, based on the
227 	Interleave mode indexes the set of nodes specified by the
236 	For allocation of page cache pages, Interleave mode indexes
244 	interleaved system default policy works in this mode.
247 	This mode specifies that the allocation should be preferably
253 NUMA memory policy supports the following optional mode flags:
257 	the user should not be remapped if the task or VMA's set of allowed
266 	With this flag, if the user-specified nodes overlap with the
267 	nodes allowed by the task's cpuset, then the memory policy is
272 	mems 1-3 that sets an Interleave policy over the same set.  If
273 	the cpuset's mems change to 3-5, the Interleave will now occur
275 	3 is allowed from the user's nodemask, the "interleave" only
276 	occurs over that node.  If no nodes from the user's nodemask are
286 	by the user will be mapped relative to the set of the task or VMA's
287 	set of allowed nodes.  The kernel stores the user-passed nodemask,
295 	preserve the relative nature of the user's passed nodemask to its
297 	1,3,5 may be remapped to 7-9 and then to 1-3 if the set of
301 	the user's passed nodemask are relative to the set of allowed
302 	nodes.  In other words, if nodes 0, 2, and 4 are set in the user's
306 	relative to task or VMA's set of allowed nodes.
308 	If the user's nodemask includes nodes that are outside the range
310 	the user's nodemask when the set of allowed nodes is only 0-3),
315 	mems 2-5 that sets an Interleave policy over the same set with
316 	MPOL_F_RELATIVE_NODES.  If the cpuset's mems change to 3-7, the
317 	interleave now occurs over nodes 3,5-7.  If the cpuset's mems
318 	then change to 0,2-3,5, then the interleave occurs over nodes
319 	0,2-3,5.
325 	memory nodes 0 to N-1, where N is the number of memory nodes the
327 	set of memory nodes allowed by the task's cpuset, as that may
347 structure, another reference is added, as the task's reference will be dropped
350 During run-time "usage" of the policy, we attempt to minimize atomic operations
358 2) examination of the policy to determine the policy mode and associated node
371    target task's task policy nor vma policies because we always acquire the
372    task's mm's mmap_lock for read during the query.  The set_mempolicy() and
391    used for non-shared policies.  For this reason, shared policies are marked
392    as such, and the extra reference is dropped "conditionally"--i.e., only
410 always affect only the calling task, the calling task's address space, or
411 some shared object mapped into the calling task's address space.
417    prefix, are defined in <linux/syscalls.h>; the mode and flag
422 	long set_mempolicy(int mode, const unsigned long *nmask,
425 Set's the calling task's "task/process memory policy" to mode
426 specified by the 'mode' argument and the set of nodes defined by
428 'maxnode' ids.  Optional mode flags may be passed by combining the
429 'mode' argument with the flag (for example: MPOL_INTERLEAVE |
437 	long get_mempolicy(int *mode,
448 Install VMA/Shared Policy for a Range of Task's Address Space::
450 	long mbind(void *start, unsigned long len, int mode,
454 mbind() installs the policy specified by (mode, nmask, maxnodes) as a
455 VMA policy for the range of the calling task's address space specified
461 Set home node for a Range of Task's Address Spacec::
468 task's address range. The system call updates the home node only for the existing
486 The numactl(8) tool is packaged with the run-time version of the library
488 package the headers and compile-time libraries in a separate development
503 installed.  If MPOL_F_RELATIVE_NODES is used, the policy's nodes are mapped
504 onto and folded into the task's set of allowed nodes as previously described.