[PATCH] PR_*ET_THP_DISABLE.2const: document addition of PR_THP_DISABLE_EXCEPT_ADVISED

[PATCH] PR_*ET_THP_DISABLE.2const: document addition of PR_THP_DISABLE_EXCEPT_ADVISED

[Usama Arif]

PR_THP_DISABLE_EXCEPT_ADVISED extended PR_SET_THP_DISABLE to only provide
THPs when advised. IOW, it allows individual processes to opt-out of THP =
"always" into THP = "madvise", without affecting other workloads on the
system. The series has been merged in [1].

This patch documents the changes introduced due to the addition of
PR_THP_DISABLE_EXCEPT_ADVISED flag:
- PR_GET_THP_DISABLE returns a value whose bits indicate how THP-disable
  is configured for the calling thread (with or without
  PR_THP_DISABLE_EXCEPT_ADVISED).
- PR_SET_THP_DISABLE now uses arg3 to specify whether to disable THP
  completely for the process, or disable except madvise
  (PR_THP_DISABLE_EXCEPT_ADVISED).

[1] https://lore.kernel.org/all/20250815135549.130506-1-usamaarif642@gmail.com/

Signed-off-by: Usama Arif <usamaarif642@gmail.com>
---
 man/man2/madvise.2                      |  4 +-
 man/man2const/PR_GET_THP_DISABLE.2const | 18 ++++++---
 man/man2const/PR_SET_THP_DISABLE.2const | 52 +++++++++++++++++++++----
 3 files changed, 61 insertions(+), 13 deletions(-)

diff --git a/man/man2/madvise.2 b/man/man2/madvise.2
index 10cc21fa4..6a5290f67 100644
--- a/man/man2/madvise.2
+++ b/man/man2/madvise.2
@@ -373,7 +373,9 @@ nor can it be stack memory or backed by a DAX-enabled device
 (unless the DAX device is hot-plugged as System RAM).
 The process must also not have
 .B PR_SET_THP_DISABLE
-set (see
+set without the
+.B PR_THP_DISABLE_EXCEPT_ADVISED
+flag (see
 .BR prctl (2)).
 .IP
 The
diff --git a/man/man2const/PR_GET_THP_DISABLE.2const b/man/man2const/PR_GET_THP_DISABLE.2const
index 38ff3b370..df239700f 100644
--- a/man/man2const/PR_GET_THP_DISABLE.2const
+++ b/man/man2const/PR_GET_THP_DISABLE.2const
@@ -6,7 +6,7 @@
 .SH NAME
 PR_GET_THP_DISABLE
 \-
-get the state of the "THP disable" flag for the calling thread
+get the state of the "THP disable" flags for the calling thread
 .SH LIBRARY
 Standard C library
 .RI ( libc ,\~ \-lc )
@@ -18,13 +18,21 @@ Standard C library
 .B int prctl(PR_GET_THP_DISABLE, 0L, 0L, 0L, 0L);
 .fi
 .SH DESCRIPTION
-Return the current setting of
-the "THP disable" flag for the calling thread:
-either 1, if the flag is set, or 0, if it is not.
+Returns a value whose bits indicate how THP-disable is configured
+for the calling thread.
+The returned value is interpreted as follows:
+.P
+.nf
+.B "Bits"
+.B " 1 0  Value  Description"
+ 0 0    0    No THP-disable behaviour specified.
+ 0 1    1    THP is entirely disabled for this process.
+ 1 1    3    THP-except-advised mode is set for this process.
+.fi
 .SH RETURN VALUE
 On success,
 .BR PR_GET_THP_DISABLE ,
-returns the boolean value described above.
+returns the value described above.
 On error, \-1 is returned, and
 .I errno
 is set to indicate the error.
diff --git a/man/man2const/PR_SET_THP_DISABLE.2const b/man/man2const/PR_SET_THP_DISABLE.2const
index 564e005d4..9f0f17702 100644
--- a/man/man2const/PR_SET_THP_DISABLE.2const
+++ b/man/man2const/PR_SET_THP_DISABLE.2const
@@ -6,7 +6,7 @@
 .SH NAME
 PR_SET_THP_DISABLE
 \-
-set the state of the "THP disable" flag for the calling thread
+set the state of the "THP disable" flags for the calling thread
 .SH LIBRARY
 Standard C library
 .RI ( libc ,\~ \-lc )
@@ -15,24 +15,62 @@ Standard C library
 .BR "#include <linux/prctl.h>" "  /* Definition of " PR_* " constants */"
 .B #include <sys/prctl.h>
 .P
-.BI "int prctl(PR_SET_THP_DISABLE, long " flag ", 0L, 0L, 0L);"
+.BI "int prctl(PR_SET_THP_DISABLE, long " thp_disable ", unsigned long " flags ", 0L, 0L);"
 .fi
 .SH DESCRIPTION
-Set the state of the "THP disable" flag for the calling thread.
+Set the state of the "THP disable" flags for the calling thread.
 If
-.I flag
-has a nonzero value, the flag is set, otherwise it is cleared.
+.I thp_disable
+has a nonzero value, the THP disable flag is set according to the value of
+.I flags,
+otherwise it is cleared.
 .P
-Setting this flag provides a method
+This
+.BR prctl (2)
+provides a method
 for disabling transparent huge pages
 for jobs where the code cannot be modified,
 and using a malloc hook with
 .BR madvise (2)
 is not an option (i.e., statically allocated data).
-The setting of the "THP disable" flag is inherited by a child created via
+The setting of the "THP disable" flags is inherited by a child created via
 .BR fork (2)
 and is preserved across
 .BR execve (2).
+.P
+The behavior depends on the value of
+.IR flags:
+.TP
+.B 0
+The
+.BR prctl (2)
+call will disable THPs completely for the process,
+irrespective of global THP controls or
+.BR MADV_COLLAPSE .
+.TP
+.B PR_THP_DISABLE_EXCEPT_ADVISED
+The
+.BR prctl (2)
+call will disable THPs for the process except when the usage of THPs is
+advised.
+Consequently, THPs will only be used when:
+.RS
+.IP \[bu] 2
+Global THP controls are set to "always" or "madvise" and
+.BR madvise (...,
+.BR MADV_HUGEPAGE )
+or
+.BR madvise (...,
+.BR MADV_COLLAPSE )
+is used.
+.IP \[bu]
+Global THP controls are set to "never" and
+.BR madvise (...,
+.BR MADV_COLLAPSE )
+is used.
+This is the same behavior as if THPs would not be disabled on
+a process level.
+.RE
 .SH RETURN VALUE
 On success,
 0 is returned.
-- 
2.47.3

Re: [PATCH] PR_*ET_THP_DISABLE.2const: document addition of PR_THP_DISABLE_EXCEPT_ADVISED

[Usama Arif]

On 01/09/2025 17:09, Usama Arif wrote:
> PR_THP_DISABLE_EXCEPT_ADVISED extended PR_SET_THP_DISABLE to only provide
> THPs when advised. IOW, it allows individual processes to opt-out of THP =
> "always" into THP = "madvise", without affecting other workloads on the
> system. The series has been merged in [1].
> 
> This patch documents the changes introduced due to the addition of
> PR_THP_DISABLE_EXCEPT_ADVISED flag:
> - PR_GET_THP_DISABLE returns a value whose bits indicate how THP-disable
>   is configured for the calling thread (with or without
>   PR_THP_DISABLE_EXCEPT_ADVISED).
> - PR_SET_THP_DISABLE now uses arg3 to specify whether to disable THP
>   completely for the process, or disable except madvise
>   (PR_THP_DISABLE_EXCEPT_ADVISED).
> 
> [1] https://lore.kernel.org/all/20250815135549.130506-1-usamaarif642@gmail.com/
> 
> Signed-off-by: Usama Arif <usamaarif642@gmail.com>
> ---
>  man/man2/madvise.2                      |  4 +-
>  man/man2const/PR_GET_THP_DISABLE.2const | 18 ++++++---
>  man/man2const/PR_SET_THP_DISABLE.2const | 52 +++++++++++++++++++++----
>  3 files changed, 61 insertions(+), 13 deletions(-)
> 

I am not sure what the right time is to send the mandoc changes.
The patches have been merged into mm-new for more than 2 weeks.
We can still review it and I can resend if needed after the kernel release if that
is a more appropriate time?

Thanks!
Usama

Re: [PATCH] PR_*ET_THP_DISABLE.2const: document addition of PR_THP_DISABLE_EXCEPT_ADVISED

[David Hildenbrand]

On 01.09.25 18:18, Usama Arif wrote:
> 
> 
> On 01/09/2025 17:09, Usama Arif wrote:
>> PR_THP_DISABLE_EXCEPT_ADVISED extended PR_SET_THP_DISABLE to only provide
>> THPs when advised. IOW, it allows individual processes to opt-out of THP =
>> "always" into THP = "madvise", without affecting other workloads on the
>> system. The series has been merged in [1].
>>
>> This patch documents the changes introduced due to the addition of
>> PR_THP_DISABLE_EXCEPT_ADVISED flag:
>> - PR_GET_THP_DISABLE returns a value whose bits indicate how THP-disable
>>    is configured for the calling thread (with or without
>>    PR_THP_DISABLE_EXCEPT_ADVISED).
>> - PR_SET_THP_DISABLE now uses arg3 to specify whether to disable THP
>>    completely for the process, or disable except madvise
>>    (PR_THP_DISABLE_EXCEPT_ADVISED).
>>
>> [1] https://lore.kernel.org/all/20250815135549.130506-1-usamaarif642@gmail.com/
>>
>> Signed-off-by: Usama Arif <usamaarif642@gmail.com>
>> ---
>>   man/man2/madvise.2                      |  4 +-
>>   man/man2const/PR_GET_THP_DISABLE.2const | 18 ++++++---
>>   man/man2const/PR_SET_THP_DISABLE.2const | 52 +++++++++++++++++++++----
>>   3 files changed, 61 insertions(+), 13 deletions(-)
>>
> 
> I am not sure what the right time is to send the mandoc changes.
> The patches have been merged into mm-new for more than 2 weeks.
> We can still review it and I can resend if needed after the kernel release if that
> is a more appropriate time?

Probably good to revive once it's in Linus' tree.

-- 
Cheers

David / dhildenb

Re: [PATCH] PR_*ET_THP_DISABLE.2const: document addition of PR_THP_DISABLE_EXCEPT_ADVISED

[Alejandro Colomar]

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

Hi Usama,

On Mon, Sep 01, 2025 at 05:18:22PM +0100, Usama Arif wrote:
> I am not sure what the right time is to send the mandoc changes.
> The patches have been merged into mm-new for more than 2 weeks.
> We can still review it and I can resend if needed after the kernel release if that
> is a more appropriate time?

No, this is fine.  Let's refine the patches for now.

Once we're done, I guess we can either wait until they arrive at Linus's
tree, or if you're very confident this will reach a release eventually,
we can merge it now here, and eventually fix it if something small
changes later.  I don't mind too much.  It's more up to you, and how
much you expect this to change before the actual release of Linux.


Have a lovely day!
Alex

-- 
<https://www.alejandro-colomar.es>
Use port 80 (that is, <...:80/>).

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

Re: [PATCH] PR_*ET_THP_DISABLE.2const: document addition of PR_THP_DISABLE_EXCEPT_ADVISED

[Usama Arif]

On 01/09/2025 17:40, Alejandro Colomar wrote:
> Hi Usama,
> 
> On Mon, Sep 01, 2025 at 05:18:22PM +0100, Usama Arif wrote:
>> I am not sure what the right time is to send the mandoc changes.
>> The patches have been merged into mm-new for more than 2 weeks.
>> We can still review it and I can resend if needed after the kernel release if that
>> is a more appropriate time?
> 
> No, this is fine.  Let's refine the patches for now.
> 
> Once we're done, I guess we can either wait until they arrive at Linus's
> tree, or if you're very confident this will reach a release eventually,
> we can merge it now here, and eventually fix it if something small
> changes later.  I don't mind too much.  It's more up to you, and how
> much you expect this to change before the actual release of Linux.
> 

Thanks!

Yeah I wouldnt expect this to change at all before the release. The patches
were extensively discussed on the mailing list and were acked by the THP
maintainers and reviewers, so the possibility of the interface changing
is extremely low.
> 
> Have a lovely day!
> Alex
> 

Re: [PATCH] PR_*ET_THP_DISABLE.2const: document addition of PR_THP_DISABLE_EXCEPT_ADVISED

[Alejandro Colomar]

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

Hi Usama,

On Mon, Sep 01, 2025 at 05:09:03PM +0100, Usama Arif wrote:
> PR_THP_DISABLE_EXCEPT_ADVISED extended PR_SET_THP_DISABLE to only provide
> THPs when advised. IOW, it allows individual processes to opt-out of THP =
> "always" into THP = "madvise", without affecting other workloads on the
> system. The series has been merged in [1].
> 
> This patch documents the changes introduced due to the addition of
> PR_THP_DISABLE_EXCEPT_ADVISED flag:
> - PR_GET_THP_DISABLE returns a value whose bits indicate how THP-disable
>   is configured for the calling thread (with or without
>   PR_THP_DISABLE_EXCEPT_ADVISED).
> - PR_SET_THP_DISABLE now uses arg3 to specify whether to disable THP
>   completely for the process, or disable except madvise
>   (PR_THP_DISABLE_EXCEPT_ADVISED).
> 
> [1] https://lore.kernel.org/all/20250815135549.130506-1-usamaarif642@gmail.com/
> 
> Signed-off-by: Usama Arif <usamaarif642@gmail.com>

Thanks for writing the patch!  Please see some comments below.

> ---
>  man/man2/madvise.2                      |  4 +-
>  man/man2const/PR_GET_THP_DISABLE.2const | 18 ++++++---
>  man/man2const/PR_SET_THP_DISABLE.2const | 52 +++++++++++++++++++++----
>  3 files changed, 61 insertions(+), 13 deletions(-)
> 
> diff --git a/man/man2/madvise.2 b/man/man2/madvise.2
> index 10cc21fa4..6a5290f67 100644
> --- a/man/man2/madvise.2
> +++ b/man/man2/madvise.2
> @@ -373,7 +373,9 @@ nor can it be stack memory or backed by a DAX-enabled device
>  (unless the DAX device is hot-plugged as System RAM).
>  The process must also not have
>  .B PR_SET_THP_DISABLE
> -set (see
> +set without the
> +.B PR_THP_DISABLE_EXCEPT_ADVISED
> +flag (see
>  .BR prctl (2)).

Double negation is confusing.  Please rephrase to something like

	The process can have X set
	only if Y is also set.

>  .IP
>  The
> diff --git a/man/man2const/PR_GET_THP_DISABLE.2const b/man/man2const/PR_GET_THP_DISABLE.2const
> index 38ff3b370..df239700f 100644
> --- a/man/man2const/PR_GET_THP_DISABLE.2const
> +++ b/man/man2const/PR_GET_THP_DISABLE.2const
> @@ -6,7 +6,7 @@
>  .SH NAME
>  PR_GET_THP_DISABLE
>  \-
> -get the state of the "THP disable" flag for the calling thread
> +get the state of the "THP disable" flags for the calling thread
>  .SH LIBRARY
>  Standard C library
>  .RI ( libc ,\~ \-lc )
> @@ -18,13 +18,21 @@ Standard C library
>  .B int prctl(PR_GET_THP_DISABLE, 0L, 0L, 0L, 0L);
>  .fi
>  .SH DESCRIPTION
> -Return the current setting of
> -the "THP disable" flag for the calling thread:
> -either 1, if the flag is set, or 0, if it is not.
> +Returns a value whose bits indicate how THP-disable is configured

s/Returns/Return/

> +for the calling thread.
> +The returned value is interpreted as follows:
> +.P
> +.nf
> +.B "Bits"
> +.B " 1 0  Value  Description"
> + 0 0    0    No THP-disable behaviour specified.
> + 0 1    1    THP is entirely disabled for this process.
> + 1 1    3    THP-except-advised mode is set for this process.

We should probably use a table with .TS/.TE.  See examples of this in
other manual pages for how to use that (or read tbl(1) if you want).

If you don't know how to use that, I can do it myself.  tbl(1) is a bit
weird.

> +.fi
>  .SH RETURN VALUE
>  On success,
>  .BR PR_GET_THP_DISABLE ,
> -returns the boolean value described above.
> +returns the value described above.
>  On error, \-1 is returned, and
>  .I errno
>  is set to indicate the error.
> diff --git a/man/man2const/PR_SET_THP_DISABLE.2const b/man/man2const/PR_SET_THP_DISABLE.2const
> index 564e005d4..9f0f17702 100644
> --- a/man/man2const/PR_SET_THP_DISABLE.2const
> +++ b/man/man2const/PR_SET_THP_DISABLE.2const
> @@ -6,7 +6,7 @@
>  .SH NAME
>  PR_SET_THP_DISABLE
>  \-
> -set the state of the "THP disable" flag for the calling thread
> +set the state of the "THP disable" flags for the calling thread
>  .SH LIBRARY
>  Standard C library
>  .RI ( libc ,\~ \-lc )
> @@ -15,24 +15,62 @@ Standard C library
>  .BR "#include <linux/prctl.h>" "  /* Definition of " PR_* " constants */"
>  .B #include <sys/prctl.h>
>  .P
> -.BI "int prctl(PR_SET_THP_DISABLE, long " flag ", 0L, 0L, 0L);"
> +.BI "int prctl(PR_SET_THP_DISABLE, long " thp_disable ", unsigned long " flags ", 0L, 0L);"

Hmmm, I'm reading this weirdly.

Old code doing prctl(PR_SET_THP_DIABLE, 1, 0L, 0L, 0L); would be
transformed from setting the flag before, to now using 0L as flags?

Or how is backwards compatibility handled?

>  .fi
>  .SH DESCRIPTION
> -Set the state of the "THP disable" flag for the calling thread.
> +Set the state of the "THP disable" flags for the calling thread.
>  If
> -.I flag
> -has a nonzero value, the flag is set, otherwise it is cleared.
> +.I thp_disable
> +has a nonzero value, the THP disable flag is set according to the value of

Please break the line after the comma.

> +.I flags,
> +otherwise it is cleared.
>  .P
> -Setting this flag provides a method
> +This
> +.BR prctl (2)
> +provides a method
>  for disabling transparent huge pages
>  for jobs where the code cannot be modified,
>  and using a malloc hook with
>  .BR madvise (2)
>  is not an option (i.e., statically allocated data).
> -The setting of the "THP disable" flag is inherited by a child created via
> +The setting of the "THP disable" flags is inherited by a child created via
>  .BR fork (2)
>  and is preserved across
>  .BR execve (2).
> +.P
> +The behavior depends on the value of
> +.IR flags:
> +.TP
> +.B 0
> +The
> +.BR prctl (2)
> +call will disable THPs completely for the process,
> +irrespective of global THP controls or
> +.BR MADV_COLLAPSE .
> +.TP
> +.B PR_THP_DISABLE_EXCEPT_ADVISED
> +The
> +.BR prctl (2)
> +call will disable THPs for the process except when the usage of THPs is
> +advised.

Please break the line before 'except'.  See 'Use semantic newlines'
in man-pages(7).

> +Consequently, THPs will only be used when:
> +.RS
> +.IP \[bu] 2

s/2/3/

See man-pages(7) ("Lists"):

       There should always be exactly 2 spaces between the list  symbol
       and  the  elements.   This doesn't apply to "tagged paragraphs",
       which use the default indentation rules.

(If you grep(1) around, you'll see that number everywhere.)

> +Global THP controls are set to "always" or "madvise" and
> +.BR madvise (...,
> +.BR MADV_HUGEPAGE )

I'd say

	.I madvise(..., MADV_HUGEPAGE)

as an inlined expression, which goes in full italics; that's simpler.

> +or
> +.BR madvise (...,
> +.BR MADV_COLLAPSE )
> +is used.
> +.IP \[bu]
> +Global THP controls are set to "never" and
> +.BR madvise (...,
> +.BR MADV_COLLAPSE )
> +is used.
> +This is the same behavior as if THPs would not be disabled on
> +a process level.

Please break the line before "as if".

> +.RE
>  .SH RETURN VALUE
>  On success,
>  0 is returned.

Have a lovely day!
Alex

-- 
<https://www.alejandro-colomar.es>
Use port 80 (that is, <...:80/>).

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

Re: [PATCH] PR_*ET_THP_DISABLE.2const: document addition of PR_THP_DISABLE_EXCEPT_ADVISED

[Usama Arif]

On 01/09/2025 17:36, Alejandro Colomar wrote:
> Hi Usama,
> 
> On Mon, Sep 01, 2025 at 05:09:03PM +0100, Usama Arif wrote:
>> PR_THP_DISABLE_EXCEPT_ADVISED extended PR_SET_THP_DISABLE to only provide
>> THPs when advised. IOW, it allows individual processes to opt-out of THP =
>> "always" into THP = "madvise", without affecting other workloads on the
>> system. The series has been merged in [1].
>>
>> This patch documents the changes introduced due to the addition of
>> PR_THP_DISABLE_EXCEPT_ADVISED flag:
>> - PR_GET_THP_DISABLE returns a value whose bits indicate how THP-disable
>>   is configured for the calling thread (with or without
>>   PR_THP_DISABLE_EXCEPT_ADVISED).
>> - PR_SET_THP_DISABLE now uses arg3 to specify whether to disable THP
>>   completely for the process, or disable except madvise
>>   (PR_THP_DISABLE_EXCEPT_ADVISED).
>>
>> [1] https://lore.kernel.org/all/20250815135549.130506-1-usamaarif642@gmail.com/
>>
>> Signed-off-by: Usama Arif <usamaarif642@gmail.com>
> 
> Thanks for writing the patch!  Please see some comments below.


Thanks for the quick review! Its my first time writing a man page so was apologies
if there were some basic mistakes in formatting.

> 
>> ---
>>  man/man2/madvise.2                      |  4 +-
>>  man/man2const/PR_GET_THP_DISABLE.2const | 18 ++++++---
>>  man/man2const/PR_SET_THP_DISABLE.2const | 52 +++++++++++++++++++++----
>>  3 files changed, 61 insertions(+), 13 deletions(-)
>>
>> diff --git a/man/man2/madvise.2 b/man/man2/madvise.2
>> index 10cc21fa4..6a5290f67 100644
>> --- a/man/man2/madvise.2
>> +++ b/man/man2/madvise.2
>> @@ -373,7 +373,9 @@ nor can it be stack memory or backed by a DAX-enabled device
>>  (unless the DAX device is hot-plugged as System RAM).
>>  The process must also not have
>>  .B PR_SET_THP_DISABLE
>> -set (see
>> +set without the
>> +.B PR_THP_DISABLE_EXCEPT_ADVISED
>> +flag (see
>>  .BR prctl (2)).
> 
> Double negation is confusing.  Please rephrase to something like
> 
> 	The process can have X set
> 	only if Y is also set.
> 

Yes, makes sense, will change to belwow in the next revision:

The process can have
.B PR_SET_THP_DISABLE
set only if
.B PR_THP_DISABLE_EXCEPT_ADVISED
flag is set (see
.BR prctl (2)).

>>  .IP
>>  The
>> diff --git a/man/man2const/PR_GET_THP_DISABLE.2const b/man/man2const/PR_GET_THP_DISABLE.2const
>> index 38ff3b370..df239700f 100644
>> --- a/man/man2const/PR_GET_THP_DISABLE.2const
>> +++ b/man/man2const/PR_GET_THP_DISABLE.2const
>> @@ -6,7 +6,7 @@
>>  .SH NAME
>>  PR_GET_THP_DISABLE
>>  \-
>> -get the state of the "THP disable" flag for the calling thread
>> +get the state of the "THP disable" flags for the calling thread
>>  .SH LIBRARY
>>  Standard C library
>>  .RI ( libc ,\~ \-lc )
>> @@ -18,13 +18,21 @@ Standard C library
>>  .B int prctl(PR_GET_THP_DISABLE, 0L, 0L, 0L, 0L);
>>  .fi
>>  .SH DESCRIPTION
>> -Return the current setting of
>> -the "THP disable" flag for the calling thread:
>> -either 1, if the flag is set, or 0, if it is not.
>> +Returns a value whose bits indicate how THP-disable is configured
> 
> s/Returns/Return/
> 

ack

>> +for the calling thread.
>> +The returned value is interpreted as follows:
>> +.P
>> +.nf
>> +.B "Bits"
>> +.B " 1 0  Value  Description"
>> + 0 0    0    No THP-disable behaviour specified.
>> + 0 1    1    THP is entirely disabled for this process.
>> + 1 1    3    THP-except-advised mode is set for this process.
> 
> We should probably use a table with .TS/.TE.  See examples of this in
> other manual pages for how to use that (or read tbl(1) if you want).
> 
> If you don't know how to use that, I can do it myself.  tbl(1) is a bit
> weird.


I tried below, and it seemed to look ok in the output, but please let me know if
its ok:

.TS
allbox;
cb cb cb l
c c c l.
Bit 1	Bit 0	Value	Description
0	0	0	No THP-disable behaviour specified.
0	1	1	THP is entirely disabled for this process.
1	1	3	THP-except-advised mode is set for this process.
.TE


> 
>> +.fi
>>  .SH RETURN VALUE
>>  On success,
>>  .BR PR_GET_THP_DISABLE ,
>> -returns the boolean value described above.
>> +returns the value described above.
>>  On error, \-1 is returned, and
>>  .I errno
>>  is set to indicate the error.
>> diff --git a/man/man2const/PR_SET_THP_DISABLE.2const b/man/man2const/PR_SET_THP_DISABLE.2const
>> index 564e005d4..9f0f17702 100644
>> --- a/man/man2const/PR_SET_THP_DISABLE.2const
>> +++ b/man/man2const/PR_SET_THP_DISABLE.2const
>> @@ -6,7 +6,7 @@
>>  .SH NAME
>>  PR_SET_THP_DISABLE
>>  \-
>> -set the state of the "THP disable" flag for the calling thread
>> +set the state of the "THP disable" flags for the calling thread
>>  .SH LIBRARY
>>  Standard C library
>>  .RI ( libc ,\~ \-lc )
>> @@ -15,24 +15,62 @@ Standard C library
>>  .BR "#include <linux/prctl.h>" "  /* Definition of " PR_* " constants */"
>>  .B #include <sys/prctl.h>
>>  .P
>> -.BI "int prctl(PR_SET_THP_DISABLE, long " flag ", 0L, 0L, 0L);"
>> +.BI "int prctl(PR_SET_THP_DISABLE, long " thp_disable ", unsigned long " flags ", 0L, 0L);"
> 
> Hmmm, I'm reading this weirdly.
> 
> Old code doing prctl(PR_SET_THP_DIABLE, 1, 0L, 0L, 0L); would be
> transformed from setting the flag before, to now using 0L as flags?
> 
> Or how is backwards compatibility handled?
> 


Its still backwards compatible. The name of the arguments is changed, but the arg values have not.
Before you could do 2 things:

prctl(PR_SET_THP_DISABLE, 0, 0, 0, 0); // to reset THP setting.
prctl(PR_SET_THP_DISABLE, 1, 0, 0, 0); // to disable THPs completely.

Now in addition to the 2 calls above, you can do:
prctl(PR_SET_THP_DISABLE, 1, PR_THP_DISABLE_EXCEPT_ADVISED, 0, 0); // to disable THPs except madvise.


Before arg2 was called flags and arg3 was always 0.
Now arg2 is called thp_disable, and arg3 is called flags.


>>  .fi
>>  .SH DESCRIPTION
>> -Set the state of the "THP disable" flag for the calling thread.
>> +Set the state of the "THP disable" flags for the calling thread.
>>  If
>> -.I flag
>> -has a nonzero value, the flag is set, otherwise it is cleared.
>> +.I thp_disable
>> +has a nonzero value, the THP disable flag is set according to the value of
> 
> Please break the line after the comma.
> 

ack

>> +.I flags,
>> +otherwise it is cleared.
>>  .P
>> -Setting this flag provides a method
>> +This
>> +.BR prctl (2)
>> +provides a method
>>  for disabling transparent huge pages
>>  for jobs where the code cannot be modified,
>>  and using a malloc hook with
>>  .BR madvise (2)
>>  is not an option (i.e., statically allocated data).
>> -The setting of the "THP disable" flag is inherited by a child created via
>> +The setting of the "THP disable" flags is inherited by a child created via
>>  .BR fork (2)
>>  and is preserved across
>>  .BR execve (2).
>> +.P
>> +The behavior depends on the value of
>> +.IR flags:
>> +.TP
>> +.B 0
>> +The
>> +.BR prctl (2)
>> +call will disable THPs completely for the process,
>> +irrespective of global THP controls or
>> +.BR MADV_COLLAPSE .
>> +.TP
>> +.B PR_THP_DISABLE_EXCEPT_ADVISED
>> +The
>> +.BR prctl (2)
>> +call will disable THPs for the process except when the usage of THPs is
>> +advised.
> 
> Please break the line before 'except'.  See 'Use semantic newlines'
> in man-pages(7).

ack> 
>> +Consequently, THPs will only be used when:
>> +.RS
>> +.IP \[bu] 2
> 
> s/2/3/

ack

> 
> See man-pages(7) ("Lists"):
> 
>        There should always be exactly 2 spaces between the list  symbol
>        and  the  elements.   This doesn't apply to "tagged paragraphs",
>        which use the default indentation rules.
> 
> (If you grep(1) around, you'll see that number everywhere.)
> 
>> +Global THP controls are set to "always" or "madvise" and
>> +.BR madvise (...,
>> +.BR MADV_HUGEPAGE )
> 
> I'd say
> 
> 	.I madvise(..., MADV_HUGEPAGE)
> 
> as an inlined expression, which goes in full italics; that's simpler.

This results in the entire line being underlined, which is probably not what
not what we want?

> 
>> +or
>> +.BR madvise (...,
>> +.BR MADV_COLLAPSE )
>> +is used.
>> +.IP \[bu]
>> +Global THP controls are set to "never" and
>> +.BR madvise (...,
>> +.BR MADV_COLLAPSE )
>> +is used.
>> +This is the same behavior as if THPs would not be disabled on
>> +a process level.
> 
> Please break the line before "as if".

ack

> 
>> +.RE
>>  .SH RETURN VALUE
>>  On success,
>>  0 is returned.
> 
> Have a lovely day!
> Alex
> 

Re: [PATCH] PR_*ET_THP_DISABLE.2const: document addition of PR_THP_DISABLE_EXCEPT_ADVISED

[Alejandro Colomar]

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

Hi Usama,

On Mon, Sep 01, 2025 at 05:58:39PM +0100, Usama Arif wrote:
> Thanks for the quick review! Its my first time writing a man page so was apologies
> if there were some basic mistakes in formatting.

No problem.  Formatting issues are usual, and expected.  :)

> >> @@ -373,7 +373,9 @@ nor can it be stack memory or backed by a DAX-enabled device
> >>  (unless the DAX device is hot-plugged as System RAM).
> >>  The process must also not have
> >>  .B PR_SET_THP_DISABLE
> >> -set (see
> >> +set without the
> >> +.B PR_THP_DISABLE_EXCEPT_ADVISED
> >> +flag (see
> >>  .BR prctl (2)).
> > 
> > Double negation is confusing.  Please rephrase to something like
> > 
> > 	The process can have X set
> > 	only if Y is also set.
> > 
> 
> Yes, makes sense, will change to belwow in the next revision:
> 
> The process can have
> .B PR_SET_THP_DISABLE
> set only if
> .B PR_THP_DISABLE_EXCEPT_ADVISED
> flag is set (see
> .BR prctl (2)).

Sounds good.

> >>  .IP
> >>  The
> >> diff --git a/man/man2const/PR_GET_THP_DISABLE.2const b/man/man2const/PR_GET_THP_DISABLE.2const
> >> index 38ff3b370..df239700f 100644
> >> --- a/man/man2const/PR_GET_THP_DISABLE.2const
> >> +++ b/man/man2const/PR_GET_THP_DISABLE.2const
> >> @@ -6,7 +6,7 @@
> >>  .SH NAME
> >>  PR_GET_THP_DISABLE
> >>  \-
> >> -get the state of the "THP disable" flag for the calling thread
> >> +get the state of the "THP disable" flags for the calling thread
> >>  .SH LIBRARY
> >>  Standard C library
> >>  .RI ( libc ,\~ \-lc )
> >> @@ -18,13 +18,21 @@ Standard C library
> >>  .B int prctl(PR_GET_THP_DISABLE, 0L, 0L, 0L, 0L);
> >>  .fi
> >>  .SH DESCRIPTION
> >> -Return the current setting of
> >> -the "THP disable" flag for the calling thread:
> >> -either 1, if the flag is set, or 0, if it is not.
> >> +Returns a value whose bits indicate how THP-disable is configured
> > 
> > s/Returns/Return/
> > 
> 
> ack

The thing is, if we were writing it from scratch, I wouldn't have a
preference.  However, given it already uses Return, I don't see strong
reasons to change it.

If you still prefer to change it, though, feel free to insist.

> >> +for the calling thread.
> >> +The returned value is interpreted as follows:
> >> +.P
> >> +.nf
> >> +.B "Bits"
> >> +.B " 1 0  Value  Description"
> >> + 0 0    0    No THP-disable behaviour specified.
> >> + 0 1    1    THP is entirely disabled for this process.
> >> + 1 1    3    THP-except-advised mode is set for this process.
> > 
> > We should probably use a table with .TS/.TE.  See examples of this in
> > other manual pages for how to use that (or read tbl(1) if you want).
> > 
> > If you don't know how to use that, I can do it myself.  tbl(1) is a bit
> > weird.
> 
> 
> I tried below, and it seemed to look ok in the output, but please let me know if
> its ok:
> 
> .TS
> allbox;
> cb cb cb l
> c c c l.
> Bit 1	Bit 0	Value	Description
> 0	0	0	No THP-disable behaviour specified.
> 0	1	1	THP is entirely disabled for this process.
> 1	1	3	THP-except-advised mode is set for this process.
> .TE

At first glance, looks good.

> >> @@ -15,24 +15,62 @@ Standard C library
> >>  .BR "#include <linux/prctl.h>" "  /* Definition of " PR_* " constants */"
> >>  .B #include <sys/prctl.h>
> >>  .P
> >> -.BI "int prctl(PR_SET_THP_DISABLE, long " flag ", 0L, 0L, 0L);"
> >> +.BI "int prctl(PR_SET_THP_DISABLE, long " thp_disable ", unsigned long " flags ", 0L, 0L);"
> > 
> > Hmmm, I'm reading this weirdly.
> > 
> > Old code doing prctl(PR_SET_THP_DIABLE, 1, 0L, 0L, 0L); would be
> > transformed from setting the flag before, to now using 0L as flags?
> > 
> > Or how is backwards compatibility handled?
> > 
> 
> 
> Its still backwards compatible. The name of the arguments is changed, but the arg values have not.
> Before you could do 2 things:
> 
> prctl(PR_SET_THP_DISABLE, 0, 0, 0, 0); // to reset THP setting.
> prctl(PR_SET_THP_DISABLE, 1, 0, 0, 0); // to disable THPs completely.
> 
> Now in addition to the 2 calls above, you can do:
> prctl(PR_SET_THP_DISABLE, 1, PR_THP_DISABLE_EXCEPT_ADVISED, 0, 0); // to disable THPs except madvise.

Thanks!  This helped me understand it.  I think this would be useful in
the commit message.

> > 
> > See man-pages(7) ("Lists"):
> > 
> >        There should always be exactly 2 spaces between the list  symbol
> >        and  the  elements.   This doesn't apply to "tagged paragraphs",
> >        which use the default indentation rules.
> > 
> > (If you grep(1) around, you'll see that number everywhere.)
> > 
> >> +Global THP controls are set to "always" or "madvise" and
> >> +.BR madvise (...,
> >> +.BR MADV_HUGEPAGE )
> > 
> > I'd say
> > 
> > 	.I madvise(..., MADV_HUGEPAGE)
> > 
> > as an inlined expression, which goes in full italics; that's simpler.
> 
> This results in the entire line being underlined, which is probably not what
> not what we want?

The entire function call is underlined; see man-pages(7):

       Expressions, if not written on a separate indented line,  should
       be  specified  in italics.  Again, the use of nonbreaking spaces
       may be appropriate if the  expression  is  inlined  with  normal
       text.

Which reminds me to prevent the line from breaking at that expression:

	.I \%madvise(...,\~MADV_HUGEPAGE)


Have a lovely day!
Alex

-- 
<https://www.alejandro-colomar.es>
Use port 80 (that is, <...:80/>).

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

[PATCH] PR_*ET_THP_DISABLE.2const: document addition of PR_THP_DISABLE_EXCEPT_ADVISED

[Usama Arif]

PR_THP_DISABLE_EXCEPT_ADVISED extended PR_SET_THP_DISABLE to only provide
THPs when advised. IOW, it allows individual processes to opt-out of THP =
"always" into THP = "madvise", without affecting other workloads on the
system. The series has been merged in [1]. Before [1], the following 2
calls were allowed with PR_SET_THP_DISABLE:

prctl(PR_SET_THP_DISABLE, 0, 0, 0, 0); // to reset THP setting.
prctl(PR_SET_THP_DISABLE, 1, 0, 0, 0); // to disable THPs completely.

Now in addition to the 2 calls above, you can do:

prctl(PR_SET_THP_DISABLE, 1, PR_THP_DISABLE_EXCEPT_ADVISED, 0, 0); // to
disable THPs except madvise.

This patch documents the changes introduced due to the addition of
PR_THP_DISABLE_EXCEPT_ADVISED flag:
- PR_GET_THP_DISABLE returns a value whose bits indicate how THP-disable
  is configured for the calling thread (with or without
  PR_THP_DISABLE_EXCEPT_ADVISED).
- PR_SET_THP_DISABLE now uses arg3 to specify whether to disable THP
  completely for the process, or disable except madvise
  (PR_THP_DISABLE_EXCEPT_ADVISED).

[1] https://lore.kernel.org/all/20250815135549.130506-1-usamaarif642@gmail.com/

Signed-off-by: Usama Arif <usamaarif642@gmail.com>
---
v1 -> v2 (Alejandro Colomar):
- Fixed diuble negation on when MADV_HUGEPAGE will succeed
- Turn return values of PR_GET_THP_DISABLE into a table
- Turn madvise calls into full italics
- Use semantic newlines
---
 man/man2/madvise.2                      |  6 ++-
 man/man2const/PR_GET_THP_DISABLE.2const | 20 +++++++---
 man/man2const/PR_SET_THP_DISABLE.2const | 52 +++++++++++++++++++++----
 3 files changed, 64 insertions(+), 14 deletions(-)

diff --git a/man/man2/madvise.2 b/man/man2/madvise.2
index 10cc21fa4..847e7aea6 100644
--- a/man/man2/madvise.2
+++ b/man/man2/madvise.2
@@ -371,9 +371,11 @@ or
 .BR VM_PFNMAP ,
 nor can it be stack memory or backed by a DAX-enabled device
 (unless the DAX device is hot-plugged as System RAM).
-The process must also not have
+The process can have
 .B PR_SET_THP_DISABLE
-set (see
+set only if
+.B PR_THP_DISABLE_EXCEPT_ADVISED
+flag is set (see
 .BR prctl (2)).
 .IP
 The
diff --git a/man/man2const/PR_GET_THP_DISABLE.2const b/man/man2const/PR_GET_THP_DISABLE.2const
index 38ff3b370..d63cff21c 100644
--- a/man/man2const/PR_GET_THP_DISABLE.2const
+++ b/man/man2const/PR_GET_THP_DISABLE.2const
@@ -6,7 +6,7 @@
 .SH NAME
 PR_GET_THP_DISABLE
 \-
-get the state of the "THP disable" flag for the calling thread
+get the state of the "THP disable" flags for the calling thread
 .SH LIBRARY
 Standard C library
 .RI ( libc ,\~ \-lc )
@@ -18,13 +18,23 @@ Standard C library
 .B int prctl(PR_GET_THP_DISABLE, 0L, 0L, 0L, 0L);
 .fi
 .SH DESCRIPTION
-Return the current setting of
-the "THP disable" flag for the calling thread:
-either 1, if the flag is set, or 0, if it is not.
+Return a value whose bits indicate how THP-disable is configured
+for the calling thread.
+The returned value is interpreted as follows:
+.P
+.TS
+allbox;
+cb cb cb l
+c c c l.
+Bit 1	Bit 0	Value	Description
+0	0	0	No THP-disable behaviour specified.
+0	1	1	THP is entirely disabled for this process.
+1	1	3	THP-except-advised mode is set for this process.
+.TE
 .SH RETURN VALUE
 On success,
 .BR PR_GET_THP_DISABLE ,
-returns the boolean value described above.
+returns the value described above.
 On error, \-1 is returned, and
 .I errno
 is set to indicate the error.
diff --git a/man/man2const/PR_SET_THP_DISABLE.2const b/man/man2const/PR_SET_THP_DISABLE.2const
index 564e005d4..82e694724 100644
--- a/man/man2const/PR_SET_THP_DISABLE.2const
+++ b/man/man2const/PR_SET_THP_DISABLE.2const
@@ -6,7 +6,7 @@
 .SH NAME
 PR_SET_THP_DISABLE
 \-
-set the state of the "THP disable" flag for the calling thread
+set the state of the "THP disable" flags for the calling thread
 .SH LIBRARY
 Standard C library
 .RI ( libc ,\~ \-lc )
@@ -15,24 +15,62 @@ Standard C library
 .BR "#include <linux/prctl.h>" "  /* Definition of " PR_* " constants */"
 .B #include <sys/prctl.h>
 .P
-.BI "int prctl(PR_SET_THP_DISABLE, long " flag ", 0L, 0L, 0L);"
+.BI "int prctl(PR_SET_THP_DISABLE, long " thp_disable ", unsigned long " flags ", 0L, 0L);"
 .fi
 .SH DESCRIPTION
-Set the state of the "THP disable" flag for the calling thread.
+Set the state of the "THP disable" flags for the calling thread.
 If
-.I flag
-has a nonzero value, the flag is set, otherwise it is cleared.
+.I thp_disable
+has a nonzero value,
+the THP disable flag is set according to the value of
+.I flags,
+otherwise it is cleared.
 .P
-Setting this flag provides a method
+This
+.BR prctl (2)
+provides a method
 for disabling transparent huge pages
 for jobs where the code cannot be modified,
 and using a malloc hook with
 .BR madvise (2)
 is not an option (i.e., statically allocated data).
-The setting of the "THP disable" flag is inherited by a child created via
+The setting of the "THP disable" flags is inherited by a child created via
 .BR fork (2)
 and is preserved across
 .BR execve (2).
+.P
+The behavior depends on the value of
+.IR flags:
+.TP
+.B 0
+The
+.BR prctl (2)
+call will disable THPs completely for the process,
+irrespective of global THP controls or
+.BR MADV_COLLAPSE .
+.TP
+.B PR_THP_DISABLE_EXCEPT_ADVISED
+The
+.BR prctl (2)
+call will disable THPs for the process
+except when the usage of THPs is
+advised.
+Consequently, THPs will only be used when:
+.RS
+.IP \[bu] 3
+Global THP controls are set to "always" or "madvise" and
+.I \%madvise(...,\~MADV_HUGEPAGE)
+or
+.I \%madvise(...,\~MADV_COLLAPSE)
+is used.
+.IP \[bu]
+Global THP controls are set to "never" and
+.I \%madvise(...,\~MADV_COLLAPSE)
+is used.
+This is the same behavior
+as if THPs would not be disabled on
+a process level.
+.RE
 .SH RETURN VALUE
 On success,
 0 is returned.
-- 
2.47.3

Re: [PATCH] PR_*ET_THP_DISABLE.2const: document addition of PR_THP_DISABLE_EXCEPT_ADVISED

[Usama Arif]

On 05/09/2025 14:25, Usama Arif wrote:
> PR_THP_DISABLE_EXCEPT_ADVISED extended PR_SET_THP_DISABLE to only provide
> THPs when advised. IOW, it allows individual processes to opt-out of THP =
> "always" into THP = "madvise", without affecting other workloads on the
> system. The series has been merged in [1]. Before [1], the following 2
> calls were allowed with PR_SET_THP_DISABLE:
> 
> prctl(PR_SET_THP_DISABLE, 0, 0, 0, 0); // to reset THP setting.
> prctl(PR_SET_THP_DISABLE, 1, 0, 0, 0); // to disable THPs completely.
> 
> Now in addition to the 2 calls above, you can do:
> 
> prctl(PR_SET_THP_DISABLE, 1, PR_THP_DISABLE_EXCEPT_ADVISED, 0, 0); // to
> disable THPs except madvise.
> 
> This patch documents the changes introduced due to the addition of
> PR_THP_DISABLE_EXCEPT_ADVISED flag:
> - PR_GET_THP_DISABLE returns a value whose bits indicate how THP-disable
>   is configured for the calling thread (with or without
>   PR_THP_DISABLE_EXCEPT_ADVISED).
> - PR_SET_THP_DISABLE now uses arg3 to specify whether to disable THP
>   completely for the process, or disable except madvise
>   (PR_THP_DISABLE_EXCEPT_ADVISED).
> 
> [1] https://lore.kernel.org/all/20250815135549.130506-1-usamaarif642@gmail.com/
> 
> Signed-off-by: Usama Arif <usamaarif642@gmail.com>
> ---
> v1 -> v2 (Alejandro Colomar):
> - Fixed diuble negation on when MADV_HUGEPAGE will succeed
> - Turn return values of PR_GET_THP_DISABLE into a table
> - Turn madvise calls into full italics
> - Use semantic newlines
> ---

Ah forgot to add "v2" to subject.