Module addresses 

Virtual and Physical Memory Address Types

Strongly typed wrappers for raw memory addresses and page bases used in paging and memory management code.

Overview

This module defines a minimal set of types that prevent mixing virtual and physical addresses at compile time while remaining zero-cost wrappers around u64 values.

The core idea is to build all higher-level memory abstractions from a few principal types:

Concept	Generic	Description
MemoryAddress	–	A raw 64-bit address, either physical or virtual.
MemoryPage<S>	S: PageSize	A page-aligned base address of a page of size S.
MemoryAddressOffset<S>	S: PageSize	An offset within a page of size S.

These are then wrapped to distinguish between virtual and physical spaces:

Wrapper	Meaning
VirtualAddress / VirtualPage<S>	Refer to virtual (page-table translated) memory.
PhysicalAddress / PhysicalPage<S>	Refer to physical memory or MMIO regions.

Page Sizes

Three standard x86-64 page sizes are supported out of the box via marker types that implement PageSize:

• Size4K — 4 KiB pages (base granularity)
• Size2M — 2 MiB huge pages
• Size1G — 1 GiB giant pages

The PageSize trait defines constants SIZE and SHIFT used throughout the helpers.

Typical Usage

// Create a virtual address
let va = VirtualAddress::new(0xFFFF_FFFF_8000_1234);

// Split it into a page base and an in-page offset
let (page, off) = va.split::<Size4K>();
assert_eq!(page.base().as_u64() & (Size4K::SIZE - 1), 0);

// Join them back to the same address
assert_eq!(page.join(off).as_u64(), va.as_u64());

// Do the same for physical addresses
let pa = PhysicalAddress::new(0x0000_0010_2000_0042);
let (pp, po) = pa.split::<Size4K>();
assert_eq!(pp.join(po).as_u64(), pa.as_u64());

Design Notes

• The types are #[repr(transparent)] and implement Copy, Eq, Ord, and Hash, making them suitable as map keys or for FFI use.
• All alignment and offset calculations are const fn and zero-cost in release builds.
• The phantom marker S enforces the page size at the type level instead of using constants, ensuring all conversions are explicit.

This forms the foundation for paging, virtual memory mapping, and kernel address-space management code.

Modules

sealed 🔒

Sealed trait pattern to restrict PageSize impls to our markers.

Structs

MemoryAddress

Principal raw memory address (virtual or physical).

MemoryAddressOffset

The offset within a page of size S (0..S::SIZE-1).

MemoryPage

A page base address (lower S::SHIFT bits are zero).

PhysicalAddress

Physical memory address.

PhysicalPage

Physical memory page base for size S.

Size1G

1 GiB page (1_073_741_824 bytes).

Size2M

2 MiB page (2_097_152 bytes).

Size4K

4 KiB page (4096 bytes).

VirtualAddress

Virtual memory address.

VirtualPage

Virtual memory page base for size S.

Traits

PageSize

Marker trait for supported page sizes.