Function prepare_gpu_for_passthrough

crates/openshell-vfio/src/gpu.rs:84–163

Bind a GPU to `vfio-pci`, returning an RAII guard that restores it on drop. Also binds all companion devices in the same IOMMU group (e.g. the HD Audio function on consumer GPUs). All bound companions are tracked and restored when the guard is dropped.

(
    sysfs: &SysfsRoot,
    bdf: &str,
)

/// function on consumer GPUs). All bound companions are tracked and restored
/// when the guard is dropped.
pub fn prepare_gpu_for_passthrough(
    sysfs: &SysfsRoot,
    bdf: &str,
) -> Result<PciBindGuard, VfioError> {
    validate_bdf(bdf)?;

    let device = sysfs.pci_device_ref(bdf);
    if !device.exists() {
        return Err(VfioError::GpuNotFound {
            bdf: bdf.to_string(),
        });
    }

    let class = device.class()?;
    if !is_gpu_class(&class) {
        return Err(VfioError::NotGpu {
            bdf: bdf.to_string(),
            class,
        });
    }

    let iommu_group = device.iommu_group()?;
    let group_devices = sysfs.iommu_group_devices(iommu_group)?;
    let peers: Vec<String> = group_devices.into_iter().filter(|d| d != bdf).collect();

    let mut bound_companions = Vec::new();
    for peer in &peers {
        if !sysfs.pci_device_ref(peer).exists() {
            continue;
        }
        match crate::bind::bind_device_to_vfio(sysfs, peer) {
            Ok(was_bound) => {
                if was_bound {
                    tracing::info!(bdf = %peer, iommu_group, "bound IOMMU group companion to vfio-pci");
                    bound_companions.push(peer.clone());
                }
            }
            Err(err) => {
                for already_bound in bound_companions.iter().rev() {
                    if let Err(restore_err) =
                        crate::bind::restore_to_host_driver(sysfs, already_bound)
                    {
                        tracing::error!(bdf = %already_bound, error = %restore_err, "failed to restore companion during rollback");
                    }
                }
                return Err(VfioError::BindFailed {
                    bdf: peer.clone(),
                    reason: format!("IOMMU group {iommu_group} companion bind failed: {err}"),
                });
            }
        }
    }

    match crate::bind::bind_device_to_vfio(sysfs, bdf) {
        Ok(was_bound) => {
            if was_bound {
                tracing::info!(bdf, "GPU bound to vfio-pci");
            } else {