feat(aarch64): add GDB debugging for Windows WHP

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>

Author: cshung

CHANGELOG.md

@@ -6,11 +6,13 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ### Added
 * Add `Sandbox::recreate()`, which rebuilds a sandbox's VM and memory from a snapshot. It recovers unrecoverable sandboxes and keeps configuration, host functions, and interrupt handles by @ludfjig in https://github.com/hyperlight-dev/hyperlight/pull/1751
+* Windows ARM64 WHP guest debugging supports software and hardware breakpoints, register and memory access, and hardware single-step.
 
 ### Fixed
 * Fix restore on WHP not rewinding the guest TSC on hosts with `TSC_ADJUST` support.
 * GDB memory reads and writes translate each guest page on hosts with larger pages.
 * ARM64 GDB snapshot recovery handles cancellation and crash detach. Snapshot checkpointing rejects software breakpoints before replacing memory.
+* WHP ARM64 cache synchronization code is read-only to guests.
 
 ## [v0.19.0] - 2026-11-04
 

Justfile

@@ -335,7 +335,7 @@ test-no-surrogate target=default-target:
 # runs tests that exercise gdb debugging
 test-rust-gdb-debugging target=default-target features="":
     {{ cargo-cmd }} test --profile={{ if target == "debug" { "dev" } else { target } }}  {{ target-triple-flag }} --example guest-debugging {{ if features =="" {'--features gdb'} else { "--features gdb," + features } }}
-    {{ cargo-cmd }} test --profile={{ if target == "debug" { "dev" } else { target } }}  {{ target-triple-flag }} -p hyperlight-host --lib {{ if features =="" {'--features gdb'} else { "--features gdb," + features } }} -- hypervisor::gdb:: hypervisor::hyperlight_vm::debug::tests:: gdb_recovery_tests::
+    {{ cargo-cmd }} test --profile={{ if target == "debug" { "dev" } else { target } }}  {{ target-triple-flag }} -p hyperlight-host --lib {{ if features =="" {'--features gdb'} else { "--features gdb," + features } }} -- hypervisor::gdb:: hypervisor::hyperlight_vm::debug::tests:: gdb_recovery_tests:: hypervisor::virtual_machine::whp::aarch64::debug_tests::
 
 # rust test for crashdump
 test-rust-crashdump target=default-target features="":

docs/how-to-debug-a-hyperlight-guest.md

@@ -7,15 +7,26 @@ to start listening for a gdb connection.
 ## Supported features
 
 The Hyperlight `gdb` feature enables guest debugging to:
-   - stop at an entry point breakpoint which is automatically set by Hyperlight
-   - add and remove HW breakpoints (maximum 4 set breakpoints at a time)
+   - stop at the entry point
    - add and remove SW breakpoints
    - read and write registers
    - read and write addresses
-   - step/continue
+   - continue
+   - single-step
    - get code offset from target
    - stop when a crash occurs and only allow read access to the guest memory and registers
 
+On x86_64, gdb supports up to four hardware breakpoints.
+Windows ARM64 WHP supports two hardware breakpoints, four-byte `BRK` software
+breakpoints, and hardware single-step. Guest exception vectors forward debug
+exceptions through HVC. Guest binaries must retain the
+`hyperlight_debug_vectors` symbol so the host can install these vectors before
+the initial debug stop. Watchpoints are not advertised.
+
+ARM64 snapshots reject installed software breakpoints, including those added
+during checkpointing. Restoring a poisoned sandbox discards its software
+breakpoint state and restores clean snapshot memory.
+
 ## Expected behavior
 
 Below is a list describing some cases of expected behavior from a gdb debug 

src/hyperlight_host/build.rs

@@ -151,7 +151,8 @@ fn main() -> Result<()> {
     // Essentially the kvm and mshv3 features are ignored on windows as long as you use #[cfg(kvm)] and not #[cfg(feature = "kvm")].
     // You should never use #[cfg(feature = "kvm")] or #[cfg(feature = "mshv3")] in the codebase.
     cfg_aliases::cfg_aliases! {
-        gdb: { all(feature = "gdb", debug_assertions, target_arch = "x86_64") },
+        gdb_platform: { any(target_arch = "x86_64", all(target_arch = "aarch64", target_os = "windows")) },
+        gdb: { all(feature = "gdb", debug_assertions, gdb_platform) },
         kvm: { all(feature = "kvm", target_os = "linux") },
         mshv3: { all(feature = "mshv3", target_os = "linux") },
         hvf: { all(feature = "hvf", target_os = "macos") },

src/hyperlight_host/src/hypervisor/hyperlight_vm/mod.rs

@@ -492,6 +492,23 @@ impl HyperlightVm {
             }
         }
 
+        // Check against the hidden debug cache-sync page
+        #[cfg(all(gdb, target_arch = "aarch64", target_os = "windows"))]
+        {
+            use crate::hypervisor::virtual_machine::whp::DEBUG_CACHE_SYNC_GPA;
+
+            let reserved_start = DEBUG_CACHE_SYNC_GPA as usize;
+            let reserved_end = reserved_start + self.page_size;
+            if new_start < reserved_end && new_end > reserved_start {
+                return Err(MapRegionError::Overlapping {
+                    new_start,
+                    new_end,
+                    existing_start: reserved_start,
+                    existing_end: reserved_end,
+                });
+            }
+        }
+
         // Try to reuse a freed slot first, otherwise use next_slot
         let slot = self.allocate_slot();
 

src/hyperlight_host/src/hypervisor/regs/aarch64/whp_reg.rs

@@ -31,6 +31,18 @@ pub(crate) const WHV_ARM64_REGISTER_MAIR_EL1: WHV_REGISTER_NAME = WHV_REGISTER_N
 pub(crate) const WHV_ARM64_REGISTER_VBAR_EL1: WHV_REGISTER_NAME = WHV_REGISTER_NAME(0x0004000C);
 pub(crate) const WHV_ARM64_REGISTER_FPCR: WHV_REGISTER_NAME = WHV_REGISTER_NAME(0x00040012);
 pub(crate) const WHV_ARM64_REGISTER_FPSR: WHV_REGISTER_NAME = WHV_REGISTER_NAME(0x00040013);
+#[cfg(gdb)]
+pub(crate) const WHV_ARM64_REGISTER_SPSR_EL1: WHV_REGISTER_NAME = WHV_REGISTER_NAME(0x00040014);
+#[cfg(gdb)]
+pub(crate) const WHV_ARM64_REGISTER_ELR_EL1: WHV_REGISTER_NAME = WHV_REGISTER_NAME(0x00040015);
+#[cfg(gdb)]
+pub(crate) const WHV_ARM64_REGISTER_ESR_EL1: WHV_REGISTER_NAME = WHV_REGISTER_NAME(0x00040008);
+#[cfg(gdb)]
+pub(crate) const WHV_ARM64_REGISTER_MDSCR_EL1: WHV_REGISTER_NAME = WHV_REGISTER_NAME(0x0005004D);
+#[cfg(gdb)]
+pub(crate) const WHV_ARM64_REGISTER_DBGBCR0_EL1: WHV_REGISTER_NAME = WHV_REGISTER_NAME(0x00050000);
+#[cfg(gdb)]
+pub(crate) const WHV_ARM64_REGISTER_DBGBVR0_EL1: WHV_REGISTER_NAME = WHV_REGISTER_NAME(0x00050020);
 pub(crate) const WHV_ARM64_REGISTER_GICR_BASE_GPA: WHV_REGISTER_NAME =
     WHV_REGISTER_NAME(0x00063000);