Re: [PATCH 21/21] Documentation: mm: clarify behaviour of compile-time folded page tables

[Randy Dunlap <rdunlap@infradead.org>]

On 9/21/26 3:55 AM, Yeoreum Yun wrote:
> From: "David Hildenbrand (Arm)" <david@kernel.org>
> 
> Compile-time folded page tables are not necessarily easy to understand, and even
> people the were once familiar with the concept might need to refresh their memory.
> 
> Add proper documentation, including a nice diagram, for the current design.
> Mention details about dummy functions, including the recently changed pXdp_get()
> helpers.
> 
> Signed-off-by: David Hildenbrand (Arm) <david@kernel.org>

Documentation/mm/page_tables.rst:197: WARNING: Bullet list ends without a blank line; unexpected unindent. [docutils]

See below for a fix.

> ---
>  Documentation/mm/page_tables.rst | 84 +++++++++++++++++++++++++++++++++++-----
>  1 file changed, 75 insertions(+), 9 deletions(-)
> 
> diff --git a/Documentation/mm/page_tables.rst b/Documentation/mm/page_tables.rst
> index 126c876282509..84f2715c7de0a 100644
> --- a/Documentation/mm/page_tables.rst
> +++ b/Documentation/mm/page_tables.rst
> @@ -143,15 +143,81 @@ pointers on each level is architecture-defined.::
>  Page Table Folding
>  ==================
>  
> -If the architecture does not use all the page table levels, they can be *folded*
> -which means skipped, and all operations performed on page tables will be
> -compile-time augmented to just skip a level when accessing the next lower
> -level.
> -
> -Page table handling code that wishes to be architecture-neutral, such as the
> -virtual memory manager, will need to be written so that it traverses all of the
> -currently five levels. This style should also be preferred for
> -architecture-specific code, so as to be robust to future changes.
> +Not all architectures support 5-level page tables; while for some of them
> +the exact number of supported page table levels is known at compile time,
> +others can determine the number of page table levels at runtime based on
> +hardware support and address space sizes.
> +
> +Generic page table walking code always assumes that 5 levels of page table
> +exist. To make page table walking code not have to worry about that,
> +`compile-time folding` and `runtime folding` of page tables are used.
> +Compile-time folding is mostly handled in common code, whereas runtime folding
> +is exclusively handled in architecture code.
> +
> +This description focuses on generic compile-time folded page tables; for
> +architecture-specific variants, some details can vary, however, without
> +affecting common page table walkers.
> +
> +When walking folded page tables, all upper page table levels up to the supported
> +level are skipped in page table walkers: this is achieved by (a) treating
> +entries in upper page table levels as present and pointing at a page table; and
> +(b) having page table walkers cast the entry pointer to the next-level entry
> +instead of dereferencing that table. From the perspective of a page table
> +walker, the entry points at itself.
> +
> +Assuming compile-time folded 4-level page tables, to achieve (a), pgd_present()
> +and pgd_leaf() are hard-coded to indicate a present page table entry that
> +points at a page table, and to achieve (b) p4d_offset() and
> +p4d_offset_lockless() simply cast the page table entry pointer to the next
> +lower level.
> +
> +In the current design, this is further modeled by having the P4D have a
> +single page table entry::
> +
> +        PGD
> +  --> +------+          NOP4D
> +      | ptr0 |-------> +------+           PUD
> +      | ptr1 |-        | ptr0 |-------> +-----+
> +      | ptr2 | \       +------+         | ptr |-------> ...
> +      | ptr3 |  \                       | ptr |
> +        ...      \                        ..
> +                  \        NOP4D
> +                   +----> +------+           PUD
> +                          | ptr1 |-------> +-----+
> +                          +------+         | ptr |-------> ...
> +                                           | ptr |
> +                                             ...
> +
> +Note that the arrows from PGD to NOP4D represent page-table-walker
> +transitions, not pointers stored in the pgd entries.
> +
> +Using p4d as an example, `nop4d`/`p4d folded` translates to the following:
> +
> +- p4d is considered folded into pgd; both are operating on the same page
> + table.

     table.
(add one more prefix space to align the indentation)

> +
> +- Most pgd_* helpers are hard-coded dummy functions that ignore the passed
> +  pgd_t values entirely. Exceptions are pgd_val() and low-level helpers
> +  set_pgd() + pgd_page_vaddr(), which effectively translate to set_p4d()/
> +  p4d_pgtable() to keep existing arch code working.
> +
> +  Architectures must provide p4d_* helpers (unless further common
> +  compile-time folding applies).
> +
> +- PTRS_PER_P4D is hard-coded to 1. Architectures must define PTRS_PER_PGD.
> +
> +To avoid reading a value that will never be used but cannot be entirely
> +optimized out, compile-time folded page table code also makes pXdp_get()
> +return a constant dummy value.
> +
> +In common code, this only affects pXd_val() when used for printing page
> +table entries for debugging purposes. As we don't want architecture code
> +that uses set_pXd(), pgd_page_vaddr() or pXd_pgtable() to accidentally
> +operate on dummy values, the compiler will error out if it detects that the
> +helpers are used with dummy values. For a folded level, pXd_page() must not
> +be used and unconditionally triggers a compiler error. Architecture code must
> +instead call the helpers on the proper first page table level: e.g., set_p4d()
> +instead of set_pgd().
>  
>  
>  MMU, TLB, and Page Faults
> 

-- 
~Randy