docs: filesystems: clarify KernelPageSize vs. MMUPageSize in smaps

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@linux.intel.com/
Reviewed-by: Zi Yan <ziy@nvidia.com>
Reviewed-by: Lance Yang <lance.yang@linux.dev>
Acked-by: Vlastimil Babka (SUSE) <vbabka@kernel.org>
Cc: Andrew Morton <akpm@linux-foundation.org>
Cc: Lorenzo Stoakes <lorenzo.stoakes@oracle.com>
Cc: Zi Yan <ziy@nvidia.com>
Cc: Baolin Wang <baolin.wang@linux.alibaba.com>
Cc: Liam R. Howlett <Liam.Howlett@oracle.com>
Cc: Nico Pache <npache@redhat.com>
Cc: Ryan Roberts <ryan.roberts@arm.com>
Cc: Dev Jain <dev.jain@arm.com>
Cc: Barry Song <baohua@kernel.org>
Cc: Lance Yang <lance.yang@linux.dev>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Shuah Khan <skhan@linuxfoundation.org>
Cc: Usama Arif <usamaarif642@gmail.com>
Cc: Andi Kleen <ak@linux.intel.com>
Signed-off-by: David Hildenbrand (Arm) <david@kernel.org>
Reviewed-by: Lorenzo Stoakes (Oracle) <ljs@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20260306081916.38872-1-david@kernel.org>

authored by

David Hildenbrand (Arm) and committed by

Jonathan Corbet 3 months ago 17eb360d 73f29b02

+28 -12

1 changed file

expand all

Documentation

filesystems

proc.rst

+28 -12

Documentation/filesystems/proc.rst

··· 464 464 KSM: 0 kB 465 465 LazyFree: 0 kB 466 466 AnonHugePages: 0 kB 467 + FilePmdMapped: 0 kB 467 468 ShmemPmdMapped: 0 kB 468 469 Shared_Hugetlb: 0 kB 469 470 Private_Hugetlb: 0 kB 470 471 Swap: 0 kB 471 472 SwapPss: 0 kB 472 - KernelPageSize: 4 kB 473 - MMUPageSize: 4 kB 474 473 Locked: 0 kB 475 474 THPeligible: 0 476 475 VmFlags: rd ex mr mw me dw 477 476 478 477 The first of these lines shows the same information as is displayed for 479 478 the mapping in /proc/PID/maps. Following lines show the size of the 480 - mapping (size); the size of each page allocated when backing a VMA 481 - (KernelPageSize), which is usually the same as the size in the page table 482 - entries; the page size used by the MMU when backing a VMA (in most cases, 483 - the same as KernelPageSize); the amount of the mapping that is currently 484 - resident in RAM (RSS); the process's proportional share of this mapping 485 - (PSS); and the number of clean and dirty shared and private pages in the 486 - mapping. 479 + mapping (size); the smallest possible page size allocated when backing a 480 + VMA (KernelPageSize), which is the granularity in which VMA modifications 481 + can be performed; the smallest possible page size that could be used by the 482 + MMU (MMUPageSize) when backing a VMA; the amount of the mapping that is 483 + currently resident in RAM (RSS); the process's proportional share of this 484 + mapping (PSS); and the number of clean and dirty shared and private pages 485 + in the mapping. 486 + 487 + "KernelPageSize" always corresponds to "MMUPageSize", except when a larger 488 + kernel page size is emulated on a system with a smaller page size used by the 489 + MMU, which is the case for some PPC64 setups with hugetlb. Furthermore, 490 + "KernelPageSize" and "MMUPageSize" always correspond to the smallest 491 + possible granularity (fallback) that can be encountered in a VMA throughout 492 + its lifetime. These values are not affected by Transparent Huge Pages 493 + being in effect, or any usage of larger MMU page sizes (either through 494 + architectural huge-page mappings or other explicit/implicit coalescing of 495 + virtual ranges performed by the MMU). "AnonHugePages", "ShmemPmdMapped" and 496 + "FilePmdMapped" provide insight into the usage of PMD-level architectural 497 + huge-page mappings. 487 498 488 499 The "proportional set size" (PSS) of a process is the count of pages it has 489 500 in memory, where each page is divided by the number of processes sharing it. ··· 539 528 be lower than the real value due to optimizations used in the current 540 529 implementation. If this is not desirable please file a bug report. 541 530 542 - "AnonHugePages" shows the amount of memory backed by transparent hugepage. 531 + "AnonHugePages", "ShmemPmdMapped" and "FilePmdMapped" show the amount of 532 + memory backed by Transparent Huge Pages that are currently mapped by 533 + architectural huge-page mappings at the PMD level. "AnonHugePages" 534 + corresponds to memory that does not belong to a file, "ShmemPmdMapped" to 535 + shared memory (shmem/tmpfs) and "FilePmdMapped" to file-backed memory 536 + (excluding shmem/tmpfs). 543 537 544 - "ShmemPmdMapped" shows the amount of shared (shmem/tmpfs) memory backed by 545 - huge pages. 538 + There are no dedicated entries for Transparent Huge Pages (or similar concepts) 539 + that are not mapped by architectural huge-page mappings at the PMD level. 546 540 547 541 "Shared_Hugetlb" and "Private_Hugetlb" show the amounts of memory backed by 548 542 hugetlbfs page which is *not* counted in "RSS" or "PSS" field for historical

Configure Feed

Configure Feed