iommufd-ioctls: Add vIOMMU and vDevice abstraction layer

Introduce `IommufdVIommu` and `IommufdVDevice` structs to provide
high-level abstractions for managing IOMMUFD virtual IOMMU instances and
virtual devices [1]. These structures encapsulate the multi-phase workflow
required for hardware-accelerated nested translation — including S2 HWPT
infrastructure setup, vIOMMU/vDevice allocation, and runtime S1 HWPT
management — into clean and ergonomic Rust APIs. This enables VMMs to
build accelerated virtual IOMMUs without directly managing low-level
IOMMUFD object lifecycles and sequencing constraints.

Key changes:
- `IommufdVIommu`: Manages the vIOMMU lifecycle, including Stage-2 HWPT
  allocation and default Stage-1 HWPT configuration (bypass/abort mode).
- `IommufdVDevice`: Represents devices attached to a vIOMMU, supporting
  dynamic Stage-1 HWPT allocation and hardware info queries.
- Type Safety: Add `IommufdInvalidateData`, `IommufdHwInfoData`, and
  `IommufdHwptData` enums to handle architecture-specific data
  (e.g., ARM SMMUv3, Intel VT-d).
- Public interfaces: Provide methods for physical device info retrieval,
  Stage-1 HWPT configuration, and invalidation.
- Resource Management: Implement `Drop` traits to ensure proper resource
  release within the IOMMUFD context.

Note: This implementation primarily targets ARM SMMUv3; Intel VT-d
structures are currently placeholders for future implementation.

[1] https://docs.kernel.org/userspace-api/iommufd.html

Signed-off-by: Bo Chen <bchen@crusoe.ai>

Author: likebreath

iommufd-ioctls/src/iommufd_ioctls.rs

@@ -5,6 +5,7 @@
 
 use std::fs::{File, OpenOptions};
 use std::os::unix::io::{AsRawFd, RawFd};
+use std::sync::Arc;
 
 use iommufd_bindings::iommufd::*;
 use vmm_sys_util::errno::Error as SysError;
@@ -68,6 +69,313 @@ impl IommuFd {
     }
 }
 
+#[derive(Debug, Copy, Clone)]
+pub enum IommufdInvalidateData {
+    Smmuv3(iommu_viommu_arm_smmuv3_invalidate),
+    Vtd(iommu_hwpt_vtd_s1_invalidate),
+}
+
+#[derive(Clone)]
+pub struct IommufdVIommu {
+    pub iommufd: Arc<IommuFd>,
+    pub viommu_id: u32,
+    pub dev_id: u32,
+    pub s2_hwpt_id: u32,
+    pub bypass_hwpt_id: u32,
+    pub abort_hwpt_id: u32,
+}
+
+impl IommufdVIommu {
+    /// Create a new vIOMMU instance
+    /// # Arguments
+    /// * `iommufd` - The iommufd instance to use
+    /// * `ioas_id` - The IOAS ID to associate with the vIOMMU
+    /// * `dev_id` - The device ID of the VFIO device
+    /// * `s1_hwpt_data_type` - The s1 hwpt data type
+    pub fn new(
+        iommufd: Arc<IommuFd>,
+        ioas_id: u32,
+        dev_id: u32,
+        s1_hwpt_data_type: iommu_hwpt_data_type,
+    ) -> Result<Self> {
+        if s1_hwpt_data_type != iommu_hwpt_data_type_IOMMU_HWPT_DATA_ARM_SMMUV3 {
+            return Err(IommufdError::UnsupportedS1HwptDataType(s1_hwpt_data_type));
+        }
+
+        // Refer to “5.2 Stream Table Entry” in SMMUv3 HW Specification
+        const SMMU_STE_VALID: u64 = 1 << 0;
+        const SMMU_STE_CFG_BYPASS: u64 = 1 << 3;
+
+        // Allocate s2_hwpt who will be shared for all devices behind this vIOMMU instance
+        let mut s2_iommufd_hwpt_alloc = iommu_hwpt_alloc {
+            size: std::mem::size_of::<iommu_hwpt_alloc>() as u32,
+            flags: iommufd_hwpt_alloc_flags_IOMMU_HWPT_ALLOC_NEST_PARENT,
+            dev_id,
+            pt_id: ioas_id,
+            data_type: iommu_hwpt_data_type_IOMMU_HWPT_DATA_NONE,
+            ..Default::default()
+        };
+        iommufd.alloc_iommu_hwpt(&mut s2_iommufd_hwpt_alloc)?;
+        let s2_hwpt_id = s2_iommufd_hwpt_alloc.out_hwpt_id;
+
+        // Allocate vIOMMU
+        let mut viommu_alloc = iommu_viommu_alloc {
+            size: std::mem::size_of::<iommu_viommu_alloc>() as u32,
+            type_: iommu_viommu_type_IOMMU_VIOMMU_TYPE_ARM_SMMUV3,
+            hwpt_id: s2_hwpt_id,
+            dev_id,
+            ..Default::default()
+        };
+        iommufd.alloc_iommu_viommu(&mut viommu_alloc)?;
+        let viommu_id = viommu_alloc.out_viommu_id;
+
+        // ALlocate bypass s1_hwpt which will be used when the virtual IOMMU
+        // is not initilized by the guest
+        let bypass_s1_hwpt_data = iommu_hwpt_arm_smmuv3 {
+            ste: [SMMU_STE_CFG_BYPASS | SMMU_STE_VALID, 0x0],
+        };
+        let mut bypass_iommufd_hwpt_alloc = iommu_hwpt_alloc {
+            size: std::mem::size_of::<iommu_hwpt_alloc>() as u32,
+            dev_id,
+            pt_id: s2_hwpt_id,
+            data_type: s1_hwpt_data_type,
+            data_len: std::mem::size_of::<iommu_hwpt_arm_smmuv3>() as u32,
+            data_uptr: &bypass_s1_hwpt_data as *const iommu_hwpt_arm_smmuv3 as u64,
+            ..Default::default()
+        };
+        iommufd.alloc_iommu_hwpt(&mut bypass_iommufd_hwpt_alloc)?;
+        let bypass_hwpt_id = bypass_iommufd_hwpt_alloc.out_hwpt_id;
+
+        // Allocate abort s1_hwpt which will be used when the virtual IOMMU
+        // is configured in such mode
+        let abort_s1_hwpt_data = iommu_hwpt_arm_smmuv3 {
+            ste: [SMMU_STE_VALID, 0x0],
+        };
+        let mut abort_iommufd_hwpt_alloc = iommu_hwpt_alloc {
+            size: std::mem::size_of::<iommu_hwpt_alloc>() as u32,
+            dev_id,
+            pt_id: s2_hwpt_id,
+            data_type: s1_hwpt_data_type,
+            data_len: std::mem::size_of::<iommu_hwpt_arm_smmuv3>() as u32,
+            data_uptr: &abort_s1_hwpt_data as *const iommu_hwpt_arm_smmuv3 as u64,
+            ..Default::default()
+        };
+        iommufd.alloc_iommu_hwpt(&mut abort_iommufd_hwpt_alloc)?;
+        let abort_hwpt_id = abort_iommufd_hwpt_alloc.out_hwpt_id;
+
+        Ok(IommufdVIommu {
+            iommufd,
+            viommu_id,
+            dev_id,
+            s2_hwpt_id,
+            bypass_hwpt_id,
+            abort_hwpt_id,
+        })
+    }
+
+    /// Invalidate a hwpt entry
+    /// # Arguments
+    /// * `cmd` - The invalidate data
+    /// Returns:
+    /// * `Ok(true)` if the entry is invalidated
+    /// * `Ok(false)` if the entry is not invalidated
+    pub fn invalidate_hwpt(&self, cmd: &mut IommufdInvalidateData) -> Result<bool> {
+        match cmd {
+            IommufdInvalidateData::Smmuv3(data) => {
+                let mut hw_invalidate = iommu_hwpt_invalidate {
+                    size: std::mem::size_of::<iommu_hwpt_invalidate>() as u32,
+                    hwpt_id: self.viommu_id,
+                    data_type:
+                        iommu_hwpt_invalidate_data_type_IOMMU_VIOMMU_INVALIDATE_DATA_ARM_SMMUV3,
+                    entry_len: std::mem::size_of::<iommu_viommu_arm_smmuv3_invalidate>() as u32,
+                    entry_num: 1,
+                    data_uptr: data as *mut iommu_viommu_arm_smmuv3_invalidate as u64,
+                    ..Default::default()
+                };
+                self.iommufd.invalidate_hwpt(&mut hw_invalidate)?;
+
+                if hw_invalidate.entry_num == 1 {
+                    Ok(true)
+                } else {
+                    Ok(false)
+                }
+            }
+            IommufdInvalidateData::Vtd(_) => {
+                unimplemented!()
+            }
+        }
+    }
+}
+
+impl Drop for IommufdVIommu {
+    fn drop(&mut self) {
+        self.iommufd
+            .destroy_iommufd(self.viommu_id)
+            .inspect_err(|e| {
+                eprintln!("Failed to destroy vIOMMU id {}: {}", self.viommu_id, e);
+            })
+            .unwrap();
+
+        self.iommufd
+            .destroy_iommufd(self.s2_hwpt_id)
+            .inspect_err(|e| {
+                eprintln!("Failed to destroy s2_hwpt id {}: {}", self.s2_hwpt_id, e);
+            })
+            .unwrap();
+
+        self.iommufd
+            .destroy_iommufd(self.bypass_hwpt_id)
+            .inspect_err(|e| {
+                eprintln!(
+                    "Failed to destroy bypass_hwpt id {}: {}",
+                    self.bypass_hwpt_id, e
+                );
+            })
+            .unwrap();
+
+        self.iommufd
+            .destroy_iommufd(self.abort_hwpt_id)
+            .inspect_err(|e| {
+                eprintln!(
+                    "Failed to destroy abort_hwpt id {}: {}",
+                    self.abort_hwpt_id, e
+                );
+            })
+            .unwrap();
+    }
+}
+
+#[derive(Debug, Copy, Clone)]
+pub enum IommufdHwInfoData {
+    Smmuv3(iommu_hw_info_arm_smmuv3),
+    Vtd(iommu_hw_info_vtd),
+}
+
+#[derive(Debug, Copy, Clone)]
+pub enum IommufdHwptData {
+    Smmuv3(iommu_hwpt_arm_smmuv3),
+    Vtd(iommu_hwpt_vtd_s1),
+}
+
+#[derive(Clone)]
+pub struct IommufdVDevice {
+    pub viommu: Arc<IommufdVIommu>,
+    pub dev_id: u32,
+    pub virt_id: u64,
+    pub vdevice_id: u32,
+    pub s1_hwpt_id: Option<u32>,
+}
+
+impl IommufdVDevice {
+    /// Create a new vDevice instance
+    /// # Arguments
+    /// * `viommu` - The vIOMMU instance the vDevice is associated with
+    /// * `dev_id` - The device ID of the vDevice
+    /// * `virt_id` - The virtual Stream ID of the vDevice
+    pub fn new(viommu: Arc<IommufdVIommu>, dev_id: u32, virt_id: u64) -> Result<Self> {
+        let mut vdevice_alloc = iommu_vdevice_alloc {
+            size: std::mem::size_of::<iommu_vdevice_alloc>() as u32,
+            viommu_id: viommu.viommu_id,
+            dev_id,
+            virt_id,
+            ..Default::default()
+        };
+        viommu.iommufd.alloc_iommu_vdevice(&mut vdevice_alloc)?;
+
+        Ok(IommufdVDevice {
+            viommu,
+            dev_id,
+            virt_id,
+            vdevice_id: vdevice_alloc.out_vdevice_id,
+            s1_hwpt_id: None,
+        })
+    }
+
+    /// Allocate s1 hwpt for the vDevice
+    pub fn allocate_s1_hwpt(&mut self, hwpt_data: &IommufdHwptData) -> Result<u32> {
+        if self.s1_hwpt_id.is_some() {
+            return Err(IommufdError::S1HwptAlreadyAllocated(self.vdevice_id));
+        }
+
+        match hwpt_data {
+            IommufdHwptData::Smmuv3(data) => {
+                let mut s1_iommufd_hwpt_alloc = iommu_hwpt_alloc {
+                    size: std::mem::size_of::<iommu_hwpt_alloc>() as u32,
+                    dev_id: self.dev_id,
+                    pt_id: self.viommu.viommu_id,
+                    data_type: iommu_hwpt_data_type_IOMMU_HWPT_DATA_ARM_SMMUV3,
+                    data_len: std::mem::size_of::<iommu_hwpt_arm_smmuv3>() as u32,
+                    data_uptr: data as *const iommu_hwpt_arm_smmuv3 as u64,
+                    ..Default::default()
+                };
+                self.viommu
+                    .iommufd
+                    .alloc_iommu_hwpt(&mut s1_iommufd_hwpt_alloc)?;
+
+                let s1_hwpt_id = s1_iommufd_hwpt_alloc.out_hwpt_id;
+                self.s1_hwpt_id = Some(s1_hwpt_id);
+
+                Ok(s1_hwpt_id)
+            }
+            IommufdHwptData::Vtd(_) => unimplemented!(),
+        }
+    }
+
+    /// Destroy s1 hwpt for the vDevice
+    pub fn destroy_s1_hwpt(&mut self) -> Result<()> {
+        if let Some(s1_hwpt_id) = self.s1_hwpt_id {
+            self.viommu.iommufd.destroy_iommufd(s1_hwpt_id)?;
+            self.s1_hwpt_id = None;
+        }
+        Ok(())
+    }
+
+    /// Get device hardware information
+    pub fn get_device_hw_info(
+        &self,
+        hw_info_data: &mut IommufdHwInfoData,
+    ) -> Result<iommu_hw_info> {
+        let mut hw_info = match hw_info_data {
+            IommufdHwInfoData::Smmuv3(data) => iommu_hw_info {
+                size: std::mem::size_of::<iommu_hw_info>() as u32,
+                dev_id: self.dev_id,
+                data_len: std::mem::size_of::<iommu_hw_info_arm_smmuv3>() as u32,
+                data_uptr: data as *mut _ as u64,
+                ..Default::default()
+            },
+            IommufdHwInfoData::Vtd(_) => {
+                unimplemented!()
+            }
+        };
+
+        self.viommu.iommufd.get_hw_info(&mut hw_info)?;
+
+        Ok(hw_info)
+    }
+}
+
+impl Drop for IommufdVDevice {
+    fn drop(&mut self) {
+        self.viommu
+            .iommufd
+            .destroy_iommufd(self.vdevice_id)
+            .inspect_err(|e| {
+                eprintln!("Failed to destroy vDevice id {}: {}", self.vdevice_id, e);
+            })
+            .unwrap();
+
+        if let Some(s1_hwpt_id) = self.s1_hwpt_id {
+            self.viommu
+                .iommufd
+                .destroy_iommufd(s1_hwpt_id)
+                .inspect_err(|e| {
+                    eprintln!("Failed to destroy s1_hwpt id {}: {}", s1_hwpt_id, e);
+                })
+                .unwrap();
+        }
+    }
+}
+
 impl AsRawFd for IommuFd {
     fn as_raw_fd(&self) -> RawFd {
         self.iommufd.as_raw_fd()
@@ -112,6 +420,8 @@ ioctl_io_nr!(
     IOMMUFD_CMD_VDEVICE_ALLOC
 );
 
+// IOMMU_HW_QUEUE_ALLOC
+
 // Safety:
 // - absolutely trust the underlying kernel
 // - absolutely trust data returned by the underlying kernel

iommufd-ioctls/src/lib.rs

@@ -14,6 +14,8 @@ pub mod iommufd_ioctls;
 
 pub use iommufd_ioctls::*;
 
+use iommufd_bindings::iommufd::*;
+
 #[derive(Debug, Error)]
 pub enum IommufdError {
     #[error("failed to open /dev/iommufd: {0}")]
@@ -36,6 +38,10 @@ pub enum IommufdError {
     IommuGetHwInfo(#[source] SysError),
     #[error("failed to invalidate HWPT: {0}")]
     IommuHwptInvalidate(#[source] SysError),
+    #[error("unsupported S1 HWPT data type: {0}")]
+    UnsupportedS1HwptDataType(iommu_hwpt_data_type),
+    #[error("S1 HWPT already allocated with for the given vDevice: {0}")]
+    S1HwptAlreadyAllocated(u32),
 }
 
 pub type Result<T> = std::result::Result<T, IommufdError>;