Re: [PATCH v3 4/6] docs: transhuge: document process level THP controls

[Lorenzo Stoakes <lorenzo.stoakes@oracle.com>]

On Mon, Aug 04, 2025 at 04:40:47PM +0100, Usama Arif wrote:
> This includes the PR_SET_THP_DISABLE/PR_GET_THP_DISABLE pair of
> prctl calls as well the newly introduced PR_THP_DISABLE_EXCEPT_ADVISED
> flag for the PR_SET_THP_DISABLE prctl call.
>
> Signed-off-by: Usama Arif <usamaarif642@gmail.com>
> ---
>  Documentation/admin-guide/mm/transhuge.rst | 38 ++++++++++++++++++++++
>  1 file changed, 38 insertions(+)
>
> diff --git a/Documentation/admin-guide/mm/transhuge.rst b/Documentation/admin-guide/mm/transhuge.rst
> index 370fba113460..a36a04394ff5 100644
> --- a/Documentation/admin-guide/mm/transhuge.rst
> +++ b/Documentation/admin-guide/mm/transhuge.rst
> @@ -225,6 +225,44 @@ to "always" or "madvise"), and it'll be automatically shutdown when
>  PMD-sized THP is disabled (when both the per-size anon control and the
>  top-level control are "never")
>
> +process THP controls
> +--------------------
> +
> +A process can control its own THP behaviour using the ``PR_SET_THP_DISABLE``
> +and ``PR_GET_THP_DISABLE`` pair of prctl(2) calls. These calls support the
> +following arguments::
> +
> +	prctl(PR_SET_THP_DISABLE, 1, 0, 0, 0):
> +		This will set the MMF_DISABLE_THP_COMPLETELY mm flag which will

I'm not sure these impl details are necessary, this is an admin guide doc.

> +		result in no THPs being faulted in or collapsed, irrespective
> +		of global THP controls. This flag and hence the behaviour is

Also irrespective of MADV_COLLAPSE right?

Important to highlight that, as it's the only way to disable that.

> +		inherited across fork(2) and execve(2).

I'd remove the 'this flag' bit here.

> +
> +	prctl(PR_SET_THP_DISABLE, 1, PR_THP_DISABLE_EXCEPT_ADVISED, 0, 0):
> +		This will set the MMF_DISABLE_THP_EXCEPT_ADVISED mm flag which

No need to refer to implementation detail of mm flag.

> +		will result in THPs being faulted in or collapsed only for
> +		the following cases:
> +		- Global THP controls are set to "always" or "madvise" and
> +		  the process has madvised the region with either MADV_HUGEPAGE
> +		  or MADV_COLLAPSE.
> +		- Global THP controls is set to "never" and the process has
> +		  madvised the region with MADV_COLLAPSE.

Nit, but prefer madvise()'d, or really 'used madvise() with the MADV_COLLAPSE
flag over the region'.

> +		This flag and hence the behaviour is inherited across fork(2)
> +		and execve(2).

Again drop 'this flag'.

> +
> +	prctl(PR_SET_THP_DISABLE, 0, 0, 0, 0):
> +		This will clear the MMF_DISABLE_THP_COMPLETELY and
> +		MMF_DISABLE_THP_EXCEPT_ADVISED mm flags. The process will

Remove impl details.

> +		behave according to the global THP controls. This behaviour
> +		will be inherited across fork(2) and execve(2).

Something like 'this will revoke any specified THP disable behaviour and the
process will behave normally with respect to THP. As with the other THP disable
flags, this change is inherited across fork/exec.'

> +
> +	prctl(PR_GET_THP_DISABLE, 0, 0, 0, 0):
> +		This will return the THP disable mm flag status of the process
> +		that was set by prctl(PR_SET_THP_DISABLE, ...). i.e.
> +		- 1 if MMF_DISABLE_THP_COMPLETELY flag is set

This is incorrect, this is set if either flag is set.

Again, remove impl details.

> +		- 3 if MMF_DISABLE_THP_EXCEPT_ADVISED flag is set
> +		- 0 otherwise.

This is really not clear, people are going to wonder why it's randomly 3.

Maybe something like:

This returns a value whose bit indicate how THP-disable is configured:

    Bits
     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.

> +
>  Khugepaged controls
>  -------------------
>
> --
> 2.47.3
>

Cheers, Lorenzo