Generic Radix Page Table — The Linux Kernel documentation
The Linux Kernel 7.4.0-rc3 Quick search Contents Working with the development community Development process Submitting patches Code of conduct Maintainer handbook All development-process docs Internal API manuals Core API Driver APIs General information for driver authors Useful support libraries Bus-level documentation Subsystem-specific APIs Linux 802.11 Driver Developer’s Guide ACPI Support Kernel driver lp855x The Common Clk Framework Confidential Computing Console Drivers Crypto Drivers DMAEngine documentation The Linux kernel dpll subsystem Error Detection And Correction (EDAC) Devices Extcon Device Subsystem Linux Firmware API FPGA Subsystem Frame Buffer Library Managing Ownership of the Framebuffer Aperture Generic Counter Interface Generic Radix Page Table General Purpose Input/Output (GPIO) High Speed Synchronous Serial Interface (HSI) The Linux Hardware Timestamping Engine (HTE) Recoverable Hardware Error Tracking in vmcoreinfo I 2 C and SMBus Subsystem Industrial I/O InfiniBand and Remote DMA (RDMA) Interfaces Input Subsystem Generic System Interconnect Subsystem IPMB Driver for a Satellite MC The Linux IPMI Driver The Intel Silicon Security Engine Interface (Intel SSEI) libATA Developer’s Guide The Common Mailbox Framework RAID Media subsystem kernel internal API Intel(R) Management Engine Interface (Intel(R) MEI) Memory Controller drivers Message-based devices Miscellaneous Devices Parallel Port Devices 16x50 UART Driver Pulse-Width Modulation (PWM) MMC/SD/SDIO card support Memory Technology Device (MTD) MTD NAND Driver Programming Interface Near Field Communication NTB Drivers Non-Volatile Memory Device (NVDIMM) NVMEM Subsystem PARPORT interface documentation Generic PHY Framework PINCTRL (PIN CONTROL) subsystem PLDM Firmware Flash Update Library PPS - Pulse Per Second PTP hardware clock infrastructure for Linux Pulse Width Modulation (PWM) interface Power Sequencing API Voltage and current regulator API Reset controller API rfkill - RF kill switch support Writing s390 channel device drivers SCSI Interfaces Guide Support for Serial devices SM501 Driver SoundWire Documentation Serial Peripheral Interface (SPI) Steal Governor Introduction Core idea Workload considerations Module Parameters Reasons for CONFIG_STEAL_GOVERNOR=m Surface System Aggregator Module (SSAM) Linux Switchtec Support Sync File API Guide target and iSCSI Interfaces Guide TEE (Trusted Execution Environment) driver API Thermal TTY WBRF - Wifi Band RFI Mitigations WMI Driver API Xilinx FPGA Writing Device Drivers for Zorro Devices Subsystems Locking Development tools and processes Licensing rules Writing documentation Development tools Testing guide Hacking guide Tracing Fault injection Livepatching Rust User-oriented documentation Administration Build system Reporting issues Userspace tools Userspace API Firmware-related documentation Firmware Firmware and Devicetree Architecture-specific documentation CPU architectures Other documentation Unsorted documentation Translations Translations This Page Show Source Generic Radix Page Table ¶ Generic Radix Page Table is a set of functions and helpers to efficiently parse radix style page tables typically seen in HW implementations.
The interface is built to deliver similar code generation as the mm’s pte/pmd/etc system by fully inlining the exact code required to handle each table level. Like the mm subsystem each format contributes its parsing implementation under common names and the common code implements the required algorithms. The system is divided into three logical levels: The page table format and its manipulation functions Generic helpers to give a consistent API regardless of underlying format An algorithm implementation (e.g.
IOMMU/DRM/KVM/MM) Multiple implementations are supported. The intention is to have the generic format code be re-usable for whatever specialized implementation is required. The generic code is solely about the format of the radix tree; it does not include memory allocation or higher level decisions that are left for the implementation. The generic framework supports a superset of functions across many HW implementations: Entries comprised of contiguous blocks of IO PTEs for larger page sizes Multi-level tables, up to 6 levels.
Runtime selected top level Runtime variable table level size (ARM’s concatenated tables) Expandable top level allowing dynamic sizing of table levels Optional leaf entries at any level 32-bit/64-bit virtual and output addresses, using every address bit Dirty tracking Sign extended addressing Language used in Generic Page Table VA The input address to the page table, often the virtual address. OA The output address from the page table, often the physical address. leaf An entry that results in an output address. start/end An half-open range, e.g. [0,0) refers to no VA. start/last An inclusive closed range, e.g. [0,0] refers to the VA 0 common The generic page table container struct pt_common level Level 0 is always a table of only leaves with no futher table pointers.
Increasing levels increase the size of the table items. The least significant VA bits used to index page tables are used to index the Level 0 table. The various labels for table levels used by HW descriptions are not used. top_level The inclusive highest level of the table. A two-level table has a top level of 1. table A linear array of translation items for that level. index The position in a table of an element: item = table[index] item A single index in a table entry A single logical element in a table.
If contiguous pages are not supported then item and entry are the same thing, otherwise entry refers to all the items that comprise a single contiguous translation. item/entry_size The number of bytes of VA the table index translates for. If the item is a table entry then the next table covers this size. If the entry translates to an output address then the full OA is: OA | (VA % entry_size) contig_count The number of consecutive items fused into a single entry. item_size * contig_count is the size of that entry’s translation. lg2 Indicates the value is encoded as log2, i.e.
1<<x is the actual value. Normally the compiler is fine to optimize divide and mod with log2 values automatically when inlining, however if the values are not constant expressions it can’t. So we do it by hand; we want to avoid 64-bit divmod. Usage ¶ Generic PT is structured as a multi-compilation system. Since each format provides an API using a common set of names there can be only one format active within a compilation unit.
This design avoids function pointers around the low level API. Instead the function pointers can end up at the higher level API (i.e. map/unmap, etc.) and the per-format code can be directly inlined into the per-format compilation unit. For something like IOMMU each format will be compiled into a per-format IOMMU operations kernel module. For this to work the .c file for each compilation unit will include both the format headers and the generic code for the implementation.
For instance in an implementation compilation unit the headers would normally be included as follows: generic_pt/fmt/iommu_amdv1.c: #include <linux/generic_pt/common.h> #include "defs_amdv1.h" #include "../pt_defs.h" #include "amdv1.h" #include "../pt_common.h" #include "../pt_iter.h" #include "../iommu_pt.h" /* The IOMMU implementation */ iommu_pt.h includes definitions that will generate the operations functions for map/unmap/etc. using the definitions provided by AMDv1.
The resulting module will have exported symbols named like pt_iommu_amdv1_init() . Refer to drivers/iommu/generic_pt/fmt/iommu_template.h for an example of how the IOMMU implementation uses multi-compilation to generate per-format ops structs pointers. The format code is written so that the common names arise from #defines to distinct format specific names. This is intended to aid debuggability by avoiding symbol clashes across all the different formats.
Expor
The rest of this page is on the live site.