virt: add irqfd trait and implement for mshv and KVM

Add irqfd support enabling the kernel to inject MSIs directly into the
guest when an eventfd is signaled, without a userspace transition. This
is required for VFIO device passthrough where physical device interrupts
must be delivered to the guest via the hypervisor's irqfd mechanism.

New traits in virt crate:
- IrqFd: allocates GSIs and registers eventfds as irqfd routes
- IrqFdRoute: updates/clears MSI routing (address/data) per GSI
- Partition::irqfd(): returns the irqfd interface if supported

mshv implementation (virt_mshv/src/irqfd.rs):
- GSI allocation table (2048 slots)
- MSHV_IRQFD ioctl for register/unregister eventfds
- MSHV_SET_MSI_ROUTING ioctl to push full routing table
- Automatic cleanup on route drop (unregister + free GSI)
- VmFd changed to Arc<VmFd> for shared ownership

KVM implementation (virt_kvm/src/gsi.rs):
- KvmIrqFdState wraps existing GsiRoute infrastructure
- KvmIrqFdRoute delegates to GsiRoute::enable/disable
- Partition::irqfd() wired in x86_64 arch module

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

Author: will-j-wright

Cargo.lock

@@ -8916,6 +8916,7 @@ dependencies = [
  "arrayvec",
  "build_rs_guest_arch",
  "guestmem",
+ "headervec",
  "hv1_emulator",
  "hv1_hypercall",
  "hvdef",

vmm_core/virt/src/generic.rs

@@ -12,6 +12,7 @@ use crate::io::CpuIo;
 use crate::irqcon::ControlGic;
 use crate::irqcon::IoApicRouting;
 use crate::irqcon::MsiRequest;
+use crate::irqfd::IrqFd;
 use crate::x86::DebugState;
 use crate::x86::HardwareBreakpoint;
 use guestmem::DoorbellRegistration;
@@ -295,6 +296,17 @@ pub trait Partition: 'static + Hv1 + Inspect + Send + Sync {
         None
     }
 
+    /// Returns an irqfd routing interface for this partition.
+    ///
+    /// irqfd allows the kernel to inject MSIs directly into the guest when an
+    /// eventfd is signaled, without a userspace transition. This is used for
+    /// device passthrough with VFIO.
+    ///
+    /// Not all partitions support this.
+    fn irqfd(&self) -> Option<Arc<dyn IrqFd>> {
+        None
+    }
+
     /// Get the partition capabilities for this partition.
     fn caps(&self) -> &PartitionCapabilities;
 

vmm_core/virt/src/irqfd.rs

@@ -0,0 +1,85 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+//! Traits for irqfd-based interrupt delivery.
+//!
+//! irqfd allows a hypervisor to directly inject an MSI into a guest when an
+//! event is signaled, without involving userspace in the interrupt delivery
+//! path. This is used for device passthrough (e.g., VFIO) where the physical
+//! device signals an event and the hypervisor injects the corresponding MSI
+//! into the guest VM.
+
+use pal_event::Event;
+
+/// Trait for partitions that support irqfd-based interrupt delivery.
+///
+/// An irqfd associates an event with a GSI (Global System Interrupt), and a
+/// GSI routing table maps GSIs to MSI addresses and data values. When the
+/// event is signaled, the kernel looks up the GSI routing and injects the
+/// configured MSI into the guest without a usermode transition.
+pub trait IrqFd: Send + Sync {
+    /// Creates a new irqfd route.
+    ///
+    /// Allocates a GSI, creates an event, and registers the event with the
+    /// hypervisor so that signaling it injects the configured MSI into the
+    /// guest.
+    ///
+    /// The caller retrieves the event via [`IrqFdRoute::event`] to pass to
+    /// VFIO or other interrupt sources.
+    ///
+    /// When the route is dropped, the irqfd is unregistered and the GSI is
+    /// freed.
+    fn new_irqfd_route(&self) -> anyhow::Result<Box<dyn IrqFdRoute>>;
+}
+
+/// A handle to a registered irqfd route.
+///
+/// Each route represents a single GSI with an associated event. When the
+/// event is signaled (e.g., by VFIO on a device interrupt), the kernel injects
+/// the MSI configured via [`set_msi`](IrqFdRoute::set_msi) into the guest.
+///
+/// Dropping this handle unregisters the irqfd and frees the GSI.
+pub trait IrqFdRoute: Send + Sync {
+    /// Returns the event that triggers interrupt injection when signaled.
+    ///
+    /// Pass this to VFIO `map_msix` or any other interrupt source. On Linux,
+    /// this is an eventfd created by the implementation. On WHP (future), this
+    /// is the event handle returned by `WHvCreateTrigger`.
+    fn event(&self) -> &Event;
+
+    /// Sets the MSI routing for this irqfd's GSI.
+    ///
+    /// `address` and `data` are the x86 MSI address and data values that the
+    /// kernel will use when injecting the interrupt into the guest.
+    fn set_msi(&self, address: u64, data: u32) -> anyhow::Result<()>;
+
+    /// Clears the MSI routing for this irqfd's GSI.
+    ///
+    /// The irqfd remains registered but interrupt delivery is disabled until
+    /// a new route is configured via [`set_msi`](IrqFdRoute::set_msi).
+    fn clear_msi(&self) -> anyhow::Result<()>;
+
+    /// Masks the route.
+    ///
+    /// While masked, interrupts arriving on the event are not injected into
+    /// the guest. The caller should use [`consume_pending`](IrqFdRoute::consume_pending)
+    /// to check whether an interrupt arrived while masked and store the
+    /// result in the MSI-X PBA. On unmask, the caller should deliver any
+    /// pending interrupt from the PBA before re-enabling the route.
+    fn mask(&self) -> anyhow::Result<()>;
+
+    /// Unmasks the route and re-enables interrupt injection.
+    fn unmask(&self) -> anyhow::Result<()>;
+
+    /// Drains the pending interrupt state and returns whether an interrupt
+    /// was pending.
+    ///
+    /// This atomically reads and clears the event's counter. The caller
+    /// should store the result in the MSI-X PBA (Pending Bit Array).
+    /// Repeated calls after the first drain will return `false` until a
+    /// new interrupt arrives, so the caller must persist the pending state
+    /// externally (e.g., in the MSI-X emulator's PBA bits).
+    fn consume_pending(&self) -> bool {
+        self.event().try_wait()
+    }
+}

vmm_core/virt/src/lib.rs

@@ -8,6 +8,7 @@ mod cpuid;
 mod generic;
 pub mod io;
 pub mod irqcon;
+pub mod irqfd;
 pub mod state;
 pub mod synic;
 pub mod x86;

vmm_core/virt_kvm/src/arch/x86_64/mod.rs

@@ -438,6 +438,7 @@ impl ProtoPartition for KvmProtoPartition<'_> {
 
         let partition = KvmPartition {
             synic_ports: Arc::new(virt::synic::SynicPorts::new(partition.clone())),
+            irqfd_state: Arc::new(crate::gsi::KvmIrqFdState::new(partition.clone())),
             inner: partition,
         };
 
@@ -514,6 +515,10 @@ impl Partition for KvmPartition {
         Some(self.inner.clone())
     }
 
+    fn irqfd(&self) -> Option<Arc<dyn virt::irqfd::IrqFd>> {
+        Some(self.irqfd_state.clone())
+    }
+
     fn caps(&self) -> &virt::PartitionCapabilities {
         &self.inner.caps
     }
@@ -739,14 +744,14 @@ impl KvmProcessor<'_> {
     }
 }
 
-struct KvmMsi {
-    address_lo: u32,
-    address_hi: u32,
-    data: u32,
+pub(crate) struct KvmMsi {
+    pub(crate) address_lo: u32,
+    pub(crate) address_hi: u32,
+    pub(crate) data: u32,
 }
 
 impl KvmMsi {
-    fn new(request: MsiRequest) -> Self {
+    pub(crate) fn new(request: MsiRequest) -> Self {
         let request_address = MsiAddress::from(request.address as u32);
         let request_data = MsiData::from(request.data);
 

vmm_core/virt_kvm/src/gsi.rs

@@ -4,13 +4,16 @@
 //! Implements GSI routing management for KVM VMs.
 
 use crate::KvmPartitionInner;
+use anyhow::Context;
 use pal_event::Event;
 use parking_lot::Mutex;
 use std::os::unix::prelude::*;
 use std::sync::Arc;
 use std::sync::Weak;
 use std::sync::atomic::AtomicBool;
 use std::sync::atomic::Ordering;
+use virt::irqfd::IrqFd;
+use virt::irqfd::IrqFdRoute;
 
 const NUM_GSIS: usize = 2048;
 
@@ -80,7 +83,6 @@ impl GsiRouting {
 
 impl KvmPartitionInner {
     /// Reserves a new route, optionally with an associated irqfd event.
-    #[expect(dead_code)]
     pub(crate) fn new_route(self: &Arc<Self>, irqfd_event: Option<Event>) -> Option<GsiRoute> {
         let gsi = self.gsi_routing.lock().alloc()?;
         Some(GsiRoute {
@@ -139,7 +141,6 @@ impl GsiRoute {
     }
 
     /// Enables the route and associated irqfd.
-    #[expect(dead_code)]
     pub fn enable(&self, entry: kvm::RoutingEntry) {
         let partition = self.set_entry(Some(entry));
         let _lock = self.enable_mutex.lock();
@@ -203,3 +204,87 @@ impl GsiRoute {
         }
     }
 }
+
+/// irqfd routing interface for a KVM partition.
+///
+/// Wraps the existing [`GsiRoute`] infrastructure to implement the
+/// [`IrqFd`]/[`IrqFdRoute`] traits.
+pub struct KvmIrqFdState {
+    partition: Arc<KvmPartitionInner>,
+}
+
+impl KvmIrqFdState {
+    pub fn new(partition: Arc<KvmPartitionInner>) -> Self {
+        Self { partition }
+    }
+}
+
+impl IrqFd for KvmIrqFdState {
+    fn new_irqfd_route(&self) -> anyhow::Result<Box<dyn IrqFdRoute>> {
+        let event = Event::new();
+        let route = self
+            .partition
+            .new_route(Some(event.clone()))
+            .context("no free GSIs available for irqfd")?;
+        Ok(Box::new(KvmIrqFdRoute {
+            route,
+            event,
+            last_entry: Mutex::new(None),
+        }))
+    }
+}
+
+/// A registered irqfd route backed by a KVM [`GsiRoute`].
+///
+/// Cleanup (disable irqfd, clear route, free GSI) is handled by
+/// [`GsiRoute::drop`].
+struct KvmIrqFdRoute {
+    route: GsiRoute,
+    event: Event,
+    /// The last routing entry configured via `set_msi`, used to restore
+    /// routing on `unmask`.
+    last_entry: Mutex<Option<kvm::RoutingEntry>>,
+}
+
+impl IrqFdRoute for KvmIrqFdRoute {
+    fn event(&self) -> &Event {
+        &self.event
+    }
+
+    fn set_msi(&self, address: u64, data: u32) -> anyhow::Result<()> {
+        let crate::arch::KvmMsi {
+            address_lo,
+            address_hi,
+            data,
+        } = crate::arch::KvmMsi::new(virt::irqcon::MsiRequest { address, data });
+        let entry = kvm::RoutingEntry::Msi {
+            address_lo,
+            address_hi,
+            data,
+        };
+        *self.last_entry.lock() = Some(entry);
+        self.route.enable(entry);
+        Ok(())
+    }
+
+    fn clear_msi(&self) -> anyhow::Result<()> {
+        *self.last_entry.lock() = None;
+        self.route.disable();
+        self.route.set_entry(None);
+        Ok(())
+    }
+
+    fn mask(&self) -> anyhow::Result<()> {
+        // Disable the irqfd but preserve the last routing entry for unmask.
+        self.route.disable();
+        Ok(())
+    }
+
+    fn unmask(&self) -> anyhow::Result<()> {
+        // Re-enable the irqfd with the previously configured routing entry.
+        if let Some(entry) = *self.last_entry.lock() {
+            self.route.enable(entry);
+        }
+        Ok(())
+    }
+}

vmm_core/virt_kvm/src/lib.rs

@@ -84,6 +84,9 @@ pub struct KvmPartition {
     inner: Arc<KvmPartitionInner>,
     #[inspect(skip)]
     synic_ports: Arc<virt::synic::SynicPorts<KvmPartitionInner>>,
+    #[cfg(guest_arch = "x86_64")]
+    #[inspect(skip)]
+    irqfd_state: Arc<dyn virt::irqfd::IrqFd>,
 }
 
 #[derive(Inspect)]

vmm_core/virt_mshv/Cargo.toml

@@ -7,6 +7,7 @@ edition.workspace = true
 rust-version.workspace = true
 
 [target.'cfg(target_os = "linux")'.dependencies]
+headervec.workspace = true
 hv1_emulator.workspace = true
 hv1_hypercall.workspace = true
 hvdef.workspace = true