Crate kernel_vmem

Expand description

§Virtual Memory Support

Minimal x86-64 paging helpers for a hobby OS loader/kernel.

§What you get

An address space describing a PML4 root page table.
Tiny PhysicalAddress/VirtualAddress newtypes (u64) to avoid mixing address kinds.
A PageSize enum for 4 KiB / 2 MiB / 1 GiB mappings.
x86-64 page-table VirtualMemoryPageBits with practical explanations.
A 4 KiB-aligned PageTable wrapper and index helpers.
A tiny allocator/mapper interface (FrameAlloc, PhysMapper).

§x86-64 Virtual Address → Physical Address Walk

Each 48-bit virtual address is divided into five fields:

| 47‒39 | 38‒30 | 29‒21 | 20‒12 | 11‒0   |
|  PML4 |  PDPT |   PD  |   PT  | Offset |

The CPU uses these fields as indices into four levels of page tables, each level containing 512 (2⁹) entries of 8 bytes (64 bits) each.

 PML4  →  PDPT  →  PD  →  PT  →  Physical Page
  │        │        │        │
  │        │        │        └───► PTE   (Page Table Entry)  → maps 4 KiB page
  │        │        └────────────► PDE   (Page Directory Entry) → PS=1 → 2 MiB page
  │        └─────────────────────► PDPTE (Page Directory Pointer Table Entry) → PS=1 → 1 GiB page
  └──────────────────────────────► PML4E (Page Map Level 4 Entry)

§Levels and their roles

Level	Table name	Entry name	Description
1	PML4 (Page Map Level 4)	PML4E	Top-level table; each entry points to a PDPT. One PML4 table per address space, referenced by Control Register 3 (`CR3`).
2	PDPT (Page Directory Pointer Table)	PDPTE	Each entry points to a PD. If `PS=1`, it directly maps a 1 GiB page (leaf).
3	PD (Page Directory)	PDE	Each entry points to a PT. If `PS=1`, it directly maps a 2 MiB page (leaf).
4	PT (Page Table)	PTE	Each entry maps a 4 KiB physical page (always a leaf).

§Leaf vs. non-leaf entries

A leaf entry directly maps physical memory — it contains the physical base address and the permission bits (PRESENT, WRITABLE, USER, GLOBAL, NX, etc.).
- A PTE is always a leaf (maps 4 KiB).
- A PDE with PS=1 is a leaf (maps 2 MiB).
- A PDPTE with PS=1 is a leaf (maps 1 GiB).
A non-leaf entry points to the next lower table level and continues the walk. For example, a PML4E points to a PDPT, and a PDE with PS=0 points to a PT.

§Offset

The final Offset field (bits 11–0) selects the byte inside the 4 KiB (or larger) page.

§Summary

A canonical 48-bit virtual address is effectively:

VA = [PML4:9] [PDPT:9] [PD:9] [PT:9] [Offset:12]

This creates a four-level translation tree that can map up to 256 TiB of virtual address space, using leaf pages of 1 GiB, 2 MiB, or 4 KiB depending on which level the translation stops.

Re-exports§

pub use crate::address_space::AddressSpace;

Modules§

address_space: Address Space (x86-64, PML4-rooted)
addresses: Virtual and Physical Memory Address Types
bits 🔒
info: Re-export constants as info module.
page_table: Memory Page Table

Structs§

VirtualMemoryPageBits: Unified, ergonomic view over x86-64 paging entries (all levels / forms).

Traits§

FrameAlloc: Minimal allocator that hands out 4 KiB page-table frames.
PhysMapper: Mapper capable of temporarily viewing physical frames as typed tables.
PhysMapperExt: Mapper capable of temporarily viewing physical frames as typed tables.

Functions§

read_cr3_phys^⚠: Reads the current value of the CR3 register (the page table base register) and returns the physical address of the top-level page table (PML4).