Re: [PATCH v2] docs: filesystems: clarify KernelPageSize vs. MMUPageSize in smaps

[Lorenzo Stoakes (Oracle)]

On Fri, Mar 06, 2026 at 09:19:16AM +0100, David Hildenbrand (Arm) wrote:
> There was recently some confusion around THPs and the interaction with
> KernelPageSize / MMUPageSize. Historically, these entries always
> correspond to the smallest size we could encounter, not any current
> usage of transparent huge pages or larger sizes used by the MMU.
>
> Ever since we added THP support many, many years ago, these entries
> would keep reporting the smallest (fallback) granularity in a VMA.
>
> For this reason, they default to PAGE_SIZE for all VMAs except for
> VMAs where we have the guarantee that the system and the MMU will
> always use larger page sizes. hugetlb, for example, exposes a custom
> vm_ops->pagesize callback to handle that. Similarly, dax/device
> exposes a custom vm_ops->pagesize callback and provides similar
> guarantees.
>
> Let's clarify the historical meaning of KernelPageSize / MMUPageSize,
> and point at "AnonHugePages", "ShmemPmdMapped" and "FilePmdMapped"
> regarding PMD entries.
>
> While at it, document "FilePmdMapped", clarify what the "AnonHugePages"
> and "ShmemPmdMapped" entries really mean, and make it clear that there
> are no other entries for other THP/folio sizes or mappings.
>
> Also drop the duplicate "KernelPageSize" and "MMUPageSize" entries in
> the example.
>
> Link: https://lore.kernel.org/all/20260225232708.87833-1-ak@xxxxxxxxxxxxxxx/
> Reviewed-by: Zi Yan <ziy@xxxxxxxxxx>
> Reviewed-by: Lance Yang <lance.yang@xxxxxxxxx>
> Acked-by: Vlastimil Babka (SUSE) <vbabka@xxxxxxxxxx>
> Cc: Andrew Morton <akpm@xxxxxxxxxxxxxxxxxxxx>
> Cc: Lorenzo Stoakes <lorenzo.stoakes@xxxxxxxxxx>
> Cc: Zi Yan <ziy@xxxxxxxxxx>
> Cc: Baolin Wang <baolin.wang@xxxxxxxxxxxxxxxxx>
> Cc: Liam R. Howlett <Liam.Howlett@xxxxxxxxxx>
> Cc: Nico Pache <npache@xxxxxxxxxx>
> Cc: Ryan Roberts <ryan.roberts@xxxxxxx
> Cc: Dev Jain <dev.jain@xxxxxxx>
> Cc: Barry Song <baohua@xxxxxxxxxx>
> Cc: Lance Yang <lance.yang@xxxxxxxxx>
> Cc: Jonathan Corbet <corbet@xxxxxxx>
> Cc: Shuah Khan <skhan@xxxxxxxxxxxxxxxxxxx>
> Cc: Usama Arif <usamaarif642@xxxxxxxxx>
> Cc: Andi Kleen <ak@xxxxxxxxxxxxxxx>
> Signed-off-by: David Hildenbrand (Arm) <david@xxxxxxxxxx>

Reads great now, thanks very much! So:

Reviewed-by: Lorenzo Stoakes (Oracle) <ljs@xxxxxxxxxx>

> ---
>
> v1 -> v2:
> * Some rewording and clarifications
> * Drop duplicate entries in the example
>
> ---
>  Documentation/filesystems/proc.rst | 40 +++++++++++++++++++++---------
>  1 file changed, 28 insertions(+), 12 deletions(-)
>
> diff --git a/Documentation/filesystems/proc.rst b/Documentation/filesystems/proc.rst
> index b0c0d1b45b99..e2d22a424dcd 100644
> --- a/Documentation/filesystems/proc.rst
> +++ b/Documentation/filesystems/proc.rst
> @@ -464,26 +464,37 @@ Memory Area, or VMA) there is a series of lines such as the following::
>      KSM:                   0 kB
>      LazyFree:              0 kB
>      AnonHugePages:         0 kB
> +    FilePmdMapped:         0 kB
>      ShmemPmdMapped:        0 kB
>      Shared_Hugetlb:        0 kB
>      Private_Hugetlb:       0 kB
>      Swap:                  0 kB
>      SwapPss:               0 kB
> -    KernelPageSize:        4 kB
> -    MMUPageSize:           4 kB
>      Locked:                0 kB
>      THPeligible:           0
>      VmFlags: rd ex mr mw me dw
>
>  The first of these lines shows the same information as is displayed for
>  the mapping in /proc/PID/maps.  Following lines show the size of the
> -mapping (size); the size of each page allocated when backing a VMA
> -(KernelPageSize), which is usually the same as the size in the page table
> -entries; the page size used by the MMU when backing a VMA (in most cases,
> -the same as KernelPageSize); the amount of the mapping that is currently
> -resident in RAM (RSS); the process's proportional share of this mapping
> -(PSS); and the number of clean and dirty shared and private pages in the
> -mapping.
> +mapping (size); the smallest possible page size allocated when backing a
> +VMA (KernelPageSize), which is the granularity in which VMA modifications
> +can be performed; the smallest possible page size that could be used by the
> +MMU (MMUPageSize) when backing a VMA; the amount of the mapping that is
> +currently resident in RAM (RSS); the process's proportional share of this
> +mapping (PSS); and the number of clean and dirty shared and private pages
> +in the mapping.
> +
> +"KernelPageSize" always corresponds to "MMUPageSize", except when a larger
> +kernel page size is emulated on a system with a smaller page size used by the
> +MMU, which is the case for some PPC64 setups with hugetlb.  Furthermore,
> +"KernelPageSize" and "MMUPageSize" always correspond to the smallest
> +possible granularity (fallback) that can be encountered in a VMA throughout
> +its lifetime.  These values are not affected by Transparent Huge Pages
> +being in effect, or any usage of larger MMU page sizes (either through
> +architectural huge-page mappings or other explicit/implicit coalescing of
> +virtual ranges performed by the MMU).  "AnonHugePages", "ShmemPmdMapped" and
> +"FilePmdMapped" provide insight into the usage of PMD-level architectural
> +huge-page mappings.
>
>  The "proportional set size" (PSS) of a process is the count of pages it has
>  in memory, where each page is divided by the number of processes sharing it.
> @@ -528,10 +539,15 @@ pressure if the memory is clean. Please note that the printed value might
>  be lower than the real value due to optimizations used in the current
>  implementation. If this is not desirable please file a bug report.
>
> -"AnonHugePages" shows the amount of memory backed by transparent hugepage.
> +"AnonHugePages", "ShmemPmdMapped" and "FilePmdMapped" show the amount of
> +memory backed by Transparent Huge Pages that are currently mapped by
> +architectural huge-page mappings at the PMD level. "AnonHugePages"
> +corresponds to memory that does not belong to a file, "ShmemPmdMapped" to
> +shared memory (shmem/tmpfs) and "FilePmdMapped" to file-backed memory
> +(excluding shmem/tmpfs).
>
> -"ShmemPmdMapped" shows the amount of shared (shmem/tmpfs) memory backed by
> -huge pages.
> +There are no dedicated entries for Transparent Huge Pages (or similar concepts)
> +that are not mapped by architectural huge-page mappings at the PMD level.
>
>  "Shared_Hugetlb" and "Private_Hugetlb" show the amounts of memory backed by
>  hugetlbfs page which is *not* counted in "RSS" or "PSS" field for historical
> --
> 2.43.0
>