Re: [PATCH v5] man2: add MPOL_WEIGHTED_INTERLEAVE documentation

[Alejandro Colomar <alx@kernel.org>]

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

Hi Svetly,

On Mon, Mar 18, 2024 at 09:32:08AM -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
> Reviewed-by: "Huang, Ying" <ying.huang@intel.com>
> Signed-off-by: Svetly Todorov <svetly.todorov@memverge.com>
> 
> Changes in v5:
> - document kernel version where WEIGHTED_INTERLEAVE was added
> - Link to v4: https://lore.kernel.org/r/20240316-weighted_interleave-v4-1-6ab516f12ced@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 | 12 ++++++++++--
>  man2/mbind.2         | 18 ++++++++++++++++++
>  man2/set_mempolicy.2 | 18 ++++++++++++++++++
>  3 files changed, 46 insertions(+), 2 deletions(-)
> 
> diff --git a/man2/get_mempolicy.2 b/man2/get_mempolicy.2
> index 5248f04ba..00ce287c9 100644
> --- a/man2/get_mempolicy.2
> +++ b/man2/get_mempolicy.2
> @@ -137,7 +137,11 @@ specifies
>  but not
>  .BR MPOL_F_ADDR ,
>  and the thread's current policy is
> -.BR MPOL_INTERLEAVE ,
> +.B MPOL_INTERLEAVE
> +or
> +.B MPOL_WEIGHTED_INTERLEAVE
> +(available since Linux 6.9),

For consistency, I try to use the same phrase everywhere:

	(since Linux x.y)

But, in simple mentions, we usually don't specify when a flag was added.
That's already documented in the proper documentation of the flag.  So
here, I'd just remove that (and the comment below).

> +.\" commit fa3bea4e1f8202d787709b7e3654eb0a99aed758
>  then
>  .BR get_mempolicy ()
>  will return in the location pointed to by a non-NULL
> @@ -206,7 +210,11 @@ specified
>  but not
>  .B MPOL_F_ADDR
>  and the current thread policy is not
> -.BR MPOL_INTERLEAVE .
> +.B MPOL_INTERLEAVE
> +or

I prefer "nor".

> +.B MPOL_WEIGHTED_INTERLEAVE
> +(added in Linux 6.9).

Same here.

> +.\" commit fa3bea4e1f8202d787709b7e3654eb0a99aed758
>  Or,
>  .I flags
>  specified
> diff --git a/man2/mbind.2 b/man2/mbind.2
> index b0e961f9c..6f2449946 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,23 @@ 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
> +.BR MPOL_WEIGHTED_INTERLEAVE " (since Linux 6.9)"
> +.\" commit fa3bea4e1f8202d787709b7e3654eb0a99aed758

Here is where we usually document the kernel versions.  So here (and
in set_mempolicy.2) is good, and enough, I think.

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..3c08b6bf0 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,23 @@ the memory bandwidth of a single node.
>  .\" To be effective the memory area should be fairly large,
>  .\" at least 1 MB or bigger.
>  .TP
> +.BR MPOL_WEIGHTED_INTERLEAVE " (since Linux 6.9)"
> +.\" commit fa3bea4e1f8202d787709b7e3654eb0a99aed758
> +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/>
Looking for a remote C programming job at the moment.

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