Make ELF loading respect program header virtual addresses for non-PIE binaries

[cshung]

Summary

For non-PIE (ET_EXEC) ELF binaries, the guest page table now maps the code region at the ELF's declared virtual address rather than identity-mapping it at the GPA. This allows statically-linked binaries with a fixed load address (e.g., --image-base=0x200000) to execute correctly.

Problem

Previously, Hyperlight assumed code GVA == code GPA (identity mapping). Non-PIE binaries that declare a non-zero base virtual address (via program header p_vaddr) would triple-fault because the guest CPU jumped to the ELF's declared entrypoint VA, which wasn't mapped in the page tables.

Solution

• Compute code_virt_base from the ELF's lowest LOAD segment p_vaddr
• For non-PIE (base_va > 0): map code at the declared VA in the guest page tables
• For PIE (base_va == 0): preserve existing identity mapping behavior (with assertion to guard the invariant)
• Compute entrypoint as code_virt_base + (entrypoint_va - base_va)

The fix leverages the existing Mapping struct's support for phys_base != virt_base — no changes to the page table code itself.

Testing

• New non_pie_guest_hello_world integration test exercises full guest lifecycle (init, COW, function call, return value) with a non-PIE simpleguest built at --image-base=0x200000
• All existing PIE guest tests continue to pass (identity mapping preserved)
• Tested on Windows/WHP and Linux/KVM

Build infrastructure

• Added build-rust-guests-non-pie Justfile targets
• Non-PIE build runs first in guests recipe to avoid clobbering normal guest binaries
• Added simple_guest_non_pie_as_string() test helper

Contributes to: #1408

[Copilot]

Pull request overview

Note

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

This PR adds support for running and testing non-PIE Rust guest binaries, including updating snapshot virtual-address mapping so non-PIE guests execute at their declared ELF virtual addresses.

Changes:

• Add a helper in hyperlight_testing to locate the non-PIE simpleguest binary.
• Update snapshot mapping/entrypoint calculation to support non-identity VA mappings for non-PIE code regions.
• Add a new integration test and build automation (Justfile) to produce and run a non-PIE guest.

Reviewed changes

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

File	Description
src/hyperlight_testing/src/lib.rs	Adds path helper(s) for locating non-PIE Rust guest binaries.
src/hyperlight_host/tests/integration_test.rs	Adds an integration test that boots and calls into a non-PIE guest.
src/hyperlight_host/src/sandbox/snapshot/mod.rs	Adjusts snapshot mappings and entrypoint VA calculation to support non-PIE guests.
Justfile	Adds tasks to build and stage non-PIE Rust guest artifacts.

[cshung]

Addressed Copilot review feedback:

1. Justfile (RUSTFLAGS on Linux) — Fixed. \RUSTFLAGS\ now prefixes \cargo\ directly after \cd &&\ so the env var applies to the build command.

2. snapshot/mod.rs (virt_base mapping) — No change needed. The code region is a single contiguous block where
   gn.guest_region.start == load_addr\ — there is no offset to lose. The \�ssert_eq!\ is deliberate per codebase convention.

3. snapshot/mod.rs (entrypoint underflow) — Fixed. Now uses \checked_sub\ with a proper error for malformed ELFs.

4. lib.rs (doc says 'elf binary') — No change needed. Hyperlight guests are always ELF regardless of host OS.

[ludfjig]

LGTM. @syntactically could you have a look too

[syntactically]

Thanks for doing this! It looks like it is moving in a good direction. I have a couple of minor suggestions/comments, as well as a bit of an alternative design that you could take (but totally up to you on that one!)

[ludfjig]

LGTM but will once again defer to @syntactically for final review

[syntactically]

This looks good to me, thank you and sorry for the delay reviewing!

I do think that there is one minor move that would make the code a little bit cleaner / better fitting with existing conventions, which I've commented on inline. Feel free to push back with a reason why this code belongs here, though!

[cshung]

All review comments have been addressed. The suggestion to move conflict-check logic into \layout.rs\ (from the Jul 15 review) is implemented in the follow-up PR #1655 via the \code_virt_base()\ method which handles both VA selection and overlap validation.

@syntactically — ready for re-review when you get a chance!

[syntactically]

If you've already done that, I think it would be slightly nice to get it cherry-picked here without the ASLR changes, since I'm not totally sure we are decided on doing ASLR---it has pretty limited benefits for the modal hyperlight use case because one can't (generally) re-slide an image after a snapshot is taken, and in practice almost all images of a given binary are expected to descend from one snapshot.

As I said before I don't feel incredibly strongly though---I will leave the decision up to you.

[jsturtevant]

This will wrap and panic if the elf file is mal formed

[syntactically]

Thanks for all the great work here & putting up with so many rounds of iteration @cshung!

The addition of guest_virt_addr made me a bit uncomfortable, because I knew that we were using memory regions that had guest virtual addresses in them already in other places. I took a little bit more of a look at it, and I realised that this PR has exposed an existing semantic inconsistency in the way that we use MemoryRegions.

As you probably noticed, we have several different variants of MemoryRegion, defined as a base MemoryRegion_<T> struct that is parameterised by a marker type. There are IIRC three of those marker types that we are using right now, and it turns out that all of them have a different idea of what "host" and "guest" mean:

• HostGuestMemoryRegion maps host virtual addresses to guest physical addresses
• GuestMemoryRegion, which presently is not a mapping at all---just legitimately a region chunk of a single address space
• CrashDumpMemoryRegion, which maps host virtual addresses to guest virtual addresses.

Adding another field for GVA to the base struct is not ideal, then, because it's semantically confusing for the other variants (one of which even already contains GVAs!). I think what this PR really needs is for GuestMemoryRegion to be a mapping, the same as the other memory regions are, which is a nice increase in consistency. We would then switch to using the two sides of the mapping as the guest phys/virt addresses.

The obvious way to fix this is just by changing <GuestMemoryRegion as MemoryRegionKind>::HostBaseType to u64 and using it as the guest physical address. The big downside is of course that the naming becomes even more misleading: whilst "host_region" would be "towards the host side" (on a semantic line of 'host physical address <- host virtual address <- guest physical address <- guest virtual address'), it's not actually located on the host.

If you wanted to make another change to rename that type and fields to something more sensible (either as another PR using stacked PRs to keep this on top, or as an early commit in this PR which we must keep without squashing when merging, since it's a noisy, large, and semantically distinct change), that would be great, but is by no means required/expected. If you did do that, taking the opportunity to (again, as distinct commits that we must not squash on merge) to also remove one of the redundant size fields in the structure (so changing from host range/guest range to host base/guest base/size) would be great.

A couple more minor nits:

• I believe that there are no longer any users of SandboxMemoryLayout::get_memory_regions_ using a region kind other than GuestMemoryRegion. So, we could rename it to get_memory_regions and concretise its type. Since it would then always be returning things with the correct host-side address type, we could avoid adding the new _with_code_va wrapper method, and just make the changes directly to get_memory_regions
• Why is code_virt_base pushed through snapshots / into the mgr? I see a comment about it being needed for gdb and tracing to resolve the offsets to the binary, but I don't see that happening
• If other regions intersect the code VA, should they be pushed around to make room, instead of signalling an error? I don't recall off the top of my head whether there is anything making assumptions about the layout of those regions, but I would rather hope not. There aren't many of them, and I hope they will all go away quite soon, so it does not matter too much, however.

[cshung]

Thanks for the thorough review @syntactically! The two refactor commits address the main feedback:

• GuestMemoryRegion is now a proper GPA-to-GVA mapping — \guest_virt_addr\ is removed. \host_region\ carries the GPA, \guest_region\ carries the GVA. For identity-mapped regions both are the same.
• \get_memory_regions\ concretised — renamed from \get_memory_regions_, generic removed since all callers use \GuestMemoryRegion.
• *\checked_add* added for the overlap check (@jsturtevant's nit).

Responding to the remaining questions:

Why is \code_virt_base\ pushed through snapshots / into the mgr?

It is used by the GDB debug path (\GetCodeSectionOffset\ in \x86_64.rs) to report where the code section lives in guest virtual space. Without it, GDB cannot resolve symbols after snapshot restore. It is also needed for
ead_guest_memory_by_gva\ (tracing feature) to translate GVAs back to physical offsets.

If other regions intersect the code VA, should they be pushed around to make room, instead of signalling an error?

For non-PIE, the code VA is fixed by the ELF linker, so the user controls it. If it conflicts, that is a build-time problem the user should fix (e.g., pick a different --image-base). Silently relocating other regions would make behavior hard to reason about, and those regions have fixed GPAs that the PEB and guest runtime depend on. I think erroring is the right call here.

[syntactically]

It is used by the GDB debug path (\GetCodeSectionOffset\ in \x86_64.rs) to report where the code section lives in guest virtual space. Without it, GDB cannot resolve symbols after snapshot restore. It is also needed for
ead_guest_memory_by_gva\ (tracing feature) to translate GVAs back to physical offsets.

Ah, of course. I think the SandboxMemoryLayout is already accessible in the relevant places and a lot of the information about the layout is already centralised there; could we just move this into that?

Silently relocating other regions would make behavior hard to reason about, and those regions have fixed GPAs that the PEB and guest runtime depend on. I think erroring is the right call here

Well, in the non-PIE mode, those gpas are not independent of the executable, because the code segment is near the bottom of the initial setup snapshot region. So, it's kind of being consistent to move them. However, I don't feel strongly.

[syntactically]

Is there ever a good reason to call this instead of get_guest_regions_with_code_va below? I see that there is a caller in hyperlight_vm/x86_64.rs, but it looks like that is in a test where the distinction does not matter.

If not, can we either inline the adjustment from get_guest_regions_with_code_va, or make this function private so that nobody calls it by accident?

[syntactically]

There's no reason for this to exist in the non-PIE binary case?

[syntactically]

I think it would be nice to be more careful about naming+documentation here, but that can wait if you would prefer.

[syntactically]

Does this actually change any behaviour, or is it just a functionally identical incidental formatting cleanup?

[syntactically]

Is layout.get_guest_code_address() meaningful at all anymore? I guess it still points to the GPA for the code region---is that actually used anywhere?

[syntactically]

(I am imagining an approach here where you, early on, do layout.set_code_va(Some(the appropriate thing)) and then get_guest_code_address and get_memory_regions both are made to incidentally do the correct thing so that further on code does not have to fix up the layout with an extra value that is threaded around next to it).

[syntactically]

This should probably go in the MemoryLayout structure below, which is more-or-less the serialisation proxy for SandboxMemoryLayout

[syntactically]

This load_addr is used in relocation processing, so it seems wrong for it to be the gpa? I think we only support R_<cls>_RELATIVE right now, which is probably not used in the non-PIC binaries that are relevant, but we should probably still do the correct math if we did encounter one.

Actually, it looks like there is a latent bug here even in the PIC code (since a PIC executable doesn't actually have to have a link address of 0): I think probably load_at needs to be adjusted to properly take into account the offset between load_addr and get_base_va, since for e.g. R_AARCH64_RELATIVE, the ABI notes that it "[...] represents a relative adjustment to the place based on the load address of the object relative to its original link address" (emphasis added).

So, probably load_at should take the gva, but also change its relocation process to use a (signed) load_addr - get_base_va() delta as the adjustment to the addend.