From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from foss.arm.com (foss.arm.com [217.140.110.172]) by smtp.subspace.kernel.org (Postfix) with ESMTP id D71BA48C40B; Wed, 2 Sep 2026 11:59:18 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=217.140.110.172 ARC-Seal:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1788350371; cv=none; b=ofCamyinUNxVgJQiqv2SLXu45HncqxGLhhEocJbj9I4O0Szrn6dahBC9hlE7KvHmTEs7EYnhnmzIzOaR6khijx4U3XaZPkjWSVpJZCmN9rUYVh8nDBKcJYX9jcOeSP3d4IlGAZCgtupnOUxT/PYeU6F0rSUY0ZoykGLdOhfF/zw= ARC-Message-Signature:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1788350371; c=relaxed/simple; bh=Br/cs+FpftnQOol6BErs3frU8GfYo1jZb/nBuxpBEq8=; h=From:Date:Subject:MIME-Version:Content-Type:Message-Id:References: In-Reply-To:To:Cc; b=RuM7Wqyd4JeaMADnO+SrEaNW3oDYZkZ497nESp4FhY12+9vii47jsM0JPjmFAk86oNmPKwQkfsyrRzjrm/2yLntgyf+sgBTQ3KlMv4mRRqDgTnofe4Gw4fD3kR0t+iaTpyc5lbpUGI5fpfgEao2e4apv+qFCWI/m1s+3NQvzfms= ARC-Authentication-Results:i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=arm.com; spf=pass smtp.mailfrom=arm.com; dkim=pass (1024-bit key) header.d=arm.com header.i=@arm.com header.b=YNIufYY9; arc=none smtp.client-ip=217.140.110.172 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=arm.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=arm.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (1024-bit key) header.d=arm.com header.i=@arm.com header.b="YNIufYY9" Received: from usa-sjc-imap-foss1.foss.arm.com (unknown [10.121.207.14]) by usa-sjc-mx-foss1.foss.arm.com (Postfix) with ESMTP id 4CC611E32; Wed, 2 Sep 2026 04:59:10 -0700 (PDT) Received: from e129823.arm.com (e129823.arm.com [10.2.213.3]) by usa-sjc-imap-foss1.foss.arm.com (Postfix) with ESMTPSA id E6C6E3F85F; Wed, 2 Sep 2026 04:59:06 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=simple/simple; d=arm.com; s=foss; t=1788350354; bh=Br/cs+FpftnQOol6BErs3frU8GfYo1jZb/nBuxpBEq8=; h=From:Date:Subject:References:In-Reply-To:To:Cc:From; b=YNIufYY97B6qUu57kfR8nwRxcLtpS+O6ostRIi/nQOuKLD58rztHwSAiT1AAYOntl fxPaSMddAYwDW8STJc6MsE8WWxYq2NPYdK+F0yYS0HcTTtt1ra7YEAriOl0DmEf2lo zM0F0pNqICHzqI3Xh+hnQZNMeBEPTobb3bXedcbs= From: Yeoreum Yun Date: Wed, 02 Sep 2026 12:56:23 +0100 Subject: [PATCH RFC v3 21/21] Documentation: mm: clarify behaviour of compile-time folded page tables Precedence: bulk X-Mailing-List: kvm@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: 7bit Message-Id: <20260902-dummy_ptxp3-v3-21-5d8f5b17c25c@arm.com> References: <20260902-dummy_ptxp3-v3-0-5d8f5b17c25c@arm.com> In-Reply-To: <20260902-dummy_ptxp3-v3-0-5d8f5b17c25c@arm.com> To: Russell King , Huacai Chen , WANG Xuerui , Thomas Bogendoerfer , Catalin Marinas , Will Deacon , Arnd Bergmann , Andrew Morton , Kairui Song , Qi Zheng , Shakeel Butt , Barry Song , Axel Rasmussen , Yuanchu Xie , Wei Xu , Johannes Weiner , David Hildenbrand , Michal Hocko , Lorenzo Stoakes , Tianrui Zhao , Bibo Mao , Anup Patel , Atish Patra , Paul Walmsley , Palmer Dabbelt , Albert Ou , Alexandre Ghiti , Dave Hansen , Andy Lutomirski , Peter Zijlstra , Thomas Gleixner , Ingo Molnar , Borislav Petkov , x86@kernel.org, "H. Peter Anvin" , "Liam R. Howlett" , Vlastimil Babka , Mike Rapoport , Suren Baghdasaryan , Michal Hocko , Jonas Bonn , Stefan Kristiansson , Stafford Horne Cc: linux-arm-kernel@lists.infradead.org, linux-kernel@vger.kernel.org, loongarch@lists.linux.dev, linux-mips@vger.kernel.org, linux-arch@vger.kernel.org, linux-mm@kvack.org, kvm@vger.kernel.org, kvm-riscv@lists.infradead.org, linux-riscv@lists.infradead.org, linux-openrisc@vger.kernel.org X-Mailer: b4 0.13.0 X-Developer-Signature: v=1; a=openpgp-sha256; l=5247; i=yeoreum.yun@arm.com; h=from:subject:message-id; bh=QkuS96DAgeRV++qcxLUFqnS2tbZYgjub9eHsvrXmSd4=; b=owEB7QES/pANAwAKAW3Vw9FaxTEzAcsmYgBqmA7r6ZZHyXCpThNLcIh389noXapBmN0QtJRA/ 0G6xN7Ry3uJAbMEAAEKAB0WIQQtg+CS3QUzuFh1pJ1t1cPRWsUxMwUCapgO6wAKCRBt1cPRWsUx M58/C/9U9B6FfYQ/fupAFaXvIw1Mnt9yYqNpnlfNtC6NDeZsWkfEpD8g8rzw/ZmT9NJlS4YfPs1 Qx6kcjhDR9PAeBJBPGh8BxQwaeLNn1ssBbAQxNDfX7yrRLWPxHK9wZ7XBK+0+Y5Lk3lgdRQJ6qI p4F+YbpHGfi22XGen2K3KAJo4nzOC2nru7i6LL5wr8wAlWshB+2+4MqDHojeNHwLITRml9jgLu1 /5lqRtOqA/q+Qf0MpV0tPwdATl3vJk5GSkq2yFyzkMR4LYpE4C4fuh5kWjMReGy62Non6aPXFa8 +6UdHtXQ4V3qp9smbO5LbcLD7qQUPFqBTFktH5C1HQXXAvjDBzouhN5N4kjlLCeCrRwIwAVEVZR TNUIXv8PMlOojSv+isqEwSGFr+0lJ0ySAkyPAXIRh55obtZ2bBmU/KQx8c+65rZmmgDb4nJ57+G Vajqff8eVIyX0IvBrlsknDMl32bDAWeQx3n/WwlNzdx1iu6CzzjQqt5l1s9+zYKYR23pU= X-Developer-Key: i=yeoreum.yun@arm.com; a=openpgp; fpr=2D83E092DD0533B85875A49D6DD5C3D15AC53133 From: "David Hildenbrand (Arm)" 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) --- 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 126c87628250..84f2715c7de0 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. + +- 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 -- 2.43.0