pci: add virtio-pci transport implementation

Add a VirtIO PCI transport implementation. When a Firecracker microVM is
launched with --enable-pci, we will create all VirtIO devices using the
PCI transport layer. Snapshotting of VirtIO PCI devices is not supported
and we will add this functionality in later commit.

Add a couple of tests that ensure that PCI configuration space is what
expected. We read common fields and make sure the BAR we allocate for
the VirtIO device is what expected.

Signed-off-by: Babis Chalios <[email protected]>

Author: bchalios

Cargo.lock

@@ -17,11 +17,13 @@ gdb = ["arrayvec", "gdbstub", "gdbstub_arch"]
 
 acpi_tables = { path = "../acpi-tables" }
 aes-gcm = { version = "0.10.1", default-features = false, features = ["aes"] }
+anyhow = "1.0.98"
 arrayvec = { version = "0.7.6", optional = true }
 aws-lc-rs = { version = "1.13.1", features = ["bindgen"] }
 base64 = "0.22.1"
 bincode = { version = "2.0.1", features = ["serde"] }
 bitflags = "2.9.1"
+byteorder = "1.5.0"
 crc64 = "2.0.0"
 derive_more = { version = "2.0.1", default-features = false, features = [
   "from",

src/vmm/Cargo.toml

@@ -169,6 +169,8 @@ pub fn build_microvm_for_boot(
 
     let mut device_manager = DeviceManager::new(event_manager, &vcpus_exit_evt, &vm)?;
 
+    let vm = Arc::new(vm);
+
     let entry_point = load_kernel(&boot_config.kernel_file, vm.guest_memory())?;
     let initrd = InitrdConfig::from_config(boot_config, vm.guest_memory())?;
 
@@ -271,7 +273,7 @@ pub fn build_microvm_for_boot(
         instance_info: instance_info.clone(),
         shutdown_exit_code: None,
         kvm,
-        vm: Arc::new(vm),
+        vm,
         uffd: None,
         vcpus_handles: Vec::new(),
         vcpus_exit_evt,
@@ -554,7 +556,7 @@ fn setup_pvtime(
 
 fn attach_entropy_device(
     device_manager: &mut DeviceManager,
-    vm: &Vm,
+    vm: &Arc<Vm>,
     cmdline: &mut LoaderKernelCmdline,
     entropy_device: &Arc<Mutex<Entropy>>,
     event_manager: &mut EventManager,
@@ -571,7 +573,7 @@ fn attach_entropy_device(
 
 fn attach_block_devices<'a, I: Iterator<Item = &'a Arc<Mutex<Block>>> + Debug>(
     device_manager: &mut DeviceManager,
-    vm: &Vm,
+    vm: &Arc<Vm>,
     cmdline: &mut LoaderKernelCmdline,
     blocks: I,
     event_manager: &mut EventManager,
@@ -600,7 +602,7 @@ fn attach_block_devices<'a, I: Iterator<Item = &'a Arc<Mutex<Block>>> + Debug>(
 
 fn attach_net_devices<'a, I: Iterator<Item = &'a Arc<Mutex<Net>>> + Debug>(
     device_manager: &mut DeviceManager,
-    vm: &Vm,
+    vm: &Arc<Vm>,
     cmdline: &mut LoaderKernelCmdline,
     net_devices: I,
     event_manager: &mut EventManager,
@@ -616,7 +618,7 @@ fn attach_net_devices<'a, I: Iterator<Item = &'a Arc<Mutex<Net>>> + Debug>(
 
 fn attach_unixsock_vsock_device(
     device_manager: &mut DeviceManager,
-    vm: &Vm,
+    vm: &Arc<Vm>,
     cmdline: &mut LoaderKernelCmdline,
     unix_vsock: &Arc<Mutex<Vsock<VsockUnixBackend>>>,
     event_manager: &mut EventManager,
@@ -629,7 +631,7 @@ fn attach_unixsock_vsock_device(
 
 fn attach_balloon_device(
     device_manager: &mut DeviceManager,
-    vm: &Vm,
+    vm: &Arc<Vm>,
     cmdline: &mut LoaderKernelCmdline,
     balloon: &Arc<Mutex<Balloon>>,
     event_manager: &mut EventManager,

src/vmm/src/builder.rs

@@ -79,6 +79,8 @@ pub enum AttachDeviceError {
     #[cfg(target_arch = "aarch64")]
     /// Error creating serial device: {0}
     CreateSerial(#[from] std::io::Error),
+    /// Error attach PCI device: {0}
+    PciTransport(#[from] PciManagerError),
 }
 
 #[derive(Debug)]
@@ -160,8 +162,10 @@ impl DeviceManager {
         })
     }
 
-    /// Attaches a VirtioDevice device to the device manager and event manager.
-    pub(crate) fn attach_virtio_device<T: 'static + VirtioDevice + MutEventSubscriber + Debug>(
+    /// Attaches an MMIO VirtioDevice device to the device manager and event manager.
+    pub(crate) fn attach_mmio_virtio_device<
+        T: 'static + VirtioDevice + MutEventSubscriber + Debug,
+    >(
         &mut self,
         vm: &Vm,
         id: String,
@@ -184,6 +188,25 @@ impl DeviceManager {
         Ok(())
     }
 
+    /// Attaches a VirtioDevice device to the device manager and event manager.
+    pub(crate) fn attach_virtio_device<T: 'static + VirtioDevice + MutEventSubscriber + Debug>(
+        &mut self,
+        vm: &Arc<Vm>,
+        id: String,
+        device: Arc<Mutex<T>>,
+        cmdline: &mut Cmdline,
+        is_vhost_user: bool,
+    ) -> Result<(), AttachDeviceError> {
+        if self.pci_devices.pci_segment.is_some() {
+            self.pci_devices
+                .attach_pci_virtio_device(vm, &self.resource_allocator, id, device)?;
+        } else {
+            self.attach_mmio_virtio_device(vm, id, device, cmdline, is_vhost_user)?;
+        }
+
+        Ok(())
+    }
+
     /// Attaches a [`BootTimer`] to the VM
     pub(crate) fn attach_boot_timer_device(
         &mut self,

src/vmm/src/device_manager/mod.rs

@@ -1,18 +1,29 @@
 // Copyright 2025 Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 
-use std::sync::Arc;
+use std::collections::HashMap;
+use std::fmt::Debug;
+use std::sync::{Arc, Mutex};
 
+use event_manager::MutEventSubscriber;
+use log::debug;
+use pci::{PciBarRegionType, PciDevice, PciDeviceError, PciRootError};
 use serde::{Deserialize, Serialize};
 use vm_device::BusError;
 
-use super::resources::ResourceAllocator;
+use crate::Vm;
+use crate::device_manager::resources::ResourceAllocator;
 use crate::devices::pci::PciSegment;
+use crate::devices::virtio::device::VirtioDevice;
+use crate::devices::virtio::transport::pci::device::{VirtioPciDevice, VirtioPciDeviceError};
+use crate::vstate::vm::InterruptError;
 
 #[derive(Debug, Default)]
 pub struct PciDevices {
     /// PCIe segment of the VMM, if PCI is enabled. We currently support a single PCIe segment.
     pub pci_segment: Option<PciSegment>,
+    /// All VirtIO PCI devices of the system
+    pub virtio_devices: HashMap<(u32, String), Arc<Mutex<VirtioPciDevice>>>,
 }
 
 #[derive(Debug, thiserror::Error, displaydoc::Display)]
@@ -21,6 +32,16 @@ pub enum PciManagerError {
     ResourceAllocation(#[from] vm_allocator::Error),
     /// Bus error: {0}
     Bus(#[from] BusError),
+    /// PCI root error: {0}
+    PciRoot(#[from] PciRootError),
+    /// MSI error: {0}
+    Msi(#[from] InterruptError),
+    /// VirtIO PCI device error: {0}
+    VirtioPciDevice(#[from] VirtioPciDeviceError),
+    /// PCI device error: {0}
+    PciDeviceError(#[from] PciDeviceError),
+    /// KVM error: {0}
+    Kvm(#[from] vmm_sys_util::errno::Error),
 }
 
 impl PciDevices {
@@ -61,6 +82,113 @@ impl PciDevices {
 
         Ok(())
     }
+
+    fn register_bars_with_bus(
+        resource_allocator: &ResourceAllocator,
+        virtio_device: &Arc<Mutex<VirtioPciDevice>>,
+    ) -> Result<(), PciManagerError> {
+        for bar in &virtio_device.lock().expect("Poisoned lock").bar_regions {
+            match bar.region_type() {
+                PciBarRegionType::IoRegion => {
+                    debug!(
+                        "Inserting I/O BAR region: {:#x}:{:#x}",
+                        bar.addr(),
+                        bar.size()
+                    );
+                    #[cfg(target_arch = "x86_64")]
+                    resource_allocator.pio_bus.insert(
+                        virtio_device.clone(),
+                        bar.addr(),
+                        bar.size(),
+                    )?;
+                    #[cfg(target_arch = "aarch64")]
+                    log::error!("pci: We do not support I/O region allocation")
+                }
+                PciBarRegionType::Memory32BitRegion | PciBarRegionType::Memory64BitRegion => {
+                    debug!(
+                        "Inserting MMIO BAR region: {:#x}:{:#x}",
+                        bar.addr(),
+                        bar.size()
+                    );
+                    resource_allocator.mmio_bus.insert(
+                        virtio_device.clone(),
+                        bar.addr(),
+                        bar.size(),
+                    )?;
+                }
+            }
+        }
+
+        Ok(())
+    }
+
+    pub(crate) fn attach_pci_virtio_device<
+        T: 'static + VirtioDevice + MutEventSubscriber + Debug,
+    >(
+        &mut self,
+        vm: &Arc<Vm>,
+        resource_allocator: &ResourceAllocator,
+        id: String,
+        device: Arc<Mutex<T>>,
+    ) -> Result<(), PciManagerError> {
+        // We should only be reaching this point if PCI is enabled
+        let pci_segment = self.pci_segment.as_ref().unwrap();
+        let pci_device_bdf = pci_segment.next_device_bdf()?;
+        debug!("Allocating BDF: {pci_device_bdf:?} for device");
+        let mem = vm.guest_memory().clone();
+
+        // Allocate one MSI vector per queue, plus one for configuration
+        let msix_num =
+            u16::try_from(device.lock().expect("Poisoned lock").queues().len() + 1).unwrap();
+
+        let msix_vectors = Arc::new(Vm::create_msix_group(
+            vm.clone(),
+            resource_allocator,
+            0,
+            msix_num,
+        )?);
+
+        // Create the transport
+        let mut virtio_device =
+            VirtioPciDevice::new(id.clone(), mem, device, msix_vectors, pci_device_bdf.into())?;
+
+        // Allocate bars
+        let mut mmio32_allocator = resource_allocator
+            .mmio32_memory
+            .lock()
+            .expect("Poisoned lock");
+        let mut mmio64_allocator = resource_allocator
+            .mmio64_memory
+            .lock()
+            .expect("Poisoned lock");
+
+        virtio_device.allocate_bars(&mut mmio32_allocator, &mut mmio64_allocator, None)?;
+
+        let virtio_device = Arc::new(Mutex::new(virtio_device));
+        pci_segment
+            .pci_bus
+            .lock()
+            .expect("Poisoned lock")
+            .add_device(pci_device_bdf.device() as u32, virtio_device.clone())?;
+
+        Self::register_bars_with_bus(resource_allocator, &virtio_device)?;
+        virtio_device
+            .lock()
+            .expect("Poisoned lock")
+            .register_notification_ioevent(vm)?;
+
+        Ok(())
+    }
+
+    /// Gets the specified device.
+    pub fn get_virtio_device(
+        &self,
+        device_type: u32,
+        device_id: &str,
+    ) -> Option<&Arc<Mutex<VirtioPciDevice>>> {
+        self.virtio_devices
+            .get(&(device_type, device_id.to_string()))
+    }
 }
 
 #[derive(Default, Debug, Clone, Serialize, Deserialize)]

src/vmm/src/device_manager/pci_mngr.rs

@@ -148,7 +148,7 @@ pub trait VirtioDevice: AsAny + Send {
 
     /// Optionally deactivates this device and returns ownership of the guest memory map, interrupt
     /// event, and queue events.
-    fn reset(&mut self) -> Option<(EventFd, Vec<EventFd>)> {
+    fn reset(&mut self) -> Option<(Arc<dyn VirtioInterrupt>, Vec<EventFd>)> {
         None
     }
 

src/vmm/src/devices/virtio/device.rs

@@ -712,6 +712,19 @@ impl Queue {
 
         new - used_event - Wrapping(1) < new - old
     }
+
+    /// Resets the Virtio Queue
+    pub(crate) fn reset(&mut self) {
+        self.ready = false;
+        self.size = self.max_size;
+        self.desc_table_address = GuestAddress(0);
+        self.avail_ring_address = GuestAddress(0);
+        self.used_ring_address = GuestAddress(0);
+        self.next_avail = Wrapping(0);
+        self.next_used = Wrapping(0);
+        self.num_added = Wrapping(0);
+        self.uses_notif_suppression = false;
+    }
 }
 
 #[cfg(kani)]

src/vmm/src/devices/virtio/queue.rs

@@ -8,6 +8,8 @@ use vmm_sys_util::eventfd::EventFd;
 
 /// MMIO transport for VirtIO devices
 pub mod mmio;
+/// PCI transport for VirtIO devices
+pub mod pci;
 
 /// Represents the types of interrupts used by VirtIO devices
 #[derive(Debug, Clone)]