feat: add hardware interrupt support (PIC, KVM IRQ chip, MSHV SynIC, WHP software timer)

.github/workflows/dep_build_test.yml

@@ -105,6 +105,11 @@ jobs:
           # with only one driver enabled (kvm/mshv3 features are unix-only, no-op on Windows)
           just test ${{ inputs.config }} ${{ inputs.hypervisor == 'mshv3' && 'mshv3' || 'kvm' }}
 
+      - name: Run Rust tests with hw-interrupts
+        run: |
+          # with hw-interrupts feature enabled (+ explicit driver on Linux)
+          just test ${{ inputs.config }} ${{ runner.os == 'Linux' && (inputs.hypervisor == 'mshv3' && 'mshv3,hw-interrupts' || 'kvm,hw-interrupts') || 'hw-interrupts' }}
+
       - name: Run Rust Gdb tests
         env:
           RUST_LOG: debug

Justfile

@@ -87,6 +87,9 @@ test-like-ci config=default-target hypervisor="kvm":
     @# with only one driver enabled + build-metadata
     just test {{config}} build-metadata,{{ if hypervisor == "mshv3" {"mshv3"} else {"kvm"} }}
 
+    @# with hw-interrupts enabled (+ explicit driver on Linux)
+    {{ if os() == "linux" { if hypervisor == "mshv3" { "just test " + config + " mshv3,hw-interrupts" } else { "just test " + config + " kvm,hw-interrupts" } } else { "just test " + config + " hw-interrupts" } }}
+
     @# make sure certain cargo features compile
     just check
 
@@ -151,6 +154,9 @@ build-test-like-ci config=default-target hypervisor="kvm":
     @# Run Rust tests with single driver
     {{ if os() == "linux" { "just test " + config+ " " + if hypervisor == "mshv3" { "mshv3" } else { "kvm" } } else { "" } }}
 
+    @# Run Rust tests with hw-interrupts
+    {{ if os() == "linux" { if hypervisor == "mshv3" { "just test " + config + " mshv3,hw-interrupts" } else { "just test " + config + " kvm,hw-interrupts" } } else { "just test " + config + " hw-interrupts" } }}
+
     @# Run Rust Gdb tests
     just test-rust-gdb-debugging {{config}}
 
@@ -286,6 +292,7 @@ check:
     {{ cargo-cmd }} check -p hyperlight-host --features trace_guest,mem_profile  {{ target-triple-flag }}
     {{ cargo-cmd }} check -p hyperlight-host --features nanvix-unstable  {{ target-triple-flag }}
     {{ cargo-cmd }} check -p hyperlight-host --features nanvix-unstable,executable_heap  {{ target-triple-flag }}
+    {{ cargo-cmd }} check -p hyperlight-host --features hw-interrupts  {{ target-triple-flag }}
 
 fmt-check: (ensure-nightly-fmt)
     cargo +nightly fmt --all -- --check

src/hyperlight_common/src/outb.rs

@@ -86,6 +86,7 @@ impl TryFrom<u8> for Exception {
 }
 
 /// Supported actions when issuing an OUTB actions by Hyperlight.
+/// These are handled by the sandbox-level outb dispatcher.
 /// - Log: for logging,
 /// - CallFunction: makes a call to a host function,
 /// - Abort: aborts the execution of the guest,
@@ -106,6 +107,22 @@ pub enum OutBAction {
     TraceMemoryFree = 106,
 }
 
+/// IO-port actions intercepted at the hypervisor level (in `run_vcpu`)
+/// before they ever reach the sandbox outb handler.  These are split
+/// from [`OutBAction`] so the outb handler does not need unreachable
+/// match arms for ports it can never see.
+pub enum VmAction {
+    /// IO port for PV timer configuration. The guest writes a 32-bit
+    /// LE value representing the desired timer period in microseconds.
+    /// A value of 0 disables the timer.
+    PvTimerConfig = 107,
+    /// IO port the guest writes to signal "I'm done" to the host.
+    /// This replaces the `hlt` instruction for halt signaling so that
+    /// KVM's in-kernel LAPIC (which absorbs HLT exits) does not interfere
+    /// with hyperlight's halt-based guest-host protocol.
+    Halt = 108,
+}
+
 impl TryFrom<u16> for OutBAction {
     type Error = anyhow::Error;
     fn try_from(val: u16) -> anyhow::Result<Self> {
@@ -124,3 +141,14 @@ impl TryFrom<u16> for OutBAction {
         }
     }
 }
+
+impl TryFrom<u16> for VmAction {
+    type Error = anyhow::Error;
+    fn try_from(val: u16) -> anyhow::Result<Self> {
+        match val {
+            107 => Ok(VmAction::PvTimerConfig),
+            108 => Ok(VmAction::Halt),
+            _ => Err(anyhow::anyhow!("Invalid VmAction value: {}", val)),
+        }
+    }
+}

src/hyperlight_guest_bin/src/arch/amd64/dispatch.rs

@@ -68,6 +68,9 @@ core::arch::global_asm!("
     mov cr4, rdi
     flush_done:
     call {internal_dispatch_function}\n
+    mov dx, 108\n
+    out dx, eax\n
+    cli\n
     hlt\n
     .cfi_endproc
 ", internal_dispatch_function = sym crate::guest_function::call::internal_dispatch_function);

src/hyperlight_guest_bin/src/arch/amd64/init.rs

@@ -173,6 +173,9 @@ core::arch::global_asm!("
     mov rsp, r8\n
     xor ebp, ebp\n
     call {generic_init}\n
+    mov dx, 108\n
+    out dx, eax\n
+    cli\n
     hlt\n
     .cfi_endproc\n
 ", generic_init = sym crate::generic_init);

src/hyperlight_host/Cargo.toml

@@ -133,6 +133,7 @@ trace_guest = ["dep:opentelemetry", "dep:tracing-opentelemetry", "dep:hyperlight
 mem_profile = [ "trace_guest", "dep:framehop", "dep:fallible-iterator", "hyperlight-common/mem_profile" ]
 kvm = ["dep:kvm-bindings", "dep:kvm-ioctls"]
 mshv3 = ["dep:mshv-bindings", "dep:mshv-ioctls"]
+hw-interrupts = []
 # This enables easy debug in the guest
 gdb = ["dep:gdbstub", "dep:gdbstub_arch"]
 fuzzing = ["hyperlight-common/fuzzing"]

src/hyperlight_host/src/hypervisor/hyperlight_vm/x86_64.rs

@@ -1550,6 +1550,7 @@ mod tests {
     // Tests
     // ==========================================================================
 
+    #[cfg_attr(feature = "hw-interrupts", ignore)]
     #[test]
     fn reset_vcpu_simple() {
         // push rax; hlt - aligns stack to 16 bytes
@@ -1695,6 +1696,7 @@ mod tests {
 
         use super::*;
 
+        #[cfg_attr(feature = "hw-interrupts", ignore)]
         #[test]
         fn reset_vcpu_regs() {
             let mut a = CodeAssembler::new(64).unwrap();
@@ -1754,6 +1756,7 @@ mod tests {
             assert_regs_reset(hyperlight_vm.vm.as_ref());
         }
 
+        #[cfg_attr(feature = "hw-interrupts", ignore)]
         #[test]
         fn reset_vcpu_fpu() {
             #[cfg(kvm)]
@@ -1885,6 +1888,7 @@ mod tests {
             }
         }
 
+        #[cfg_attr(feature = "hw-interrupts", ignore)]
         #[test]
         fn reset_vcpu_debug_regs() {
             let mut a = CodeAssembler::new(64).unwrap();
@@ -1927,6 +1931,7 @@ mod tests {
             assert_debug_regs_reset(hyperlight_vm.vm.as_ref());
         }
 
+        #[cfg_attr(feature = "hw-interrupts", ignore)]
         #[test]
         fn reset_vcpu_sregs() {
             // Build code that modifies special registers and halts
@@ -1980,6 +1985,7 @@ mod tests {
 
         /// Verifies guest-visible FPU state (via FXSAVE) is properly reset.
         /// Unlike tests using hypervisor API, this runs actual guest code with FXSAVE.
+        #[cfg_attr(feature = "hw-interrupts", ignore)]
         #[test]
         fn reset_vcpu_fpu_guest_visible_state() {
             let mut ctx = hyperlight_vm_with_mem_mgr_fxsave();

src/hyperlight_host/src/hypervisor/mod.rs

@@ -469,6 +469,7 @@ pub(crate) mod tests {
     use crate::sandbox::{SandboxConfiguration, UninitializedSandbox};
     use crate::{Result, is_hypervisor_present, new_error};
 
+    #[cfg_attr(feature = "hw-interrupts", ignore)]
     #[test]
     fn test_initialise() -> Result<()> {
         if !is_hypervisor_present() {