分析源码这件事有时候比看文档更能让人长记性。最近社区里聊 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 上分配 IOASI/O Address Space和 HWPTHardware 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_pagesarea 建好之后真正写硬件页表的动作发生在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_unmapunmap 路径的核心函数大致上是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常见原因排查方向EINVALiova 未按页对齐、length 非法、flags 不支持先看用户态传参再看内核校验分支EFAULT用户态虚拟地址无对应 VMA、权限不足检查进程地址空间是否已释放对应区间ENOMEM物理页 pin 失败、内核内存不足关注系统内存水位看是否有 overcommit 限制ENOSPCIOVA 空间不足、无法分配连续区间检查 ioas 里有没有 IOVA 碎片考虑调整分配策略EBUSY对象正在被使用、设备 attach 状态冲突检查 hwpt 和设备绑定关系是否有重复 attach遇到问题不要一上来就看硬件先把这几个 errno 对照自己传的参数过一遍往往能省很多时间。内核里也提供了iommu_map、iommu_error等 tracepoint用trace-cmd或者 bpftrace 挂上之后可以清楚地看到映射请求落在哪个地址、哪一步失败了。5. 从老 container 切到 IOMMUFD 的实际经验5.1 用户态代码改动点老 vfio container 的代码大概长这样打开/dev/vfio/vfio创建 containerVFIO_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,idiommufd0和-device vfio-pci,iommufdiommufd0这类参数让 QEMU 内部自动完成切换。手写库的话就得老老实实把老的 container ioctl 全部替换掉。这里提醒一点IOMMUFD 的ioas_id和内核里的iommu_group没有直接关系不要想当然地认为同一个 group 的设备必须共享 ioas它们完全可以各自建 hwpt甚至指向不同的 ioas。5.2 性能和 iotlb 相关的注意点切到 IOMMUFD 之后性能表现不一定立刻变好但至少不会因为框架本身拖慢太多。有一个值得注意的点是IOMMU 硬件页表的建立是分页进行的如果你每次只映射 4K频繁 map/unmappage 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 入口开始逐层向下追很快就能定位到是参数校验、区间管理还是硬件页表写入出了问题。