[PATCH v4 0/4] Add documentation for PR_FUTEX_HASH

[PATCH v4 0/4] Add documentation for PR_FUTEX_HASH

[Sebastian Andrzej Siewior]

Add some documentation of the prctl(PR_FUTEX_HASH, …) interface.
The PR_FUTEX_HASH interface has been merged during the merge window,
v6.16-rc1 is expected this weekend.

Signed-off-by: Sebastian Andrzej Siewior <bigeasy@linutronix.de>
---
v3…v4: https://lore.kernel.org/all/20250526155523.1382465-1-bigeasy@linutronix.de/
  - Make FH_FLAG_IMMUTABLE and CONFIG_PROVE_LOCKING bold.
  - Drop one too many "Relative inset"
  - Reword return value for "GET_IMMUTABLE"
  - Reword the description of "unrelated futexes" in PR_FUTEX_HASH

v2…v3: https://lore.kernel.org/all/20250520104247.S-gVcgxM@linutronix.de/
  - Split the individual PR_FUTEX_HASH ops into their own man page.
  - Reword a sentence referring to uaddr in order to link to futex(2).
  - Address remaining review feedback such the semantic new line.

v1…v2: https://lore.kernel.org/all/20250516161422.BqmdlxlF@linutronix.de/
  - Partly reword
  - Use "semantic newlines"

Sebastian Andrzej Siewior (4):
  man/man2/prctl.2, man/man2const/PR_FUTEX_HASH.2const: Document
    PR_FUTEX_HASH
  man/man2/prctl.2, PR_FUTEX_HASH_SET_SLOTS.2const: Document
    PR_FUTEX_HASH_SET_SLOTS
  man/man2/prctl.2, PR_FUTEX_HASH_GET_SLOTS.2const: Document
    PR_FUTEX_HASH_GET_SLOTS
  man/man2/prctl.2, PR_FUTEX_HASH_GET_IMMUTABLE.2const: Document
    PR_FUTEX_HASH_GET_IMMUTABLE

 man/man2/prctl.2                              |  3 +
 man/man2const/PR_FUTEX_HASH.2const            | 89 +++++++++++++++++++
 .../PR_FUTEX_HASH_GET_IMMUTABLE.2const        | 39 ++++++++
 man/man2const/PR_FUTEX_HASH_GET_SLOTS.2const  | 37 ++++++++
 man/man2const/PR_FUTEX_HASH_SET_SLOTS.2const  | 82 +++++++++++++++++
 5 files changed, 250 insertions(+)
 create mode 100644 man/man2const/PR_FUTEX_HASH.2const
 create mode 100644 man/man2const/PR_FUTEX_HASH_GET_IMMUTABLE.2const
 create mode 100644 man/man2const/PR_FUTEX_HASH_GET_SLOTS.2const
 create mode 100644 man/man2const/PR_FUTEX_HASH_SET_SLOTS.2const

-- 
2.49.0

[PATCH v4 1/4] man/man2/prctl.2, man/man2const/PR_FUTEX_HASH.2const: Document PR_FUTEX_HASH

[Sebastian Andrzej Siewior]

The prctl(PR_FUTEX_HASH) is queued for the v6.16 merge window.
Add some documentation of the interface.

Signed-off-by: Sebastian Andrzej Siewior <bigeasy@linutronix.de>
---
 man/man2/prctl.2                   |  3 +
 man/man2const/PR_FUTEX_HASH.2const | 89 ++++++++++++++++++++++++++++++
 2 files changed, 92 insertions(+)
 create mode 100644 man/man2const/PR_FUTEX_HASH.2const

diff --git a/man/man2/prctl.2 b/man/man2/prctl.2
index cb5e75bf79ab2..ddfd1d1f5b940 100644
--- a/man/man2/prctl.2
+++ b/man/man2/prctl.2
@@ -150,6 +150,8 @@ with a significance depending on the first one.
 .B PR_GET_MDWE
 .TQ
 .B PR_RISCV_SET_ICACHE_FLUSH_CTX
+.TQ
+.B PR_FUTEX_HASH
 .SH RETURN VALUE
 On success,
 a nonnegative value is returned.
@@ -262,4 +264,5 @@ so these operations should be used with care.
 .BR PR_SET_MDWE (2const),
 .BR PR_GET_MDWE (2const),
 .BR PR_RISCV_SET_ICACHE_FLUSH_CTX (2const),
+.BR PR_FUTEX_HASH (2const),
 .BR core (5)
diff --git a/man/man2const/PR_FUTEX_HASH.2const b/man/man2const/PR_FUTEX_HASH.2const
new file mode 100644
index 0000000000000..08511b18335b2
--- /dev/null
+++ b/man/man2const/PR_FUTEX_HASH.2const
@@ -0,0 +1,89 @@
+.\" Copyright, the authors of the Linux man-pages project
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH PR_FUTEX_HASH 2const (date) "Linux man-pages (unreleased)"
+.SH NAME
+PR_FUTEX_HASH
+\-
+configure the private futex hash
+.SH LIBRARY
+Standard C library
+.RI ( libc ,\~ \-lc )
+.SH SYNOPSIS
+.nf
+.BR "#include <linux/prctl.h>" "  /* Definition of " PR_* " constants */"
+.B #include <sys/prctl.h>
+.P
+.BI "int prctl(PR_FUTEX_HASH, unsigned long " op ", ...);"
+.fi
+.SH DESCRIPTION
+Configure the attributes for the underlying hash used by the
+.BR futex (2)
+family of operations.
+The Linux kernel uses a hash to distribute the unrelated
+.BR futex (2)
+requests to different data structures
+in order to reduce the lock contention.
+Unrelated requests are requests which are not related to one another
+because they use a different futex word.
+The data structure holds the in-kernel representation of the operation and
+keeps track of the current users which are enqueued and wait for a wake up.
+It also provides synchronisation of waiters against wakers.
+The size of the global hash is determined at boot time
+and is based on the number of CPUs in the system.
+Due to hash collision,
+two unrelated
+.BR futex (2)
+requests can share the same hash bucket.
+This in turn can lead to delays of the
+.BR futex (2)
+operation due to lock contention while accessing the data structure.
+These delays can be problematic on a real-time system
+since random processes can
+share in-kernel locks
+and it is not deterministic which process will be involved.
+.P
+Linux 6.16 implements a process-wide private hash which is used by all
+.BR futex (2)
+operations that specify the
+.B FUTEX_PRIVATE_FLAG
+option as part of the operation.
+Without any configuration
+the kernel will allocate 16 hash slots
+once the first thread has been created.
+If the process continues to create threads,
+the kernel will try to resize the private hash based on the number of threads
+and available CPUs in the system.
+The kernel will only increase the size and will make sure it does not exceed
+the size of the global hash.
+.P
+The user can configure the size of the private
+hash which will also disable the
+automatic resize provided by the kernel.
+.P
+The value in
+.I op
+is one of the options below.
+.TP
+.B PR_FUTEX_HASH_GET_IMMUTABLE
+.TQ
+.B PR_FUTEX_HASH_GET_SLOTS
+.TQ
+.B PR_FUTEX_HASH_SET_SLOTS
+.SH RETURN VALUE
+On success,
+these calls return a nonnegative value.
+On error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.SH STANDARDS
+Linux.
+.SH HISTORY
+Linux 6.16.
+.SH SEE ALSO
+.BR prctl (2),
+.BR futex (2),
+.BR PR_FUTEX_HASH_GET_IMMUTABLE (2const),
+.BR PR_FUTEX_HASH_GET_SLOTS (2const),
+.BR PR_FUTEX_HASH_SET_SLOTS (2const)
-- 
2.49.0

[PATCH v4 2/4] man/man2/prctl.2, PR_FUTEX_HASH_SET_SLOTS.2const: Document PR_FUTEX_HASH_SET_SLOTS

[Sebastian Andrzej Siewior]

Signed-off-by: Sebastian Andrzej Siewior <bigeasy@linutronix.de>
---
 man/man2const/PR_FUTEX_HASH_SET_SLOTS.2const | 83 ++++++++++++++++++++
 1 file changed, 83 insertions(+)
 create mode 100644 man/man2const/PR_FUTEX_HASH_SET_SLOTS.2const

diff --git a/man/man2const/PR_FUTEX_HASH_SET_SLOTS.2const b/man/man2const/PR_FUTEX_HASH_SET_SLOTS.2const
new file mode 100644
index 0000000000000..1f08d1bb30485
--- /dev/null
+++ b/man/man2const/PR_FUTEX_HASH_SET_SLOTS.2const
@@ -0,0 +1,83 @@
+.\" Copyright, the authors of the Linux man-pages project
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH PR_FUTEX_HASH_SET_SLOTS 2const (date) "Linux man-pages (unreleased)"
+.SH NAME
+PR_FUTEX_HASH_SET_SLOTS
+\-
+set the size of the private hash
+.SH LIBRARY
+Standard C library
+.RI ( libc ,\~ \-lc )
+.SH SYNOPSIS
+.nf
+.BR "#include <linux/prctl.h>" "  /* Definition of " PR_* " constants */"
+.B #include <sys/prctl.h>
+.P
+.B int prctl(PR_FUTEX_HASH, PR_FUTEX_HASH_SET_SLOTS,
+.BI "          unsigned long " hash_size ", unsigned long " hash_flags ");
+.fi
+.SH DESCRIPTION
+Set the number of slots to use for the private hash.
+.TP
+.I hash_size
+Specifies the size of private hash to allocate.
+.RS
+.TP
+.I 0
+Use the global hash.
+This is the behaviour used before 6.16.
+The operation implies the
+.I FH_FLAG_IMMUTABLE
+flag.
+.TP
+.I >0
+Specifies the number of slots to allocate.
+The value must be power of two and the lowest possible value is 2.
+The upper limit depends on the available memory in the system.
+Each slot requires 64bytes of memory.
+Kernels compiled with
+.I CONFIG_PROVE_LOCKING
+will consume more than that.
+.RE
+.TP
+.I hash_flags
+.RS
+The following flags can be specified:
+.TP
+.I FH_FLAG_IMMUTABLE
+The private hash can no longer be changed.
+By using an immutable private hash
+the kernel can avoid some accounting for the data structure.
+This accounting is visible in benchmarks if many
+.BR futex (2)
+operations are invoked in parallel on different CPUs.
+.RE
+.RE
+.SH RETURN VALUE
+On success,
+0 is returned.
+On error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+.TP
+.B EINVAL
+One of the supplied argument is invalid.
+.TP
+.B ENOMEM
+Failed to allocate memory.
+.TP
+.B EBUSY
+An immutable hash is already in use
+and can not be changed.
+.SH STANDARDS
+Linux.
+.SH HISTORY
+Linux 6.16.
+.SH SEE ALSO
+.BR prctl (2),
+.BR PR_FUTEX_HASH (2const),
+.BR PR_FUTEX_HASH_GET_IMMUTABLE (2const),
+.BR PR_FUTEX_HASH_GET_SLOTS (2const)
-- 
2.49.0

[PATCH v4 3/4] man/man2/prctl.2, PR_FUTEX_HASH_GET_SLOTS.2const: Document PR_FUTEX_HASH_GET_SLOTS

[Sebastian Andrzej Siewior]

Reviewed-by: Alejandro Colomar <alx@kernel.org>
Signed-off-by: Sebastian Andrzej Siewior <bigeasy@linutronix.de>
---
 man/man2const/PR_FUTEX_HASH_GET_SLOTS.2const | 37 ++++++++++++++++++++
 man/man2const/PR_FUTEX_HASH_SET_SLOTS.2const |  7 ++--
 2 files changed, 40 insertions(+), 4 deletions(-)
 create mode 100644 man/man2const/PR_FUTEX_HASH_GET_SLOTS.2const

diff --git a/man/man2const/PR_FUTEX_HASH_GET_SLOTS.2const b/man/man2const/PR_FUTEX_HASH_GET_SLOTS.2const
new file mode 100644
index 0000000000000..f5c6380ef1fe7
--- /dev/null
+++ b/man/man2const/PR_FUTEX_HASH_GET_SLOTS.2const
@@ -0,0 +1,37 @@
+.\" Copyright, the authors of the Linux man-pages project
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH PR_FUTEX_HASH_GET_SLOTS 2const (date) "Linux man-pages (unreleased)"
+.SH NAME
+PR_FUTEX_HASH_GET_SLOTS
+\-
+return the size of the private hash
+.SH LIBRARY
+Standard C library
+.RI ( libc ,\~ \-lc )
+.SH SYNOPSIS
+.nf
+.BR "#include <linux/prctl.h>" "  /* Definition of " PR_* " constants */"
+.B #include <sys/prctl.h>
+.P
+.B int prctl(PR_FUTEX_HASH, PR_FUTEX_HASH_GET_SLOTS);
+.fi
+.SH DESCRIPTION
+Return the current size of the private hash.
+.SH RETURN VALUE
+A value of 0 means that a private hash has not been allocated
+and the global hash is in use.
+A value >0 specifies the size of the private hash.
+On error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.SH STANDARDS
+Linux.
+.SH HISTORY
+Linux 6.16.
+.SH SEE ALSO
+.BR prctl (2),
+.BR PR_FUTEX_HASH (2const),
+.BR PR_FUTEX_HASH_GET_IMMUTABLE (2const),
+.BR PR_FUTEX_HASH_SET_SLOTS (2const)
diff --git a/man/man2const/PR_FUTEX_HASH_SET_SLOTS.2const b/man/man2const/PR_FUTEX_HASH_SET_SLOTS.2const
index 1f08d1bb30485..531e3bcca112d 100644
--- a/man/man2const/PR_FUTEX_HASH_SET_SLOTS.2const
+++ b/man/man2const/PR_FUTEX_HASH_SET_SLOTS.2const
@@ -29,7 +29,7 @@ Specifies the size of private hash to allocate.
 Use the global hash.
 This is the behaviour used before 6.16.
 The operation implies the
-.I FH_FLAG_IMMUTABLE
+.B FH_FLAG_IMMUTABLE
 flag.
 .TP
 .I >0
@@ -38,7 +38,7 @@ The value must be power of two and the lowest possible value is 2.
 The upper limit depends on the available memory in the system.
 Each slot requires 64bytes of memory.
 Kernels compiled with
-.I CONFIG_PROVE_LOCKING
+.B CONFIG_PROVE_LOCKING
 will consume more than that.
 .RE
 .TP
@@ -46,7 +46,7 @@ will consume more than that.
 .RS
 The following flags can be specified:
 .TP
-.I FH_FLAG_IMMUTABLE
+.B FH_FLAG_IMMUTABLE
 The private hash can no longer be changed.
 By using an immutable private hash
 the kernel can avoid some accounting for the data structure.
@@ -54,7 +54,6 @@ This accounting is visible in benchmarks if many
 .BR futex (2)
 operations are invoked in parallel on different CPUs.
 .RE
-.RE
 .SH RETURN VALUE
 On success,
 0 is returned.
-- 
2.49.0

[PATCH v4 4/4] man/man2/prctl.2, PR_FUTEX_HASH_GET_IMMUTABLE.2const: Document PR_FUTEX_HASH_GET_IMMUTABLE

[Sebastian Andrzej Siewior]

Signed-off-by: Sebastian Andrzej Siewior <bigeasy@linutronix.de>
---
 .../PR_FUTEX_HASH_GET_IMMUTABLE.2const        | 39 +++++++++++++++++++
 1 file changed, 39 insertions(+)
 create mode 100644 man/man2const/PR_FUTEX_HASH_GET_IMMUTABLE.2const

diff --git a/man/man2const/PR_FUTEX_HASH_GET_IMMUTABLE.2const b/man/man2const/PR_FUTEX_HASH_GET_IMMUTABLE.2const
new file mode 100644
index 0000000000000..d3b9e95ccbc98
--- /dev/null
+++ b/man/man2const/PR_FUTEX_HASH_GET_IMMUTABLE.2const
@@ -0,0 +1,39 @@
+.\" Copyright, the authors of the Linux man-pages project
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH PR_FUTEX_HASH_GET_IMMUTABLE 2const (date) "Linux man-pages (unreleased)"
+.SH NAME
+PR_FUTEX_HASH_GET_IMMUTABLE
+\-
+check if the private hash is immutable.
+.SH LIBRARY
+Standard C library
+.RI ( libc ,\~ \-lc )
+.SH SYNOPSIS
+.nf
+.BR "#include <linux/prctl.h>" "  /* Definition of " PR_* " constants */"
+.B #include <sys/prctl.h>
+.P
+.B int prctl(PR_FUTEX_HASH, PR_FUTEX_HASH_GET_IMMUTABLE);
+.fi
+.SH DESCRIPTION
+Check if the private hash is immutable.
+.SH RETURN VALUE
+If the hash is immutable,
+it returns 1;
+otherwise,
+it returns 0.
+.P
+On error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.SH STANDARDS
+Linux.
+.SH HISTORY
+Linux 6.16.
+.SH SEE ALSO
+.BR prctl (2),
+.BR PR_FUTEX_HASH (2const),
+.BR PR_FUTEX_HASH_GET_SLOTS (2const),
+.BR PR_FUTEX_HASH_SET_SLOTS (2const)
-- 
2.49.0

Re: [PATCH v4 1/4] man/man2/prctl.2, man/man2const/PR_FUTEX_HASH.2const: Document PR_FUTEX_HASH

[Alejandro Colomar]

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

Hi Sebastian,

On Mon, Jun 02, 2025 at 04:01:01PM +0200, Sebastian Andrzej Siewior wrote:
> The prctl(PR_FUTEX_HASH) is queued for the v6.16 merge window.
> Add some documentation of the interface.
> 
> Signed-off-by: Sebastian Andrzej Siewior <bigeasy@linutronix.de>

LGTM, thanks!  Please let me know when this is merged into Linus's tree.


Have a lovely day!
Alex

> ---
>  man/man2/prctl.2                   |  3 +
>  man/man2const/PR_FUTEX_HASH.2const | 89 ++++++++++++++++++++++++++++++
>  2 files changed, 92 insertions(+)
>  create mode 100644 man/man2const/PR_FUTEX_HASH.2const
> 
> diff --git a/man/man2/prctl.2 b/man/man2/prctl.2
> index cb5e75bf79ab2..ddfd1d1f5b940 100644
> --- a/man/man2/prctl.2
> +++ b/man/man2/prctl.2
> @@ -150,6 +150,8 @@ with a significance depending on the first one.
>  .B PR_GET_MDWE
>  .TQ
>  .B PR_RISCV_SET_ICACHE_FLUSH_CTX
> +.TQ
> +.B PR_FUTEX_HASH
>  .SH RETURN VALUE
>  On success,
>  a nonnegative value is returned.
> @@ -262,4 +264,5 @@ so these operations should be used with care.
>  .BR PR_SET_MDWE (2const),
>  .BR PR_GET_MDWE (2const),
>  .BR PR_RISCV_SET_ICACHE_FLUSH_CTX (2const),
> +.BR PR_FUTEX_HASH (2const),
>  .BR core (5)
> diff --git a/man/man2const/PR_FUTEX_HASH.2const b/man/man2const/PR_FUTEX_HASH.2const
> new file mode 100644
> index 0000000000000..08511b18335b2
> --- /dev/null
> +++ b/man/man2const/PR_FUTEX_HASH.2const
> @@ -0,0 +1,89 @@
> +.\" Copyright, the authors of the Linux man-pages project
> +.\"
> +.\" SPDX-License-Identifier: Linux-man-pages-copyleft
> +.\"
> +.TH PR_FUTEX_HASH 2const (date) "Linux man-pages (unreleased)"
> +.SH NAME
> +PR_FUTEX_HASH
> +\-
> +configure the private futex hash
> +.SH LIBRARY
> +Standard C library
> +.RI ( libc ,\~ \-lc )
> +.SH SYNOPSIS
> +.nf
> +.BR "#include <linux/prctl.h>" "  /* Definition of " PR_* " constants */"
> +.B #include <sys/prctl.h>
> +.P
> +.BI "int prctl(PR_FUTEX_HASH, unsigned long " op ", ...);"
> +.fi
> +.SH DESCRIPTION
> +Configure the attributes for the underlying hash used by the
> +.BR futex (2)
> +family of operations.
> +The Linux kernel uses a hash to distribute the unrelated
> +.BR futex (2)
> +requests to different data structures
> +in order to reduce the lock contention.
> +Unrelated requests are requests which are not related to one another
> +because they use a different futex word.
> +The data structure holds the in-kernel representation of the operation and
> +keeps track of the current users which are enqueued and wait for a wake up.
> +It also provides synchronisation of waiters against wakers.
> +The size of the global hash is determined at boot time
> +and is based on the number of CPUs in the system.
> +Due to hash collision,
> +two unrelated
> +.BR futex (2)
> +requests can share the same hash bucket.
> +This in turn can lead to delays of the
> +.BR futex (2)
> +operation due to lock contention while accessing the data structure.
> +These delays can be problematic on a real-time system
> +since random processes can
> +share in-kernel locks
> +and it is not deterministic which process will be involved.
> +.P
> +Linux 6.16 implements a process-wide private hash which is used by all
> +.BR futex (2)
> +operations that specify the
> +.B FUTEX_PRIVATE_FLAG
> +option as part of the operation.
> +Without any configuration
> +the kernel will allocate 16 hash slots
> +once the first thread has been created.
> +If the process continues to create threads,
> +the kernel will try to resize the private hash based on the number of threads
> +and available CPUs in the system.
> +The kernel will only increase the size and will make sure it does not exceed
> +the size of the global hash.
> +.P
> +The user can configure the size of the private
> +hash which will also disable the
> +automatic resize provided by the kernel.
> +.P
> +The value in
> +.I op
> +is one of the options below.
> +.TP
> +.B PR_FUTEX_HASH_GET_IMMUTABLE
> +.TQ
> +.B PR_FUTEX_HASH_GET_SLOTS
> +.TQ
> +.B PR_FUTEX_HASH_SET_SLOTS
> +.SH RETURN VALUE
> +On success,
> +these calls return a nonnegative value.
> +On error, \-1 is returned, and
> +.I errno
> +is set to indicate the error.
> +.SH STANDARDS
> +Linux.
> +.SH HISTORY
> +Linux 6.16.
> +.SH SEE ALSO
> +.BR prctl (2),
> +.BR futex (2),
> +.BR PR_FUTEX_HASH_GET_IMMUTABLE (2const),
> +.BR PR_FUTEX_HASH_GET_SLOTS (2const),
> +.BR PR_FUTEX_HASH_SET_SLOTS (2const)
> -- 
> 2.49.0
> 
> 

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

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

Re: [PATCH v4 1/4] man/man2/prctl.2, man/man2const/PR_FUTEX_HASH.2const: Document PR_FUTEX_HASH

[Sebastian Andrzej Siewior]

On 2025-06-11 10:43:07 [+0200], Alejandro Colomar wrote:
> Hi Sebastian,
Hi,

> On Mon, Jun 02, 2025 at 04:01:01PM +0200, Sebastian Andrzej Siewior wrote:
> > The prctl(PR_FUTEX_HASH) is queued for the v6.16 merge window.
> > Add some documentation of the interface.
> > 
> > Signed-off-by: Sebastian Andrzej Siewior <bigeasy@linutronix.de>
> 
> LGTM, thanks!  Please let me know when this is merged into Linus's tree.

This is in v6.16-rc1 since last Monday. We do regression handling now
but I think it will stay. I can poke you once v6.16 is out in case we
need a last minute revert of this.

> Have a lovely day!
> Alex

Sebastian

Re: [PATCH v4 2/4] man/man2/prctl.2, PR_FUTEX_HASH_SET_SLOTS.2const: Document PR_FUTEX_HASH_SET_SLOTS

[Alejandro Colomar]

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

Hi Sebastian,

On Mon, Jun 02, 2025 at 04:01:02PM +0200, Sebastian Andrzej Siewior wrote:
> Signed-off-by: Sebastian Andrzej Siewior <bigeasy@linutronix.de>
> ---
>  man/man2const/PR_FUTEX_HASH_SET_SLOTS.2const | 83 ++++++++++++++++++++
>  1 file changed, 83 insertions(+)
>  create mode 100644 man/man2const/PR_FUTEX_HASH_SET_SLOTS.2const
> 
> diff --git a/man/man2const/PR_FUTEX_HASH_SET_SLOTS.2const b/man/man2const/PR_FUTEX_HASH_SET_SLOTS.2const
> new file mode 100644
> index 0000000000000..1f08d1bb30485
> --- /dev/null
> +++ b/man/man2const/PR_FUTEX_HASH_SET_SLOTS.2const
> @@ -0,0 +1,83 @@
> +.\" Copyright, the authors of the Linux man-pages project
> +.\"
> +.\" SPDX-License-Identifier: Linux-man-pages-copyleft
> +.\"
> +.TH PR_FUTEX_HASH_SET_SLOTS 2const (date) "Linux man-pages (unreleased)"
> +.SH NAME
> +PR_FUTEX_HASH_SET_SLOTS
> +\-
> +set the size of the private hash
> +.SH LIBRARY
> +Standard C library
> +.RI ( libc ,\~ \-lc )
> +.SH SYNOPSIS
> +.nf
> +.BR "#include <linux/prctl.h>" "  /* Definition of " PR_* " constants */"
> +.B #include <sys/prctl.h>
> +.P
> +.B int prctl(PR_FUTEX_HASH, PR_FUTEX_HASH_SET_SLOTS,
> +.BI "          unsigned long " hash_size ", unsigned long " hash_flags ");
> +.fi
> +.SH DESCRIPTION
> +Set the number of slots to use for the private hash.
> +.TP
> +.I hash_size
> +Specifies the size of private hash to allocate.

s/Specifies/Specify/ for consistency with "Set" and "Use".

> +.RS
> +.TP
> +.I 0
> +Use the global hash.
> +This is the behaviour used before 6.16.
> +The operation implies the
> +.I FH_FLAG_IMMUTABLE
> +flag.
> +.TP
> +.I >0
> +Specifies the number of slots to allocate.

Same here.

> +The value must be power of two and the lowest possible value is 2.

s/two/&,/

> +The upper limit depends on the available memory in the system.
> +Each slot requires 64bytes of memory.

s/64bytes/64 bytes/

> +Kernels compiled with
> +.I CONFIG_PROVE_LOCKING
> +will consume more than that.
> +.RE
> +.TP
> +.I hash_flags
> +.RS
> +The following flags can be specified:
> +.TP
> +.I FH_FLAG_IMMUTABLE
> +The private hash can no longer be changed.
> +By using an immutable private hash
> +the kernel can avoid some accounting for the data structure.
> +This accounting is visible in benchmarks if many
> +.BR futex (2)
> +operations are invoked in parallel on different CPUs.
> +.RE
> +.RE

One RE doesn't match any RS.

> +.SH RETURN VALUE
> +On success,
> +0 is returned.
> +On error, \-1 is returned, and
> +.I errno
> +is set to indicate the error.
> +.SH ERRORS
> +.TP
> +.B EINVAL
> +One of the supplied argument is invalid.

This sentence seems to have some issues about singular/plural.  I can't
read it properly.  I think we can simplify to

	An argument is invalid.

> +.TP
> +.B ENOMEM
> +Failed to allocate memory.
> +.TP
> +.B EBUSY
> +An immutable hash is already in use
> +and can not be changed.
> +.SH STANDARDS
> +Linux.
> +.SH HISTORY
> +Linux 6.16.
> +.SH SEE ALSO
> +.BR prctl (2),
> +.BR PR_FUTEX_HASH (2const),
> +.BR PR_FUTEX_HASH_GET_IMMUTABLE (2const),
> +.BR PR_FUTEX_HASH_GET_SLOTS (2const)

I think we can simplify this to link just to the parents:

	+.BR prctl (2),
	+.BR PR_FUTEX_HASH (2const),

Since PR_FUTEX_HASH(2const) already links to all of them, we don't need
to cross link.  That'll be simpler to maintain.


Have a lovely day!
Alex

> -- 
> 2.49.0
> 

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

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

Re: [PATCH v4 3/4] man/man2/prctl.2, PR_FUTEX_HASH_GET_SLOTS.2const: Document PR_FUTEX_HASH_GET_SLOTS

[Alejandro Colomar]

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

Hi Sebastian,

On Mon, Jun 02, 2025 at 04:01:03PM +0200, Sebastian Andrzej Siewior wrote:
> Reviewed-by: Alejandro Colomar <alx@kernel.org>
> Signed-off-by: Sebastian Andrzej Siewior <bigeasy@linutronix.de>
> ---
>  man/man2const/PR_FUTEX_HASH_GET_SLOTS.2const | 37 ++++++++++++++++++++
>  man/man2const/PR_FUTEX_HASH_SET_SLOTS.2const |  7 ++--
>  2 files changed, 40 insertions(+), 4 deletions(-)
>  create mode 100644 man/man2const/PR_FUTEX_HASH_GET_SLOTS.2const
> 
> diff --git a/man/man2const/PR_FUTEX_HASH_GET_SLOTS.2const b/man/man2const/PR_FUTEX_HASH_GET_SLOTS.2const
> new file mode 100644
> index 0000000000000..f5c6380ef1fe7
> --- /dev/null
> +++ b/man/man2const/PR_FUTEX_HASH_GET_SLOTS.2const
> @@ -0,0 +1,37 @@
> +.\" Copyright, the authors of the Linux man-pages project
> +.\"
> +.\" SPDX-License-Identifier: Linux-man-pages-copyleft
> +.\"
> +.TH PR_FUTEX_HASH_GET_SLOTS 2const (date) "Linux man-pages (unreleased)"
> +.SH NAME
> +PR_FUTEX_HASH_GET_SLOTS
> +\-
> +return the size of the private hash
> +.SH LIBRARY
> +Standard C library
> +.RI ( libc ,\~ \-lc )
> +.SH SYNOPSIS
> +.nf
> +.BR "#include <linux/prctl.h>" "  /* Definition of " PR_* " constants */"
> +.B #include <sys/prctl.h>
> +.P
> +.B int prctl(PR_FUTEX_HASH, PR_FUTEX_HASH_GET_SLOTS);
> +.fi
> +.SH DESCRIPTION
> +Return the current size of the private hash.
> +.SH RETURN VALUE
> +A value of 0 means that a private hash has not been allocated
> +and the global hash is in use.
> +A value >0 specifies the size of the private hash.
> +On error, \-1 is returned, and
> +.I errno
> +is set to indicate the error.
> +.SH STANDARDS
> +Linux.
> +.SH HISTORY
> +Linux 6.16.
> +.SH SEE ALSO
> +.BR prctl (2),
> +.BR PR_FUTEX_HASH (2const),
> +.BR PR_FUTEX_HASH_GET_IMMUTABLE (2const),
> +.BR PR_FUTEX_HASH_SET_SLOTS (2const)
> diff --git a/man/man2const/PR_FUTEX_HASH_SET_SLOTS.2const b/man/man2const/PR_FUTEX_HASH_SET_SLOTS.2const
> index 1f08d1bb30485..531e3bcca112d 100644
> --- a/man/man2const/PR_FUTEX_HASH_SET_SLOTS.2const
> +++ b/man/man2const/PR_FUTEX_HASH_SET_SLOTS.2const
> @@ -29,7 +29,7 @@ Specifies the size of private hash to allocate.
>  Use the global hash.
>  This is the behaviour used before 6.16.
>  The operation implies the
> -.I FH_FLAG_IMMUTABLE
> +.B FH_FLAG_IMMUTABLE

This seems like a rebase accident.  This does not belong in this patch.
A few others below too.


Cheers,
Alex

>  flag.
>  .TP
>  .I >0
> @@ -38,7 +38,7 @@ The value must be power of two and the lowest possible value is 2.
>  The upper limit depends on the available memory in the system.
>  Each slot requires 64bytes of memory.
>  Kernels compiled with
> -.I CONFIG_PROVE_LOCKING
> +.B CONFIG_PROVE_LOCKING
>  will consume more than that.
>  .RE
>  .TP
> @@ -46,7 +46,7 @@ will consume more than that.
>  .RS
>  The following flags can be specified:
>  .TP
> -.I FH_FLAG_IMMUTABLE
> +.B FH_FLAG_IMMUTABLE
>  The private hash can no longer be changed.
>  By using an immutable private hash
>  the kernel can avoid some accounting for the data structure.
> @@ -54,7 +54,6 @@ This accounting is visible in benchmarks if many
>  .BR futex (2)
>  operations are invoked in parallel on different CPUs.
>  .RE
> -.RE
>  .SH RETURN VALUE
>  On success,
>  0 is returned.
> -- 
> 2.49.0
> 

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

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

Re: [PATCH v4 1/4] man/man2/prctl.2, man/man2const/PR_FUTEX_HASH.2const: Document PR_FUTEX_HASH

[Alejandro Colomar]

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

Hi Sebastian,

On Wed, Jun 11, 2025 at 10:47:16AM +0200, Sebastian Andrzej Siewior wrote:
> On 2025-06-11 10:43:07 [+0200], Alejandro Colomar wrote:
> > Hi Sebastian,
> Hi,
> 
> > On Mon, Jun 02, 2025 at 04:01:01PM +0200, Sebastian Andrzej Siewior wrote:
> > > The prctl(PR_FUTEX_HASH) is queued for the v6.16 merge window.
> > > Add some documentation of the interface.
> > > 
> > > Signed-off-by: Sebastian Andrzej Siewior <bigeasy@linutronix.de>
> > 
> > LGTM, thanks!  Please let me know when this is merged into Linus's tree.
> 
> This is in v6.16-rc1 since last Monday. We do regression handling now
> but I think it will stay. I can poke you once v6.16 is out in case we
> need a last minute revert of this.

Thanks!

I've applied patch 1/4, with the following amendments:

	diff --git i/man/man2const/PR_FUTEX_HASH.2const w/man/man2const/PR_FUTEX_HASH.2const
	index 08511b183..b500c943b 100644
	--- i/man/man2const/PR_FUTEX_HASH.2const
	+++ w/man/man2const/PR_FUTEX_HASH.2const
	@@ -53,14 +53,16 @@ .SH DESCRIPTION
	 the kernel will allocate 16 hash slots
	 once the first thread has been created.
	 If the process continues to create threads,
	-the kernel will try to resize the private hash based on the number of threads
	+the kernel will try to resize the private hash
	+based on the number of threads
	 and available CPUs in the system.
	-The kernel will only increase the size and will make sure it does not exceed
	-the size of the global hash.
	+The kernel will only increase the size
	+and will make sure
	+it does not exceed the size of the global hash.
	 .P
	-The user can configure the size of the private
	-hash which will also disable the
	-automatic resize provided by the kernel.
	+The user can configure the size of the private hash
	+which will also
	+disable the automatic resize provided by the kernel.
	 .P
	 The value in
	 .I op

<https://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/commit/?h=contrib&id=243de1dbc9cf818fa71c97856cbaf88b9d255b44>


Cheers,
Alex

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

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