Skip to contentSkip to conversation

man/man2/{mbind,set_mempolicy}.2: added mode argument MPOL_PREFERRED_MANY

PATCH In review Matthew Cassell 2 participants 3 messages Feb 21, 2025 Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 man/man2/{mbind,set_mempolicy}.2: added mode argument MPOL_PREFERRED_MANY

Browsing a header file in the kernel source and saw the memory policy enum used for mbind() and set_mempolicy() using an entry that I didn't recognize. I man 2'd both system calls and didn't see an entry for MPOL_PREFERRED_MANY. The commit on the enum entry:

linux.git b27abaccf8e8 (2021-09-02; "mm/mempolicy: add MPOL_PREFERRED_MANY for multiple preferred nodes")

The commit message gives the rationale as to why the MPOL_PREFERRED_MANY mode would be beneficial. Giving the ability to set the memory policy to target different tiers of memory over various NUMA nodes.

v0 -> v1
- changed text width from 80 to 72 characters
- added Cc tag for commit author
- improved source readability with semantic newlines
- changed mbind() to refer to set_mempolicy() to avoid unnecessary duplication

---
 man/man2/mbind.2         |  6 ++++++
 man/man2/set_mempolicy.2 | 14 ++++++++++++++
 2 files changed, 20 insertions(+)
man/man2/mbind.2 +6 -0
index fd1aca4ad..a060e1401 100644
@@ -107,6 +107,7 @@ argument must specify one of
 .BR MPOL_INTERLEAVE ,
 .BR MPOL_WEIGHTED_INTERLEAVE ,
 .BR MPOL_PREFERRED ,
+.BR MPOL_PREFERRED_MANY ,
 or
 .B MPOL_LOCAL
 (which are described in detail below).
@@ -277,6 +278,11 @@ and
 arguments specify the empty set, then the memory is allocated on
 the node of the CPU that triggered the allocation.
 .TP
+.BR MPOL_PREFERRED_MANY " (since Linux 5.15)"
+.\" commit b27abaccf8e8b012f126da0c2a1ab32723ec8b9f
+Specifies a set of nodes for allocation; see
+.BR set_mempolicy(2)
+.TP
 .BR MPOL_LOCAL " (since Linux 3.8)"
 .\" commit 479e2802d09f1e18a97262c4c6f8f17ae5884bd8
 .\" commit f2a07f40dbc603c15f8b06e6ec7f768af67b424f
man/man2/set_mempolicy.2 +14 -0
index 2d0b1da19..32c360f22 100644
@@ -65,6 +65,7 @@ argument must specify one of
 .BR MPOL_INTERLEAVE ,
 .BR MPOL_WEIGHTED_INTERLEAVE ,
 .BR MPOL_PREFERRED ,
+.BR MPOL_PREFERRED_MANY ,
 or
 .B MPOL_LOCAL
 (which are described in detail below).
@@ -234,6 +235,19 @@ arguments specify the empty set, then the policy
 specifies "local allocation"
 (like the system default policy discussed above).
 .TP
+.BR MPOL_PREFERRED_MANY " (since Linux 5.15)"
+.\" commit b27abaccf8e8b012f126da0c2a1ab32723ec8b9f
+This mode specifies a preference for nodes
+from which the kernel will try to allocate from.
+This differs from
+.BR MPOL_PREFERRED
+in that it accepts a set of nodes
+versus a single node.
+This policy is intended to benefit page allocations
+where specific memory types
+(i.e. non-volatile, high-bandwidth, or accelerator memory)
+are of greater importance than node location.
+.TP
 .BR MPOL_LOCAL " (since Linux 3.8)"
 .\" commit 479e2802d09f1e18a97262c4c6f8f17ae5884bd8
 .\" commit f2a07f40dbc603c15f8b06e6ec7f768af67b424f
Signature · 1 line
2.39.5 (Apple Git-154)
#1 lore raw

Hi Matthew,

Quoted 20 lines · Matthew Cassell

Browsing a header file in the kernel source and saw the memory policy enum used for mbind() and set_mempolicy() using an entry that I didn't recognize. I man 2'd both system calls and didn't see an entry for MPOL_PREFERRED_MANY. The commit on the enum entry:

linux.git b27abaccf8e8 (2021-09-02; "mm/mempolicy: add MPOL_PREFERRED_MANY for multiple preferred nodes")

The commit message gives the rationale as to why the MPOL_PREFERRED_MANY mode would be beneficial. Giving the ability to set the memory policy to target different tiers of memory over various NUMA nodes.

v0 -> v1
- changed text width from 80 to 72 characters
- added Cc tag for commit author
- improved source readability with semantic newlines
- changed mbind() to refer to set_mempolicy() to avoid unnecessary duplication

Quoted 2 lines

Thanks! I've applied the patch, and amended it with some minor tweaks that the CI reminded me (see comments below). Here's the final path applied:
<https://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/commit/?h=contrib&id=fe7e094e78139a4ac5ee31b2321b77041c725794>

Quoted 18 lines
---
 man/man2/mbind.2         |  6 ++++++
 man/man2/set_mempolicy.2 | 14 ++++++++++++++
 2 files changed, 20 insertions(+)
man/man2/mbind.2 +1 -0
index fd1aca4ad..a060e1401 100644
@@ -107,6 +107,7 @@ argument must specify one of
 .BR MPOL_INTERLEAVE ,
 .BR MPOL_WEIGHTED_INTERLEAVE ,
 .BR MPOL_PREFERRED ,
+.BR MPOL_PREFERRED_MANY ,
 or
 .B MPOL_LOCAL
 (which are described in detail below).

man/man2/mbind.2 and · line 284

Quoted 7 lines
man/man2/mbind.2 +4 -0
@@ -277,6 +278,11 @@ and
 arguments specify the empty set, then the memory is allocated on
 the node of the CPU that triggered the allocation.
 .TP
+.BR MPOL_PREFERRED_MANY " (since Linux 5.15)"
+.\" commit b27abaccf8e8b012f126da0c2a1ab32723ec8b9f
+Specifies a set of nodes for allocation; see
+.BR set_mempolicy(2)

You missed a space before the (2).

Quoted 17 lines
man/man2/mbind.2 +1 -0
+.TP
 .BR MPOL_LOCAL " (since Linux 3.8)"
 .\" commit 479e2802d09f1e18a97262c4c6f8f17ae5884bd8
 .\" commit f2a07f40dbc603c15f8b06e6ec7f768af67b424f
man/man2/set_mempolicy.2 +1 -0
index 2d0b1da19..32c360f22 100644
@@ -65,6 +65,7 @@ argument must specify one of
 .BR MPOL_INTERLEAVE ,
 .BR MPOL_WEIGHTED_INTERLEAVE ,
 .BR MPOL_PREFERRED ,
+.BR MPOL_PREFERRED_MANY ,
 or
 .B MPOL_LOCAL
 (which are described in detail below).

man/man2/set_mempolicy.2 arguments specify the empty set, then the policy · line 243

Quoted 9 lines
man/man2/set_mempolicy.2 +6 -0
@@ -234,6 +235,19 @@ arguments specify the empty set, then the policy
 specifies "local allocation"
 (like the system default policy discussed above).
 .TP
+.BR MPOL_PREFERRED_MANY " (since Linux 5.15)"
+.\" commit b27abaccf8e8b012f126da0c2a1ab32723ec8b9f
+This mode specifies a preference for nodes
+from which the kernel will try to allocate from.
+This differs from
+.BR MPOL_PREFERRED

This should be s/BR/B/

Have a lovely night!
Alex

Quoted 14 lines
man/man2/set_mempolicy.2 +7 -0
+in that it accepts a set of nodes
+versus a single node.
+This policy is intended to benefit page allocations
+where specific memory types
+(i.e. non-volatile, high-bandwidth, or accelerator memory)
+are of greater importance than node location.
+.TP
 .BR MPOL_LOCAL " (since Linux 3.8)"
 .\" commit 479e2802d09f1e18a97262c4c6f8f17ae5884bd8
 .\" commit f2a07f40dbc603c15f8b06e6ec7f768af67b424f
Signature · 1 line
2.39.5 (Apple Git-154)
Signature · 1 line
<https://www.alejandro-colomar.es/>
#2 lore raw

Thank you Alejandro. Have a good one.

-Matt C

Quoted 110 lines · Alejandro Colomar

Hi Matthew,

Quoted 20 lines · Matthew Cassell

Browsing a header file in the kernel source and saw the memory policy enum used for mbind() and set_mempolicy() using an entry that I didn't recognize. I man 2'd both system calls and didn't see an entry for MPOL_PREFERRED_MANY. The commit on the enum entry:

linux.git b27abaccf8e8 (2021-09-02; "mm/mempolicy: add MPOL_PREFERRED_MANY for multiple preferred nodes")

The commit message gives the rationale as to why the MPOL_PREFERRED_MANY mode would be beneficial. Giving the ability to set the memory policy to target different tiers of memory over various NUMA nodes.

v0 -> v1
- changed text width from 80 to 72 characters
- added Cc tag for commit author
- improved source readability with semantic newlines
- changed mbind() to refer to set_mempolicy() to avoid unnecessary duplication

Quoted 2 lines

Thanks! I've applied the patch, and amended it with some minor tweaks that the CI reminded me (see comments below). Here's the final path applied:
<https://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/commit/?h=contrib&id=fe7e094e78139a4ac5ee31b2321b77041c725794>

Quoted 18 lines
---
 man/man2/mbind.2         |  6 ++++++
 man/man2/set_mempolicy.2 | 14 ++++++++++++++
 2 files changed, 20 insertions(+)
man/man2/mbind.2 +1 -0
index fd1aca4ad..a060e1401 100644
@@ -107,6 +107,7 @@ argument must specify one of
 .BR MPOL_INTERLEAVE ,
 .BR MPOL_WEIGHTED_INTERLEAVE ,
 .BR MPOL_PREFERRED ,
+.BR MPOL_PREFERRED_MANY ,
 or
 .B MPOL_LOCAL
 (which are described in detail below).

man/man2/mbind.2 and · line 284

Quoted 7 lines
man/man2/mbind.2 +4 -0
@@ -277,6 +278,11 @@ and
 arguments specify the empty set, then the memory is allocated on
 the node of the CPU that triggered the allocation.
 .TP
+.BR MPOL_PREFERRED_MANY " (since Linux 5.15)"
+.\" commit b27abaccf8e8b012f126da0c2a1ab32723ec8b9f
+Specifies a set of nodes for allocation; see
+.BR set_mempolicy(2)

You missed a space before the (2).

Quoted 17 lines
man/man2/mbind.2 +1 -0
+.TP
 .BR MPOL_LOCAL " (since Linux 3.8)"
 .\" commit 479e2802d09f1e18a97262c4c6f8f17ae5884bd8
 .\" commit f2a07f40dbc603c15f8b06e6ec7f768af67b424f
man/man2/set_mempolicy.2 +1 -0
index 2d0b1da19..32c360f22 100644
@@ -65,6 +65,7 @@ argument must specify one of
 .BR MPOL_INTERLEAVE ,
 .BR MPOL_WEIGHTED_INTERLEAVE ,
 .BR MPOL_PREFERRED ,
+.BR MPOL_PREFERRED_MANY ,
 or
 .B MPOL_LOCAL
 (which are described in detail below).

man/man2/set_mempolicy.2 arguments specify the empty set, then the policy · line 243

Quoted 9 lines
man/man2/set_mempolicy.2 +6 -0
@@ -234,6 +235,19 @@ arguments specify the empty set, then the policy
 specifies "local allocation"
 (like the system default policy discussed above).
 .TP
+.BR MPOL_PREFERRED_MANY " (since Linux 5.15)"
+.\" commit b27abaccf8e8b012f126da0c2a1ab32723ec8b9f
+This mode specifies a preference for nodes
+from which the kernel will try to allocate from.
+This differs from
+.BR MPOL_PREFERRED

This should be s/BR/B/

Have a lovely night!
Alex

Quoted 11 lines
man/man2/set_mempolicy.2 +7 -1
+in that it accepts a set of nodes
+versus a single node.
+This policy is intended to benefit page allocations
+where specific memory types
+(i.e. non-volatile, high-bandwidth, or accelerator memory)
+are of greater importance than node location.
+.TP
 .BR MPOL_LOCAL " (since Linux 3.8)"
 .\" commit 479e2802d09f1e18a97262c4c6f8f17ae5884bd8
 .\" commit f2a07f40dbc603c15f8b06e6ec7f768af67b424f
--
Quoted 3 lines

2.39.5 (Apple Git-154)

--
<https://www.alejandro-colomar.es/>