Struct PageTableRef 

pub struct PageTableRef<T: TableMeta, A: FrameAllocator> { /* private fields */ }

Implementations

impl<T: TableMeta, A: FrameAllocator> PageTableRef<T, A>

pub unsafe fn from_paddr(paddr: PhysAddr, allocator: A) -> Self

Creates a non-owning view of an existing page-table root.

The returned view may inspect and mutate page-table entries, but it never owns or releases any page-table frame. Only PageTable carries the corresponding frame-reclamation capability.

Safety

The caller must ensure that paddr names an aligned, initialized root table for T, that every table frame reachable from it remains mapped by allocator for the entire use of this value, and that all mutable access is serialized with hardware walkers and other page-table users. The caller must also ensure that the owning page table outlives this view.

pub fn map_page( &mut self, vaddr: VirtAddr, paddr: PhysAddr, page_size: usize, config: PteConfigOf<T>, ) -> PagingResult

Maps one page with the requested page size.

pub fn map_region( &mut self, start_vaddr: VirtAddr, get_paddr: impl Fn(VirtAddr) -> PhysAddr, size: usize, config: PteConfigOf<T>, ) -> PagingResult

Maps a virtual region from a per-base-page physical resolver.

The resolver may return a non-contiguous physical page sequence, so this API deliberately installs only base-page leaves. Use [Self::map_linear_pages] when the physical range is known to be contiguous and block mappings are allowed.

Mappings installed by this call are rolled back if a later page fails. TLB invalidation is deferred and batched until the region has been updated.

pub fn map_region_checked( &mut self, start_vaddr: VirtAddr, get_paddr: impl FnMut(VirtAddr) -> PagingResult<PhysAddr>, size: usize, config: PteConfigOf<T>, ) -> PagingResult

Maps a virtual region using a fallible physical-address resolver.

The resolver is evaluated before each PTE write. If it rejects a later page, mappings already installed by this invocation are rolled back and the resolver error is returned. This is the capability used by allocation-backed or sparse device mappings: address resolution must remain checked all the way through the page-table walker. Because the resolver does not prove contiguity, this API uses base-page leaves.

pub fn unmap_page( &mut self, vaddr: VirtAddr, ) -> PagingResult<(PhysAddr, PteConfigOf<T>, usize)>

Unmaps one page and returns its physical address, flags, and page size.

pub fn unmap_page_deferred( &mut self, vaddr: VirtAddr, ) -> PagingResult<(PhysAddr, PteConfigOf<T>, usize, DeferredPageTableFrames<A>)>

Unmaps one occupied leaf without reclaiming detached intermediate page-table frames.

The returned ownership token must be retained by the stage-1 TLB gather until every CPU that could use this page table confirms invalidation. This method performs no TLB invalidation itself.

pub fn peek_huge_block( &self, vaddr: VirtAddr, ) -> Option<(PhysAddr, PteConfigOf<T>, usize)>

Returns the huge block covering vaddr without changing the table. Retained non-present blocks are reported when the PTE format preserves their descriptor state.

pub fn plan_map_page( &self, vaddr: VirtAddr, page_size: usize, ) -> PagingResult<PageTableMapPlan<T, A>>

Captures the existing page-table prefix for one currently absent leaf.

This operation performs no allocation. The returned plan owns only an allocator capability and copyable identity data, so a caller can drop its page-table lock before PageTableMapPlan::prepare allocates the missing suffix. Apply rewalks the prefix and rejects a stale plan.

pub fn try_map_page_with( &mut self, deposit: PageTableMapDeposit<T, A>, ) -> Result<(), PageTableMapApplyError<T, A>>

Installs one fully prepared leaf without allocating or releasing memory.

On failure the move-only deposit is returned to the caller, which must drop it after leaving any non-sleeping page-table critical section. A successful apply publishes an already initialized suffix with one release-ordered parent store, then transfers every reserved frame to the live page-table tree.

pub fn try_install_map_path( &mut self, deposit: PageTablePathDeposit<T, A>, ) -> Result<(), PageTablePathApplyError<T, A>>

Publishes a prepared, empty page-table suffix.

The operation only revalidates the captured prefix and performs one release-ordered parent-entry store. It never allocates, frees, or flushes; a failed apply returns the detached suffix to its caller.

pub fn plan_unmap_page( &self, vaddr: VirtAddr, ) -> PagingResult<PageTableLeafPlan<T>>

Captures the exact occupied leaf covering vaddr without allocating.

pub fn plan_move_page( &self, source_vaddr: VirtAddr, destination_vaddr: VirtAddr, ) -> PagingResult<PageTableMovePlan<T, A>>

Captures one source leaf and the destination state for a later batch move. The destination hierarchy must already exist when it is vacant.

pub fn try_unmap_page_with( &mut self, plan: PageTableLeafPlan<T>, ) -> PagingResult<(PhysAddr, PteConfigOf<T>, usize)>

where PteConfigOf<T>: PartialEq,

Clears one previously planned leaf without pruning directories or performing a TLB flush.

The caller retains ownership of the mapped data frame and must attach a later TLB obligation before releasing it. Empty page-table directories remain owned by this page table and can be reused by a subsequent fault.

pub fn try_move_pages_with( &mut self, plans: &[PageTableMovePlan<T, A>], ) -> PagingResult<usize>

where PteConfigOf<T>: PartialEq,

Applies a sorted batch of page moves after validating every preimage.

No descriptor is changed until the whole slice passes validation. The apply phase then consists only of PTE clears/stores: it cannot allocate, free, flush, or fail. Source directories are intentionally retained, matching Linux’s PTE move before free_pgtables() handles the detached source VMA.

pub fn prepare_huge_split( &self, vaddr: VirtAddr, ) -> PagingResult<HugeSplitDeposit<T, A>>

Allocates a pre-zeroed child table and binds it to the currently observed huge leaf.

The returned deposit may be stored by a mapping owner until a future partial operation needs to split the leaf. Apply revalidates the root, virtual range, physical frame, configuration, and size before touching any descriptor.

pub fn split_huge_page_with( &mut self, deposit: HugeSplitDeposit<T, A>, ) -> PagingResult<InstalledHugeSplit<T>>

where PteConfigOf<T>: PartialEq,

Consumes a bound deposit and splits its huge block into inherited finer leaves. No allocation occurs during apply.

pub fn try_split_huge_page_with( &mut self, deposit: HugeSplitDeposit<T, A>, ) -> Result<InstalledHugeSplit<T>, HugeSplitApplyError<T, A>>

where PteConfigOf<T>: PartialEq,

Transactional variant of Self::split_huge_page_with. On failure the caller receives the still-owned deposit and can put it back into its mapping slot without allocating during recovery.

pub fn split_huge_block_to_empty_table( &mut self, deposit: HugeSplitDeposit<T, A>, ) -> PagingResult<InstalledHugeSplit<T>>

where PteConfigOf<T>: PartialEq,

Splits a huge block and installs an empty child table for a caller that will materialize non-contiguous finer leaves under the same mutation domain. The old block metadata is returned for rollback/accounting.

pub fn restore_huge_split( &mut self, installed: InstalledHugeSplit<T>, ) -> PagingResult<HugeSplitDeposit<T, A>>

Rolls an installed split back to the exact huge descriptor captured by its receipt and returns ownership of the withdrawn child table.

No allocation occurs. The returned deposit is bound to the restored block and can either be retained for a retry or dropped to release the now-unpublished page-table frame. This is the inverse of Self::split_huge_page_with used by unpublished transaction aborts.

pub fn split_huge_page(&mut self, vaddr: VirtAddr) -> PagingResult<usize>

where PteConfigOf<T>: PartialEq,

Prepares and performs an inherited huge split. Transactional callers should retain HugeSplitDeposit from Self::prepare_huge_split before entering their mutation critical section.

pub fn protect_page( &mut self, vaddr: VirtAddr, config: PteConfigOf<T>, ) -> PagingResult<usize>

Changes one existing mapping’s flags and returns its page size.

pub fn protect_region( &mut self, start_vaddr: VirtAddr, size: usize, config: PteConfigOf<T>, ) -> PagingResult

Changes flags for a region. Unmapped base pages are skipped.

pub fn remap_page( &mut self, vaddr: VirtAddr, paddr: PhysAddr, config: PteConfigOf<T>, ) -> PagingResult<usize>

Remaps one existing mapping and returns its page size.

pub fn query( &self, vaddr: VirtAddr, ) -> PagingResult<(PhysAddr, PteConfigOf<T>, usize)>

Queries one mapping and returns the translated physical address, flags, and page size.

pub fn query_occupied(&self, vaddr: VirtAddr) -> PagingResult<(T::P, usize)>

Queries one occupied leaf, including a non-present software mapping.

Unlike Self::query, this method distinguishes an unused entry from a leaf whose descriptor is retained while address translation is disabled. It is intended for ownership, rollback, and destructive page-table operations. Callers must not use a successful result as proof that the virtual address is currently accessible.

pub fn map(&mut self, config: &MapConfig<PteConfigOf<T>>) -> PagingResult

映射虚拟地址范围到物理地址范围

pub fn unmap(&mut self, start_vaddr: VirtAddr, size: usize) -> PagingResult<()>

取消映射虚拟地址范围

参数

• start_vaddr: 要取消映射的起始虚拟地址
• size: 要取消映射的大小（字节）

返回值

• Ok(()): 取消映射成功
• Err(PagingError): 取消映射失败

行为

• 清除指定虚拟地址范围内的所有页表项
• 自动回收空的子页表帧
• 支持大页和普通页面的取消映射
• 根据配置刷新TLB

pub fn unmap_with_config(&mut self, config: &UnmapConfig) -> PagingResult<()>

使用配置对象取消映射

pub fn walk_all(&self, config: WalkConfig) -> PageTableWalker<'_, T, A>

创建页表遍历迭代器

pub fn walk( &self, start_vaddr: VirtAddr, end_vaddr: VirtAddr, ) -> impl Iterator<Item = PteInfo<T::P>> + '_

pub fn walk_valid(&self) -> impl Iterator<Item = PteInfo<T::P>> + '_

遍历所有有效的最终映射页表项（过滤掉无效项和中间级别的页表指针）

pub fn walk_occupied(&self) -> impl Iterator<Item = PteInfo<T::P>> + '_

Walks every occupied final leaf, including retained non-present leaves.

Rollback and quarantine code must distinguish an empty page-table slot from a descriptor that still owns a physical mapping but has had its access permissions removed. The walk scales with allocated page-table frames rather than with the represented virtual address span.

pub fn walk_occupied_range( &self, start_vaddr: VirtAddr, end_vaddr: VirtAddr, ) -> impl Iterator<Item = PteInfo<T::P>> + '_

Walks occupied final leaves whose represented range overlaps [start_vaddr, end_vaddr).

Unlike probing every base page, this follows only allocated page-table paths that intersect the requested range. Retained non-present leaves remain visible so rollback can keep PTE and software ownership in sync.

pub fn mapping_size_for_level(&self, level: usize) -> Option<usize>

Returns the mapping size represented by one page-table level.

pub const fn page_size() -> usize

pub const fn table_levels() -> usize

pub const fn valid_bits() -> usize

pub fn translate(&self, vaddr: VirtAddr) -> PagingResult<(PhysAddr, T::P)>

通过虚拟地址查询页表项

参数

• vaddr: 要查询的虚拟地址

返回值

• Ok(T::P): 找到的页表项，包含物理地址信息
• Err(PagingError): 查询失败，原因可能包括：
  • 地址未映射
  • 页表项无效
  • 页表层次结构错误

pub fn translate_with_level( &self, vaddr: VirtAddr, ) -> PagingResult<(PhysAddr, T::P, usize)>

Translates a virtual address and returns the matched PTE level.

pub fn translate_phys(&self, vaddr: VirtAddr) -> PagingResult<PhysAddr>

通过虚拟地址查询物理地址（便利方法）

参数

• vaddr: 要查询的虚拟地址

返回值

• Ok(PhysAddr): 找到的物理地址
• Err(PagingError): 查询失败

pub fn is_mapped(&self, vaddr: VirtAddr) -> bool

检查虚拟地址是否已映射

这是一个便利方法，用于快速检查地址是否已映射而不需要获取页表项

参数

• vaddr: 要检查的虚拟地址

返回值

• true: 地址已映射
• false: 地址未映射

pub fn root_paddr(&self) -> PhysAddr

获取页表的根帧物理地址

Trait Implementations

impl<T: TableMeta, A: FrameAllocator> Debug for PageTableRef<T, A>

where T::P: Debug,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T: TableMeta, A: FrameAllocator> PageTableOp for PageTableRef<T, A>

type PteConfig = <<T as TableMeta>::P as PageTableEntry>::PteConfig

fn addr(&self) -> PhysAddr

fn map(&mut self, config: &MapConfig<Self::PteConfig>) -> PagingResult

fn unmap( &mut self, virt_start: VirtAddr, size: usize, ) -> Result<(), PagingError>