Implement MSHV aarch64 backend by cshung · Pull Request #1626 · hyperlight-dev/hyperlight

cshung · 2026-07-06T22:39:28Z

ARM64 Linux MSHV

The backend provides partition creation, memory mappings, MMIO dispatch,
general and FPU registers, batched special-register access, and replacement-VM
reset. MMIO PC advancement wraps at the address boundary.

Native ARM64 MSHV CI uses hierarchical-virtualization runners and bounded test
scheduling for the platform's partition limit. Stress tests retain their
iteration counts.

Commit layers

This PR is D, one signed commit directly above main. It is independent of
GDB support. The MSHV debugger branch has a cherry-pick of shared support A as
E, followed by one MSHV-specific debugger commit F in #2052.

The complete graph and update rules are in
docs/gdb-commit-layers.md.

Validation

Formatting and ARM64 MSHV-only cross-Clippy pass after consolidation.
Backend Rust source matches the natively validated implementation.
Native ARM64 MSHV CI before consolidation passed debug and release, with
1,076 passed execution records per profile.
The dedicated ARM64 MSHV debugger VM also passed the five backend tests.

Copilot

🟡 Changes recommended

A guest-controlled MMIO store can overflow the PC increment and panic the host, while snapshot capture and restore also issue unnecessary separate register requests.

3 open issues

A guest can map the upper virtual-address range and execute an MMIO store at… · New
Snapshot capture issues seven separate MSHV register requests here. Fetch all seven registers with… · New
Every sandbox restore reaches this setter through HyperlightVm::apply_sregs, so these calls add… · New

What changed in this PR

This PR implements the Linux aarch64 MSHV backend, allowing Hyperlight to run ARM64 sandboxes through MSHV.

Changes:

Implements VM creation, memory mapping, MMIO dispatch, register access, and vCPU reset.
Connects MSHV to ARM64 backend selection and memory-access decoding.
Adds ARM64 MSHV CI coverage and adjusts test concurrency and platform expectations.

File	Description
`typos.toml`	Allows an identifier spelling required by MSHV bindings.
`src/hyperlight_host/tests/sandbox_host_tests.rs`	Limits parallel callbacks for ARM64 MSHV.
`src/hyperlight_host/tests/integration_test.rs`	Limits ARM64 MSHV stress-test concurrency.
`src/hyperlight_host/src/sandbox/snapshot/file/config.rs`	Accepts Arm CPU implementers in Linux snapshot tests.
`src/hyperlight_host/src/mem/memory_region.rs`	Decodes ARM64 MSHV memory-access flags.
`src/hyperlight_host/src/hypervisor/virtual_machine/mshv/aarch64.rs`	Implements the ARM64 MSHV virtual machine backend.
`src/hyperlight_host/src/hypervisor/hyperlight_vm/aarch64.rs`	Instantiates MSHV when selected on ARM64.
`.github/workflows/ValidatePullRequest.yml`	Adds debug and release ARM64 MSHV jobs.
`.github/workflows/dep_build_test.yml`	Configures runners, test limits, and snapshot-golden exclusions for ARM64 MSHV.

_{Review effort: Balanced}

simongdavies

We should update https://github.com/hyperlight-dev/hyperlight/blob/main/README.md#platform-support.

@syntactically should take a look at this as well

MSHV provides partition creation, memory mappings, MMIO dispatch, batched register access and replacement-VM reset on ARM64. Native CI uses tagged hierarchical-virtualization runners and bounded scheduling for the partition limit. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: cshung <3410332+cshung@users.noreply.github.com>

cshung · 2026-11-12T18:16:31Z

The README platform-support table lists ARM64 Linux/MSHV general support in 93e0ffa. Guest debugging remains in the separate PR #2052.

hyperlight-gh-bot · 2026-11-12T21:17:38Z

Benchmark Results

Measured commit: 93e0ffa5b941
Baseline commit: 01df99173865

kvm / amd (Linux) (➖ stable)

No benchmark improved or regressed.

Benchmark Results

function_call_codec

	`encode_control`	`decode_vec_bytes_copy`
`byte_chunks`	`777.28 ns` (➖ 1.00x slower)
`vec_bytes`	`598.31 ns` (➖ 1.01x slower)
		`374.18 µs` (➖ 1.01x faster)

payload_allocation

	`slot_pool_segmented`
`262144`	`534.65 ns` (➖ 1.02x slower)
`65536`	`142.00 ns` (➖ 1.02x faster)

sandboxes

	`create_initialized_and_drop`
`medium`	`13.35 ms` (➖ 1.00x slower)

slot_pool

	`alloc_dealloc_128`	`alloc_dealloc_4096`	`alloc_dealloc_1500`
	`7.69 ns` (➖ 1.00x faster)	`7.68 ns` (➖ 1.00x faster)	`7.69 ns` (➖ 1.00x faster)

snapshot_files

	`load_snapshot_unverified`
`small`	`104.44 µs` (➖ 1.06x slower)

virtq_readonly

	`slot_pool_segmented`	`slot_pool_segmented_fragmented`
`262144`	`7.18 µs` (➖ 1.01x faster)	`7.18 µs` (➖ 1.03x faster)
`65536`	`1.94 µs` (➖ 1.07x faster)	`2.06 µs` (➖ 1.08x slower)

virtq_readwrite

	`slot_pool_segmented`	`slot_pool_segmented_fragmented`
`262144`	`26.97 µs` (➖ 1.00x faster)
`65536`	`6.25 µs` (➖ 1.01x faster)	`6.18 µs` (➖ 1.03x faster)
`8192`	`1.04 µs` (➖ 1.01x slower)	`1.03 µs` (➖ 1.00x faster)

kvm / intel (Linux) (➖ stable)

No benchmark improved or regressed.

Benchmark Results

function_call_codec

	`encode_control`	`decode_vec_bytes_copy`
`byte_chunks`	`699.86 ns` (➖ 1.01x slower)
`vec_bytes`	`518.70 ns` (➖ 1.02x faster)
		`682.48 µs` (➖ 1.01x slower)

payload_allocation

	`slot_pool_segmented`
`262144`	`497.63 ns` (➖ 1.09x faster)
`65536`	`170.78 ns` (➖ 1.08x faster)

sandboxes

	`create_initialized_and_drop`
`medium`	`14.90 ms` (➖ 1.05x faster)

slot_pool

	`alloc_dealloc_128`	`alloc_dealloc_4096`	`alloc_dealloc_1500`
	`6.79 ns` (➖ 1.10x faster)	`6.80 ns` (➖ 1.09x faster)	`6.81 ns` (➖ 1.10x faster)

snapshot_files

	`load_snapshot_unverified`
`small`	`50.63 µs` (➖ 1.06x slower)

virtq_readonly

	`slot_pool_segmented`	`slot_pool_segmented_fragmented`
`262144`	`7.61 µs` (➖ 1.07x faster)	`7.57 µs` (➖ 1.08x faster)
`65536`	`2.15 µs` (➖ 1.08x faster)	`2.13 µs` (➖ 1.09x faster)

virtq_readwrite

	`slot_pool_segmented`	`slot_pool_segmented_fragmented`
`262144`	`29.20 µs` (➖ 1.12x faster)
`65536`	`7.08 µs` (➖ 1.09x faster)	`7.20 µs` (➖ 1.08x faster)
`8192`	`726.34 ns` (➖ 1.04x faster)	`731.23 ns` (➖ 1.09x faster)

mshv3 / amd (Linux) (➖ stable)

No benchmark improved or regressed.

Benchmark Results

function_call_codec

	`encode_control`	`decode_vec_bytes_copy`
`byte_chunks`	`934.14 ns` (➖ 1.00x faster)
`vec_bytes`	`716.81 ns` (➖ 1.01x slower)
		`268.94 µs` (➖ 1.32x faster)

payload_allocation

	`slot_pool_segmented`
`262144`	`730.76 ns` (➖ 1.04x faster)
`65536`	`192.97 ns` (➖ 1.01x faster)

sandboxes

	`create_initialized_and_drop`
`medium`	`64.68 ms` (➖ 1.08x faster)

slot_pool

	`alloc_dealloc_128`	`alloc_dealloc_4096`	`alloc_dealloc_1500`
	`9.52 ns` (➖ 1.01x faster)	`9.56 ns` (➖ 1.00x faster)	`9.76 ns` (➖ 1.00x faster)

snapshot_files

	`load_snapshot_unverified`
`small`	`105.15 µs` (➖ 1.04x faster)

virtq_readonly

	`slot_pool_segmented`	`slot_pool_segmented_fragmented`
`262144`	`9.83 µs` (➖ 1.00x faster)	`10.14 µs` (➖ 1.03x faster)
`65536`	`2.25 µs` (➖ 1.00x slower)	`2.39 µs` (➖ 1.03x faster)

virtq_readwrite

	`slot_pool_segmented`	`slot_pool_segmented_fragmented`
`262144`	`36.33 µs` (➖ 1.04x faster)
`65536`	`8.21 µs` (➖ 1.16x faster)	`8.02 µs` (➖ 1.22x faster)
`8192`	`1.25 µs` (➖ 1.04x slower)	`1.25 µs` (➖ 1.10x faster)

mshv3 / intel (Linux) (❌ 1.73x)

Top regressions

function_call_codec/decode_vec_bytes_copy — ❌ 1.73x slower
sandboxes/create_initialized_and_drop/medium — ❌ 1.63x slower

Benchmark Results

function_call_codec

	`encode_control`	`decode_vec_bytes_copy`
`byte_chunks`	`950.90 ns` (➖ 1.00x slower)
`vec_bytes`	`667.32 ns` (➖ 1.01x slower)
		`1.26 ms` (❌ 1.73x slower)

payload_allocation

	`slot_pool_segmented`
`262144`	`790.88 ns` (➖ 1.02x faster)
`65536`	`255.21 ns` (➖ 1.04x faster)

sandboxes

	`create_initialized_and_drop`
`medium`	`85.20 ms` (❌ 1.63x slower)

slot_pool

	`alloc_dealloc_128`	`alloc_dealloc_4096`	`alloc_dealloc_1500`
	`8.74 ns` (➖ 1.07x faster)	`8.71 ns` (➖ 1.00x slower)	`8.84 ns` (➖ 1.01x slower)

snapshot_files

	`load_snapshot_unverified`
`small`	`60.21 µs` (➖ 1.04x slower)

virtq_readonly

	`slot_pool_segmented`	`slot_pool_segmented_fragmented`
`262144`	`8.01 µs` (➖ 1.00x slower)	`8.06 µs` (➖ 1.00x slower)
`65536`	`2.31 µs` (➖ 1.00x slower)	`2.30 µs` (➖ 1.01x slower)

virtq_readwrite

	`slot_pool_segmented`	`slot_pool_segmented_fragmented`
`262144`	`38.24 µs` (➖ 1.01x faster)
`65536`	`7.63 µs` (➖ 1.01x slower)	`7.71 µs` (➖ 1.03x slower)
`8192`	`914.73 ns` (➖ 1.00x faster)	`923.99 ns` (➖ 1.00x slower)

hyperv-ws2025 / amd (Windows) (➖ stable)

No benchmark improved or regressed.

Benchmark Results

function_call_codec

	`encode_control`	`decode_vec_bytes_copy`
`byte_chunks`	`1.17 µs` (➖ 1.02x faster)
`vec_bytes`	`762.32 ns` (➖ 1.02x faster)
		`1.94 ms` (➖ 1.01x faster)

payload_allocation

	`slot_pool_segmented`
`262144`	`788.73 ns` (➖ 1.01x slower)
`65536`	`237.38 ns` (➖ 1.01x slower)

sandboxes

	`create_initialized_and_drop`
`medium`	`13.74 ms` (➖ 1.02x slower)

slot_pool

	`alloc_dealloc_128`	`alloc_dealloc_4096`	`alloc_dealloc_1500`
	`9.97 ns` (➖ 1.07x faster)	`9.98 ns` (➖ 1.03x faster)	`9.92 ns` (➖ 1.06x faster)

snapshot_files

	`load_snapshot_unverified`
`small`	`783.10 µs` (➖ 1.02x faster)

virtq_readonly

	`slot_pool_segmented`	`slot_pool_segmented_fragmented`
`262144`	`9.12 µs` (➖ 1.03x faster)	`9.12 µs` (➖ 1.04x faster)
`65536`	`2.35 µs` (➖ 1.01x slower)	`2.32 µs` (➖ 1.02x faster)

virtq_readwrite

	`slot_pool_segmented`	`slot_pool_segmented_fragmented`
`262144`	`40.05 µs` (➖ 1.02x slower)
`65536`	`8.87 µs` (➖ 1.02x slower)	`8.93 µs` (➖ 1.02x faster)
`8192`	`1.25 µs` (➖ 1.08x faster)	`1.26 µs` (➖ 1.06x faster)

hyperv-ws2025 / intel (Windows) (➖ stable)

No benchmark improved or regressed.

Benchmark Results

function_call_codec

	`encode_control`	`decode_vec_bytes_copy`
`byte_chunks`	`1.23 µs` (➖ 1.03x faster)
`vec_bytes`	`803.94 ns` (➖ 1.00x faster)
		`3.13 ms` (➖ 1.01x faster)

payload_allocation

	`slot_pool_segmented`
`262144`	`735.43 ns` (➖ 1.03x faster)
`65536`	`209.48 ns` (➖ 1.00x slower)

sandboxes

	`create_initialized_and_drop`
`medium`	`14.53 ms` (➖ 1.01x faster)

slot_pool

	`alloc_dealloc_128`	`alloc_dealloc_4096`	`alloc_dealloc_1500`
	`9.85 ns` (➖ 1.01x slower)	`10.06 ns` (➖ 1.00x slower)	`9.81 ns` (➖ 1.09x faster)

snapshot_files

	`load_snapshot_unverified`
`small`	`692.64 µs` (➖ 1.00x slower)

virtq_readonly

	`slot_pool_segmented`	`slot_pool_segmented_fragmented`
`262144`	`7.67 µs` (➖ 1.00x slower)	`7.69 µs` (➖ 1.00x slower)
`65536`	`2.32 µs` (➖ 1.00x slower)	`2.31 µs` (➖ 1.01x faster)

virtq_readwrite

	`slot_pool_segmented`	`slot_pool_segmented_fragmented`
`262144`	`50.93 µs` (➖ 1.00x faster)
`65536`	`8.50 µs` (➖ 1.02x slower)	`8.40 µs` (➖ 1.08x faster)
`8192`	`1.06 µs` (➖ 1.11x faster)	`1.06 µs` (➖ 1.00x slower)

_{Reported by cargo ci bench-report --candidate run:43277990563 --config-file bench_report.toml.}

cshung added the C-enhancement For PRs adding features, improving functionality, docs, tests, etc. label Jul 7, 2026

cshung force-pushed the cshung/mshv-aarch64 branch from b34cc5d to fb92ede Compare July 31, 2026 16:13

cshung force-pushed the cshung/mshv-aarch64 branch from fb92ede to 3736e16 Compare August 12, 2026 14:55

cshung force-pushed the cshung/mshv-aarch64 branch 2 times, most recently from b440e24 to 4ada969 Compare August 20, 2026 17:42

cshung force-pushed the cshung/mshv-aarch64 branch from 4ada969 to 7f2289d Compare September 2, 2026 22:47

cshung force-pushed the cshung/mshv-aarch64 branch from a70dcfa to 1b275f2 Compare September 29, 2026 05:30

cshung force-pushed the cshung/mshv-aarch64 branch from 1b275f2 to 2f42d32 Compare November 2, 2026 17:10

This comment has been minimized.

Sign in to view

cshung force-pushed the cshung/mshv-aarch64 branch from 2f42d32 to 0e44f0a Compare November 5, 2026 17:24

This comment has been minimized.

Sign in to view

cshung force-pushed the cshung/mshv-aarch64 branch from e039b60 to 747ee00 Compare November 10, 2026 16:59

This comment has been minimized.

Sign in to view

cshung marked this pull request as ready for review November 10, 2026 18:22

cshung requested review from andreiltd, danbugs, dblnz, devigned, jprendes, jsturtevant, ludfjig, simongdavies, squillace and syntactically as code owners November 10, 2026 18:22

Copilot AI balanced review requested due to automatic review settings November 10, 2026 18:22

Copilot started reviewing on behalf of cshung November 10, 2026 18:23

View session

Copilot AI reviewed Nov 10, 2026

View reviewed changes

Comment thread src/hyperlight_host/src/hypervisor/virtual_machine/mshv/aarch64.rs Resolved

Comment thread src/hyperlight_host/src/hypervisor/virtual_machine/mshv/aarch64.rs Resolved

Comment thread src/hyperlight_host/src/hypervisor/virtual_machine/mshv/aarch64.rs Resolved

This comment has been minimized.

Sign in to view

cshung force-pushed the cshung/mshv-aarch64 branch from bcd0df1 to 938f7e1 Compare November 11, 2026 19:52

cshung mentioned this pull request Nov 11, 2026

feat(aarch64): add GDB debugging for Linux MSHV #2052

Open

cshung force-pushed the cshung/mshv-aarch64 branch from 938f7e1 to fb09873 Compare November 12, 2026 00:12

This comment has been minimized.

Sign in to view

simongdavies reviewed Nov 12, 2026

View reviewed changes

Comment thread src/hyperlight_host/tests/integration_test.rs Resolved

Comment thread src/hyperlight_host/tests/integration_test.rs Resolved

Comment thread src/hyperlight_host/tests/integration_test.rs Resolved

cshung force-pushed the cshung/mshv-aarch64 branch from fb09873 to 93e0ffa Compare November 12, 2026 18:15

Conversation

cshung commented Jul 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

ARM64 Linux MSHV

Commit layers

Validation

Uh oh!

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

Uh oh!

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

simongdavies left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cshung commented Nov 12, 2026

Uh oh!

hyperlight-gh-bot Bot commented Nov 12, 2026

Benchmark Results

Benchmark Results

function_call_codec

payload_allocation

sandboxes

slot_pool

snapshot_files

virtq_readonly

virtq_readwrite

Benchmark Results

function_call_codec

payload_allocation

sandboxes

slot_pool

snapshot_files

virtq_readonly

virtq_readwrite

Benchmark Results

function_call_codec

payload_allocation

sandboxes

slot_pool

snapshot_files

virtq_readonly

virtq_readwrite

Top regressions

Benchmark Results

function_call_codec

payload_allocation

sandboxes

slot_pool

snapshot_files

virtq_readonly

virtq_readwrite

Benchmark Results

function_call_codec

payload_allocation

sandboxes

slot_pool

snapshot_files

virtq_readonly

virtq_readwrite

Benchmark Results

function_call_codec

payload_allocation

sandboxes

slot_pool

snapshot_files

virtq_readonly

virtq_readwrite

Uh oh!

cshung commented Jul 6, 2026 •

edited

Loading