Skip to content

Unify page table manipulation code between the guest and the host #1093

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
simongdavies wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Unify page table manipulation code between the guest and the host #1093

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
737efa9
Unify page table manipulation code between the guest and the host
syntactically Jul 29, 2025
e30e043
Only include vm mod when init-paging is enabled
simongdavies Dec 10, 2025
5626c95
Review changes
simongdavies Dec 16, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions src/hyperlight_common/Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,7 @@ fuzzing = ["dep:arbitrary"]
trace_guest = []
mem_profile = []
std = ["thiserror/std", "log/std", "tracing/std"]
init-paging = []

[lib]
bench = false # see https://bheisler.github.io/criterion.rs/book/faq.html#cargo-bench-gives-unrecognized-option-errors-for-valid-command-line-options
Expand Down
737 changes: 737 additions & 0 deletions src/hyperlight_common/src/arch/amd64/vm.rs
View file
Open in desktop

Large diffs are not rendered by default.

3 changes: 3 additions & 0 deletions src/hyperlight_common/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,3 +38,6 @@ pub mod resource;

/// cbindgen:ignore
pub mod func;
// cbindgen:ignore
#[cfg(feature = "init-paging")]
pub mod vm;
142 changes: 142 additions & 0 deletions src/hyperlight_common/src/vm.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,142 @@
/*
Copyright 2025 The Hyperlight Authors.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/

#[cfg_attr(target_arch = "x86_64", path = "arch/amd64/vm.rs")]
mod arch;

#[cfg(target_arch = "x86_64")]
pub use arch::{PAGE_NX, PAGE_PRESENT, PAGE_RW};
Copy link
Member

@syntactically syntactically Dec 16, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IMO the purpose of the not-inside-arch vm module is to provide an architecture-independent veneer so that other code does not need to worry about the architecture-specific details which are confined to the private module. I do not like adding architecture-specific exports to the top level module. If it is really necessary in order to allow a test in another file or something (but I am not sure if it is?), perhaps pub mod arch would be a way to expose them that at least made it easy to tell which code in fact needed to worry about architecture-dependent things (use vm::... vs use vm::arch::...).

pub use arch::{PAGE_SIZE, PAGE_TABLE_SIZE, PageTableEntry, PhysAddr, VirtAddr};
pub const PAGE_TABLE_ENTRIES_PER_TABLE: usize =
PAGE_TABLE_SIZE / core::mem::size_of::<PageTableEntry>();

/// The operations used to actually access the page table structures,
/// used to allow the same code to be used in the host and the guest
/// for page table setup
pub trait TableOps {
/// The type of table addresses
type TableAddr: Copy;

/// Allocate a zeroed table
///
/// # Safety
/// The current implementations of this function are not
/// inherently unsafe, but the guest implementation will likely
/// become so in the future when a real physical page allocator is
/// implemented.
///
/// Currently, callers should take care not to call this on
/// multiple threads at the same time.
///
/// # Panics
/// This function may panic if:
/// - The Layout creation fails
/// - Memory allocation fails
unsafe fn alloc_table(&self) -> Self::TableAddr;

/// Offset the table address by the given offset in bytes.
///
/// # Parameters
/// - `addr`: The base address of the table.
/// - `entry_offset`: The offset in **bytes** within the page table. This is
/// not an entry index; callers must multiply the entry index by the size
/// of a page table entry (typically 8 bytes) to obtain the correct byte offset.
///
/// # Returns
/// The address of the entry at the given byte offset from the base address.
fn entry_addr(addr: Self::TableAddr, entry_offset: u64) -> Self::TableAddr;

/// Read a u64 from the given address, used to read existing page
/// table entries
///
/// # Safety
/// This reads from the given memory address, and so all the usual
/// Rust things about raw pointers apply. This will also be used
/// to update guest page tables, so especially in the guest, it is
/// important to ensure that the page tables updates do not break
/// invariants. The implementor of the trait should ensure that
/// nothing else will be reading/writing the address at the same
/// time as mapping code using the trait.
unsafe fn read_entry(&self, addr: Self::TableAddr) -> PageTableEntry;

/// Write a u64 to the given address, used to write updated page
/// table entries
///
/// # Safety
/// This writes to the given memory address, and so all the usual
/// Rust things about raw pointers apply. This will also be used
/// to update guest page tables, so especially in the guest, it is
/// important to ensure that the page tables updates do not break
/// invariants. The implementor of the trait should ensure that
/// nothing else will be reading/writing the address at the same
/// time as mapping code using the trait.
unsafe fn write_entry(&self, addr: Self::TableAddr, entry: PageTableEntry);

/// Convert an abstract table address to a concrete physical address (u64)
/// which can be e.g. written into a page table entry
fn to_phys(addr: Self::TableAddr) -> PhysAddr;

/// Convert a concrete physical address (u64) which may have been e.g. read
/// from a page table entry back into an abstract table address
fn from_phys(addr: PhysAddr) -> Self::TableAddr;

/// Return the address of the root page table
fn root_table(&self) -> Self::TableAddr;
}

#[derive(Debug)]
pub struct BasicMapping {
pub readable: bool,
pub writable: bool,
pub executable: bool,
}

#[derive(Debug)]
pub enum MappingKind {
BasicMapping(BasicMapping),
/* TODO: What useful things other than basic mappings actually
* require touching the tables? */
}

#[derive(Debug)]
pub struct Mapping {
pub phys_base: u64,
pub virt_base: u64,
pub len: u64,
pub kind: MappingKind,
}

/// Assumption: all are page-aligned
///
/// # Safety
/// This function modifies pages backing a virtual memory range which
/// is inherently unsafe w.r.t. the Rust memory model.
///
/// When using this function, please note:
/// - No locking is performed before touching page table data structures,
/// as such do not use concurrently with any other page table operations
/// - TLB invalidation is not performed, if previously-mapped ranges
/// are being remapped, TLB invalidation may need to be performed
/// afterwards.
pub use arch::map;
/// This function is not presently used for anything, but is useful
/// for debugging
///
/// # Safety
/// This function traverses page table data structures, and should not
/// be called concurrently with any other operations that modify the
/// page table.
pub use arch::virt_to_phys;
2 changes: 1 addition & 1 deletion src/hyperlight_guest_bin/Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ macros = ["dep:hyperlight-guest-macro", "dep:linkme"]

[dependencies]
hyperlight-guest = { workspace = true, default-features = false }
hyperlight-common = { workspace = true, default-features = false }
hyperlight-common = { workspace = true, default-features = false, features = [ "init-paging" ] }
hyperlight-guest-tracing = { workspace = true, default-features = false }
hyperlight-guest-macro = { workspace = true, default-features = false, optional = true }
buddy_system_allocator = "0.11.0"
Expand Down
Loading