[PATCH] docs: hugetlbpage.rst: clarify HugePages_Total in hugetlbpage.rst

[PATCH] docs: hugetlbpage.rst: clarify HugePages_Total in hugetlbpage.rst

[Enze Li]

"the size of the pool of huge pages" confused me, since it sounds
like a size in bytes.  It's actually the number of persistent huge
pages of the default size, and pools of other sizes aren't shown
here at all.  Reword it and point to /sys/kernel/mm/hugepages for
those.

Signed-off-by: Enze Li <lienze@kylinos.cn>
---
 Documentation/admin-guide/mm/hugetlbpage.rst | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/Documentation/admin-guide/mm/hugetlbpage.rst b/Documentation/admin-guide/mm/hugetlbpage.rst
index 2075f1f14a42..01fa9f61c9a9 100644
--- a/Documentation/admin-guide/mm/hugetlbpage.rst
+++ b/Documentation/admin-guide/mm/hugetlbpage.rst
@@ -43,7 +43,9 @@ The output of ``cat /proc/meminfo`` will include lines like::
 where:
 
 HugePages_Total
-	is the size of the pool of huge pages.
+	is the number of persistent huge pages of the default size
+	in the pool.  Pools of other huge page sizes are not shown
+	here; see ``/sys/kernel/mm/hugepages`` described below.
 HugePages_Free
 	is the number of huge pages in the pool that are not yet
         allocated.

base-commit: 3fdcce698abd9193752ee89fb1a440cdceb1b74a
-- 
2.56.0

Re: [PATCH] docs: hugetlbpage.rst: clarify HugePages_Total in hugetlbpage.rst

[Daniel Pereira]

On Fri, Oct 23, 2026, Enze Li wrote:
> HugePages_Total
> - is the size of the pool of huge pages.
> + is the number of persistent huge pages of the default size
> + in the pool. Pools of other huge page sizes are not shown
> + here; see ``/sys/kernel/mm/hugepages`` described below.

Hi Enze,

Thanks for this, the current wording is indeed confusing. I checked the
new text against mm/hugetlb.c and have two comments.

1) "persistent" is not accurate. hugetlb_report_meminfo() prints
h->nr_huge_pages for the default hstate, and that counter includes
the surplus pages: alloc_surplus_hugetlb_folio() accounts the new
folio in nr_huge_pages and bumps surplus_huge_pages in the same lock
cycle (persistent_huge_pages() is defined as the difference). The
HugePages_Surp entry just below already says that surplus pages are
"in the pool above the value in /proc/sys/vm/nr_hugepages". So with
overcommit in use, HugePages_Total can be larger than nr_hugepages,
and describing it as the number of persistent pages would be wrong.

2) "Pools of other huge page sizes are not shown here" is not quite
right either. The Hugetlb: line, a few entries below, accounts for
pages of all sizes (as a total in kB) and already points to
/sys/kernel/mm/hugepages. What is missing is only the per-size
count.

Something like this would fix the confusion and stay accurate:

HugePages_Total
is the number of huge pages of the default size in the pool,
both persistent and surplus. Counts for the other huge page
sizes are available in ``/sys/kernel/mm/hugepages`` (described
below).

I built the admin-guide/mm documentation with your patch applied and it
adds no new warnings, so my comments are only about the wording.

Thanks,
Daniel


Em sex., 23 de out. de 2026 às 07:10, Enze Li <lienze@kylinos.cn> escreveu:
>
> "the size of the pool of huge pages" confused me, since it sounds
> like a size in bytes.  It's actually the number of persistent huge
> pages of the default size, and pools of other sizes aren't shown
> here at all.  Reword it and point to /sys/kernel/mm/hugepages for
> those.
>
> Signed-off-by: Enze Li <lienze@kylinos.cn>
> ---
>  Documentation/admin-guide/mm/hugetlbpage.rst | 4 +++-
>  1 file changed, 3 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/admin-guide/mm/hugetlbpage.rst b/Documentation/admin-guide/mm/hugetlbpage.rst
> index 2075f1f14a42..01fa9f61c9a9 100644
> --- a/Documentation/admin-guide/mm/hugetlbpage.rst
> +++ b/Documentation/admin-guide/mm/hugetlbpage.rst
> @@ -43,7 +43,9 @@ The output of ``cat /proc/meminfo`` will include lines like::
>  where:
>
>  HugePages_Total
> -       is the size of the pool of huge pages.
> +       is the number of persistent huge pages of the default size
> +       in the pool.  Pools of other huge page sizes are not shown
> +       here; see ``/sys/kernel/mm/hugepages`` described below.
>  HugePages_Free
>         is the number of huge pages in the pool that are not yet
>          allocated.
>
> base-commit: 3fdcce698abd9193752ee89fb1a440cdceb1b74a
> --
> 2.56.0
>
>

Re: [PATCH] docs: hugetlbpage.rst: clarify HugePages_Total in hugetlbpage.rst

[Enze Li]

Hi Daniel,

Thanks for the careful review and for building the docs.

On 10/25/26 9:25 PM, Daniel Pereira wrote:
> On Fri, Oct 23, 2026, Enze Li wrote:
>> HugePages_Total
>> - is the size of the pool of huge pages.
>> + is the number of persistent huge pages of the default size
>> + in the pool. Pools of other huge page sizes are not shown
>> + here; see ``/sys/kernel/mm/hugepages`` described below.
> 
> Hi Enze,
> 
> Thanks for this, the current wording is indeed confusing. I checked the
> new text against mm/hugetlb.c and have two comments.
> 
> 1) "persistent" is not accurate. hugetlb_report_meminfo() prints
> h->nr_huge_pages for the default hstate, and that counter includes
> the surplus pages: alloc_surplus_hugetlb_folio() accounts the new
> folio in nr_huge_pages and bumps surplus_huge_pages in the same lock
> cycle (persistent_huge_pages() is defined as the difference). The
> HugePages_Surp entry just below already says that surplus pages are
> "in the pool above the value in /proc/sys/vm/nr_hugepages". So with
> overcommit in use, HugePages_Total can be larger than nr_hugepages,
> and describing it as the number of persistent pages would be wrong.

Good catch on "persistent" -- I forgot nr_huge_pages includes surplus pages.

> 
> 2) "Pools of other huge page sizes are not shown here" is not quite
> right either. The Hugetlb: line, a few entries below, accounts for
> pages of all sizes (as a total in kB) and already points to
> /sys/kernel/mm/hugepages. What is missing is only the per-size
> count.

On "here": I only meant the HugePages_Total line itself, which only
prints the default hstate's count, but I agree "here" reads as the
whole /proc/meminfo output and clashes with the Hugetlb line.  Your
wording is more accurate.

> 
> Something like this would fix the confusion and stay accurate:
> 
> HugePages_Total
> is the number of huge pages of the default size in the pool,
> both persistent and surplus. Counts for the other huge page
> sizes are available in ``/sys/kernel/mm/hugepages`` (described
> below).

I'll send a v2 using your wording and add your Suggested-by tag.

Best regards,
Enze

> 
> I built the admin-guide/mm documentation with your patch applied and it
> adds no new warnings, so my comments are only about the wording.
> 
> Thanks,
> Daniel
> 
> 
> Em sex., 23 de out. de 2026 às 07:10, Enze Li <lienze@kylinos.cn> escreveu:
>>
>> "the size of the pool of huge pages" confused me, since it sounds
>> like a size in bytes.  It's actually the number of persistent huge
>> pages of the default size, and pools of other sizes aren't shown
>> here at all.  Reword it and point to /sys/kernel/mm/hugepages for
>> those.
>>
>> Signed-off-by: Enze Li <lienze@kylinos.cn>
>> ---
>>  Documentation/admin-guide/mm/hugetlbpage.rst | 4 +++-
>>  1 file changed, 3 insertions(+), 1 deletion(-)
>>
>> diff --git a/Documentation/admin-guide/mm/hugetlbpage.rst b/Documentation/admin-guide/mm/hugetlbpage.rst
>> index 2075f1f14a42..01fa9f61c9a9 100644
>> --- a/Documentation/admin-guide/mm/hugetlbpage.rst
>> +++ b/Documentation/admin-guide/mm/hugetlbpage.rst
>> @@ -43,7 +43,9 @@ The output of ``cat /proc/meminfo`` will include lines like::
>>  where:
>>
>>  HugePages_Total
>> -       is the size of the pool of huge pages.
>> +       is the number of persistent huge pages of the default size
>> +       in the pool.  Pools of other huge page sizes are not shown
>> +       here; see ``/sys/kernel/mm/hugepages`` described below.
>>  HugePages_Free
>>         is the number of huge pages in the pool that are not yet
>>          allocated.
>>
>> base-commit: 3fdcce698abd9193752ee89fb1a440cdceb1b74a
>> --
>> 2.56.0
>>
>>