feat(gdb): share ARM64 debugger support across backends by cshung · Pull Request #2050 · hyperlight-dev/hyperlight

cshung · 2026-11-11T20:03:31Z

Shared GDB support

Architecture adapters and common debugger handling support ARM64 register
packets, software breakpoints, page-sized memory access, guest debug vectors,
and snapshot, cancellation and crash-detach recovery.

The existing x86_64 platform guard remains. Backend PRs enable ARM64 GDB.

Commit layers

main
|-- A: shared GDB support, this PR
|   |-- B: WHP GDB, #1907
|   `-- C: KVM GDB, #2016
`-- D: MSHV backend, #1626
    `-- E: cherry-pick of A
        `-- F: MSHV GDB, #2052

Each layer is one signed commit. B and C are siblings.
E carries A's patch over the independent MSHV prerequisite.
Shared updates propagate to B, C and E/F for validation on all backends.

Branch ownership, update rules and validation requirements are documented in
docs/gdb-commit-layers.md.

Validation

Native ARM64 MSHV validation through E/F passes formatting, Clippy, host build
and the full just test recipe with 1,076 successful test executions.
All 26 native debugger, backend and recovery tests pass with default and
MSHV-only GDB features. All seven real GDB client tests pass.
Native regressions cover resume errors, unbacked MMIO, listener setup,
bootstrap stack preservation, exception-context selection and MMIO stepping.
Debug and release Rust and C guest builds pass on the MSHV VM.
Windows x64 standard and GDB-enabled Clippy, WHP ARM64 cross-Clippy and Linux
just clippyw pass.
Linux x64 and ARM64 GDB-enabled Clippy pass. ARM64 checks cover default and
KVM-only features.
Native WHP and KVM runtime tests were not repeated for these shared fixes.

Copilot

🟡 Changes recommended

Resume translation errors can terminate the debugger session, and partially successful code writes can return without synchronizing the guest instruction cache.

2 open issues

What changed in this PR

This PR provides shared ARM64 debugger infrastructure for Hyperlight’s WHP, KVM and MSHV backends. ARM64 platform enablement remains in separate backend PRs.

Changes:

Adds architecture-specific register handling, breakpoint support and shared debugger request processing.
Adds guest-page-sized memory access, cache synchronization hooks and snapshot recovery safeguards.
Adds debugger tests, guest exception forwarding and backend-layer documentation.

File	Description
`src/hyperlight_host/src/sandbox/uninitialized_evolve.rs`	Initializes ARM64 guest debug vectors.
`src/hyperlight_host/src/sandbox/snapshot/memory/backing.rs`	Exposes backing ranges for cache synchronization.
`src/hyperlight_host/src/sandbox/initialized.rs`	Adds breakpoint guards, recovery handling and tests.
`src/hyperlight_host/src/mem/mgr.rs`	Exposes guest backing host ranges to debugging code.
`src/hyperlight_host/src/mem/exe.rs`	Carries debug-vector addresses in load metadata.
`src/hyperlight_host/src/mem/elf.rs`	Finds and relocates guest debug-vector symbols.
`src/hyperlight_host/src/hypervisor/virtual_machine/whp/x86_64.rs`	Adopts the shared address-translation interface.
`src/hyperlight_host/src/hypervisor/virtual_machine/mshv/x86_64.rs`	Adopts the shared address-translation interface.
`src/hyperlight_host/src/hypervisor/virtual_machine/mod.rs`	Adds ARM64 debug exit and initialization types.
`src/hyperlight_host/src/hypervisor/virtual_machine/kvm/x86_64.rs`	Adopts the shared address-translation interface.
`src/hyperlight_host/src/hypervisor/hyperlight_vm/x86_64.rs`	Uses shared debugger handling and breakpoint storage.
`src/hyperlight_host/src/hypervisor/hyperlight_vm/mod.rs`	Integrates shared debug state and stop handling.
`src/hyperlight_host/src/hypervisor/hyperlight_vm/debug.rs`	Implements shared requests, breakpoints and ARM64 stepping.
`src/hyperlight_host/src/hypervisor/hyperlight_vm/aarch64.rs`	Adds debugger initialization and reset hooks.
`src/hyperlight_host/src/hypervisor/gdb/target.rs`	Supports ARM64 register packets and conversion tests.
`src/hyperlight_host/src/hypervisor/gdb/mod.rs`	Adds page-table translation and cache synchronization hooks.
`src/hyperlight_host/src/hypervisor/gdb/event_loop.rs`	Handles ARM64 initial-stop notifications.
`src/hyperlight_host/src/hypervisor/gdb/arch/x86_64.rs`	Contains x86_64 breakpoint and stop classification logic.
`src/hyperlight_host/src/hypervisor/gdb/arch/aarch64.rs`	Defines ARM64 BRK encoding and alignment checks.
`src/hyperlight_host/src/hypervisor/gdb/arch.rs`	Selects the architecture-specific debugger adapter.
`src/hyperlight_host/examples/guest-debugging/main.rs`	Adds ARM64 GDB client scenarios.
`src/hyperlight_guest_bin/src/arch/aarch64/exception/entry.rs`	Exports debug vectors and forwards synchronous exceptions.
`src/hyperlight_common/src/arch/aarch64/exn.rs`	Defines the debug exception HVC immediate.
`Justfile`	Includes shared debugger and recovery test filters.
`docs/gdb-commit-layers.md`	Documents backend dependencies and validation requirements.
`CHANGELOG.md`	Records debugger memory-access and recovery fixes.

_{Review effort: Balanced}

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>

hyperlight-gh-bot · 2026-11-12T20:40:55Z

Benchmark Results

Measured commit: 7d01a90e9317
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`	`761.92 ns` (➖ 1.02x faster)
`vec_bytes`	`592.03 ns` (➖ 1.01x faster)
		`372.26 µs` (➖ 1.00x faster)

payload_allocation

	`slot_pool_segmented`
`262144`	`527.25 ns` (➖ 1.01x faster)
`65536`	`141.52 ns` (➖ 1.02x faster)

sandboxes

	`create_initialized_and_drop`
`medium`	`13.12 ms` (➖ 1.07x faster)

slot_pool

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

snapshot_files

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

virtq_readonly

	`slot_pool_segmented`	`slot_pool_segmented_fragmented`
`262144`	`7.06 µs` (➖ 1.00x slower)	`7.16 µs` (➖ 1.01x slower)
`65536`	`1.91 µs` (➖ 1.09x faster)	`2.02 µs` (➖ 1.06x slower)

virtq_readwrite

	`slot_pool_segmented`	`slot_pool_segmented_fragmented`
`262144`	`27.01 µs` (➖ 1.00x faster)
`65536`	`6.25 µs` (➖ 1.00x slower)	`6.24 µs` (➖ 1.01x faster)
`8192`	`1.01 µs` (➖ 1.04x faster)	`1.10 µs` (➖ 1.09x slower)

kvm / intel (Linux) (➖ stable)

No benchmark improved or regressed.

Benchmark Results

function_call_codec

	`encode_control`	`decode_vec_bytes_copy`
`byte_chunks`	`701.05 ns` (➖ 1.04x slower)
`vec_bytes`	`521.09 ns` (➖ 1.01x slower)
		`677.13 µs` (➖ 1.04x slower)

payload_allocation

	`slot_pool_segmented`
`262144`	`501.41 ns` (➖ 1.01x slower)
`65536`	`171.42 ns` (➖ 1.01x faster)

sandboxes

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

slot_pool

	`alloc_dealloc_128`	`alloc_dealloc_4096`	`alloc_dealloc_1500`
	`6.78 ns` (➖ 1.00x slower)	`6.80 ns` (➖ 1.00x slower)	`6.78 ns` (➖ 1.00x faster)

snapshot_files

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

virtq_readonly

	`slot_pool_segmented`	`slot_pool_segmented_fragmented`
`262144`	`7.58 µs` (➖ 1.01x slower)	`7.48 µs` (➖ 1.00x slower)
`65536`	`2.12 µs` (➖ 1.00x slower)	`2.11 µs` (➖ 1.01x faster)

virtq_readwrite

	`slot_pool_segmented`	`slot_pool_segmented_fragmented`
`262144`	`30.68 µs` (➖ 1.05x slower)
`65536`	`6.97 µs` (➖ 1.01x faster)	`7.00 µs` (➖ 1.01x faster)
`8192`	`708.66 ns` (➖ 1.00x faster)	`722.53 ns` (➖ 1.01x faster)

mshv3 / amd (Linux) (➖ stable)

No benchmark improved or regressed.

Benchmark Results

function_call_codec

	`encode_control`	`decode_vec_bytes_copy`
`byte_chunks`	`944.80 ns` (➖ 1.01x faster)
`vec_bytes`	`712.92 ns` (➖ 1.01x slower)
		`318.14 µs` (➖ 1.00x faster)

payload_allocation

	`slot_pool_segmented`
`262144`	`675.68 ns` (➖ 1.01x slower)
`65536`	`187.70 ns` (➖ 1.03x slower)

sandboxes

	`create_initialized_and_drop`
`medium`	`65.80 ms` (➖ 1.02x faster)

slot_pool

	`alloc_dealloc_128`	`alloc_dealloc_4096`	`alloc_dealloc_1500`
	`9.88 ns` (➖ 1.00x faster)	`9.87 ns` (➖ 1.00x faster)	`9.90 ns` (➖ 1.00x slower)

snapshot_files

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

virtq_readonly

	`slot_pool_segmented`	`slot_pool_segmented_fragmented`
`262144`	`9.32 µs` (➖ 1.00x slower)	`9.01 µs` (➖ 1.04x faster)
`65536`	`2.47 µs` (➖ 1.02x faster)	`2.60 µs` (➖ 1.03x faster)

virtq_readwrite

	`slot_pool_segmented`	`slot_pool_segmented_fragmented`
`262144`	`34.41 µs` (➖ 1.03x faster)
`65536`	`7.99 µs` (➖ 1.02x faster)	`9.11 µs` (➖ 1.12x slower)
`8192`	`1.26 µs` (➖ 1.03x faster)	`1.32 µs` (➖ 1.03x slower)

mshv3 / intel (Linux) (➖ stable)

No benchmark improved or regressed.

Benchmark Results

function_call_codec

	`encode_control`	`decode_vec_bytes_copy`
`byte_chunks`	`978.20 ns` (➖ 1.05x slower)
`vec_bytes`	`663.98 ns` (➖ 1.00x slower)
		`687.98 µs` (➖ 1.04x slower)

payload_allocation

	`slot_pool_segmented`
`262144`	`667.81 ns` (➖ 1.01x slower)
`65536`	`253.04 ns` (➖ 1.04x faster)

sandboxes

	`create_initialized_and_drop`
`medium`	`72.44 ms` (➖ 1.02x faster)

slot_pool

	`alloc_dealloc_128`	`alloc_dealloc_4096`	`alloc_dealloc_1500`
	`8.75 ns` (➖ 1.00x slower)	`8.70 ns` (➖ 1.01x faster)	`8.70 ns` (➖ 1.00x slower)

snapshot_files

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

virtq_readonly

	`slot_pool_segmented`	`slot_pool_segmented_fragmented`
`262144`	`8.04 µs` (➖ 1.02x slower)	`8.04 µs` (➖ 1.00x slower)
`65536`	`2.33 µs` (➖ 1.03x slower)	`2.28 µs` (➖ 1.01x slower)

virtq_readwrite

	`slot_pool_segmented`	`slot_pool_segmented_fragmented`
`262144`	`39.07 µs` (➖ 1.02x slower)
`65536`	`7.43 µs` (➖ 1.01x faster)	`7.48 µs` (➖ 1.00x faster)
`8192`	`909.89 ns` (➖ 1.01x faster)	`910.56 ns` (➖ 1.01x faster)

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.00x faster)
`vec_bytes`	`781.98 ns` (➖ 1.02x faster)
		`1.95 ms` (➖ 1.03x faster)

payload_allocation

	`slot_pool_segmented`
`262144`	`788.14 ns` (➖ 1.00x slower)
`65536`	`229.82 ns` (➖ 1.01x faster)

sandboxes

	`create_initialized_and_drop`
`medium`	`11.81 ms` (➖ 1.06x faster)

slot_pool

	`alloc_dealloc_128`	`alloc_dealloc_4096`	`alloc_dealloc_1500`
	`10.98 ns` (➖ 1.10x slower)	`9.99 ns` (➖ 1.00x slower)	`9.92 ns` (➖ 1.00x faster)

snapshot_files

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

virtq_readonly

	`slot_pool_segmented`	`slot_pool_segmented_fragmented`
`262144`	`9.10 µs` (➖ 1.02x faster)	`9.29 µs` (➖ 1.00x slower)
`65536`	`2.35 µs` (➖ 1.00x slower)	`2.33 µs` (➖ 1.01x faster)

virtq_readwrite

	`slot_pool_segmented`	`slot_pool_segmented_fragmented`
`262144`	`39.06 µs` (➖ 1.13x faster)
`65536`	`9.24 µs` (➖ 1.01x slower)	`9.19 µs` (➖ 1.04x faster)
`8192`	`1.28 µs` (➖ 1.03x slower)	`1.30 µs` (➖ 1.05x slower)

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

No benchmark improved or regressed.

Benchmark Results

function_call_codec

	`encode_control`	`decode_vec_bytes_copy`
`byte_chunks`	`1.25 µs` (➖ 1.01x faster)
`vec_bytes`	`784.76 ns` (➖ 1.01x faster)
		`3.14 ms` (➖ 1.01x faster)

payload_allocation

	`slot_pool_segmented`
`262144`	`745.15 ns` (➖ 1.05x faster)
`65536`	`211.27 ns` (➖ 1.01x slower)

sandboxes

	`create_initialized_and_drop`
`medium`	`14.62 ms` (➖ 1.05x slower)

slot_pool

	`alloc_dealloc_128`	`alloc_dealloc_4096`	`alloc_dealloc_1500`
	`9.75 ns` (➖ 1.00x slower)	`10.05 ns` (➖ 1.03x faster)	`9.88 ns` (➖ 1.02x slower)

snapshot_files

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

virtq_readonly

	`slot_pool_segmented`	`slot_pool_segmented_fragmented`
`262144`	`7.72 µs` (➖ 1.01x slower)	`7.68 µs` (➖ 1.00x faster)
`65536`	`2.33 µs` (➖ 1.01x slower)	`2.32 µs` (➖ 1.01x slower)

virtq_readwrite

	`slot_pool_segmented`	`slot_pool_segmented_fragmented`
`262144`	`41.07 µs` (➖ 1.01x faster)
`65536`	`8.47 µs` (➖ 1.01x slower)	`8.35 µs` (➖ 1.00x faster)
`8192`	`1.07 µs` (➖ 1.10x faster)	`1.09 µs` (➖ 1.02x slower)

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

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

cshung requested review from andreiltd, danbugs, dblnz, devigned, jprendes, jsturtevant, ludfjig, simongdavies, squillace and syntactically as code owners November 11, 2026 20:03

Copilot AI balanced review requested due to automatic review settings November 11, 2026 20:03

Copilot started reviewing on behalf of cshung November 11, 2026 20:07

View session

This was referenced Nov 11, 2026

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

Open

feat(aarch64): add GDB debugging for Windows ARM64 WHP #1907

Open

Copilot AI reviewed Nov 11, 2026

View reviewed changes

Comment thread src/hyperlight_host/src/hypervisor/hyperlight_vm/debug.rs Resolved

Comment thread src/hyperlight_host/src/hypervisor/hyperlight_vm/debug.rs Resolved

cshung mentioned this pull request Nov 11, 2026

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

Open

cshung added the S-needs-review PR is ready for (re-)review label Nov 11, 2026

cshung force-pushed the cshung/gdb-shared branch 2 times, most recently from a1e7706 to 1790d3c Compare November 12, 2026 00:12

This comment has been minimized.

Sign in to view

cshung force-pushed the cshung/gdb-shared branch from 1790d3c to 7d01a90 Compare November 12, 2026 18:15

Conversation

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

Uh oh!

Shared GDB support

Commit layers

Validation

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

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!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

cshung commented Nov 11, 2026 •

edited

Loading