What must I check before assigning a PCIe device directly to a virtual machine?
PCIe passthrough gives a guest direct use of selected hardware and requires a supported IOMMU and virtualization stack. Devices can share isolation groups, so the unit of safe assignment may be broader than one visible function. A storage controller, NIC or GPU needed by the host must not be detached merely to test passthrough.
Before you start
- A supported Linux VFIO/hypervisor environment and read access to PCI/IOMMU inventory.
Instructions
1. Identify the hardware and current driver
Read the PCI inventory on the bare-metal host. Record the exact bus address and whether the host currently depends on the device.
lspci -nnkTrace storage and network dependencies before considering any driver rebinding. A device visible on the PCI bus is not automatically suitable for guest assignment.
2. Inspect exposed isolation groups
On a Linux host with IOMMU groups available, list their device links. Match those addresses to the inventory.
find /sys/kernel/iommu_groups -maxdepth 2 -type l -printDevices within an IOMMU group have isolation constraints that must be handled by the supported VFIO/hypervisor procedure. Do not bypass those constraints to force a configuration.
3. Check workload and recovery constraints
Confirm guest driver support, reset behaviour and the platform’s migration limitations. Keep an independent management path if the candidate device participates in host networking.
Check the result
- The full group and host dependencies are understood, the hardware/platform combination supports assignment, and the guest’s recovery and migration plan accounts for the device.
Troubleshooting
- No groups are listed
- Check firmware IOMMU support and the kernel’s documented platform requirements.
- The group contains a host storage controller
- Choose another supported arrangement; detaching it could remove the host’s own disks.
- The device works once but fails after a guest restart
- Investigate supported reset behaviour and vendor/hypervisor guidance.
Official references
Use the documentation for your installed version when a flag, service name or platform feature differs.