.\" Copyright 2003,2004 Andi Kleen, SuSE Labs.
.\" and Copyright 2007 Lee Schermerhorn, Hewlett Packard
.\"
+.\" %%%LICENSE_START(VERBATIM_PROF)
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
+.\" %%%LICENSE_END
.\"
.\" 2006-02-03, mtk, substantial wording changes and other improvements
.\" 2007-08-27, Lee Schermerhorn <Lee.Schermerhorn@hp.com>
.\" more precise specification of behavior.
.\"
-.TH MBIND 2 2008-04-22 Linux "Linux Programmer's Manual"
+.\" FIXME
+.\" Linux 3.8 added MPOL_MF_LAZY, which needs to be documented.
+.\" Does it also apply for move_pages()?
+.\"
+.\" commit b24f53a0bea38b266d219ee651b22dba727c44ae
+.\" Author: Lee Schermerhorn <lee.schermerhorn@hp.com>
+.\" Date: Thu Oct 25 14:16:32 2012 +0200
+.\"
+.TH MBIND 2 2021-03-22 "Linux man-pages (unreleased)" "Linux Programmer's Manual"
.SH NAME
-mbind \- Set memory policy for a memory range
+mbind \- set memory policy for a memory range
+.SH LIBRARY
+NUMA (Non-Uniform Memory Access) policy library
+.RI ( libnuma ", " \-lnuma )
.SH SYNOPSIS
.nf
.B "#include <numaif.h>"
-.sp
-.BI "int mbind(void *" addr ", unsigned long " len ", int " mode ,
-.BI " unsigned long *" nodemask ", unsigned long " maxnode ,
-.BI " unsigned " flags );
-.sp
-Link with \fI\-lnuma\fP
+.PP
+.BI "long mbind(void *" addr ", unsigned long " len ", int " mode ,
+.BI " const unsigned long *" nodemask ", unsigned long " maxnode ,
+.BI " unsigned int " flags );
.fi
.SH DESCRIPTION
.BR mbind ()
and continuing for
.I len
bytes.
-The memory of a NUMA machine is divided into multiple nodes.
The memory policy defines from which node memory is allocated.
-
+.PP
If the memory range specified by the
.IR addr " and " len
arguments includes an "anonymous" region of memory\(emthat is
.BR mmap (2)
system call with the
.BR MAP_ANONYMOUS \(emor
-a memory mapped file, mapped using the
+a memory-mapped file, mapped using the
.BR mmap (2)
system call with the
.B MAP_PRIVATE
-flag, pages will only be allocated according to the specified
-policy when the application writes [stores] to the page.
+flag, pages will be allocated only according to the specified
+policy when the application writes (stores) to the page.
For anonymous regions, an initial read access will use a shared
page in the kernel containing all zeros.
For a file mapped with
.BR MAP_PRIVATE ,
an initial read access will allocate pages according to the
-process policy of the process that causes the page to be allocated.
-This may not be the process that called
+memory policy of the thread that causes the page to be allocated.
+This may not be the thread that called
.BR mbind ().
-
+.PP
The specified policy will be ignored for any
.B MAP_SHARED
mappings in the specified memory range.
-Rather the pages will be allocated according to the process policy
-of the process that caused the page to be allocated.
-Again, this may not be the process that called
+Rather the pages will be allocated according to the memory policy
+of the thread that caused the page to be allocated.
+Again, this may not be the thread that called
.BR mbind ().
-
+.PP
If the specified memory range includes a shared memory region
created using the
.BR shmget (2)
.BR shmat (2)
system call,
pages allocated for the anonymous or shared memory region will
-be allocated according to the policy specified, regardless which
+be allocated according to the policy specified, regardless of which
process attached to the shared memory segment causes the allocation.
If, however, the shared memory region was created with the
.B SHM_HUGETLB
flag,
the huge pages will be allocated according to the policy specified
-only if the page allocation is caused by the task that calls
+only if the page allocation is caused by the process that calls
.BR mbind ()
for that region.
-
+.PP
By default,
.BR mbind ()
-only has an effect for new allocations; if the pages inside
+has an effect only for new allocations; if the pages inside
the range have been already touched before setting the policy,
then the policy has no effect.
This default behavior may be overridden by the
and
.B MPOL_MF_MOVE_ALL
flags described below.
-
+.PP
The
.I mode
argument must specify one of
.BR MPOL_DEFAULT ,
.BR MPOL_BIND ,
-.B MPOL_INTERLEAVE
+.BR MPOL_INTERLEAVE ,
+.BR MPOL_PREFERRED ,
or
-.BR MPOL_PREFERRED .
+.B MPOL_LOCAL
+(which are described in detail below).
All policy modes except
.B MPOL_DEFAULT
-require the caller to specify via the
+require the caller to specify the node or nodes to which the mode applies,
+via the
+.I nodemask
+argument.
+.PP
+The
+.I mode
+argument may also include an optional
+.IR "mode flag" .
+The supported
+.I "mode flags"
+are:
+.TP
+.BR MPOL_F_STATIC_NODES " (since Linux-2.6.26)"
+A nonempty
.I nodemask
-parameter,
-the node or nodes to which the mode applies.
-
+specifies physical node IDs.
+Linux does not remap the
.I nodemask
-points to a bitmask of nodes containing up to
+when the thread moves to a different cpuset context,
+nor when the set of nodes allowed by the thread's
+current cpuset context changes.
+.TP
+.BR MPOL_F_RELATIVE_NODES " (since Linux-2.6.26)"
+A nonempty
+.I nodemask
+specifies node IDs that are relative to the set of
+node IDs allowed by the thread's current cpuset.
+.PP
+.I nodemask
+points to a bit mask of nodes containing up to
.I maxnode
bits.
The bit mask size is rounded to the next multiple of
.IR "sizeof(unsigned long)" ,
-but the kernel will only use bits up to
+but the kernel will use bits only up to
.IR maxnode .
A NULL value of
.I nodemask
the
.I nodemask
argument is ignored.
-
+Where a
+.I nodemask
+is required, it must contain at least one node that is on-line,
+allowed by the thread's current cpuset context
+(unless the
+.B MPOL_F_STATIC_NODES
+mode flag is specified),
+and contains memory.
+.PP
The
+.I mode
+argument must include one of the following values:
+.TP
.B MPOL_DEFAULT
-mode specifies that the default policy should be used.
+This mode requests that any nondefault policy be removed,
+restoring default behavior.
When applied to a range of memory via
.BR mbind (),
-this means to use the process policy,
+this means to use the thread memory policy,
which may have been set with
.BR set_mempolicy (2).
-If the mode of the process policy is also
+If the mode of the thread memory policy is also
.BR MPOL_DEFAULT ,
the system-wide default policy will be used.
-The system-wide default policy will allocate
+The system-wide default policy allocates
pages on the node of the CPU that triggers the allocation.
For
.BR MPOL_DEFAULT ,
and
.I maxnode
arguments must be specify the empty set of nodes.
-
-The
+.TP
.B MPOL_BIND
-mode specifies a strict policy that restricts memory allocation to
+This mode specifies a strict policy that restricts memory allocation to
the nodes specified in
.IR nodemask .
If
.I nodemask
specifies more than one node, page allocations will come from
+the node with sufficient free memory that is closest to
+the node where the allocation takes place.
+Pages will not be allocated from any node not specified in the
+IR nodemask .
+(Before Linux 2.6.26,
+.\" commit 19770b32609b6bf97a3dece2529089494cbfc549
+page allocations came from
the node with the lowest numeric node ID first, until that node
-contains no free memory.
-Allocations will then come from the node with the next highest
+contained no free memory.
+Allocations then came from the node with the next highest
node ID specified in
.I nodemask
-and so forth, until none of the specified nodes contain free memory.
-Pages will not be allocated from any node not specified in the
-.IR nodemask .
-
-The
+and so forth, until none of the specified nodes contained free memory.)
+.TP
.B MPOL_INTERLEAVE
-mode specifies that page allocations be interleaved across the
+This mode specifies that page allocations be interleaved across the
set of nodes specified in
.IR nodemask .
This optimizes for bandwidth instead of latency
by spreading out pages and memory accesses to those pages across
multiple nodes.
To be effective the memory area should be fairly large,
-at least 1MB or bigger with a fairly uniform access pattern.
+at least 1\ MB or bigger with a fairly uniform access pattern.
Accesses to a single page of the area will still be limited to
the memory bandwidth of a single node.
-
+.TP
.B MPOL_PREFERRED
-sets the preferred node for allocation.
+This mode sets the preferred node for allocation.
The kernel will try to allocate pages from this
node first and fall back to other nodes if the
preferred nodes is low on free memory.
.I maxnode
arguments specify the empty set, then the memory is allocated on
the node of the CPU that triggered the allocation.
-This is the only way to specify "local allocation" for a
-range of memory via
-.BR mbind ().
-
+.TP
+.BR MPOL_LOCAL " (since Linux 3.8)"
+.\" commit 479e2802d09f1e18a97262c4c6f8f17ae5884bd8
+.\" commit f2a07f40dbc603c15f8b06e6ec7f768af67b424f
+This mode specifies "local allocation"; the memory is allocated on
+the node of the CPU that triggered the allocation (the "local node").
+The
+.I nodemask
+and
+.I maxnode
+arguments must specify the empty set.
+If the "local node" is low on free memory,
+the kernel will try to allocate memory from other nodes.
+The kernel will allocate memory from the "local node"
+whenever memory for this node is available.
+If the "local node" is not allowed by the thread's current cpuset context,
+the kernel will try to allocate memory from other nodes.
+The kernel will allocate memory from the "local node" whenever
+it becomes allowed by the thread's current cpuset context.
+By contrast,
+.B MPOL_DEFAULT
+reverts to the memory policy of the thread (which may be set via
+.BR set_mempolicy (2));
+that policy may be something other than "local allocation".
+.PP
If
.B MPOL_MF_STRICT
is passed in
.I flags
and
-.I policy
+.I mode
is not
.BR MPOL_DEFAULT ,
-then the call will fail with the error
+then the call fails with the error
.B EIO
if the existing pages in the memory range don't follow the policy.
.\" According to the kernel code, the following is not true
.\" --Lee Schermerhorn
.\" In 2.6.16 or later the kernel will also try to move pages
.\" to the requested node with this flag.
-
+.PP
If
.B MPOL_MF_MOVE
is specified in
Pages that are shared with other processes will not be moved.
If
.B MPOL_MF_STRICT
-is also specified, then the call will fail with the error
+is also specified, then the call fails with the error
.B EIO
if some pages could not be moved.
-
+.PP
If
.B MPOL_MF_MOVE_ALL
is passed in
.IR flags ,
then the kernel will attempt to move all existing pages in the memory range
regardless of whether other processes use the pages.
-The calling process must be privileged
+The calling thread must be privileged
.RB ( CAP_SYS_NICE )
to use this flag.
If
.B MPOL_MF_STRICT
-is also specified, then the call will fail with the error
+is also specified, then the call fails with the error
.B EIO
if some pages could not be moved.
.\" ---------------------------------------------------------------
.\" I think I got all of the error returns. --Lee Schermerhorn
.TP
.B EFAULT
-Part of all of the memory range specified by
+Part or all of the memory range specified by
.I nodemask
and
.I maxnode
points outside your accessible address space.
-Or, there was an unmapped hole in the specified memory range.
+Or, there was an unmapped hole in the specified memory range specified by
+.I addr
+and
+.IR len .
.TP
.B EINVAL
An invalid value was specified for
.B MPOL_DEFAULT
and
.I nodemask
-specified a non-empty set;
+specified a nonempty set;
or
.I mode
is
is empty.
Or,
.I maxnode
-exceeds kernel-imposed limit.
+exceeds a kernel-imposed limit.
.\" As at 2.6.23, this limit is "a page worth of bits", e.g.,
.\" 8 * 4096 bits, assuming a 4kB page size.
Or,
.I nodemask
specifies one or more node IDs that are
-greater than the maximum supported node ID,
-or are not allowed in the calling task's context.
-.\" "calling task's context" refers to cpusets.
-.\" No man page avail to ref. --Lee Schermerhorn
+greater than the maximum supported node ID.
Or, none of the node IDs specified by
.I nodemask
-are on-line, or none of the specified nodes contain memory.
+are on-line and allowed by the thread's current cpuset context,
+or none of the specified nodes contain memory.
+Or, the
+.I mode
+argument specified both
+.B MPOL_F_STATIC_NODES
+and
+.BR MPOL_F_RELATIVE_NODES .
.TP
.B EIO
.B MPOL_MF_STRICT
.B CAP_SYS_NICE
privilege.
.\" ---------------------------------------------------------------
-.SH CONFORMING TO
+.SH VERSIONS
+The
+.BR mbind ()
+system call was added to the Linux kernel in version 2.6.7.
+.SH STANDARDS
This system call is Linux-specific.
.SH NOTES
-NUMA policy is not supported on a memory mapped file range
+For information on library support, see
+.BR numa (7).
+.PP
+NUMA policy is not supported on a memory-mapped file range
that was mapped with the
.B MAP_SHARED
flag.
-
-.B MPOL_MF_STRICT
-is ignored on huge page mappings.
-
+.PP
The
-.BR MPOL_DEFAULT ,
-mode has different effects for
+.B MPOL_DEFAULT
+mode can have different effects for
.BR mbind ()
and
.BR set_mempolicy (2).
When
.B MPOL_DEFAULT
+is specified for
+.BR set_mempolicy (2),
+the thread's memory policy reverts to the system default policy
+or local allocation.
+When
+.B MPOL_DEFAULT
is specified for a range of memory using
.BR mbind (),
any pages subsequently allocated for that range will use
-the process's policy, as set by
+the thread's memory policy, as set by
.BR set_mempolicy (2).
This effectively removes the explicit policy from the
-specified range.
-To select "local allocation" for a memory range,
+specified range, "falling back" to a possibly nondefault
+policy.
+To select explicit "local allocation" for a memory range,
specify a
.I mode
of
+.B MPOL_LOCAL
+or
.B MPOL_PREFERRED
with an empty set of nodes.
This method will work for
.BR set_mempolicy (2),
as well.
-.\" ---------------------------------------------------------------
-.SS "Versions and Library Support"
-The
-.BR mbind (),
-.BR get_mempolicy (2),
-and
-.BR set_mempolicy (2)
-system calls were added to the Linux kernel with version 2.6.7.
-They are only available on kernels compiled with
-.BR CONFIG_NUMA .
-
-You can link with
-.I \-lnuma
-to get system call definitions.
-.I libnuma
-and the required
-.I <numaif.h>
-header are available in the
-.I numactl
-package.
-
-However, applications should not use these system calls directly.
-Instead, the higher level interface provided by the
-.BR numa (3)
-functions in the
-.I numactl
-package is recommended.
-The
-.I numactl
-package is available at
-.IR ftp://ftp.suse.com/pub/people/ak/numa/ .
-The package is also included in some Linux distributions.
-Some distributions include the development library and header
-in the separate
-.I numactl-devel
-package.
-
+.PP
Support for huge page policy was added with 2.6.16.
For interleave policy to be effective on huge page mappings the
policied memory needs to be tens of megabytes or larger.
-
+.PP
+Before Linux 5.7.
+.\" commit dcf1763546d76c372f3136c8d6b2b6e77f140cf0
+.B MPOL_MF_STRICT
+was ignored on huge page mappings.
+.PP
.B MPOL_MF_MOVE
and
.B MPOL_MF_MOVE_ALL
-are only available on Linux 2.6.16 and later.
+are available only on Linux 2.6.16 and later.
.SH SEE ALSO
.BR get_mempolicy (2),
+.BR getcpu (2),
.BR mmap (2),
.BR set_mempolicy (2),
.BR shmat (2),
.BR shmget (2),
.BR numa (3),
+.BR cpuset (7),
+.BR numa (7),
.BR numactl (8)
projects / thirdparty / man-pages.git / blobdiff