[PATCH v2] man2: add MPOL_WEIGHTED_INTERLEAVE documentation

[PATCH v2] man2: add MPOL_WEIGHTED_INTERLEAVE documentation

[Svetly Todorov]

---
Adding documentation for the new MPOL_WEIGHTED_INTERLEAVE mode in the same
manpages that mention MPOL_INTERLEAVE; namely, mbind(2), set_mempolicy(2),
and get_mempolicy(2).

Descriptions were based on the changes introduced in this patch: 
https://lore.kernel.org/all/20240202170238.90004-4-gregory.price@memverge.com/

Which was upstreamed to 6.9 here:
https://lore.kernel.org/linux-mm/20240313200532.34e4cff216acd3db8def4637@linux-foundation.org/

To: alx@kernel.org
Cc: linux-man@vger.kernel.org
Cc: gregory.price@memverge.com
Cc: ying.huang@intel.com
Signed-off-by: Svetly Todorov <svetly.todorov@memverge.com>

Changes in v2:
- make flag documentation implementation-agnostic
- Link to v1: https://lore.kernel.org/r/20240314-weighted_interleave-v1-1-ce85d64db0d4@memverge.com
---
 man2/get_mempolicy.2 |  8 ++++++--
 man2/mbind.2         | 12 ++++++++++++
 man2/set_mempolicy.2 | 12 ++++++++++++
 3 files changed, 30 insertions(+), 2 deletions(-)

diff --git a/man2/get_mempolicy.2 b/man2/get_mempolicy.2
index 5248f04ba..03550331d 100644
--- a/man2/get_mempolicy.2
+++ b/man2/get_mempolicy.2
@@ -137,7 +137,9 @@ specifies
 but not
 .BR MPOL_F_ADDR ,
 and the thread's current policy is
-.BR MPOL_INTERLEAVE ,
+.BR MPOL_INTERLEAVE
+or
+.BR MPOL_WEIGHTED_INTERLEAVE ,
 then
 .BR get_mempolicy ()
 will return in the location pointed to by a non-NULL
@@ -206,7 +208,9 @@ specified
 but not
 .B MPOL_F_ADDR
 and the current thread policy is not
-.BR MPOL_INTERLEAVE .
+.BR MPOL_INTERLEAVE
+or
+.BR MPOL_WEIGHTED_INTERLEAVE .
 Or,
 .I flags
 specified
diff --git a/man2/mbind.2 b/man2/mbind.2
index b0e961f9c..4673f077e 100644
--- a/man2/mbind.2
+++ b/man2/mbind.2
@@ -105,6 +105,7 @@ argument must specify one of
 .BR MPOL_DEFAULT ,
 .BR MPOL_BIND ,
 .BR MPOL_INTERLEAVE ,
+.BR MPOL_WEIGHTED_INTERLEAVE ,
 .BR MPOL_PREFERRED ,
 or
 .B MPOL_LOCAL
@@ -243,6 +244,17 @@ 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_WEIGHTED_INTERLEAVE
+This mode interleaves page allocations across the nodes specified in
+.I nodemask
+according to the weights in /sys/kernel/mm/mempolicy/weighted_interleave.
+For example, if bits 0, 2, and 5 are raised in
+.IR nodemask ,
+and the contents of /sys/kernel/mm/mempolicy/weighted_interleave/node0,
+/sys/.../node2, and /sys/.../node5 are 4, 7, and 9, respectively,
+then pages in this region will be allocated on nodes 0, 2, and 5
+in a 4:7:9 ratio.
+.TP
 .B MPOL_PREFERRED
 This mode sets the preferred node for allocation.
 The kernel will try to allocate pages from this
diff --git a/man2/set_mempolicy.2 b/man2/set_mempolicy.2
index fc3ad9df8..e2f5e5bf8 100644
--- a/man2/set_mempolicy.2
+++ b/man2/set_mempolicy.2
@@ -63,6 +63,7 @@ argument must specify one of
 .BR MPOL_DEFAULT ,
 .BR MPOL_BIND ,
 .BR MPOL_INTERLEAVE ,
+.BR MPOL_WEIGHTED_INTERLEAVE ,
 .BR MPOL_PREFERRED ,
 or
 .B MPOL_LOCAL
@@ -199,6 +200,17 @@ the memory bandwidth of a single node.
 .\" To be effective the memory area should be fairly large,
 .\" at least 1 MB or bigger.
 .TP
+.B MPOL_WEIGHTED_INTERLEAVE
+This mode interleaves page allocations across the nodes specified in
+.I nodemask
+according to the weights in /sys/kernel/mm/mempolicy/weighted_interleave.
+For example, if bits 0, 2, and 5 are raised in
+.IR nodemask ,
+and the contents of /sys/kernel/mm/mempolicy/weighted_interleave/node0,
+/sys/.../node2, and /sys/.../node5 are 4, 7, and 9, respectively,
+then pages in this region will be allocated on nodes 0, 2, and 5
+in a 4:7:9 ratio.
+.TP
 .B MPOL_PREFERRED
 This mode sets the preferred node for allocation.
 The kernel will try to allocate pages from this node first

---
base-commit: a4ea5f76215dcf1d8d017eb65ab12919ccf09f3f
change-id: 20240313-weighted_interleave-e8141ed754f9

Best regards,
-- 
Svetly Todorov <svetly.todorov@memverge.com>

Re: [PATCH v2] man2: add MPOL_WEIGHTED_INTERLEAVE documentation

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 5327 bytes --]

Hi Svetly,

On Fri, Mar 15, 2024 at 11:02:06AM -0700, Svetly Todorov wrote:
> ---
> Adding documentation for the new MPOL_WEIGHTED_INTERLEAVE mode in the same
> manpages that mention MPOL_INTERLEAVE; namely, mbind(2), set_mempolicy(2),
> and get_mempolicy(2).
> 
> Descriptions were based on the changes introduced in this patch: 
> https://lore.kernel.org/all/20240202170238.90004-4-gregory.price@memverge.com/
> 
> Which was upstreamed to 6.9 here:
> https://lore.kernel.org/linux-mm/20240313200532.34e4cff216acd3db8def4637@linux-foundation.org/
> 
> To: alx@kernel.org
> Cc: linux-man@vger.kernel.org
> Cc: gregory.price@memverge.com
> Cc: ying.huang@intel.com
> Signed-off-by: Svetly Todorov <svetly.todorov@memverge.com>
> 
> Changes in v2:
> - make flag documentation implementation-agnostic
> - Link to v1: https://lore.kernel.org/r/20240314-weighted_interleave-v1-1-ce85d64db0d4@memverge.com
> ---
>  man2/get_mempolicy.2 |  8 ++++++--
>  man2/mbind.2         | 12 ++++++++++++
>  man2/set_mempolicy.2 | 12 ++++++++++++
>  3 files changed, 30 insertions(+), 2 deletions(-)
> 
> diff --git a/man2/get_mempolicy.2 b/man2/get_mempolicy.2
> index 5248f04ba..03550331d 100644
> --- a/man2/get_mempolicy.2
> +++ b/man2/get_mempolicy.2
> @@ -137,7 +137,9 @@ specifies
>  but not
>  .BR MPOL_F_ADDR ,
>  and the thread's current policy is
> -.BR MPOL_INTERLEAVE ,
> +.BR MPOL_INTERLEAVE
> +or
> +.BR MPOL_WEIGHTED_INTERLEAVE ,
>  then
>  .BR get_mempolicy ()
>  will return in the location pointed to by a non-NULL
> @@ -206,7 +208,9 @@ specified
>  but not
>  .B MPOL_F_ADDR
>  and the current thread policy is not
> -.BR MPOL_INTERLEAVE .
> +.BR MPOL_INTERLEAVE
> +or
> +.BR MPOL_WEIGHTED_INTERLEAVE .
>  Or,
>  .I flags
>  specified
> diff --git a/man2/mbind.2 b/man2/mbind.2
> index b0e961f9c..4673f077e 100644
> --- a/man2/mbind.2
> +++ b/man2/mbind.2
> @@ -105,6 +105,7 @@ argument must specify one of
>  .BR MPOL_DEFAULT ,
>  .BR MPOL_BIND ,
>  .BR MPOL_INTERLEAVE ,
> +.BR MPOL_WEIGHTED_INTERLEAVE ,
>  .BR MPOL_PREFERRED ,
>  or
>  .B MPOL_LOCAL
> @@ -243,6 +244,17 @@ 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_WEIGHTED_INTERLEAVE
> +This mode interleaves page allocations across the nodes specified in
> +.I nodemask
> +according to the weights in /sys/kernel/mm/mempolicy/weighted_interleave.

Path names should go in italics.  See groff_man(7):

     .I [text]
            Set  text in an italic or oblique face.  If no argument is
            given, a one‐line input trap is planted; text on the  next
            line,  which can be further formatted with a macro, is set
            in an italic or oblique face.

            Use italics for file and path names, [...]
                    An exception involves variant text  in  a  context
            already  typeset  in  italics,  such as file or path names
            with replaceable components; in  such  cases,  follow  the
            convention  of  mathematical  typography:  set the file or
            path name in italics as usual but use roman for the  vari‐
            ant  part  (see  .IR  and .RI below), and italics again in
            running roman text when referring to the variant material.

Have a lovely day!
Alex

> +For example, if bits 0, 2, and 5 are raised in
> +.IR nodemask ,
> +and the contents of /sys/kernel/mm/mempolicy/weighted_interleave/node0,
> +/sys/.../node2, and /sys/.../node5 are 4, 7, and 9, respectively,
> +then pages in this region will be allocated on nodes 0, 2, and 5
> +in a 4:7:9 ratio.
> +.TP
>  .B MPOL_PREFERRED
>  This mode sets the preferred node for allocation.
>  The kernel will try to allocate pages from this
> diff --git a/man2/set_mempolicy.2 b/man2/set_mempolicy.2
> index fc3ad9df8..e2f5e5bf8 100644
> --- a/man2/set_mempolicy.2
> +++ b/man2/set_mempolicy.2
> @@ -63,6 +63,7 @@ argument must specify one of
>  .BR MPOL_DEFAULT ,
>  .BR MPOL_BIND ,
>  .BR MPOL_INTERLEAVE ,
> +.BR MPOL_WEIGHTED_INTERLEAVE ,
>  .BR MPOL_PREFERRED ,
>  or
>  .B MPOL_LOCAL
> @@ -199,6 +200,17 @@ the memory bandwidth of a single node.
>  .\" To be effective the memory area should be fairly large,
>  .\" at least 1 MB or bigger.
>  .TP
> +.B MPOL_WEIGHTED_INTERLEAVE
> +This mode interleaves page allocations across the nodes specified in
> +.I nodemask
> +according to the weights in /sys/kernel/mm/mempolicy/weighted_interleave.
> +For example, if bits 0, 2, and 5 are raised in
> +.IR nodemask ,
> +and the contents of /sys/kernel/mm/mempolicy/weighted_interleave/node0,
> +/sys/.../node2, and /sys/.../node5 are 4, 7, and 9, respectively,
> +then pages in this region will be allocated on nodes 0, 2, and 5
> +in a 4:7:9 ratio.
> +.TP
>  .B MPOL_PREFERRED
>  This mode sets the preferred node for allocation.
>  The kernel will try to allocate pages from this node first
> 
> ---
> base-commit: a4ea5f76215dcf1d8d017eb65ab12919ccf09f3f
> change-id: 20240313-weighted_interleave-e8141ed754f9
> 
> Best regards,
> -- 
> Svetly Todorov <svetly.todorov@memverge.com>
> 

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v2] man2: add MPOL_WEIGHTED_INTERLEAVE documentation

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 1088 bytes --]

On Fri, Mar 15, 2024 at 08:22:05PM +0100, Alejandro Colomar wrote:
> 
> Path names should go in italics.  See groff_man(7):

Oops, that's groff_man_style(7), actually.

>      .I [text]
>             Set  text in an italic or oblique face.  If no argument is
>             given, a one‐line input trap is planted; text on the  next
>             line,  which can be further formatted with a macro, is set
>             in an italic or oblique face.
> 
>             Use italics for file and path names, [...]
>                     An exception involves variant text  in  a  context
>             already  typeset  in  italics,  such as file or path names
>             with replaceable components; in  such  cases,  follow  the
>             convention  of  mathematical  typography:  set the file or
>             path name in italics as usual but use roman for the  vari‐
>             ant  part  (see  .IR  and .RI below), and italics again in
>             running roman text when referring to the variant material.

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v2] man2: add MPOL_WEIGHTED_INTERLEAVE documentation

[Svetly Todorov]

Hey Alex,

> On Mar 15, 2024, at 12:22 PM, Alejandro Colomar <alx@kernel.org> wrote:
> 
> On Fri, Mar 15, 2024 at 08:22:05PM +0100, Alejandro Colomar wrote:
>> 
>> Path names should go in italics.  See groff_man(7):
> 
> Oops, that's groff_man_style(7), actually.

My bad! I should have sought out the style guide. Will fix in v3.

Svetly

Re: [PATCH v2] man2: add MPOL_WEIGHTED_INTERLEAVE documentation

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 441 bytes --]

Hey Svetly,

On Fri, Mar 15, 2024 at 11:00:58PM +0000, Svetly Todorov wrote:
> >> Path names should go in italics.  See groff_man(7):
> > 
> > Oops, that's groff_man_style(7), actually.
> 
> My bad! I should have sought out the style guide. Will fix in v3.

Heh, that's a long page to read.  I wouldn't blame anyone for not
reading it.  :)

Have a lovely night!
Alex

> 
> Svetly

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v2] man2: add MPOL_WEIGHTED_INTERLEAVE documentation

[Huang, Ying]

Svetly Todorov <svetly.todorov@memverge.com> writes:

> ---
> Adding documentation for the new MPOL_WEIGHTED_INTERLEAVE mode in the same
> manpages that mention MPOL_INTERLEAVE; namely, mbind(2), set_mempolicy(2),
> and get_mempolicy(2).
>
> Descriptions were based on the changes introduced in this patch: 
> https://lore.kernel.org/all/20240202170238.90004-4-gregory.price@memverge.com/
>
> Which was upstreamed to 6.9 here:
> https://lore.kernel.org/linux-mm/20240313200532.34e4cff216acd3db8def4637@linux-foundation.org/
>
> To: alx@kernel.org
> Cc: linux-man@vger.kernel.org
> Cc: gregory.price@memverge.com
> Cc: ying.huang@intel.com
> Signed-off-by: Svetly Todorov <svetly.todorov@memverge.com>
>
> Changes in v2:
> - make flag documentation implementation-agnostic
> - Link to v1: https://lore.kernel.org/r/20240314-weighted_interleave-v1-1-ce85d64db0d4@memverge.com
> ---
>  man2/get_mempolicy.2 |  8 ++++++--
>  man2/mbind.2         | 12 ++++++++++++
>  man2/set_mempolicy.2 | 12 ++++++++++++
>  3 files changed, 30 insertions(+), 2 deletions(-)
>
> diff --git a/man2/get_mempolicy.2 b/man2/get_mempolicy.2
> index 5248f04ba..03550331d 100644
> --- a/man2/get_mempolicy.2
> +++ b/man2/get_mempolicy.2
> @@ -137,7 +137,9 @@ specifies
>  but not
>  .BR MPOL_F_ADDR ,
>  and the thread's current policy is
> -.BR MPOL_INTERLEAVE ,
> +.BR MPOL_INTERLEAVE
> +or
> +.BR MPOL_WEIGHTED_INTERLEAVE ,
>  then
>  .BR get_mempolicy ()
>  will return in the location pointed to by a non-NULL
> @@ -206,7 +208,9 @@ specified
>  but not
>  .B MPOL_F_ADDR
>  and the current thread policy is not
> -.BR MPOL_INTERLEAVE .
> +.BR MPOL_INTERLEAVE
> +or
> +.BR MPOL_WEIGHTED_INTERLEAVE .
>  Or,
>  .I flags
>  specified
> diff --git a/man2/mbind.2 b/man2/mbind.2
> index b0e961f9c..4673f077e 100644
> --- a/man2/mbind.2
> +++ b/man2/mbind.2
> @@ -105,6 +105,7 @@ argument must specify one of
>  .BR MPOL_DEFAULT ,
>  .BR MPOL_BIND ,
>  .BR MPOL_INTERLEAVE ,
> +.BR MPOL_WEIGHTED_INTERLEAVE ,
>  .BR MPOL_PREFERRED ,
>  or
>  .B MPOL_LOCAL
> @@ -243,6 +244,17 @@ 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_WEIGHTED_INTERLEAVE
> +This mode interleaves page allocations across the nodes specified in
> +.I nodemask
> +according to the weights in /sys/kernel/mm/mempolicy/weighted_interleave.
> +For example, if bits 0, 2, and 5 are raised in
> +.IR nodemask ,
> +and the contents of /sys/kernel/mm/mempolicy/weighted_interleave/node0,
> +/sys/.../node2, and /sys/.../node5 are 4, 7, and 9, respectively,
> +then pages in this region will be allocated on nodes 0, 2, and 5
> +in a 4:7:9 ratio.
> +.TP

LGTM for the description of weighted interleave mode.  Thanks!  Feel
free to add

Reviewed-by: "Huang, Ying" <ying.huang@intel.com>

in the future versions for that.

>  .B MPOL_PREFERRED
>  This mode sets the preferred node for allocation.
>  The kernel will try to allocate pages from this
> diff --git a/man2/set_mempolicy.2 b/man2/set_mempolicy.2
> index fc3ad9df8..e2f5e5bf8 100644
> --- a/man2/set_mempolicy.2
> +++ b/man2/set_mempolicy.2
> @@ -63,6 +63,7 @@ argument must specify one of
>  .BR MPOL_DEFAULT ,
>  .BR MPOL_BIND ,
>  .BR MPOL_INTERLEAVE ,
> +.BR MPOL_WEIGHTED_INTERLEAVE ,
>  .BR MPOL_PREFERRED ,
>  or
>  .B MPOL_LOCAL
> @@ -199,6 +200,17 @@ the memory bandwidth of a single node.
>  .\" To be effective the memory area should be fairly large,
>  .\" at least 1 MB or bigger.
>  .TP
> +.B MPOL_WEIGHTED_INTERLEAVE
> +This mode interleaves page allocations across the nodes specified in
> +.I nodemask
> +according to the weights in /sys/kernel/mm/mempolicy/weighted_interleave.
> +For example, if bits 0, 2, and 5 are raised in
> +.IR nodemask ,
> +and the contents of /sys/kernel/mm/mempolicy/weighted_interleave/node0,
> +/sys/.../node2, and /sys/.../node5 are 4, 7, and 9, respectively,
> +then pages in this region will be allocated on nodes 0, 2, and 5
> +in a 4:7:9 ratio.
> +.TP
>  .B MPOL_PREFERRED
>  This mode sets the preferred node for allocation.
>  The kernel will try to allocate pages from this node first
>
> ---
> base-commit: a4ea5f76215dcf1d8d017eb65ab12919ccf09f3f
> change-id: 20240313-weighted_interleave-e8141ed754f9
>
> Best regards,

Re: [PATCH v2] man2: add MPOL_WEIGHTED_INTERLEAVE documentation

[Svetly Todorov]

Hi Ying.

> LGTM for the description of weighted interleave mode.  Thanks!  Feel
> free to add
>
> Reviewed-by: "Huang, Ying" <ying.huang@intel.com>
>
> in the future versions for that.

Done. Thanks a bunch!

Svetly