Add initial single-sandbox-executing-at-a-time support for Hypervisor.framework#1674
Open
syntactically wants to merge 15 commits into
Open
Add initial single-sandbox-executing-at-a-time support for Hypervisor.framework#1674syntactically wants to merge 15 commits into
syntactically wants to merge 15 commits into
Conversation
Signed-off-by: Lucy Menon <168595099+syntactically@users.noreply.github.com>
syntactically
requested review from
andreiltd,
danbugs,
dblnz,
devigned,
jprendes,
jsturtevant,
ludfjig,
simongdavies and
squillace
as code owners
July 21, 2026 15:27
syntactically
added
kind/enhancement
Contributor
There was a problem hiding this comment.
Pull request overview
Adds initial Hypervisor.framework (HVF) support to hyperlight-host on macOS, along with a snapshot ABI/version bump and memory-layout/page-size changes needed for platforms with 16K host pages.
Changes:
- Introduce an HVF
VirtualMachinebackend and macOS-specific build/runtime glue (bindgen + codesigning runner + interrupt handling). - Bump snapshot ABI/goldens versions and update snapshot file metadata/config handling for the new hypervisor tag and ABI.
- Adjust host/guest memory layout assumptions (page size usage, base addresses, alignment) and tune tests to avoid unsupported parallelism on HVF.
Reviewed changes
Copilot reviewed 39 out of 41 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| src/hyperlight_host/tests/snapshot_goldens/platform.rs | Add HVF hypervisor tag handling in snapshot golden platform selection. |
| src/hyperlight_host/tests/snapshot_goldens/goldens_version.rs | Bump goldens version and set arch-specific compatibility list. |
| src/hyperlight_host/tests/sandbox_host_tests.rs | Serialize/scale down thread-heavy tests under HVF; adjust scratch sizing. |
| src/hyperlight_host/tests/integration_test.rs | Reduce stress-test thread counts under HVF. |
| src/hyperlight_host/src/sandbox/snapshot/tripwires.rs | Bump expected snapshot ABI and update page-size/base-address invariants. |
| src/hyperlight_host/src/sandbox/snapshot/mod.rs | Align snapshot memory to host page size; update tests to use runtime page size. |
| src/hyperlight_host/src/sandbox/snapshot/file/media_types.rs | Bump SNAPSHOT_ABI_VERSION for snapshot memory blob. |
| src/hyperlight_host/src/sandbox/snapshot/file/config.rs | Add HVF hypervisor tag and macOS/aarch64 CPU vendor behavior. |
| src/hyperlight_host/src/sandbox/snapshot/file_tests.rs | Accept hvf annotation/tag in snapshot file tests. |
| src/hyperlight_host/src/sandbox/initialized_multi_use.rs | Use runtime page size in test helpers and overlap calculations. |
| src/hyperlight_host/src/sandbox/file_mapping.rs | Broaden mmap-backed file mapping resource handling to unix. |
| src/hyperlight_host/src/sandbox/config.rs | Enable interrupt retry delay config for HVF as well as Linux hypervisors. |
| src/hyperlight_host/src/mem/shared_mem.rs | Generalize mmap code to unix and switch guard sizing to runtime page size. |
| src/hyperlight_host/src/mem/shared_mem_tests.rs | Update tests to use runtime page size. |
| src/hyperlight_host/src/mem/mgr.rs | Account for host page alignment when locating snapshot PT tail. |
| src/hyperlight_host/src/mem/memory_region.rs | Use vmem page size constants and runtime page size where needed. |
| src/hyperlight_host/src/mem/layout.rs | Move base address to 0x4000; align sizes for mixed guest/host page sizes. |
| src/hyperlight_host/src/hypervisor/virtual_machine/whp.rs | Make register setters require &mut self to match new VM trait. |
| src/hyperlight_host/src/hypervisor/virtual_machine/mshv/x86_64.rs | Make register setters require &mut self to match new VM trait. |
| src/hyperlight_host/src/hypervisor/virtual_machine/mod.rs | Add HVF module/type and selection; extend error enums for HVF sync/errors. |
| src/hyperlight_host/src/hypervisor/virtual_machine/kvm/x86_64.rs | Make register setters require &mut self to match new VM trait. |
| src/hyperlight_host/src/hypervisor/virtual_machine/kvm/aarch64.rs | Make register setters require &mut self to match new VM trait. |
| src/hyperlight_host/src/hypervisor/virtual_machine/hvf/mod.rs | New HVF backend implementing VM lifecycle, memory mapping, and state sync. |
| src/hyperlight_host/src/hypervisor/virtual_machine/hvf/fp_abi.c | C ABI shims for SIMD FP register access not supported in stable Rust FFI. |
| src/hyperlight_host/src/hypervisor/virtual_machine/hvf/bindings.h | Header for bindgen + shim declarations, includes Hypervisor.framework. |
| src/hyperlight_host/src/hypervisor/surrogate_process.rs | Use runtime page size for guard pages in Windows surrogate mapping. |
| src/hyperlight_host/src/hypervisor/mod.rs | Refactor interrupt handle state tracking; add HVF cancel mechanism support. |
| src/hyperlight_host/src/hypervisor/hyperlight_vm/x86_64.rs | Switch to new interrupt handle constructors; adjust VM mutability. |
| src/hyperlight_host/src/hypervisor/hyperlight_vm/mod.rs | Route interrupt state through the new state machine in the VM run loop. |
| src/hyperlight_host/src/hypervisor/hyperlight_vm/aarch64.rs | Add HVF VM construction path and HVF interrupt handle wiring. |
| src/hyperlight_host/Cargo.toml | Add hvf feature, bindgen/cc build deps, parking_lot, and default-enable HVF. |
| src/hyperlight_host/build.rs | Generate HVF bindings and compile the C shim; add HVF cfg alias. |
| src/hyperlight_common/src/mem.rs | Remove fixed page-size constants from mem (shifted to vmem). |
| src/hyperlight_common/src/arch/aarch64/layout.rs | Adjust fixed AArch64 addresses to accommodate 16K pages. |
| flake.nix | Add aarch64-darwin target support and adjust tooling availability per platform. |
| flake.lock | Update pinned nixpkgs revision/hash. |
| dev/macos-sign-and-run.sh | Add macOS runner that codesigns binaries with hypervisor entitlement before exec. |
| dev/macos-entitlements.plist | Add com.apple.security.hypervisor entitlement for signed binaries. |
| CHANGELOG.md | Document the snapshot incompatibility caused by the address/layout change. |
| Cargo.lock | Record new dependencies (parking_lot, bindgen, cc) in the lockfile. |
| .cargo/config.toml | Configure macOS Cargo runner to use the codesign wrapper script. |
Previously, the Linux and WHP interrupt handle implementations used exactly the same logic to update three bits of atomic state, and further interrupt handle implementations would likely need the same. This commit extracts the state machine logic into a single shared implementation used by both interrupt handles. It also refactors `WindowsInterruptHandle` to pull the logic around locking into another separate type, which will be shared with other interrupt handle implementations in the future Signed-off-by: Lucy Menon <168595099+syntactically@users.noreply.github.com>
Signed-off-by: Lucy Menon <168595099+syntactically@users.noreply.github.com>
This commit moves a bunch of code (primarily mmap-based implementations of things) from cfg(target_os = "linux") to cfg(unix), allowing it to compile on MacOS (where it will be useful). It also moves the kvm and mshv package dependencies from cfg(unix) to cfg(target_os = "linux"), so that Cargo does not try (and fail) to build them on MacOS. Signed-off-by: Lucy Menon <168595099+syntactically@users.noreply.github.com>
Signed-off-by: Lucy Menon <168595099+syntactically@users.noreply.github.com>
Signed-off-by: Lucy Menon <168595099+syntactically@users.noreply.github.com>
todo: squash: hvf interrupt handle implementation Signed-off-by: Lucy Menon <168595099+syntactically@users.noreply.github.com>
On AArch64, there is no particular reason to expect the page size of the
host to match the page size of the guest, but the host previously used
some constants (`hyperlight_common::mem::{PAGE_SIZE, PAGE_SIZE_USIZE,
PAGE_SHIFT}`) both when computing guest memory layouts and when
constructing host->guest mappings.
This commit removes all the uses of those ambiguous constants, replacing
them with `page_size::get()` when the host page size is needed and
`hyperlight_common::vmem::PAGE_SIZE` when the guest page size is
required. It also makes a few tweaks to remove assumptions that the
page sizes are the same, allowing (at the very least) operation on a
host with 16k pages while allowing guests to continue using 4k pages.
Signed-off-by: Lucy Menon <168595099+syntactically@users.noreply.github.com>
Signed-off-by: Lucy Menon <168595099+syntactically@users.noreply.github.com>
These conceptually mutate the state of the guest, so it makes sense that they should take &mut. This is useful for HVF, which stores a copy of the regs when they are set, and in this manner can avoid an extra Rust lock. add fpu to the commit msg Signed-off-by: Lucy Menon <168595099+syntactically@users.noreply.github.com>
Signed-off-by: Lucy Menon <168595099+syntactically@users.noreply.github.com>
Other operating systems do not support its use in EL0 Signed-off-by: Lucy Menon <168595099+syntactically@users.noreply.github.com>
Signed-off-by: Lucy Menon <168595099+syntactically@users.noreply.github.com>
On MacOS, communicating with the hypervisor requires that a binary be signed with an "entitlement" `com.apple.security.hypervisor`. This commit adds a script that locally signs and then runs a binary, and configures Cargo to use that script to run tests/exmaples/etc. Signed-off-by: Lucy Menon <168595099+syntactically@users.noreply.github.com>
Signed-off-by: Lucy Menon <168595099+syntactically@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.