feat(aarch64): add GDB debugging for Windows ARM64 WHP by cshung · Pull Request #1907 · hyperlight-dev/hyperlight

cshung · 2026-10-08T17:36:47Z

Windows ARM64 WHP GDB

WHP guests support register and memory access, two hardware breakpoints,
four-byte BRK software breakpoints, and hardware single-step.
Guest synchronous exception vectors forward debug stops through HVC.
The backend preserves interrupted context and debugger state across cache
synchronization and vCPU reset.

Commit layers

This PR is B, one WHP-specific commit above shared support A in #2050.
KVM support in #2016 is an independent sibling.

WHP-only comparison.

Shared debugger handling, page-sized memory access and recovery tests belong
to #2050. This layer contains WHP integration, platform enablement, the
read-only cache-sync page and backend tests.

The graph and update rules are in
docs/gdb-commit-layers.md.
The full PR diff includes the unmerged shared prerequisite.

Validation

Formatting and Windows ARM64 GDB-enabled cross-Clippy pass.
The Linux just clippyw recipe passes.
WHP backend and register-access source match the tested combined tree.
Shared support passes native ARM64 MSHV formatting, Clippy, build, the full
just test recipe, 26 debugger/backend tests and seven real GDB client tests.
Earlier native Windows ARM64 validation passed six real GDB client tests and
14 backend/recovery tests on the combined WHP/KVM tree.
Native WHP ARM64 runtime tests were not repeated for these shared fixes.

Copilot

🟡 Changes recommended

Breakpoint state can survive crash or cancellation recovery, and the hidden cache-sync mapping conflicts with the public mapping contract.

4 open findings

Clean up debugger breakpoints after crash detach · New
Cancel ARM64 software steps for all cancellation sources · New
Reserve hidden GPA 0x1000 in the mapping contract · New
Restore corrupted mathematical symbols in comments · New

What changed in this PR

Adds Windows ARM64 WHP guest debugging and generalizes the GDB implementation across architectures.

Changes:

Adds ARM64 registers, software breakpoints, stepping, and cache synchronization.
Extracts shared debugger logic from x86_64 code.
Updates tests, documentation, and platform configuration.

File	Description
`CHANGELOG.md`	Records ARM64 GDB support.
`docs/how-to-debug-a-hyperlight-guest.md`	Documents architecture-specific capabilities.
`src/hyperlight_host/build.rs`	Enables GDB on Windows ARM64.
`src/hyperlight_host/examples/guest-debugging/main.rs`	Adds ARM64 debugging tests.
`src/hyperlight_host/src/hypervisor/gdb/arch.rs`	Dispatches architecture-specific logic.
`src/hyperlight_host/src/hypervisor/gdb/arch/aarch64.rs`	Implements ARM64 breakpoint and step decoding.
`src/hyperlight_host/src/hypervisor/gdb/arch/x86_64.rs`	Houses extracted x86_64 logic.
`src/hyperlight_host/src/hypervisor/gdb/event_loop.rs`	Maps ARM64 stop reasons.
`src/hyperlight_host/src/hypervisor/gdb/mod.rs`	Extends shared debugging interfaces.
`src/hyperlight_host/src/hypervisor/gdb/target.rs`	Adds architecture-specific GDB registers.
`src/hyperlight_host/src/hypervisor/hyperlight_vm/aarch64.rs`	Connects GDB to ARM64 VMs.
`src/hyperlight_host/src/hypervisor/hyperlight_vm/debug.rs`	Centralizes breakpoint and stepping state.
`src/hyperlight_host/src/hypervisor/hyperlight_vm/mod.rs`	Handles ARM64 debug exits.
`src/hyperlight_host/src/hypervisor/hyperlight_vm/x86_64.rs`	Removes extracted debugger logic.
`src/hyperlight_host/src/hypervisor/virtual_machine/mod.rs`	Extends VM exits and errors.
`src/hyperlight_host/src/hypervisor/virtual_machine/whp/aarch64.rs`	Implements WHP debugging and cache synchronization.
`src/hyperlight_host/src/sandbox/initialized.rs`	Guards snapshots with active breakpoints.

🧠 Review effort: Balanced

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

syntactically · 2026-10-12T15:50:39Z

@cshung I guess you are using software breakpoints here because WHPX aarch64 does not yet support setting MDCR_EL2.TDE. I think this is very divergent from the other implementations and especially the emulation of software step looks very fragile in its current state.

I wonder if we can make things a little bit more congruent with the other implementations by using the same hardware debug approach as other targets, but on WHP set MDSCR_EL1.KDE and have little assembly stubs catch this case and make hvcs (or, even make an hvc on every exception entry, when in gdb mode)? Admittedly this will not work very well if VBAR_EL1 or virtual memory configuration for the exception handlers are messed up, but in that case I think given the current guest architecture it is extremely unlikely that guest code would continue to execute and produce any useful results.

Architecture adapters, software breakpoints, page-sized memory access and recovery handling are shared by backend layers. Guest debug vectors and common tests support ARM64. Backend layers control platform enablement. The commit-layer document defines dependencies and shared-update validation. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: cshung <3410332+cshung@users.noreply.github.com>

Guest debug exceptions reach WHP through HVC. Saved exception context, hardware breakpoints and single-step survive cache synchronization and vCPU reset. The cache-sync trampoline is read-only to guests. Shared debugger behavior belongs to the parent commit. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: cshung <3410332+cshung@users.noreply.github.com>

hyperlight-gh-bot · 2026-11-12T20:50:17Z

Benchmark Results

Measured commit: 8cce8f00a701
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`	`774.73 ns` (➖ 1.02x slower)
`vec_bytes`	`591.76 ns` (➖ 1.04x faster)
		`375.57 µs` (➖ 1.00x slower)

payload_allocation

	`slot_pool_segmented`
`262144`	`527.81 ns` (➖ 1.01x slower)
`65536`	`145.23 ns` (➖ 1.01x slower)

sandboxes

	`create_initialized_and_drop`
`medium`	`13.43 ms` (➖ 1.00x faster)

slot_pool

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

snapshot_files

	`load_snapshot_unverified`
`small`	`99.87 µs` (➖ 1.02x slower)

virtq_readonly

	`slot_pool_segmented`	`slot_pool_segmented_fragmented`
`262144`	`6.87 µs` (➖ 1.16x faster)	`7.06 µs` (➖ 1.04x faster)
`65536`	`1.92 µs` (➖ 1.10x faster)	`2.04 µs` (➖ 1.06x slower)

virtq_readwrite

	`slot_pool_segmented`	`slot_pool_segmented_fragmented`
`262144`	`28.52 µs` (➖ 1.05x slower)
`65536`	`6.25 µs` (➖ 1.04x faster)	`6.22 µs` (➖ 1.06x faster)
`8192`	`1.02 µs` (➖ 1.05x faster)	`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`	`804.36 ns` (➖ 1.12x slower)
`vec_bytes`	`597.77 ns` (➖ 1.09x slower)
		`726.93 µs` (➖ 1.08x slower)

payload_allocation

	`slot_pool_segmented`
`262144`	`565.49 ns` (➖ 1.06x faster)
`65536`	`195.97 ns` (➖ 1.06x slower)

sandboxes

	`create_initialized_and_drop`
`medium`	`15.69 ms` (➖ 1.04x slower)

slot_pool

	`alloc_dealloc_128`	`alloc_dealloc_4096`	`alloc_dealloc_1500`
	`7.76 ns` (➖ 1.04x slower)	`7.72 ns` (➖ 1.03x slower)	`7.75 ns` (➖ 1.03x slower)

snapshot_files

	`load_snapshot_unverified`
`small`	`54.86 µs` (➖ 1.03x slower)

virtq_readonly

	`slot_pool_segmented`	`slot_pool_segmented_fragmented`
`262144`	`8.55 µs` (➖ 1.04x slower)	`8.47 µs` (➖ 1.04x slower)
`65536`	`2.40 µs` (➖ 1.05x slower)	`2.40 µs` (➖ 1.04x slower)

virtq_readwrite

	`slot_pool_segmented`	`slot_pool_segmented_fragmented`
`262144`	`33.25 µs` (➖ 1.04x slower)
`65536`	`7.92 µs` (➖ 1.02x slower)	`7.93 µs` (➖ 1.00x slower)
`8192`	`789.01 ns` (➖ 1.03x slower)	`814.99 ns` (➖ 1.03x slower)

mshv3 / amd (Linux) (➖ stable)

No benchmark improved or regressed.

Benchmark Results

function_call_codec

	`encode_control`	`decode_vec_bytes_copy`
`byte_chunks`	`932.91 ns` (➖ 1.00x slower)
`vec_bytes`	`715.29 ns` (➖ 1.01x slower)
		`352.96 µs` (➖ 1.05x slower)

payload_allocation

	`slot_pool_segmented`
`262144`	`729.19 ns` (➖ 1.00x faster)
`65536`	`192.94 ns` (➖ 1.00x faster)

sandboxes

	`create_initialized_and_drop`
`medium`	`63.80 ms` (➖ 1.01x slower)

slot_pool

	`alloc_dealloc_128`	`alloc_dealloc_4096`	`alloc_dealloc_1500`
	`9.60 ns` (➖ 1.00x faster)	`9.66 ns` (➖ 1.00x slower)	`9.62 ns` (➖ 1.00x faster)

snapshot_files

	`load_snapshot_unverified`
`small`	`104.57 µs` (➖ 1.01x faster)

virtq_readonly

	`slot_pool_segmented`	`slot_pool_segmented_fragmented`
`262144`	`10.04 µs` (➖ 1.03x slower)	`10.16 µs` (➖ 1.02x faster)
`65536`	`2.25 µs` (➖ 1.00x slower)	`2.40 µs` (➖ 1.03x faster)

virtq_readwrite

	`slot_pool_segmented`	`slot_pool_segmented_fragmented`
`262144`	`35.79 µs` (➖ 1.08x faster)
`65536`	`8.14 µs` (➖ 1.19x faster)	`9.35 µs` (➖ 1.02x faster)
`8192`	`1.28 µs` (➖ 1.06x slower)	`1.24 µs` (➖ 1.08x faster)

mshv3 / intel (Linux) (➖ stable)

No benchmark improved or regressed.

Benchmark Results

function_call_codec

	`encode_control`	`decode_vec_bytes_copy`
`byte_chunks`	`916.20 ns` (➖ 1.01x faster)
`vec_bytes`	`659.91 ns` (➖ 1.00x slower)
		`647.65 µs` (➖ 1.02x slower)

payload_allocation

	`slot_pool_segmented`
`262144`	`657.43 ns` (➖ 1.02x slower)
`65536`	`248.06 ns` (➖ 1.04x faster)

sandboxes

	`create_initialized_and_drop`
`medium`	`75.00 ms` (➖ 1.03x faster)

slot_pool

	`alloc_dealloc_128`	`alloc_dealloc_4096`	`alloc_dealloc_1500`
	`8.68 ns` (➖ 1.00x faster)	`8.69 ns` (➖ 1.02x faster)	`8.69 ns` (➖ 1.00x slower)

snapshot_files

	`load_snapshot_unverified`
`small`	`52.80 µs` (➖ 1.00x faster)

virtq_readonly

	`slot_pool_segmented`	`slot_pool_segmented_fragmented`
`262144`	`7.91 µs` (➖ 1.00x faster)	`7.95 µs` (➖ 1.00x faster)
`65536`	`2.27 µs` (➖ 1.01x slower)	`2.25 µs` (➖ 1.03x faster)

virtq_readwrite

	`slot_pool_segmented`	`slot_pool_segmented_fragmented`
`262144`	`41.06 µs` (➖ 1.07x slower)
`65536`	`7.47 µs` (➖ 1.01x faster)	`7.51 µs` (➖ 1.00x slower)
`8192`	`889.91 ns` (➖ 1.02x faster)	`906.64 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.20 µs` (➖ 1.29x faster)
`vec_bytes`	`777.91 ns` (➖ 1.11x faster)
		`1.98 ms` (➖ 1.10x faster)

payload_allocation

	`slot_pool_segmented`
`262144`	`992.68 ns` (➖ 1.27x slower)
`65536`	`236.74 ns` (➖ 1.03x slower)

sandboxes

	`create_initialized_and_drop`
`medium`	`12.18 ms` (➖ 1.00x faster)

slot_pool

	`alloc_dealloc_128`	`alloc_dealloc_4096`	`alloc_dealloc_1500`
	`11.75 ns` (➖ 1.18x slower)	`10.51 ns` (➖ 1.00x slower)	`10.38 ns` (➖ 1.05x slower)

snapshot_files

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

virtq_readonly

	`slot_pool_segmented`	`slot_pool_segmented_fragmented`
`262144`	`9.26 µs` (➖ 1.02x faster)	`9.17 µs` (➖ 1.01x faster)
`65536`	`2.36 µs` (➖ 1.01x slower)	`2.33 µs` (➖ 1.01x faster)

virtq_readwrite

	`slot_pool_segmented`	`slot_pool_segmented_fragmented`
`262144`	`39.13 µs` (➖ 1.02x slower)
`65536`	`8.82 µs` (➖ 1.00x faster)	`8.84 µs` (➖ 1.00x faster)
`8192`	`1.24 µs` (➖ 1.08x faster)	`1.26 µs` (➖ 1.02x 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.22 µs` (➖ 1.00x slower)
`vec_bytes`	`816.28 ns` (➖ 1.02x slower)
		`3.05 ms` (➖ 1.02x faster)

payload_allocation

	`slot_pool_segmented`
`262144`	`742.30 ns` (➖ 1.01x faster)
`65536`	`210.21 ns` (➖ 1.01x slower)

sandboxes

	`create_initialized_and_drop`
`medium`	`14.24 ms` (➖ 1.03x slower)

slot_pool

	`alloc_dealloc_128`	`alloc_dealloc_4096`	`alloc_dealloc_1500`
	`9.63 ns` (➖ 1.00x faster)	`9.90 ns` (➖ 1.10x faster)	`10.09 ns` (➖ 1.06x slower)

snapshot_files

	`load_snapshot_unverified`
`small`	`670.84 µs` (➖ 1.01x slower)

virtq_readonly

	`slot_pool_segmented`	`slot_pool_segmented_fragmented`
`262144`	`7.79 µs` (➖ 1.02x slower)	`7.47 µs` (➖ 1.03x faster)
`65536`	`2.31 µs` (➖ 1.01x slower)	`2.33 µs` (➖ 1.02x slower)

virtq_readwrite

	`slot_pool_segmented`	`slot_pool_segmented_fragmented`
`262144`	`41.22 µs` (➖ 1.00x slower)
`65536`	`9.16 µs` (➖ 1.08x slower)	`8.29 µs` (➖ 1.04x faster)
`8192`	`1.07 µs` (➖ 1.10x faster)	`1.13 µs` (➖ 1.04x slower)

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

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

This comment has been minimized.

Sign in to view

cshung marked this pull request as ready for review October 8, 2026 19:33

Copilot AI balanced review requested due to automatic review settings October 8, 2026 19:33

cshung requested review from andreiltd, danbugs, dblnz, devigned, jprendes, jsturtevant, ludfjig, simongdavies, squillace and syntactically as code owners October 8, 2026 19:33

Copilot started reviewing on behalf of cshung October 8, 2026 19:37

View session

Copilot AI reviewed Oct 8, 2026

View reviewed changes

cshung force-pushed the cshung/whp-aarch64-gdb branch from 8c0c245 to 39ea4cb Compare October 9, 2026 16:54

This comment has been minimized.

Sign in to view

cshung force-pushed the cshung/whp-aarch64-gdb branch from 7238539 to 6c35092 Compare October 19, 2026 14:56

This comment has been minimized.

Sign in to view

cshung force-pushed the cshung/whp-aarch64-gdb branch from dd86b49 to 698b851 Compare October 20, 2026 17:59

This comment has been minimized.

Sign in to view

cshung force-pushed the cshung/whp-aarch64-gdb branch from 698b851 to 3e3983f Compare October 26, 2026 16:30

This comment has been minimized.

Sign in to view

cshung force-pushed the cshung/whp-aarch64-gdb branch from 3e3983f to bed283f Compare October 30, 2026 16:47

This comment has been minimized.

Sign in to view

cshung force-pushed the cshung/whp-aarch64-gdb branch from bed283f to 905ca05 Compare November 2, 2026 16:19

This comment has been minimized.

Sign in to view

cshung mentioned this pull request Nov 3, 2026

feat(aarch64): add GDB debugging for Linux KVM #2016

Open

This comment has been minimized.

Sign in to view

cshung force-pushed the cshung/whp-aarch64-gdb branch from 00b7212 to d8d79a5 Compare November 5, 2026 17:22

This comment has been minimized.

Sign in to view

cshung force-pushed the cshung/whp-aarch64-gdb branch 3 times, most recently from 8a9493e to bd2cc61 Compare November 12, 2026 00:12

This comment has been minimized.

Sign in to view

cshung and others added 2 commits November 12, 2026 10:05

cshung force-pushed the cshung/whp-aarch64-gdb branch from bd2cc61 to 8cce8f0 Compare November 12, 2026 18:15

Conversation

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

Uh oh!

Windows ARM64 WHP GDB

Commit layers

Validation

Uh oh!

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!

Uh oh!

This comment has been minimized.

syntactically commented Oct 12, 2026

Uh oh!

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

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

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 Oct 8, 2026 •

edited

Loading