[PATCH 0/2] Docs: THP documentation fixes

[PATCH 0/2] Docs: THP documentation fixes

[Song Hu]

Two fixes for the transparent hugepage documentation:

 1. the shrink_underused sysfs knob (added in commit 81d3ff3c6f76) is
    missing from the ABI document;
 2. the transparent_hugepage_shmem= and transparent_hugepage_tmpfs= boot
    parameters are documented with wrong policy counts (six, not seven
    and four).

Song Hu (2):
  Docs/ABI: document transparent_hugepage/shrink_underused
  Docs/mm: fix THP policy counts in transhuge

 .../ABI/testing/sysfs-kernel-mm-transparent-hugepage   | 10 ++++++++++
 Documentation/admin-guide/mm/transhuge.rst             |  6 +++---
 2 files changed, 13 insertions(+), 3 deletions(-)

-- 
2.43.0

[PATCH 1/2] Docs/ABI: document transparent_hugepage/shrink_underused

[Song Hu]

The shrink_underused knob was added in commit 81d3ff3c6f76 ("mm: add
sysfs entry to disable splitting underused THPs") but is missing from
Documentation/ABI/testing/sysfs-kernel-mm-transparent-hugepage, although
transhuge.rst already documents it.  Add the ABI entry.

Signed-off-by: Song Hu <husong@kylinos.cn>
---
 .../ABI/testing/sysfs-kernel-mm-transparent-hugepage   | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/Documentation/ABI/testing/sysfs-kernel-mm-transparent-hugepage b/Documentation/ABI/testing/sysfs-kernel-mm-transparent-hugepage
index 7bfbb9cc2c11..bbdfae2c0caa 100644
--- a/Documentation/ABI/testing/sysfs-kernel-mm-transparent-hugepage
+++ b/Documentation/ABI/testing/sysfs-kernel-mm-transparent-hugepage
@@ -10,9 +10,19 @@ Description:
 			- hpage_pmd_size
 			- khugepaged
 			- shmem_enabled
+			- shrink_underused
 			- use_zero_page
 			- subdirectories of the form hugepages-<size>kB, where <size>
 			  is the page size of the hugepages supported by the kernel/CPU
 			  combination.
 
 		See Documentation/admin-guide/mm/transhuge.rst for details.
+
+What:		/sys/kernel/mm/transparent_hugepage/shrink_underused
+Date:		Sep 2024
+Contact:	Linux memory management mailing list <linux-mm@kvack.org>
+Description:	Reading and writing this file controls whether khugepaged
+		splits underused transparent huge pages (THPs) under memory
+		pressure.  A THP is considered underused when its number of
+		zero-filled pages is above max_ptes_none.  Enabled by default;
+		writing 0 disables the splitting and 1 enables it.
-- 
2.43.0

Re: [PATCH 1/2] Docs/ABI: document transparent_hugepage/shrink_underused

[Lorenzo Stoakes (ARM)]

Please don't send patch series like this - we really require a cover letter if
patch count > 1, and every patch should reply to the cover letter.

On Wed, Aug 12, 2026 at 04:03:12PM +0800, Song Hu wrote:
> The shrink_underused knob was added in commit 81d3ff3c6f76 ("mm: add
> sysfs entry to disable splitting underused THPs") but is missing from
> Documentation/ABI/testing/sysfs-kernel-mm-transparent-hugepage, although
> transhuge.rst already documents it.  Add the ABI entry.

Hmm what even is this file? :) What is the contract on this file?

>
> Signed-off-by: Song Hu <husong@kylinos.cn>
> ---
>  .../ABI/testing/sysfs-kernel-mm-transparent-hugepage   | 10 ++++++++++
>  1 file changed, 10 insertions(+)
>
> diff --git a/Documentation/ABI/testing/sysfs-kernel-mm-transparent-hugepage b/Documentation/ABI/testing/sysfs-kernel-mm-transparent-hugepage
> index 7bfbb9cc2c11..bbdfae2c0caa 100644
> --- a/Documentation/ABI/testing/sysfs-kernel-mm-transparent-hugepage
> +++ b/Documentation/ABI/testing/sysfs-kernel-mm-transparent-hugepage
> @@ -10,9 +10,19 @@ Description:
>  			- hpage_pmd_size
>  			- khugepaged
>  			- shmem_enabled
> +			- shrink_underused

I mean I guess fine for consistency.

>  			- use_zero_page
>  			- subdirectories of the form hugepages-<size>kB, where <size>
>  			  is the page size of the hugepages supported by the kernel/CPU
>  			  combination.

But we already handwave literally everything else here....


>
>  		See Documentation/admin-guide/mm/transhuge.rst for details.
> +
> +What:		/sys/kernel/mm/transparent_hugepage/shrink_underused
> +Date:		Sep 2024
> +Contact:	Linux memory management mailing list <linux-mm@kvack.org>
> +Description:	Reading and writing this file controls whether khugepaged
> +		splits underused transparent huge pages (THPs) under memory
> +		pressure.  A THP is considered underused when its number of
> +		zero-filled pages is above max_ptes_none.  Enabled by default;
> +		writing 0 disables the splitting and 1 enables it.

Nothing else is documented in this file so why is this getting special
treatment? And why is it backdated to Sep 2024?...

Drop it please.

> --
> 2.43.0
>

--
Cheers, Lorenzo

[PATCH 2/2] Docs/mm: fix THP policy counts in transhuge

[Song Hu]

transhuge.rst claims seven policies for transparent_hugepage_shmem= and
four for transparent_hugepage_tmpfs=.  Both boot parameters are parsed by
shmem_parse_huge(), which accepts six: always, within_size, advise, never,
deny and force.  The "four" applies only to the per-mount huge= option
(shmem_param_enums_huge).  Fix both counts to six.

Signed-off-by: Song Hu <husong@kylinos.cn>
---
 Documentation/admin-guide/mm/transhuge.rst | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/admin-guide/mm/transhuge.rst b/Documentation/admin-guide/mm/transhuge.rst
index b187d618452f..72e944f49da5 100644
--- a/Documentation/admin-guide/mm/transhuge.rst
+++ b/Documentation/admin-guide/mm/transhuge.rst
@@ -389,14 +389,14 @@ is not defined within a valid ``thp_anon``, its policy will default to
 Similarly to ``transparent_hugepage``, you can control the hugepage
 allocation policy for the internal shmem mount by using the kernel parameter
 ``transparent_hugepage_shmem=<policy>``, where ``<policy>`` is one of the
-seven valid policies for shmem (``always``, ``within_size``, ``advise``,
+six valid policies for shmem (``always``, ``within_size``, ``advise``,
 ``never``, ``deny``, and ``force``).
 
 Similarly to ``transparent_hugepage_shmem``, you can control the default
 hugepage allocation policy for the tmpfs mount by using the kernel parameter
 ``transparent_hugepage_tmpfs=<policy>``, where ``<policy>`` is one of the
-four valid policies for tmpfs (``always``, ``within_size``, ``advise``,
-``never``). The tmpfs mount default policy is ``never``.
+six valid policies for tmpfs (``always``, ``within_size``, ``advise``,
+``never``, ``deny``, and ``force``). The tmpfs mount default policy is ``never``.
 
 Additionally, Kconfig options are available to set the default hugepage
 policies for shmem (``CONFIG_TRANSPARENT_HUGEPAGE_SHMEM_HUGE_*``) and tmpfs
-- 
2.43.0

Re: [PATCH 2/2] Docs/mm: fix THP policy counts in transhuge

[Baolin Wang]

On 8/12/26 4:03 PM, Song Hu wrote:
> transhuge.rst claims seven policies for transparent_hugepage_shmem= and
> four for transparent_hugepage_tmpfs=.  Both boot parameters are parsed by
> shmem_parse_huge(), which accepts six: always, within_size, advise, never,
> deny and force.  The "four" applies only to the per-mount huge= option
> (shmem_param_enums_huge).  Fix both counts to six.
> 
> Signed-off-by: Song Hu <husong@kylinos.cn>
> ---
>   Documentation/admin-guide/mm/transhuge.rst | 6 +++---
>   1 file changed, 3 insertions(+), 3 deletions(-)
> 
> diff --git a/Documentation/admin-guide/mm/transhuge.rst b/Documentation/admin-guide/mm/transhuge.rst
> index b187d618452f..72e944f49da5 100644
> --- a/Documentation/admin-guide/mm/transhuge.rst
> +++ b/Documentation/admin-guide/mm/transhuge.rst
> @@ -389,14 +389,14 @@ is not defined within a valid ``thp_anon``, its policy will default to
>   Similarly to ``transparent_hugepage``, you can control the hugepage
>   allocation policy for the internal shmem mount by using the kernel parameter
>   ``transparent_hugepage_shmem=<policy>``, where ``<policy>`` is one of the
> -seven valid policies for shmem (``always``, ``within_size``, ``advise``,
> +six valid policies for shmem (``always``, ``within_size``, ``advise``,
>   ``never``, ``deny``, and ``force``).

Right.


>   Similarly to ``transparent_hugepage_shmem``, you can control the default
>   hugepage allocation policy for the tmpfs mount by using the kernel parameter
>   ``transparent_hugepage_tmpfs=<policy>``, where ``<policy>`` is one of the
> -four valid policies for tmpfs (``always``, ``within_size``, ``advise``,
> -``never``). The tmpfs mount default policy is ``never``.
> +six valid policies for tmpfs (``always``, ``within_size``, ``advise``,
> +``never``, ``deny``, and ``force``). The tmpfs mount default policy is ``never``.

But this is wrong. Original comments are correct.

Re: [PATCH 2/2] Docs/mm: fix THP policy counts in transhuge

[Lorenzo Stoakes (ARM)]

On Wed, Aug 12, 2026 at 04:03:13PM +0800, Song Hu wrote:
> transhuge.rst claims seven policies for transparent_hugepage_shmem= and
> four for transparent_hugepage_tmpfs=.  Both boot parameters are parsed by
> shmem_parse_huge(), which accepts six: always, within_size, advise, never,
> deny and force.  The "four" applies only to the per-mount huge= option
> (shmem_param_enums_huge).  Fix both counts to six.
>
> Signed-off-by: Song Hu <husong@kylinos.cn>
> ---
>  Documentation/admin-guide/mm/transhuge.rst | 6 +++---
>  1 file changed, 3 insertions(+), 3 deletions(-)
>
> diff --git a/Documentation/admin-guide/mm/transhuge.rst b/Documentation/admin-guide/mm/transhuge.rst
> index b187d618452f..72e944f49da5 100644
> --- a/Documentation/admin-guide/mm/transhuge.rst
> +++ b/Documentation/admin-guide/mm/transhuge.rst
> @@ -389,14 +389,14 @@ is not defined within a valid ``thp_anon``, its policy will default to
>  Similarly to ``transparent_hugepage``, you can control the hugepage
>  allocation policy for the internal shmem mount by using the kernel parameter
>  ``transparent_hugepage_shmem=<policy>``, where ``<policy>`` is one of the
> -seven valid policies for shmem (``always``, ``within_size``, ``advise``,
> +six valid policies for shmem (``always``, ``within_size``, ``advise``,
>  ``never``, ``deny``, and ``force``).

I'm not sure we really want to advertise 'special' testing modes like this,
sorry. These are not modes anybody should be using in practice especially at
kernel boot. We should probably stop people doing that...!

>
>  Similarly to ``transparent_hugepage_shmem``, you can control the default
>  hugepage allocation policy for the tmpfs mount by using the kernel parameter
>  ``transparent_hugepage_tmpfs=<policy>``, where ``<policy>`` is one of the
> -four valid policies for tmpfs (``always``, ``within_size``, ``advise``,
> -``never``). The tmpfs mount default policy is ``never``.
> +six valid policies for tmpfs (``always``, ``within_size``, ``advise``,
> +``never``, ``deny``, and ``force``). The tmpfs mount default policy is ``never``.
>

Similarly here.

>  Additionally, Kconfig options are available to set the default hugepage
>  policies for shmem (``CONFIG_TRANSPARENT_HUGEPAGE_SHMEM_HUGE_*``) and tmpfs
> --
> 2.43.0
>

--
Cheers, Lorenzo

Re: [PATCH 2/2] Docs/mm: fix THP policy counts in transhuge

[Baolin Wang]

On 8/12/26 5:27 PM, Lorenzo Stoakes (ARM) wrote:
> On Wed, Aug 12, 2026 at 04:03:13PM +0800, Song Hu wrote:
>> transhuge.rst claims seven policies for transparent_hugepage_shmem= and
>> four for transparent_hugepage_tmpfs=.  Both boot parameters are parsed by
>> shmem_parse_huge(), which accepts six: always, within_size, advise, never,
>> deny and force.  The "four" applies only to the per-mount huge= option
>> (shmem_param_enums_huge).  Fix both counts to six.
>>
>> Signed-off-by: Song Hu <husong@kylinos.cn>
>> ---
>>   Documentation/admin-guide/mm/transhuge.rst | 6 +++---
>>   1 file changed, 3 insertions(+), 3 deletions(-)
>>
>> diff --git a/Documentation/admin-guide/mm/transhuge.rst b/Documentation/admin-guide/mm/transhuge.rst
>> index b187d618452f..72e944f49da5 100644
>> --- a/Documentation/admin-guide/mm/transhuge.rst
>> +++ b/Documentation/admin-guide/mm/transhuge.rst
>> @@ -389,14 +389,14 @@ is not defined within a valid ``thp_anon``, its policy will default to
>>   Similarly to ``transparent_hugepage``, you can control the hugepage
>>   allocation policy for the internal shmem mount by using the kernel parameter
>>   ``transparent_hugepage_shmem=<policy>``, where ``<policy>`` is one of the
>> -seven valid policies for shmem (``always``, ``within_size``, ``advise``,
>> +six valid policies for shmem (``always``, ``within_size``, ``advise``,
>>   ``never``, ``deny``, and ``force``).
> 
> I'm not sure we really want to advertise 'special' testing modes like this,
> sorry. These are not modes anybody should be using in practice especially at
> kernel boot. We should probably stop people doing that...!

Yes, 'deny' and 'force' are testing-only configurations and really 
shouldn't be exposed via the kernel command line. I'll clean them up.

Re: [PATCH 2/2] Docs/mm: fix THP policy counts in transhuge

[Lorenzo Stoakes (ARM)]

On Wed, Aug 12, 2026 at 06:52:30PM +0800, Baolin Wang wrote:
>
>
> On 8/12/26 5:27 PM, Lorenzo Stoakes (ARM) wrote:
> > On Wed, Aug 12, 2026 at 04:03:13PM +0800, Song Hu wrote:
> > > transhuge.rst claims seven policies for transparent_hugepage_shmem= and
> > > four for transparent_hugepage_tmpfs=.  Both boot parameters are parsed by
> > > shmem_parse_huge(), which accepts six: always, within_size, advise, never,
> > > deny and force.  The "four" applies only to the per-mount huge= option
> > > (shmem_param_enums_huge).  Fix both counts to six.
> > >
> > > Signed-off-by: Song Hu <husong@kylinos.cn>
> > > ---
> > >   Documentation/admin-guide/mm/transhuge.rst | 6 +++---
> > >   1 file changed, 3 insertions(+), 3 deletions(-)
> > >
> > > diff --git a/Documentation/admin-guide/mm/transhuge.rst b/Documentation/admin-guide/mm/transhuge.rst
> > > index b187d618452f..72e944f49da5 100644
> > > --- a/Documentation/admin-guide/mm/transhuge.rst
> > > +++ b/Documentation/admin-guide/mm/transhuge.rst
> > > @@ -389,14 +389,14 @@ is not defined within a valid ``thp_anon``, its policy will default to
> > >   Similarly to ``transparent_hugepage``, you can control the hugepage
> > >   allocation policy for the internal shmem mount by using the kernel parameter
> > >   ``transparent_hugepage_shmem=<policy>``, where ``<policy>`` is one of the
> > > -seven valid policies for shmem (``always``, ``within_size``, ``advise``,
> > > +six valid policies for shmem (``always``, ``within_size``, ``advise``,
> > >   ``never``, ``deny``, and ``force``).
> >
> > I'm not sure we really want to advertise 'special' testing modes like this,
> > sorry. These are not modes anybody should be using in practice especially at
> > kernel boot. We should probably stop people doing that...!
>
> Yes, 'deny' and 'force' are testing-only configurations and really shouldn't
> be exposed via the kernel command line. I'll clean them up.

Thanks!

--
Cheers, Lorenzo