feat: i686 page tables, snapshot compaction, and CoW (standalone)

[danbugs]

Summary

The cleaned-up version of #1381: drops the dependencies on #1379 and #1380 so this PR can land on its own.

Commits

• refactor: replace nanvix-unstable with i686-guest and guest-counter features
• feat: i686 protected-mode boot and unified restore path
• feat: i686 page tables, snapshot compaction, and CoW support
• fixup: address PR #1381 review comments

What this adds

• i686 guest support on the x86_64 host: 32-bit protected-mode boot, unified restore path, 2-level page-table walking and snapshot compaction with CoW-resolved PTE reads.
• Feature rename — the prior nanvix-unstable gates split into i686-guest (PT walker, protected-mode boot, compaction) and guest-counter (scratch counter plumbing). No behavior change for consumers using the old feature flag; Cargo.toml / Justfile / build.rs updated to match.

What it does not include (vs #1381)

• The NOBITS-section ELF-loader zero-fill (fix: zero-fill NOBITS sections in ELF loader #1379).
• The PEB file_mappings removal (Remove HyperlightPEB file mappings #1380).

Both can land separately; #1381 happened to stack on top of them.

Review items from #1381 addressed here

• PTE decode uses u32::from_le_bytes (previously from_ne_bytes) — PTEs are little-endian by arch spec.
• i686-guest feature guarded with a compile_error! on targets that are neither x86 (guest) nor x86_64 (host).
• restore_snapshot rewrites the scratch PD-roots bookkeeping (SCRATCH_TOP_PD_ROOTS_{COUNT,ARRAY}_OFFSET) so a subsequent snapshot() doesn't see a stale zero count. Snapshot persists the root count; root GPAs are deterministic (layout.get_pt_base_gpa() + i * PAGE_SIZE).

Verification

Built with cargo check -p hyperlight-{common,host,guest} --features kvm,mshv3,executable_heap,i686-guest,guest-counter — clean. End-to-end tested against nanvix@e61306676: Hello 5/5 with NANVIX_REPEAT=4 through the restore+call loop.

[simongdavies]

Reviewers: Opus, Gemini,ChatGPT

All three reviewers agree this is a well-structured PR that cleanly separates the nanvix-unstable feature into i686-guest and guest-counter, and replaces the TODO-laden real-mode boot with proper 32-bit protected mode + paging. The code quality is generally good — comments are thorough, unsafe blocks are contained, and the architecture is sensible.

However, all three independently flagged critical concerns around the CoW flag logic, potential scratch memory layout overlap, and the complete absence of tests for the i686 code path.

🟢 Good Stuff

• Unified restore_all_state(): Removing the TODO-laden nanvix-unstable branch with its "this is probably not correct" comment is a significant improvement. The CR3-based restore is now clean and shared.
• compile_error! guard for i686-guest on non-x86 — nice defensive programming.
• OOB-safe read_entry implementations: Both Snapshot and SharedMemoryPageTableBuffer return 0 (not-present) for OOB addresses rather than panicking. Exactly right for defensively walking guest-controlled page tables.
• Clean feature flag split: i686-guest + guest-counter are genuinely independent concerns.
• Thorough doc comments on Snapshot fields (n_pd_roots, separate_pt_bytes).
• Scratch bookkeeping factoring: Extracting copy_pt_to_scratch() from update_scratch_bookkeeping() is a clean refactor.

🔴 Additional findings (on lines outside the diff)

Snapshot impl of TableReadOps always reads 8-byte entries (snapshot.rs line 131, Flagged by: 2/3)

The impl TableReadOps for Snapshot at line 131 of snapshot.rs unconditionally reads 8 bytes for a PTE. While it appears to only be used in the #[cfg(not(feature = "i686-guest"))] path currently, it's not gated by #[cfg]. If anyone ever calls virt_to_phys with a Snapshot on the i686 path, it will read 8-byte entries from a 4-byte PTE table — reading cross-entry data and producing garbage mappings. Either gate with #[cfg(not(feature = "i686-guest"))] or add a comment + compile_error! guard.

Endianness inconsistency (snapshot.rs line 149, Flagged by: 2/3)

Line 149 of snapshot.rs uses u64::from_ne_bytes() (native endian), while the i686 SharedMemoryPageTableBuffer::read_entry() at line 273 correctly uses u32::from_le_bytes() with a comment noting "Page-table entries are little-endian by arch spec". The x86_64 path happens to work on LE hosts but is technically incorrect by the same reasoning. Should use from_le_bytes consistently.

See inline comments for the remaining findings.

[syntactically]

The high-level feature here (supporting x86-32 VA spaces instead of the pretending-to-be-real-mode #[cfg(feature = "nanvix-unstable")]) is great.

It seems like all of the i686 page table code is scattered around in various places and does not follow the same structure or architecture-independent API as the amd64 and aarch64 code. I don't think that's at all maintainable. Please try to use the same structures and APIs as the amd64 code, having i686 implementations in hyperlight_common/src/arch/i686/vmem.rs that implement the architecture-independent re-exports of hyperlight_common/src/vmem.rs and allowing most/all of the downstream code to use the same APIs and patterns. (It may be sensible to extract out the page table iterator code that is currently amd64 only, in which case I would expect it to not require much extra code to support i686 page tables (although, if you do this, please check that inlining the iterators still works, at least in release builds---e.g. vmem::map should inline down to basically the same thing as a handwritten loop in a single function)).

I would expect the changes to src/hyperlight_host/src/sandbox/snapshot.rs in particular to be limited to basically

• Make Snapshot::new iterate through several different VA spaces worth of mappings, instead of just one (there ought to be no need to do anything special to avoid duplicated backing pages as long as the existing phys_seen map is kept)
• (If necessary) minor changes to support keeping the PTs generated for the new mappings in a separate vec in the snapshot, instead of at the end of the snapshot memory where they are now on all architectures. Ideally, rather than being #[cfg] items directly in the crate, this would be controlled by some constant e.g. hyperlight_common::vmem::PA_SPACE_IS_SMALL: bool (with the naming reflecting the actual motivation for making this different across architectures).
  • It occurs to me that this may not even need any changes here---perhaps it could be achieved simply by changing the mem mgr or hypervisor manager code to avoid mapping the end of the snapshot region into the guest PA space on i686.

I have left a few other minor inline comments, but the above issue is the only thing that I think is actually quite important.

I didn't review any of the i686 address space manipulation code yet, because it seems like it will need to be refactored and generalised a little to be able to provide the same APIs that we use on other architectures. I think it is quite important that all the guest architectures implement the same APIs, so that most of the code can be architecture-independent.

[syntactically]

I think it would make more sense to have the i686/vmem.rs module used when feature = i686-guest---we should understand that the arch in hyperlight_common is always about the guest arch.

[ludfjig]

moved

[syntactically]

It seems like this for some reason still pulls in a bunch of amd64 code and then exports another sub-module for i686? I am somewhat confused by what is going on, but I really think that this should follow the same pattern as amd64 and arm64 guests---all the exports from the architecture-independent vmem are the i686 values when we are compiling for an i686 guest.

[syntactically]

This whole base va sliding is a hack because of some executables we used to have + the lack of virtual memory in the guest. I don't think that any of the usual guests end up computing anything other than 0 here, so I was thinking it was worth getting rid of entirely. Do the nanvix binaries actually end up with something here? If so, can we replace the unpleasant semantics-breaking relocation with just changing the initial page tables slightly to get things mapped to the VAs that they ask for?

(Not relevant for merging this PR---just curious about answers to these questions for the future).

[ludfjig]

Yes nanvix requires this

[syntactically]

What does it actually end up being out of curiosity? And, is the binary actually PIC or not? I don't see any added code for processing textrels or anything, so if it's not PIC I would expect shifting text around like this not to work, and if it is PIC, I wouldn't expect this to be necessary at all since generally PIEs are based at 0.

If so, can we replace the unpleasant semantics-breaking relocation with just changing the initial page tables slightly to get things mapped to the VAs that they ask for

I still think this is the right way to go, although for PIC binaries that look like they start from 0 we should move them somewhere e.g. 0x1000. It can be a different PR, however.

[syntactically]

Does this need to make the same differentiation between the i686 and x86-64 sources of the initial page table information?

[syntactically]

Why is this information necessary beyond the scope of one address space traversal? And, why is this a useful form of this information?

[ludfjig]

it's used in a couple of places and TableReadOps::read_entry takes a &self...

[syntactically]

What are the places, and why is it used when we didn't need a similar structure on amd64/arm64?

[syntactically]

This can just use mem::size_of::<hyperlight_common::vmem::PageTableEntry>(). Or, if it can't because of some limitation on the const-ness of that expression, it should just be another constant and/or type synonym defined in the same place.

There should ideally be little-to-no arch-specific code in this module: the hyperlight_common::vmem and related APIs should abstract over the architecture-of-the-guest differences well enough that this code can be more-or-less entirely generic. (If there are problems with the vmem api assuming to much, we should fix them, rather than introduce more #[cfg] here).

[ludfjig]

please take another look, I believe it's mostly fixed

[syntactically]

There is still a bunch of #[cfg] gated code that looks identical apart from some sizes. I don't see why this can't just directly be something like

let Some(pte_bytes) = memoff.and_then(|(mem, off)| mem.get(off..off+mem::size_of::<vmem::PageTableEntry>())) else {
  return 0;
};
let n: [u8; mem::size_of::<vmem::PageTableEntry>()] = pte_bytes.try_into().unwrap();
vmem::PageTableEntry::from_le_bytes(n)

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds standalone i686 guest support (protected-mode boot, 2-level PT walking, CoW-aware PTE reads) and snapshot compaction, while splitting the old nanvix-unstable gating into i686-guest and guest-counter.

Changes:

• Introduces i686 page-table walking/mapping and updates snapshot creation/restore to support multi-root compaction + CoW resolution.
• Adds an optional PtRootFinder callback to snapshot multiple page-table roots (e.g., per-process PD roots).
• Renames feature gating across host/guest/common (nanvix-unstable → i686-guest + guest-counter) and updates build tooling.

Reviewed changes

Copilot reviewed 29 out of 29 changed files in this pull request and generated 11 comments.

Show a summary per file

File	Description
src/hyperlight_host/src/sandbox/uninitialized_evolve.rs	Updates feature gate for publishing scratch HostSharedMemory for guest counter.
src/hyperlight_host/src/sandbox/uninitialized.rs	Renames feature gate and propagates guest-counter gating through GuestCounter + tests.
src/hyperlight_host/src/sandbox/snapshot.rs	Implements i686-aware PT reading, CoW resolution, multi-root walking, and separate PT storage for i686 snapshots.
src/hyperlight_host/src/sandbox/mod.rs	Re-exports PtRootFinder alongside MultiUseSandbox.
src/hyperlight_host/src/sandbox/initialized_multi_use.rs	Adds PtRootFinder callback and uses it to supply multiple PT roots to snapshotting.
src/hyperlight_host/src/mem/shared_mem.rs	Renames feature gate for test-only HostSharedMemory view.
src/hyperlight_host/src/mem/mgr.rs	Generalizes GuestPageTableBuffer over PTE size, adds i686 multi-root finalization, and updates restore PT copying logic.
src/hyperlight_host/src/mem/memory_region.rs	Updates cfg attributes to the new i686-guest feature naming.
src/hyperlight_host/src/mem/layout.rs	Removes nanvix-unstable-specific base address split; updates cfg attrs to i686-guest.
src/hyperlight_host/src/mem/exe.rs	Exposes ELF base VA to compute entrypoint offsets correctly.
src/hyperlight_host/src/lib.rs	Re-exports GuestCounter under guest-counter feature.
src/hyperlight_host/src/hypervisor/virtual_machine/whp.rs	Updates test gating from nanvix-unstable to i686-guest.
src/hyperlight_host/src/hypervisor/virtual_machine/mshv/x86_64.rs	Updates test gating from nanvix-unstable to i686-guest.
src/hyperlight_host/src/hypervisor/virtual_machine/mod.rs	Updates XSAVE constant/test gating from nanvix-unstable to i686-guest.
src/hyperlight_host/src/hypervisor/virtual_machine/kvm/x86_64.rs	Updates test gating from nanvix-unstable to i686-guest.
src/hyperlight_host/src/hypervisor/regs/x86_64/special_regs.rs	Adds i686 protected-mode paging defaults and reorganizes shared constants.
src/hyperlight_host/src/hypervisor/hyperlight_vm/x86_64.rs	Switches to i686 paging defaults when i686-guest is enabled and unifies CR3 handling.
src/hyperlight_host/build.rs	Adjusts unshared_snapshot_mem documentation/logic ordering around feature flags.
src/hyperlight_host/Cargo.toml	Adds i686-guest and guest-counter features; keeps nanvix-unstable as a compatibility alias.
src/hyperlight_guest/src/layout.rs	Renames guest counter gating to guest-counter.
src/hyperlight_guest/Cargo.toml	Adds i686-guest and guest-counter features.
src/hyperlight_common/src/vmem.rs	Adds shared PT iterator infrastructure, i686 guest module export, and i686-guest target validation.
src/hyperlight_common/src/layout.rs	Switches x86_64 layout selection based on i686-guest; renames guest-counter constant gating.
src/hyperlight_common/src/arch/i686/vmem.rs	Implements real i686 2-level paging map + walk support (incl. CoW tag via AVL bits).
src/hyperlight_common/src/arch/i686/layout.rs	Implements real i686 min scratch size calculation.
src/hyperlight_common/src/arch/amd64/vmem.rs	Refactors amd64 PT code to use shared iterator infrastructure + shared UpdateParent logic.
src/hyperlight_common/src/arch/aarch64/vmem.rs	Updates TableMovability impls to match new shared trait shape.
src/hyperlight_common/Cargo.toml	Adds i686-guest and guest-counter features; keeps nanvix-unstable as alias.
Justfile	Updates i686 checks and replaces nanvix-unstable checks with i686-guest where appropriate.

[Copilot]

Deduplicating by phys_base here can drop valid alias mappings (multiple virt_base values mapping to the same phys_base). That would cause the rebuilt page tables to miss some virtual mappings in the compacted snapshot. A safer approach is to keep all mappings (or at most dedupe by (effective_root, virt_base)), and rely on the later phys_seen compaction map to dedupe page contents.

[Copilot]

Deduplicating by phys_base here can drop valid alias mappings (multiple virt_base values mapping to the same phys_base). That would cause the rebuilt page tables to miss some virtual mappings in the compacted snapshot. A safer approach is to keep all mappings (or at most dedupe by (effective_root, virt_base)), and rely on the later phys_seen compaction map to dedupe page contents.

[Copilot]

This still decodes 8-byte page-table entries using from_ne_bytes. Page table entries are little-endian by architecture spec (including x86_64), so this should use u64::from_le_bytes to avoid host-endianness dependence.

Suggested change

	u64::from_ne_bytes(n)
	// Page-table entries are little-endian by arch spec;
	// use `from_le_bytes` so host endianness doesn't leak in.
	u64::from_le_bytes(n)

[Copilot]

These hard-coded masks duplicate PAGE_SIZE knowledge. Using PAGE_SIZE-derived masks (e.g., !(PAGE_SIZE as u64 - 1) / (PAGE_SIZE as u64 - 1)) would make the intent clearer and avoid accidental inconsistencies if constants ever change.

Suggested change

	let page_gpa = addr & 0xFFFFF000;
	if let Some(map) = self.cow_map {
	if let Some(&scratch_gpa) = map.get(&page_gpa) {
	scratch_gpa + (addr & 0xFFF)
	let page_gpa = addr & !(PAGE_SIZE as u64 - 1);
	if let Some(map) = self.cow_map {
	if let Some(&scratch_gpa) = map.get(&page_gpa) {
	scratch_gpa + (addr & (PAGE_SIZE as u64 - 1))

[Copilot]

Under i686-guest, _pml4_addr is passed as the 32-bit page directory base. Renaming this variable to something architecture-neutral (e.g., root_pt_addr/root_table_addr) would reduce confusion now that the same path supports both amd64 and i686.

[Copilot]

The new multi-root + dedup/collection logic in filtered_mappings is central to snapshot correctness but isn’t directly covered by the existing tests in this module. Adding a unit test that creates two distinct VAs mapping to the same PA (aliasing) and verifies both VAs remain mapped after compaction would help prevent regressions (especially given the new dedup behavior).

Suggested change

	#[cfg(test)]
	fn filtered_mapping_dedup_key(root_index: usize, virt_base: u64) -> (usize, u64) {
	(root_index, virt_base)
	}
	#[cfg(test)]
	mod tests {
	use super::*;
	use std::collections::HashMap;
	#[test]
	fn compaction_dedup_preserves_aliasing_virtual_addresses() {
	let root_index = 0usize;
	let virt_a = 0x1000_u64;
	let virt_b = 0x2000_u64;
	let shared_phys = 0x3000_u64;
	let kind = MappingKind::Basic(BasicMapping {
	readable: true,
	writable: true,
	executable: false,
	});
	let mut collected = HashMap::new();
	collected.insert(
	filtered_mapping_dedup_key(root_index, virt_a),
	(shared_phys, compaction_kind(&kind)),
	);
	collected.insert(
	filtered_mapping_dedup_key(root_index, virt_b),
	(shared_phys, compaction_kind(&kind)),
	);
	assert_eq!(collected.len(), 2);
	assert_eq!(
	collected
	.get(&filtered_mapping_dedup_key(root_index, virt_a))
	.map(|(phys, _)| *phys),
	Some(shared_phys)
	);
	assert_eq!(
	collected
	.get(&filtered_mapping_dedup_key(root_index, virt_b))
	.map(|(phys, _)| *phys),
	Some(shared_phys)
	);
	assert!(matches!(
	collected
	.get(&filtered_mapping_dedup_key(root_index, virt_a))
	.map(|(_, kind)| kind),
	Some(MappingKind::Cow(_))
	));
	assert!(matches!(
	collected
	.get(&filtered_mapping_dedup_key(root_index, virt_b))
	.map(|(_, kind)| kind),
	Some(MappingKind::Cow(_))
	));
	}
	#[test]
	fn compaction_dedup_preserves_same_virtual_address_across_roots() {
	let virt = 0x4000_u64;
	let phys = 0x5000_u64;
	let kind = MappingKind::Basic(BasicMapping {
	readable: true,
	writable: false,
	executable: false,
	});
	let mut collected = HashMap::new();
	collected.insert(filtered_mapping_dedup_key(0, virt), (phys, compaction_kind(&kind)));
	collected.insert(filtered_mapping_dedup_key(1, virt), (phys, compaction_kind(&kind)));
	assert_eq!(collected.len(), 2);
	assert!(collected.contains_key(&filtered_mapping_dedup_key(0, virt)));
	assert!(collected.contains_key(&filtered_mapping_dedup_key(1, virt)));
	assert!(matches!(
	collected.get(&filtered_mapping_dedup_key(0, virt)).map(|(_, kind)| kind),
	Some(MappingKind::Basic(BasicMapping {
	readable: true,
	writable: false,
	executable: false,
	}))
	));
	}
	}

[Copilot]

The new multi-root + dedup/collection logic in filtered_mappings is central to snapshot correctness but isn’t directly covered by the existing tests in this module. Adding a unit test that creates two distinct VAs mapping to the same PA (aliasing) and verifies both VAs remain mapped after compaction would help prevent regressions (especially given the new dedup behavior).

[Copilot]

The comment mentions only gdb, but the condition also includes nanvix-unstable. Either update the comment to reflect both reasons, or (if intended) migrate this to the new feature split (i686-guest / guest-counter) so the build-time behavior matches the new feature naming.

Suggested change

	// gdb needs writable snapshot memory for debug access.
	// Writable snapshot memory is required for gdb debug access and nanvix-unstable builds.

[syntactically]

This is definitely a big step in the right direction!

I still have some significant concerns about divergences in code flow between the i686 guests and other architectures. Really, this PR has (at least) two parts:

• Support multiple virtual address spaces in the guest (this should all be totally architecture-independent, in order to keep the high-level model of hyperlight the same across architectures---if it is not, bugs will certainly creep in)
• Support i686 guests. (This should ideally be pretty much limited to files in arch/i686 and a few places where some new architecture-specific logic is unavoidable or code sharing opportunities are too good to ignore (e.g. the hypervisor driver x86_64.rs files, which are now I guess somewhat misnamed).

I say "at least two" because it seems to me that there are some other smaller features as well, such as adding support for round-tripping some extra permission information (acknowledging the use of two protection levels in the guest), etc. These should also to the maximum extent possible be split into architecture-independent and architecture-dependent portions---for example, whatever extra generic architecture-independent semantic information about mappings needs to be added to track whether or not they are user should go in the architecture-independent vmem::Mapping structures, but it's probably fine if the architecture-dependent code in arch/i686/vmem.rs is the only thing that actually produces or consumes mappings with those flags.

[syntactically]

Why isn't this just mod arch like it is on the other architectures? This implies that on i686 we pull in the amd64 arch module and the i686 one? Which doesn't make sense to me.

[syntactically]

Probably all of these can be pub(self) or something so that they are accessible by the mod arch but not the rest of the crate?

[syntactically]

This should not be in the arch-independent code in this module, since it depends on an architecture-dependent feature (bit 0 being the present bit).

[syntactically]

Similarly, since the actual impl for this has to be in each architecture-specific module, I would expect the type to be there as well. If some architecture needed to actually have state here (which some might) the use of the trait fn to construct this was beneficial.

[syntactically]

Is there a reason to take this here rather than use mem::size_of::<arch::PageTableEntry>()?

[syntactically]

Why is this inlined? It looks to me as though the equivalent operation is still needed in both places it originally was, and it is a convenient place to centralise special mappings---e.g. at some point the snapshot pt mapping will actually come back, and when that is supported on a platform this is a nice single point to make sure it gets done.

[syntactically]

What does it actually end up being out of curiosity? And, is the binary actually PIC or not? I don't see any added code for processing textrels or anything, so if it's not PIC I would expect shifting text around like this not to work, and if it is PIC, I wouldn't expect this to be necessary at all since generally PIEs are based at 0.

If so, can we replace the unpleasant semantics-breaking relocation with just changing the initial page tables slightly to get things mapped to the VAs that they ask for

I still think this is the right way to go, although for PIC binaries that look like they start from 0 we should move them somewhere e.g. 0x1000. It can be a different PR, however.

[syntactically]

If you just refrain from filtering out the kernel PDEs earlier you will not have to replicate them here (which is important: this code introduces an assumption that all guest kernels will behave precisely as Nanvix does in terms of what kinds of task virtual address layouts they use, which definitely does not belong in Hyperlight core).

[syntactically]

This shouldn't need to be architecture-specific here---the whole point of exporting an architecture-independent veneer of an interface from hyperlight_common::vmem is to remove the need for this sort of thing.

[syntactically]

Why is the explanatory comment removed, and why is this now cfg-guarded?