StarFive Linux内核中的IOMMUFD用户空间API详解

概述

IOMMUFD是Linux内核提供的一套用户空间API，用于管理IOMMU子系统，特别是通过文件描述符从用户空间控制IO页表。它为需要向用户空间暴露DMA能力的驱动程序提供通用支持，旨在替代各驱动内部实现的IOMMU逻辑（如vfio_iommu_type1.c）。

IOMMUFD最小功能集包括对所有IOMMU的I/O地址空间和I/O页表的通用管理支持，同时设计上也预留了扩展空间以支持特定硬件功能。

核心概念

用户可见对象

IOMMUFD向用户空间暴露了以下关键对象类型：

1. IOAS（I/O地址空间）：

   • 代表一个I/O虚拟地址(IOVA)空间
   • 支持将用户空间内存映射/解映射到IOVA范围
   • 功能上替代VFIO容器概念

2. DEVICE（设备）：

   • 表示通过外部驱动绑定到iommufd的设备

3. HWPT_PAGING（硬件页表-分页类型）：

   • 代表实际的硬件I/O页表（iommu_domain结构）
   • 必须链接到IOAS对象
   • 支持非托管阶段1域或嵌套父阶段2域

4. HWPT_NESTED（硬件页表-嵌套类型）：

   • 代表由用户空间管理的硬件I/O页表
   • 必须链接到HWPT_PAGING对象
   • 用于支持嵌套翻译功能

5. VIOMMU（虚拟IOMMU）：

   • 表示物理IOMMU实例的一个切片
   • 支持虚拟化功能如安全命名空间、事件报告等
   • 必须基于一个嵌套父HWPT_PAGING创建

6. VDEVICE（虚拟设备）：

   • 表示针对VIOMMU的虚拟设备
   • 包含设备在虚拟机中的虚拟信息和属性

对象关系图解

IOMMUFD中的对象通过以下方式关联：

1. 基本分页模式：

   IOAS <--- HWPT_PAGING <--- DEVICE
     |            |              |
     v            v              v
   PFN存储    iommu_domain    物理设备
   

2. 嵌套翻译模式：

   IOAS <--- HWPT_PAGING <--- HWPT_NESTED <--- DEVICE
     |            |                |              |
     v            v                v              v
   PFN存储    iommu_domain     iommu_domain    物理设备
   

3. 虚拟化模式：

   VIOMMU <--- VDEVICE
     |            |
     v            v
   HWPT_PAGING   DEVICE
   

对象创建与管理

对象创建方式

1. IOAS对象：

   • 通过IOMMU_IOAS_ALLOC uAPI创建
   • 一个iommufd可包含多个IOAS对象

2. DEVICE对象：

   • 外部驱动调用IOMMUFD kAPI绑定设备时创建
   • 需设置driver_managed_dma标志

3. HWPT_PAGING对象：

   • 自动创建：设备附加到IOAS时
   • 手动创建：通过IOMMU_HWPT_ALLOC uAPI
   • 可指定为嵌套父域(IOMMU_HWPT_ALLOC_NEST_PARENT标志)

4. HWPT_NESTED对象：

   • 只能通过IOMMU_HWPT_ALLOC uAPI手动创建
   • 必须基于嵌套父HWPT_PAGING创建
   • 支持2阶段嵌套翻译

5. VIOMMU对象：

   • 通过IOMMU_VIOMMU_ALLOC uAPI创建
   • 需要指定物理IOMMU设备和父HWPT_PAGING

6. VDEVICE对象：

   • 通过IOMMU_VDEVICE_ALLOC uAPI创建
   • 绑定VIOMMU和物理设备

使用限制

• 一个设备只能绑定到一个iommufd
• 目前不支持PASID
• 设备最多附加到一个IOAS对象

内核数据结构

用户可见对象在内核中由以下数据结构支持：

• iommufd_ioas：对应IOAS对象
• iommufd_device：对应DEVICE对象
• iommufd_hwpt_paging：对应HWPT_PAGING对象
• iommufd_hwpt_nested：对应HWPT_NESTED对象
• iommufd_viommu：对应VIOMMU对象
• iommufd_vdevice：对应VDEVICE对象

关键术语

1. 自动域：

   • 设备附加到IOAS时自动创建的iommu域
   • 兼容VFIO type1语义

2. 手动域：

   • 用户指定为目标页表的iommu域
   • 当前无直接创建uAPI，但数据结构已支持

3. 内核用户：

   • 如VFIO mdev等通过IOMMUFD访问接口使用IOAS的实体
   • 通过创建iommufd_access对象实现

IOAS内部结构

iommufd_ioas作为管理IOVA到内存页映射的元数据结构，包含：

• io_pagetable：保存IOVA映射
• iopt_area：表示IOVA的已填充区域
• iopt_pages：表示PFN的存储
• iommu_domain：表示IOMMU中的IO页表
• iopt_pages_access：表示PFN的内核用户
• pinned_pfns xarray：保存内核用户固定的页列表

设计特点

1. 共享机制：

   • 多个io_pagetable可通过iopt_area共享单个iopt_pages
   • 避免多次固定页面和重复计算页消耗

2. 跨子系统共享：

   • IOAS可在VFIO和VDPA等子系统间共享
   • 前提是设备绑定到同一个iommufd

与VFIO的关系

VFIO设备可通过两种方式连接到iommufd：

1. VFIO兼容方式：

   • 将/dev/vfio/vfio容器IOCTL映射到io_pagetable操作
   • 通过符号链接/dev/vfio/vfio到/dev/iommufd实现

2. 原生方式：

   • 直接使用IOMMUFD原生API
   • 需要应用程序修改以使用新接口

这种设计使得IOMMUFD既能支持传统VFIO应用，又能为需要更高级功能的现代应用提供原生支持。

总结

StarFive Linux内核中的IOMMUFD子系统提供了一套完整的用户空间API来管理IOMMU功能，特别适合虚拟化场景和需要精细控制DMA的应用。通过对象化的设计，它支持从简单的分页映射到复杂的嵌套翻译和虚拟化用例，同时保持了与传统VFIO的兼容性。