[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

[sashiko-bot]

Thank you for your contribution! Sashiko AI review found 1 potential issue(s) to consider:
- [Low] docs: hugetlb: HugePages_Total falsely documented as persistent page count
--

commit 7d6d3b965cd5f08c4d5dcbd9da32baf62e0f76e3
Author: Enze Li <lienze@kylinos.cn>

docs: hugetlbpage.rst: clarify HugePages_Total in hugetlbpage.rst

This commit updates the description of HugePages_Total in
Documentation/admin-guide/mm/hugetlbpage.rst to clarify that it reports a
page count for the default huge page size and points readers to
/sys/kernel/mm/hugepages for other huge page sizes.

> diff --git a/Documentation/admin-guide/mm/hugetlbpage.rst b/Documentation/admin-guide/mm/hugetlbpage.rst
> index 2075f1f14a421..01fa9f61c9a92 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.

[Severity: Low]
Is it accurate to describe HugePages_Total as the number of persistent huge
pages?

In mm/hugetlb.c, hugetlb_report_meminfo() prints h->nr_huge_pages for
default_hstate:

	for_each_hstate(h) {
		unsigned long count = h->nr_huge_pages;

		total += huge_page_size(h) * count;

		if (h == &default_hstate)
			seq_printf(m,
				   "HugePages_Total:   %5lu\n"
				   "HugePages_Free:    %5lu\n"
				   "HugePages_Rsvd:    %5lu\n"
				   "HugePages_Surp:    %5lu\n"
				   "Hugepagesize:   %8lu kB\n",
				   count,
				   h->free_huge_pages,
				   h->resv_huge_pages,
				   h->surplus_huge_pages,
				   huge_page_size(h) / SZ_1K);
	}

However, h->nr_huge_pages includes both persistent and surplus huge pages, as
shown by persistent_huge_pages() and alloc_surplus_hugetlb_folio() in
mm/hugetlb.c:

	#define persistent_huge_pages(h) (h->nr_huge_pages - h->surplus_huge_pages)

	alloc_surplus_hugetlb_folio()
	  account_new_hugetlb_folio(h, folio)
	    h->nr_huge_pages++;
	  h->surplus_huge_pages++;

Should this say "is the number of huge pages of the default size in the pool"
(or note that it includes both persistent and surplus huge pages) rather than
restricting it to persistent huge pages?

-- 
Sashiko AI review · https://sashiko.dev/#/patchset/20261023100859.70744-1-lienze@kylinos.cn?part=1

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