[PATCH v4] man2: add MPOL_WEIGHTED_INTERLEAVE documentation

[PATCH v4] 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 v4:
- BR -> B in get_mempolicy
- use roman for ellipses; format using \|
- Link to v3: https://lore.kernel.org/r/20240315-weighted_interleave-v3-1-416a1ab01524@memverge.com

Changes in v3:
- italicize paths
- Link to v2: https://lore.kernel.org/r/20240315-weighted_interleave-v2-1-b742a48750b0@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         | 17 +++++++++++++++++
 man2/set_mempolicy.2 | 17 +++++++++++++++++
 3 files changed, 40 insertions(+), 2 deletions(-)

diff --git a/man2/get_mempolicy.2 b/man2/get_mempolicy.2
index 5248f04ba..a81b84a00 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 ,
+.B 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 .
+.B MPOL_INTERLEAVE
+or
+.BR MPOL_WEIGHTED_INTERLEAVE .
 Or,
 .I flags
 specified
diff --git a/man2/mbind.2 b/man2/mbind.2
index b0e961f9c..cd4e6f4a4 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,22 @@ 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
+.IR /sys/kernel/mm/mempolicy/weighted_interleave .
+For example, if bits 0, 2, and 5 are raised in
+.IR nodemask ,
+and the contents of
+.IR /sys/kernel/mm/mempolicy/weighted_interleave/node0 ,
+.IR /sys/ .\|.\|. /node2 ,
+and
+.IR /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..f9837d918 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,22 @@ 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
+.IR /sys/kernel/mm/mempolicy/weighted_interleave .
+For example, if bits 0, 2, and 5 are raised in
+.IR nodemask ,
+and the contents of
+.IR /sys/kernel/mm/mempolicy/weighted_interleave/node0 ,
+.IR /sys/ .\|.\|. /node2 ,
+and
+.IR /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 v4] man2: add MPOL_WEIGHTED_INTERLEAVE documentation

[Alejandro Colomar]

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

Hi Svetly,

On Sat, Mar 16, 2024 at 12:50:47PM -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 v4:
> - BR -> B in get_mempolicy
> - use roman for ellipses; format using \|
> - Link to v3: https://lore.kernel.org/r/20240315-weighted_interleave-v3-1-416a1ab01524@memverge.com
> 
> Changes in v3:
> - italicize paths
> - Link to v2: https://lore.kernel.org/r/20240315-weighted_interleave-v2-1-b742a48750b0@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         | 17 +++++++++++++++++
>  man2/set_mempolicy.2 | 17 +++++++++++++++++
>  3 files changed, 40 insertions(+), 2 deletions(-)
> 
> diff --git a/man2/get_mempolicy.2 b/man2/get_mempolicy.2
> index 5248f04ba..a81b84a00 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 ,
> +.B 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 .
> +.B MPOL_INTERLEAVE
> +or
> +.BR MPOL_WEIGHTED_INTERLEAVE .
>  Or,
>  .I flags
>  specified
> diff --git a/man2/mbind.2 b/man2/mbind.2
> index b0e961f9c..cd4e6f4a4 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,22 @@ 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

We should document the kernel version that added this.
Please look for other (since ...) in the same page.

Have a lovely night!
Alex

> +This mode interleaves page allocations across the nodes specified in
> +.I nodemask
> +according to the weights in
> +.IR /sys/kernel/mm/mempolicy/weighted_interleave .
> +For example, if bits 0, 2, and 5 are raised in
> +.IR nodemask ,
> +and the contents of
> +.IR /sys/kernel/mm/mempolicy/weighted_interleave/node0 ,
> +.IR /sys/ .\|.\|. /node2 ,
> +and
> +.IR /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..f9837d918 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,22 @@ 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
> +.IR /sys/kernel/mm/mempolicy/weighted_interleave .
> +For example, if bits 0, 2, and 5 are raised in
> +.IR nodemask ,
> +and the contents of
> +.IR /sys/kernel/mm/mempolicy/weighted_interleave/node0 ,
> +.IR /sys/ .\|.\|. /node2 ,
> +and
> +.IR /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 v4] man2: add MPOL_WEIGHTED_INTERLEAVE documentation

[Svetly Todorov]

Happy Monday Alex,

Thanks for looking at this over the weekend! Hopefully
not too many more changes to go.

> We should document the kernel version that added this.
> Please look for other (since ...) in the same page
> 
> Have a lovely night!
> Alex

I was referencing MPOL_LOCAL in the same page and there are
two commits listed under it:

> .BR MPOL_LOCAL " (since Linux 3.8)”
> .\" commit 479e2802d09f1e18a97262c4c6f8f17ae5884bd8
> .\" commit f2a07f40dbc603c15f8b06e6ec7f768af67b424f

I want to add a similar comment for MPOL_WEIGHTED_INTERLEAVE
but I’m not sure what the equivalent would be.
I’m thinking to have something like

> .BR MPOL_WEIGHTED_INTERLEAVE " since (Linux 6.9)"
> .\" commit fa3bea4e1f8202d787709b7e3654eb0a99aed758

Where fa3bea... is the commit in the kernel git
for the weighted interleave patch:

https://git.kernel.org/pub/scm/linux/kernel/git/akpm/mm.git/commit/?h=mm-stable-2024-03-13-20-04&id=fa3bea4e1f8202d787709b7e3654eb0a99aed758

(Forgive me, not sure if there’s a way to shorten long links like that).

I can’t tell why there are two commits listed under MPOL_LOCAL, though. 
Do you think just fa3ea... would be sufficient?

Svetly

Re: [PATCH v4] man2: add MPOL_WEIGHTED_INTERLEAVE documentation

[Alejandro Colomar]

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

On Mon, Mar 18, 2024 at 02:38:48PM +0000, Svetly Todorov wrote:
> Happy Monday Alex,

Happy Monday Svetly!

> Thanks for looking at this over the weekend! Hopefully
> not too many more changes to go.

Nah, I think we're almost done.  The patch LGTM.

> > We should document the kernel version that added this.
> > Please look for other (since ...) in the same page
> > 
> > Have a lovely night!
> > Alex
> 
> I was referencing MPOL_LOCAL in the same page and there are
> two commits listed under it:
> 
> > .BR MPOL_LOCAL " (since Linux 3.8)”
> > .\" commit 479e2802d09f1e18a97262c4c6f8f17ae5884bd8
> > .\" commit f2a07f40dbc603c15f8b06e6ec7f768af67b424f
> 
> I want to add a similar comment for MPOL_WEIGHTED_INTERLEAVE
> but I’m not sure what the equivalent would be.
> I’m thinking to have something like
> 
> > .BR MPOL_WEIGHTED_INTERLEAVE " since (Linux 6.9)"

Yes, the above is fine.

> > .\" commit fa3bea4e1f8202d787709b7e3654eb0a99aed758

And yeah, this is good too.

> Where fa3bea... is the commit in the kernel git
> for the weighted interleave patch:

Yup.  That commit is already in Linus's tree:

alx@debian:~/src/linux/linux/master$ git describe --contains fa3bea4e1f82
fatal: cannot describe 'fa3bea4e1f8202d787709b7e3654eb0a99aed758'
alx@debian:~/src/linux/linux/master$ git describe fa3bea4e1f82
v6.8-rc5-108-gfa3bea4e1f82
alx@debian:~/src/linux/linux/master$ git log --oneline torvalds/master | grep fa3bea4e1f82
fa3bea4e1f82 mm/mempolicy: introduce MPOL_WEIGHTED_INTERLEAVE for weighted interleaving

> https://git.kernel.org/pub/scm/linux/kernel/git/akpm/mm.git/commit/?h=mm-stable-2024-03-13-20-04&id=fa3bea4e1f8202d787709b7e3654eb0a99aed758
> 
> (Forgive me, not sure if there’s a way to shorten long links like that).

No problem.  I don't either.  :)

> I can’t tell why there are two commits listed under MPOL_LOCAL, though. 

Maybe one commit significantly changed the feature.  Don't worry;
normally there's just 1 commit listed in the comments.

> Do you think just fa3ea... would be sufficient?

Yup!  Please send and I'll apply already.  (And remember to add the
'Reviewed-by: "Huang, Ying" <ying.huang@intel.com>'.)

Cheers,
Alex

> 
> Svetly
> 

-- 
<https://www.alejandro-colomar.es/>
Looking for a remote C programming job at the moment.

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

Re: [PATCH v4] man2: add MPOL_WEIGHTED_INTERLEAVE documentation

[Stefan Puiu]

Hi Alex,

On Mon, Mar 18, 2024 at 5:09 PM Alejandro Colomar <alx@kernel.org> wrote:
>
> On Mon, Mar 18, 2024 at 02:38:48PM +0000, Svetly Todorov wrote:
> > Happy Monday Alex,
>
> Happy Monday Svetly!
>
> > Thanks for looking at this over the weekend! Hopefully
> > not too many more changes to go.
>
> Nah, I think we're almost done.  The patch LGTM.
>
> > > We should document the kernel version that added this.
> > > Please look for other (since ...) in the same page
> > >
> > > Have a lovely night!
> > > Alex
> >
> > I was referencing MPOL_LOCAL in the same page and there are
> > two commits listed under it:
> >
> > > .BR MPOL_LOCAL " (since Linux 3.8)”
> > > .\" commit 479e2802d09f1e18a97262c4c6f8f17ae5884bd8
> > > .\" commit f2a07f40dbc603c15f8b06e6ec7f768af67b424f
> >
> > I want to add a similar comment for MPOL_WEIGHTED_INTERLEAVE
> > but I’m not sure what the equivalent would be.
> > I’m thinking to have something like
> >
> > > .BR MPOL_WEIGHTED_INTERLEAVE " since (Linux 6.9)"
>
> Yes, the above is fine.
>
> > > .\" commit fa3bea4e1f8202d787709b7e3654eb0a99aed758
>
> And yeah, this is good too.
>
> > Where fa3bea... is the commit in the kernel git
> > for the weighted interleave patch:
>
> Yup.  That commit is already in Linus's tree:
>
> alx@debian:~/src/linux/linux/master$ git describe --contains fa3bea4e1f82
> fatal: cannot describe 'fa3bea4e1f8202d787709b7e3654eb0a99aed758'
> alx@debian:~/src/linux/linux/master$ git describe fa3bea4e1f82
> v6.8-rc5-108-gfa3bea4e1f82
> alx@debian:~/src/linux/linux/master$ git log --oneline torvalds/master | grep fa3bea4e1f82
> fa3bea4e1f82 mm/mempolicy: introduce MPOL_WEIGHTED_INTERLEAVE for weighted interleaving

I think you can do a simple:

$ git branch --contains fa3bea4e1f82
* master

Just my 2 cents,
Stefan.

>
> > https://git.kernel.org/pub/scm/linux/kernel/git/akpm/mm.git/commit/?h=mm-stable-2024-03-13-20-04&id=fa3bea4e1f8202d787709b7e3654eb0a99aed758
> >
> > (Forgive me, not sure if there’s a way to shorten long links like that).
>
> No problem.  I don't either.  :)
>
> > I can’t tell why there are two commits listed under MPOL_LOCAL, though.
>
> Maybe one commit significantly changed the feature.  Don't worry;
> normally there's just 1 commit listed in the comments.
>
> > Do you think just fa3ea... would be sufficient?
>
> Yup!  Please send and I'll apply already.  (And remember to add the
> 'Reviewed-by: "Huang, Ying" <ying.huang@intel.com>'.)
>
> Cheers,
> Alex
>
> >
> > Svetly
> >
>
> --
> <https://www.alejandro-colomar.es/>
> Looking for a remote C programming job at the moment.

Re: [PATCH v4] man2: add MPOL_WEIGHTED_INTERLEAVE documentation

[Alejandro Colomar]

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

Hi Stefan,

On Tue, Mar 19, 2024 at 12:05:08PM +0200, Stefan Puiu wrote:
> Hi Alex,
> 
> On Mon, Mar 18, 2024 at 5:09 PM Alejandro Colomar <alx@kernel.org> wrote:
> > Yup.  That commit is already in Linus's tree:
> >
> > alx@debian:~/src/linux/linux/master$ git describe --contains fa3bea4e1f82
> > fatal: cannot describe 'fa3bea4e1f8202d787709b7e3654eb0a99aed758'
> > alx@debian:~/src/linux/linux/master$ git describe fa3bea4e1f82
> > v6.8-rc5-108-gfa3bea4e1f82
> > alx@debian:~/src/linux/linux/master$ git log --oneline torvalds/master | grep fa3bea4e1f82
> > fa3bea4e1f82 mm/mempolicy: introduce MPOL_WEIGHTED_INTERLEAVE for weighted interleaving
> 
> I think you can do a simple:
> 
> $ git branch --contains fa3bea4e1f82
> * master

Ahhh, didn't know that thing!  Thanks!  I'm still wondering why
`git describe --contains` failed.  Is it because it's in a merged branch
and it would be ambiguous with another parallel commit?

Have a lovely day!
Alex

> 
> Just my 2 cents,
> Stefan.

-- 
<https://www.alejandro-colomar.es/>
Looking for a remote C programming job at the moment.

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