feat(aarch64): add GDB debugging for Linux MSHV

MSHV forwards guest debug exceptions through intercepted HVCs. Register access uses the saved exception context and active stack pointer. Two hardware breakpoints and single-step survive replacement-VM reset. Native ARM64 GDB tests run in debug CI. Non-debug KVM use is available with default features.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Signed-off-by: cshung <3410332+cshung@users.noreply.github.com>

Author: cshung

.github/workflows/dep_build_test.yml

@@ -229,6 +229,16 @@ jobs:
           RUST_LOG: debug
         run: just test-rust-gdb-debugging ${{ inputs.config }}
 
+      - name: Run ARM64 MSHV Gdb tests
+        if: inputs.arch == 'arm64' && inputs.hypervisor == 'mshv3' && inputs.config == 'debug'
+        env:
+          RUST_LOG: debug
+        run: |
+          if ! command -v gdb > /dev/null 2>&1; then
+            sudo tdnf install -y gdb
+          fi
+          just test-rust-gdb-debugging debug mshv3
+
       - name: Run Rust Crashdump tests
         if: inputs.arch == 'X64'
         env:

CHANGELOG.md

@@ -6,6 +6,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ### Added
 * ARM64 Linux guests can run on MSHV.
+* ARM64 Linux/MSHV guest debugging supports software and hardware breakpoints, register and memory access, and hardware single-step.
 
 ### Fixed
 * GDB memory reads and writes translate each guest page on hosts with larger pages.

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::mshv::aarch64::
 
 # 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.
+ARM64 Linux/MSHV 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 = "linux", feature = "mshv3")) },
+        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/virtual_machine/kvm/aarch64.rs

@@ -12,6 +12,8 @@ use kvm_bindings::{
 use kvm_ioctls::{Kvm, VcpuExit, VcpuFd, VmFd};
 use tracing::{Span, instrument};
 
+#[cfg(gdb)]
+use crate::hypervisor::gdb::{DebugError, DebugMemoryView, DebuggableVm};
 use crate::hypervisor::regs::{CommonFpu, CommonRegisters, CommonSpecialRegisters};
 use crate::hypervisor::virtual_machine::{
     CreateVmError, HypervisorError, MapMemoryError, RegisterError, ResetVcpuError, RunVcpuError,
@@ -21,6 +23,21 @@ use crate::hypervisor::virtual_machine::{
 static KVM: LazyLock<std::result::Result<Kvm, CreateVmError>> =
     LazyLock::new(|| Kvm::new().map_err(|e| CreateVmError::HypervisorNotAvailable(e.into())));
 
+#[cfg(gdb)]
+impl DebuggableVm for KvmVm {
+    fn translate_gva(&self, _gva: u64, _memory: &DebugMemoryView<'_>) -> Result<u64, DebugError> {
+        Err(DebugError::Unsupported("ARM64 KVM debugging"))
+    }
+
+    fn set_debug(&mut self, enable: bool) -> Result<(), DebugError> {
+        if enable {
+            Err(DebugError::Unsupported("ARM64 KVM debugging"))
+        } else {
+            Ok(())
+        }
+    }
+}
+
 /// Return `true` if the KVM API is available
 #[instrument(skip_all, parent = Span::current(), level = "Trace")]
 pub(crate) fn is_hypervisor_present() -> bool {