深入剖析IOMMUFD模式下VFIO DMA映射机制与源码实现

分析源码这件事，有时候比看文档更能让人长记性。最近社区里聊 pgvector 源码分析的不少，那是数据库侧把向量映射到索引结构；而在内核侧，决定你虚拟机直通网卡或显卡能不能跑满带宽的，是 VFIO/IOMMUFD 这条链路上的 DMA 映射机制。这篇文章接着系列第（二十一）篇，专门把 IOMMUFD 模式下的 DMA 映射机制拆开看。围绕标题里的 VFIO、IOMMUFD 和 DMA 映射机制这三个关键词，我会从整体设计、ioctl 入口、页表落地、unmap 路径一直到常见问题排查完整走一遍，适合正在啃内核源码、或者在调 DPDK/SPDK/直通性能的工程师参考。

1. IOMMUFD 模式的整体设计与新老路径对比

1.1 为什么要从 VFIO container 迁移到 IOMMUFD

老一代 VFIO 用户应该都对/dev/vfio/vfio这个 container 设备很熟。传统模式下，你打开 container，往里面塞 group，再给 container 设一个 IOMMU domain，最后通过VFIO_IOMMU_MAP_DMA这条 ioctl 把用户态虚拟地址映射成设备可访问的 IOVA。这套机制本身能跑，而且跑了很多年，但它最大的问题在于：container 和 group、domain 的耦合太紧。一个 container 对应一个 domain，一个 group 里的设备天然被绑定到同一套地址空间，你想给不同设备用不同页表，或者想精细控制每个设备映射到哪个 domain，都非常别扭。

IOMMUFD 的诞生就是把这件事重构了。它的核心思路不是把“容器”做大，而是把“地址空间”和“硬件页表”拆成两个独立对象。你打开一个/dev/iommufd文件描述符，然后在这个 fd 上分配 IOAS（I/O Address Space）和 HWPT（Hardware Page Table），再用一个显式的操作把某个设备 attach 到某个 HWPT 上。这样一来，地址空间归地址空间管理，设备页表归设备页表管理，谁跟谁配对由用户态说了算，而不是内核里预先焊死。

这个设计对虚拟化场景特别重要。你跑 QEMU 的时候，可能既要给 vIOMMU 提供一张 emulate 出来的页表，又要让直通设备用真实 IOMMU 硬件页表，这两者在老 container 模型里很难优雅地共存。IOMMUFD 让每个虚拟设备都能拿到独立的 hwpt，同时多个设备又可以共享同一个 IOAS，灵活性完全不在一个数量级。

1.2 IOAS 与 HWPT：地址空间和硬件页表解耦

IOAS 可以理解成一个纯软件的 IOVA 分配器，它维护的是一段连续的 IOVA 空间里有哪些区间已经映射了，哪些还是空洞。它不关心具体是哪个设备在用这段地址，也不关心底下是 Intel IOMMU 还是 ARM SMMU，只要保证“这一段 IOVA 对应哪些物理页”这个信息是准确的就行。HWPT 则贴近硬件，它内部封装了一个struct iommu_domain，这个 domain 已经和一个具体 IOMMU 实例绑定，操作它就是在操作真实的硬件页表。

这套解耦带来的直接好处是：同一个 IOAS 可以同时喂给多个 HWPT，多个设备即便底层 IOMMU 不同，也能看到一致的 IOVA 布局。反过来，一个 HWPT 也可以只从某个 IOAS 里挑一部分区间映射，做细粒度的隔离。代码里最直观的体现是，iommufd_ioas结构体里嵌着一个struct iommu_option，所有区间管理操作都围绕这个iopt展开；而iommufd_hwpt_paging里则同时保存了domain指针和指向ioas的回指。两者互相配合，构成了整个 DMA 映射机制的地基。

1.3 VFIO 与 IOMMUFD 的新协作关系

很多第一次接触 IOMMUFD 的人会问：那 VFIO 是不是就不需要了？答案是否定的。VFIO 仍然负责设备层面的暴露、中断管理、设备状态迁移这些脏活累活，只是把原来属于 container 的 DMA 映射职责剥离出来交给 IOMMUFD。你仍然可以打开/dev/vfio/vfio，也可以用新版 vfio 设备 fd 直接和 iommufd 通信，但不会再走VFIO_IOMMU_MAP_DMA那套逻辑。

具体到代码路径，设备侧通过vfio_device_bind_iommufd这类接口把自己的struct device和某个iommufd_ctx关联起来，之后用户态再发IOMMUFD_CMD_HWPT_ALLOC创建一个 hwpt，并把设备 attach 上去。从这一刻开始，设备要访问的内存就由 IOMMUFD 的 ioas/hwpt 体系来维护了。如果你还在老代码里用 container ioctl 去 map DMA，内核会直接返回ENOTTY，因为设备已经换了东家。

2. DMA 映射请求是怎么一路走到内核的

2.1 用户态 ioctl 入口与命令分发表

IOMMUFD 的入口非常集中。用户态先open("/dev/iommufd", O_RDWR)拿到一个文件描述符，之后所有操作都走ioctl()。内核侧对应的文件操作集是iommufd_fops，而真正的分发逻辑在iommufd_ioctl()里。这个函数会根据命令号去查一张静态表iommufd_ioctl_ops，表里每项都写明了命令号、参数结构体、处理函数。以 map 操作来看，uapi 头文件里有这样的结构体：

struct iommu_map_dma { __u32 size; __u32 flags; __u32 ioas_id; __u32 __reserved; __aligned_u64 iova; __aligned_u64 data; /* user virtual address */ __aligned_u64 length; };

注意这里的data字段，它指的不是物理地址，而是用户态进程的虚拟地址。IOMMUFD 要做的事情就是把这个虚拟地址背后的一串物理页找出来，再把这些物理页映射到iova指定的设备地址空间。换句话说，一次 DMA 映射的输入是“用户态 VA + 设备 IOVA + 长度”，输出是“IOMMU 硬件页表里的一组映射条目”。理解了这个语义，后面看代码就不容易绕晕。

2.2 命令参数校验与两条入口

iommufd_hwpt_map_dma()在动手之前会做非常严格的参数检查。首先size字段必须等于结构体实际大小，防止未来扩展时用户态和内核态版本不一致；其次iova必须按页对齐，length不能为 0。这里还有一个很容易被忽略的规则：length不需要按页对齐，但内核会在内部向上取整到页边界，并且最终映射的实际区间也以页为单位。

不同内核版本里，入口参数还有细微差别。早期 IOMMUFD 只有ioas_id，用户态告诉内核“我要在哪个地址空间里映射”，内核自己选默认的 hwpt/domain。后来为了支持 vIOMMU 和多 domain 场景，增加了显式传递hwpt_id的路径，你可以精确指定“用这张硬件页表去映射”。这两条入口在代码里会走不同的分支，但最终殊途同归，都汇聚到iopt_map_pages()。如果你看到代码里既有iommufd_get_ioas()又有iommufd_get_hwpt()，别困惑，它们只是老版本接口和新版本接口并存的结果。

2.3 iommufd_hwpt_map_dma 与 iopt_map_pages 的分工

iommufd_hwpt_map_dma()本身做的事情不多，它可以被理解成一个“快递分拣站”：从 ucmd 里解析出对象 id，拿引用计数，找到对应的 hwpt 或者 ioas，然后转身就把活交给iopt_map_pages()。真正复杂的映射逻辑全在drivers/iommu/iommufd/io_pagetable.c里。这种薄入口、厚实现的写法在内核里很常见，好处是错误处理和对象生命周期管理能集中在一个地方，不至于散落各处。

iopt_map_pages()的签名大致是接收iopt、domain、iova、用户态指针uptr、length和flags。它的第一件事是为这段内存建立struct iopt_pages对象，这个对象负责管理被 pin 住的物理页；然后分配一个struct iopt_area节点，把它插入到 iopt 的红黑树或者区间树里；最后调用填充函数，把物理页逐段写进 domain 的硬件页表。这三步如果中间任何一步失败，都要把前面已经分配的资源回滚干净。

3. 核心数据结构与 DMA 页表建立细节

3.1 iopt_pages：把用户 VA“钉”成物理页

DMA 映射最忌讳的一件事是：设备正在访问某块内存，用户态却把这块内存释放或者换出了。IOMMUFD 的解决办法是在映射时就把用户态虚拟地址对应的物理页“钉”住，让它们不能被换出、不能被迁移。代码里这个动作最终落到底层辅助函数上，本质上是调用pin_user_pages()一类机制，并且带上FOLL_LONGTERM标志，告诉内核这是长期 pin，不能走短期的 get_user_pages 路径。

这里有个经验之谈：如果你在调试时看到映射失败返回EFAULT，十有八九是用户态传进来的指针根本没有对应合法 VMA，比如已经munmap过，或者跨了进程地址空间没有正确映射。IOMMUFD 在这一步会遍历相关的 VMA，检查权限是否可读可写，然后才真正把页钉住。被钉住的页会被记录在一个 pfn 数组或者 scatterlist 里，后续填充硬件页表时直接从这个数组里取物理页号就行，不需要再回到进程页表去查。

3.2 iopt_area：区间树上的关键节点

struct iopt_area是 IOMMUFD 管理 IOVA 区间的基本单元。它内部记录了iova起点、长度、关联的iopt_pages指针、映射 flags，以及自己在区间树里的位置信息。iopt 维护的区间树可以让内核以 O(log n) 的复杂度去查找某个 IOVA 是否已经有映射、是否有重叠。每当你调用 map 时，内核会先查树，看看你想要的区间是否和已有的 area 冲突；如果冲突，轻则返回EINVAL，重则在极端情况下会尝试拆分成更小的 area 来满足请求。

很多人在看代码时会忽略 area 的拆分逻辑，但它是整个 IOMMUFD 最精巧的地方之一。比如你连续映射了 0x1000 和 0x2000 两段，如果两段的物理页并不连续，内核会维护两个独立的 area；如果物理页恰好连续且 flags 一致，某些版本的内核会尝试合并。反过来，unmap 一段位于 area 中间的区间时，内核会把一个 area 拆成左右两个 area。这些操作都要求对区间树节点的插入、删除、旋转足够谨慎，稍有不慎就会导致 IOVA 泄漏或者映射错乱。

3.3 从 area 到 IOMMU 硬件页表：iommu_map_pages

area 建好之后，真正写硬件页表的动作发生在iopt_area_fill_pages()或者类似命名的函数里。它遍历之前 pin 好的物理页，根据页是否连续来决定是一次性调用iommu_map_pages()批量映射，还是拆成多次单页映射。iommu_map_pages()是 IOMMU 核心层的通用接口，它会把“IOVA 地址 + 物理地址 + 长度 + 权限”翻译成具体 IOMMU 驱动的页表操作。Intel 的 IOMMU 驱动写的是 VT-d 页表，ARM SMMUv3 驱动写的是 CD/STE 指向的页表，但在这层接口之上，IOMMUFD 不需要关心差异。

权限标志是另一个值得留意的点。用户态传入的 flags 会决定最终映射是只读还是可写，是否带IOMMU_CACHE等属性。如果你在直通场景里发现设备能读但不能写，或者出现一致性问题，优先检查是不是 flags 里少了该有的 cache 位。代码里这块逻辑通常表现为把用户态 flags 翻译成IOMMU_READ、IOMMU_WRITE、IOMMU_CACHE这几个标准位，翻译的过程藏着一堆平台相关的坑。

4. DMA 映射失败、unmap 与资源回收

4.1 unmap 接口的 length 特殊约定

有映射就有解映射。IOMMUFD 的 unmap 命令叫IOMMUFD_CMD_UNMAP_DMA，用户态需要传入iova和一个length。但这里有个非常容易踩坑的约定：如果length传的是 1，内核会把它解释成“从 iova 开始一直 unmap 到该 area 结束”，而不是真的只解映射 1 字节。这算是个历史遗留的取巧设计，因为用户态在不确定 area 大小时，可以先查再 unmap，也可以直接传 1 让内核帮你算。函数返回后，length会被改写成实际 unmap 的长度。

我见过不止一个项目在这里翻车。有人从旧 vfio container 迁移过来，习惯性地按页大小传 length，结果发现只 unmap 掉了一部分，剩下半截映射还残留在那里。说好的“设备不再访问这块内存”，实际上硬件页表还偷偷留着旧映射。排查这类问题最好的办法是 unmap 后用iopt的调试节点看剩余 area，或者直接在代码里打 tracepoint 观察iopt_unmap_pages()返回的length是否和预期一致。

4.2 从 area 移除到 iommu_unmap

unmap 路径的核心函数大致上是iopt_unmap_pages()。它会先根据iova找到命中的 area，然后根据 unmap 长度决定是整体删除 area，还是把 area 缩小，或者把 area 拆成两段。删除 area 的同时会调用iommu_unmap()系列函数，把硬件页表里对应的条目清掉，并触发必要的 iotlb 失效。注意，iommu_unmap()的返回值是实际 unmap 的字节数，如果硬件页表里本来就没有映射，返回 0，这也是为什么用户态最好对 unmap 返回值做一次校验。

资源回收的顺序很关键。一般来说，先摘掉 area 节点、unmap 硬件页表，然后释放iopt_pages里 pin 住的页引用。如果顺序反了，可能出现硬件页表已经清了但物理页还被 pin 着的情况，这在长时间运行的进程里会累积成内存泄漏。IOMMUFD 在这个流程里加了很多引用计数保护，但引用计数本身也会成为 bug 温床，我建议阅读代码时重点关注各个函数入口和出口的refcount变化，这是理解整个模块的钥匙。

4.3 常见错误码与问题定位

DMA 映射失败时，用户态拿到的 errno 往往很笼统。我整理了一个速查表，方便大家对照排查：

遇到问题不要一上来就看硬件，先把这几个 errno 对照自己传的参数过一遍，往往能省很多时间。内核里也提供了iommu_map、iommu_error等 tracepoint，用trace-cmd或者 bpftrace 挂上之后，可以清楚地看到映射请求落在哪个地址、哪一步失败了。

5. 从老 container 切到 IOMMUFD 的实际经验

5.1 用户态代码改动点

老 vfio container 的代码大概长这样：打开/dev/vfio/vfio，创建 container，VFIO_SET_IOMMU，然后反复调VFIO_IOMMU_MAP_DMA。切到 IOMMUFD 之后，流程变成打开/dev/iommufd，用IOMMUFD_CMD_IOAS_ALLOC建地址空间，用IOMMUFD_CMD_HWPT_ALLOC建硬件页表，再把设备和 hwpt 绑定。映射 DMA 的调用也从VFIO_IOMMU_MAP_DMA改成IOMMUFD_CMD_MAP_DMA，参数结构体虽然很像，但语义上多了 hwpt/ioas 这个维度。

如果你用 QEMU，比较省事的做法是加-object iommufd,id=iommufd0和-device vfio-pci,iommufd=iommufd0这类参数，让 QEMU 内部自动完成切换。手写库的话，就得老老实实把老的 container ioctl 全部替换掉。这里提醒一点：IOMMUFD 的ioas_id和内核里的iommu_group没有直接关系，不要想当然地认为同一个 group 的设备必须共享 ioas，它们完全可以各自建 hwpt，甚至指向不同的 ioas。

5.2 性能和 iotlb 相关的注意点

切到 IOMMUFD 之后，性能表现不一定立刻变好，但至少不会因为框架本身拖慢太多。有一个值得注意的点是：IOMMU 硬件页表的建立是分页进行的，如果你每次只映射 4K，频繁 map/unmap，page table walk 和 iotlb 失效的开销会非常明显。实际项目中最好尽量映射大块连续内存，或者把映射生命周期拉长，避免在热路径上频繁创建小 area。IOMMUFD 也支持通过用户态预分配大 IOVA 区间来降低碎片化，ioas 层面的分配器会尽量使用自顶向下或者最优适配策略，但最终效果还是取决于使用方式。

另一个和平台强相关的问题是 iotlb 刷新。x86 上通常由驱动负责在 unmap 后发送 invalidation 描述符，而 ARM SMMUv3 的命令队列机制完全不同。IOMMUFD 会把这些差异封装到底层iommu_domain的操作里，但你在做性能分析时还是要把 iotlb flush 的代价算进去。如果一个设备频繁 unmap 再 map 同样大小的区域，反复刷 iotlb 可能比实际 DMA 拷贝还贵。

5.3 我踩过的几个坑

第一个坑是老的 vfio container 和 IOMMUFD 混用。设备一旦 bind 到 iommufd，你再往 container 里塞它就会失败，错误往往是EBUSY或者ENOTTY。解决的办法是确认用户态和内核版本支持 IOMMUFD，并且 vfio-pci 等驱动模块加载时带了正确的内核配置。

第二个坑和 mdev/vfio-pci 迁移有关。设备热迁移时，fd 的关闭顺序会影响 iommufd_ctx 的释放。如果设备 fd 先关、iommufd fd 后关，或者反过来，某些内核版本会出现引用计数告警。我的经验是严格按照 bind -> alloc hwpt -> attach -> map -> unmap -> detach -> free hwpt -> close fd 的顺序操作，不要跳步。

第三个坑是 passthrough 模式和 dedicated mode 的选择。iommufd 更偏 dedicated domain 的设计，但在某些平台上，系统默认配置可能是 passthrough。如果你发现IOMMUFD_CMD_HWPT_ALLOC建出来的 domain 并没有强制开启地址翻译能力，性能对比数据会变得很难看。检查方法很简单：看设备每次 DMA 时 IOMMU 有没有实际做页表 walk，或者在驱动里打印 domain 的 capabilities。

回到源码阅读本身，我个人最大的体会是：VFIO/IOMMUFD 这条路径虽然绕，但读代码时始终抓住“地址空间对象和硬件页表对象分离”这条主线就不会迷路。IOAS 管 IOVA 布局，HWPT 管设备页表，iopt_pages 管物理页引用，三者各司其职。你如果在实际项目里被 DMA 映射问题卡住，不妨按这个思路从 ioctl 入口开始逐层向下追，很快就能定位到是参数校验、区间管理还是硬件页表写入出了问题。