1. 从 VFIO 到 IOMMUFD：DMA 映射机制的核心演进

老读者应该知道，我这个 VFIO 系列已经写到了第二十一篇，前面花了大量篇幅在讲 VFIO 的容器模型、group 管理、设备直通流程，以及传统VFIO_IOMMU_TYPE1路径下 DMA 映射是怎么通过vfio_dma_map配合 IOMMU 页表完成的。坦白说，Type1 这套机制虽然稳定，但设计上确实有些年头了。它把容器、group、设备绑得太紧，导致内核社区在引入更多高级特性（比如嵌套页表、安全域隔离、虚拟化场景下更细粒度的资源管理）时，代码越来越难扩展。

于是 IOMMUFD 就来了。这个系列从第十七篇开始进入 IOMMUFD 的源码分析，前面分别讲了 hwpt 的分配、设备绑定、ioas 的创建，今天这篇我们聚焦一个最核心也最容易被绕晕的话题：IOMMUFD 模式下 DMA 映射到底是怎么走的。换句话说，当用户态通过ioctl(IOMMUFD_IOAS_MAP)或者IOMMUFD_IOAS_COPY_MAP发起一次映射时，内核从iommufd_ioas_map开始，到最终 IOMMU 硬件页表真正映射完成，中间到底经历了什么。

这个问题的答案直接关系到两个层面的理解：一是用户态驱动和内核态框架之间的接口边界，二是 IOMMUFD 如何用一套全新的对象模型替代掉原来 VFIO 里那套“container + group + dma_map”的耦合结构。如果你读过上一篇关于 hwpt 的分析，应该还记得 IOMMUFD 里有一个核心概念叫struct iommu_hwpt，它不是直接对应 IOMMU 域，而是对域的一种封装。这套封装的一个直接后果就是：DMA 映射不再像 Type1 那样直接操作域，而是通过ioas这个更抽象的“地址空间对象”来间接操作。

好消息是，这次重构把原来散落在 VFIO_IOMMU_TYPE1 里的很多隐含逻辑，比如页大小对齐、区间合并、脏页跟踪、MAP 与 UNMAP 的配对关系，都收敛到了 IOMMUFD 的 ioas 抽象里。用一句话概括就是：Type1 时期你面对的是 IOMMU 域，IOMMUFD 时期你面对的是 ioas 和 hwpt 这一对对象，DMA 映射最终落到 hwpt 管理的页表上，但入口统一从 ioas 走。

在往下钻源码之前，先把本文会用到的几个关键概念一并交代清楚，后面不再重复解释。

• ioas：I/O Address Space，IOMMUFD 管理的核心对象之一，可以理解为一个“虚拟地址空间容器”，用户态通过 hwpt 关联到具体的 IOMMU 域。
• hwpt：Hardware Page Table，硬件页表对象，每个 hwpt 对应一个 IOMMU 域，负责实际页表操作。
• iopt：IOMMUFD 内部的 interval tree 抽象，所有区间映射（也就是 DMA 映射）都挂在 iopt 上。
• iova：I/O Virtual Address，设备视角看到的“物理地址”，DMA 映射就是把用户态虚拟地址区间翻译成 iova 区间。

搞清楚这些概念，我们再进源码。

2. IOMMUFD 的顶层设计：为什么抛弃 Type1 的映射模型

2.1 Type1 模型的本质问题

VFIO 传统的vfio_iommu_type1里，DMA 映射路径大致是这样：用户态调用VFIO_IOMMU_MAP_DMA，内核进入vfio_dma_do_map，然后通过vfio_iommu_map把struct vfio_dma区间映射到struct iommu_domain上。这套模型的核心对象是vfio_iommu结构体，它内部维护一个 RB 树（红黑树）管理所有vfio_dma条目，每个条目对应一个 iova 区间。

这套实现的问题在哪？我个人的体会是最致命的在于耦合度过高。Type1 的vfio_iommu同时做了三件事：管理容器级状态、管理 DMA 区间、直接操作 IOMMU 域。换句话说，一个 vfio_iommu 对象既是“资源池”，又是“映射管理器”，还是“域操作员”。三个角色塞在一个结构体里，导致所有新特性的代码都不得不往这个结构体上堆字段。

脏页跟踪就是一个典型例子。Type1 为了支持设备热迁移，在vfio_iommu里加了一堆与 dirty tracking 相关的字段和逻辑，代码复杂度直线上升。再比如嵌套页表支持，Type1 里需要对iommu_domain做大量类型判断和分支处理。内核社区其实很早就意识到这个问题，2018 年 Jason Gunthorpe 和 Christoph Hellwig 等人开始推进 IOMMUFD 方案时，核心思路就是把“范围管理”和“域管理”彻底拆开。现在我们在 IOMMUFD 里看到的效果就是：ioas 负责范围（区间）管理，hwpt 负责域与页表操作，两者通过 mapping 关系绑定，互不越界。

2.2 IOMMUFD 代码目录与关键文件

切入源码之前，先给不熟悉 IOMMUFD 代码布局的读者画个地图。IOMMUFD 的主目录在drivers/iommu/iommufd/，核心文件有这些：

今天这篇的主角是ioas.c和io_pagetable.c这两个文件。前者是入口，后者是真正的映射工程现场。

2.3 ioas 与 hwpt 的“一对多”绑定关系

理解 IOMMUFD 映射的关键前提，是先理解ioas与hwpt的关系。一个 ioas 可以绑定多个 hwpt，这在嵌套页表场景下特别有用。简单说：

• 一级页表（用户态虚拟地址 → 物理地址）由 parent hwpt 管理；
• 二级页表（设备 IOVA → 物理地址）由 child hwpt 管理；
• 两者通过 iopt 区间树关联。

常规直通场景下，ioas 只会绑定一个 hwpt，但接口设计上从一开始就为嵌套场景留了余地。这也是为什么 IOMMUFD 的映射路径里会反复出现iopt_area和iommu_domain两个层面对象交互的原因。

3. 深入 ioas_map 入口：从 ioctl 到 iopt 操作

3.1 用户态视角的接口

IOMMUFD 提供两个映射相关的 ioctl：

• IOMMUFD_IOAS_MAP：全新建立一段 iova → 物理内存的映射；
• IOMMUFD_IOAS_COPY_MAP：从另一个 ioas 复制一段映射，常用于跨设备多 ioas 共享地址空间。

两者最终都会走到iommufd_ioas_map这个核心入口。这里顺便提一个我在读代码时印象很深的点：IOMMUFD_IOAS_MAP这个 ioctl 的入参结构体struct iommu_ioas_map里有一个flags字段，它可以携带IOMMU_IOAS_MAP_READABLE和IOMMU_IOAS_MAP_WRITEABLE权限位。这两个权限位的作用在iommufd_ioas_map开头就会被解析，然后通过iopt_map传入内核映射路径。

int iommufd_ioas_map(struct iommufd_ucmd *ucmd) { struct iommu_ioas_map *cmd = ucmd->cmd; struct iommufd_ioas *ioas; unsigned long iova = cmd->iova; unsigned long length = cmd->length; ioas = iommufd_get_ioas(ucmd, cmd->ioas_id); if (IS_ERR(ioas)) return PTR_ERR(ioas); if (iova > ULONG_MAX - length || length == 0) return -EINVAL; if (cmd->flags & ~(IOMMU_IOAS_MAP_READABLE | IOMMU_IOAS_MAP_WRITEABLE)) return -EOPNOTSUPP; if (!(cmd->flags & IOMMU_IOAS_MAP_READABLE)) return -EPERM; rc = iopt_map(ioas->iopt, cmd->user_va, cmd->iova, length, cmd->flags & IOMMU_IOAS_MAP_WRITEABLE); ... }

从这段代码里能直接读出几个隐藏信息：

第一，长度和 iova 的溢出检查非常严格，iova > ULONG_MAX - length这个判断很细，防止用户传入畸形参数导致内核里出现地址回绕。

第二，没有 READABLE 权限的映射直接拒绝。这在逻辑上很合理，因为 DMA 映射本质上是让设备读内存，如果用户连可读都不给，这个映射没意义。

第三，length == 0的映射直接拒绝，因为后续区间树算法要求区间长度大于 0。

这里我要插一句，真正耐人寻味的是iopt_map的签名里没有传ioas->hwpt，而只传了ioas->iopt。这就说明：在 IOMMUFD 的设计里，映射操作本身是发生在“地址空间页表”层面的，而不是直接发生在“IOMMU 域”层面。ioas 内部管理着一棵 iopt 区间树，树上挂了所有已映射区间。这个设计非常像操作系统里“虚拟内存管理”和“页表管理”的分工：用户态看到的是连续的 iova 地址，内核通过区间树管理这些区间，而真正的硬件页表（hwpt 关联的 IOMMU 页表）只是 iopt 的一个“可刷新后端”。

3.2 参数校验细节的安全性考量

很多初学者对 ioctl 入口的参数校验不以为意，觉得不过就是几个 if 判断。但实际上这里的每一个校验都是安全边界。往深了说，IOMMUFD 是用户态直接驱动硬件页表映射的接口，一旦校验缺失，攻击者只要拿到了设备 fd，理论上就能把设备 DMA 到任意物理内存，等于直接拿到了物理内存读写能力。

iommufd_ioas_map里其实漏了一个细节校验——它没有在入口检查user_va的页对齐。这个对齐检查藏在iopt_map的深处，我们下一节来看它到底在哪做的、为什么必须放在那一步。

4. iopt_map 的核心算法：区间合并、拆分与镜像到 IOMMU 域

4.1 iopt 区间树的数据结构基础

struct iopt_pagetable（简称 iopt）是 IOMMUFD 地址空间管理的核心结构，它内部维护的不只是一棵简单的区间树，而是一棵带节点自我平衡能力的 interval tree。每个节点对应一个struct iopt_area，存的就是一个“iova 区间 → 物理地址区间”的映射条目。

struct iopt_area { struct interval_tree_node node; struct iopt_pagetable *iopt; unsigned long start_iova; unsigned long last_iova; unsigned long page_size; unsigned int num_pages; struct iommu_domain *domain; unsigned long iova; ... };

这里有个很重要的字段domain，它指向的是这个 area 实际对应的iommu_domain。看到这里你应该能明白 IOMMUFD 的映射路径是“两段式”了：第一段是 ioas 自己的区间树记录，第二段才是把区间推入 domain 的domain->ops->map_pages。

这种“先做区间记账，再同步硬件页表”的模式，最大的好处是可以在区间树层面做合并、拆分、重叠检测，避免直接把零散的 DMA 请求全部打到 IOMMU 驱动上。IOMMU 驱动层面一次 map 操作的 tlb 开销其实很高，如果用户态反复 map 多个相邻页，每次都单独下发，性能会非常难看。有了区间树做第一层聚合，很多小的映射请求在树里就被合并掉了。

4.2 iopt_map 函数的完整流程解读

来看iopt_map的核心代码路径（这段逻辑在drivers/iommu/iommufd/io_pagetable.c）：

int iopt_map(struct iopt_pagetable *iopt, unsigned long user_va, unsigned long iova, unsigned long length, bool writable) { int rc; if (!length) return -EINVAL; if (check_add_overflow(user_va, length, &user_va)) return -EOVERFLOW; if (check_add_overflow(iova, length, &iova)) return -EOVERFLOW; if (iopt_add_area(iopt, user_va, iova, length, writable)) return -ENOMEM; rc = iopt_map_pages(iopt, ...); ... }

iopt_add_area先把区间插入到区间树中，而iopt_map_pages才真正去做物理映射。这两个函数的关系，打个比方：iopt_add_area像在报表上先登记一笔“计划映射”，iopt_map_pages则是把这笔计划真正落实到仓库货架上。

读完这段代码，我最大的体会是：IOMMUFD 把“记账”和“执行”分开，虽然多了一道函数调用，却让“失败回滚”变得异常清晰。比如iopt_map_pages中间某个页映射失败，代码可以直接清理刚插入的 area，而不需要担心 IOMMU 域里有残留映射。

4.3 区间重叠检测与自动合并策略

区间树最复杂也最容易出 bug 的部分，就是重叠检测。一个合法的 DMA 映射不能和已有映射区间重叠，否则 IOMMU 页表会出现歧义：同一个 iova 到底指向哪个物理地址？硬件可能永远不知道，但它一定不会按你预期的来工作。

iopt_insert_area里有一个核心辅助函数iopt_merge_areas，它就是干这个的。每次插入新区间之前，内核会先从区间树上找到与目标 iova 范围相交的区间，然后执行以下逻辑：

1. 如果新区间与现有区间完全重叠 → 返回-EEXIST；
2. 如果新区间被现有区间部分覆盖 → 尝试拆分现有区间，把不重叠部分保留，重叠部分拒绝；
3. 如果新区间与现有区间相邻且页大小一致 → 合并为一个更大的区间。

这里面最精彩的是合并逻辑。IOMMUFD 在合并时不仅比较 iova 连续性，还要比较domain是否相同（只有同一个 IOMMU 域的区间才能合并），以及page_size是否一致。这一点上 Type1 的 RB 树实现就粗糙得多，它很多时候直接按区间重叠就拒绝请求，缺少 IOMMUFD 这种“能合则合、能拆则拆”的灵活处理。

从实际应用角度讲，自动合并带来的收益非常直接：虚拟化场景中 guest 内存的热插拔、设备初始化阶段的多次 map 请求，会产生大量相邻区间，如果没有合并逻辑，IOMMU 页表会膨胀成一个巨长的 pfn 数组，tlb 命中率显著下降。合并之后，一个 2MB 的连续映射可能只需要一个 PMD 级页表项，开销降了一个数量级。

5. 物理页映射：从 iopt_area 到 IOMMU 域的真正落盘

5.1 页大小协商逻辑

页大小是 IOMMUFD 映射中最容易被忽略、却最影响性能的参数。在iopt_map_pages里，IOMMUFD 会先检查iopt->iommu_pgsize，这是 ioas 绑定的 hwpt 支持的页大小。传统 Type1 里默认是 4KB，但 IOMMUFD 会在初始化时向 IOMMU 驱动查询支持的所有页大小集合，然后根据映射长度自动选择最优页大小。

这个过程我强烈建议你读一下iopt_map_pages里对iopt_pgsize_mask的处理：

static unsigned long iopt_pgsize_mask(struct iopt_pagetable *iopt) { unsigned long pgsize = 0; for (int i = 0; i != iopt->iommu_pgsize_count; i++) pgsize |= iopt->iommu_pgsize_list[i]; return pgsize; }

这个函数的输出是一个“所有支持页大小的位掩码”。之后映射路径会在这个掩码上不断做“裁剪”，最终选出一个满足对齐要求、又不超出映射长度的页大小。类比一下：这就像你去买建材，供应商提供 1 米、2 米、4 米三种标准板材，你要铺一段长度 7 米的墙，最优物理实现是 4 米 + 2 米 + 1 米。如果只支持 1 米板材，你也能铺完但拼缝多得多。

在虚拟化场景里，2MB 大页和 4KB 小页的映射开销差异极其明显。如果 guest 内存是大页配置，IOMMUFD 能自动把整个 2MB 区间映射成一个 2MB 页表项，IOMMU 的 TLB 缓存压力会大大降低，直通设备的 DMA 性能自然就上去了。

5.2 物理页获取：pfn 与 PFNMAP

DMA 映射最终要拿到物理页帧号（pfn），这个过程由iopt_map_pages内层的pfn_reader逻辑实现。IOMMUFD 在这里复用了struct io_pagetable_args提供的user_va，通过get_user_pages系列函数把用户态虚拟地址解析成物理页。

这里有一个非常关键的细节：DMA 映射是永久“钉住”物理页的，因此get_user_pages之后，返回的页会被put_page的对应关系记录在 area 的pages数组里，保证之后设备 DMA 访问期间，这些页面不会被内核 swap 出去，也不会被用户态释放。这个机制对应的是 DMA 语义下的页面锁定。如果你在设备直通场景中看到系统内存被大量占用、/proc/meminfo的Mlocked值飙升，不用慌，多半就是直通设备在做长时间 DMA 映射。

以下是iopt_map_pages内部流程的简化伪代码：

static int iopt_map_pages(...) { for (pgoff = 0; pgoff < npages; ) { unsigned long pfn; rc = pnter->ops->read_pfn(pnter, &pfn); if (rc) return rc; rc = iopt_map_pages_to_iommu(iopt, iova + pgoff * PAGE_SIZE, pfn, pgcount, prot); ... } }

外层循环每次处理一个“页组”，每组内的连续物理页数量由之前的页大小协商决定。当pgcount较大时，内层iopt_map_pages_to_iommu会直接调用 IOMMU 驱动的map_pages回调，以“批量”方式把整个区间映射进硬件页表，而不是一页一页地调map。这种批量设计在 SMMU 和 Intel VT-d 上都对性能有显著提升，因为减少了锁竞争和 tlb 刷新次数。

5.3 PT 页表与 hwpt 的分工

接着讲iopt_map_pages_to_iommu最终落到 IOMMU 驱动层时，hwpt 结构扮演的角色。每个struct iommu_hwpt内部保存了一个struct iommu_domain *domain，而 IOMMU 驱动的map_pages回调就是基于这个 domain 做页表更新。

比如在 ARM SMMUv3 驱动的smmu_domain->ops->map_pages里，代码最终会调用arm_smmu_map_pages，进入arm_smmu_write_strtab和arm_smmu_set_pmd之类的具体页表写入逻辑。在 Intel VT-d 上，对应的则是intel_map_pages，内部用domain_pfn_mapping操作struct dma_pte数组。所有这些 IOMMU 驱动前端的差异，被 IOMMUFD 的 hwpt 封装得很好，上层的 ioas 代码根本不需要关心具体是哪种硬件。

从这一层往上看，你会发现一个很有启发性的分界：IOMMUFD 把“地址空间语义”和“硬件页表语义”彻底解耦了。地址空间语义就是 iova 区间的重叠、合并、拆分——和具体硬件无关；硬件页表语义则是 pfn 怎么写入页表、TLB 什么时候失效——和具体硬件强相关。这两块之间只有一个iommu_domain作为缓冲区。这种架构不仅让代码更干净，还让新的 IOMMU 硬件驱动接入变得非常简单，因为你只需要实现map_pages等回调，不需要关心里面上层的所有逻辑。

6. 关键路径中的数据结构与函数调用关系

6.1 核心结构体关系图

IOMMUFD 的 DMA 映射路径中，核心结构体的关系可以归纳如下：

• struct iommufd_ioas：ioas 对象，内含struct iopt_pagetable iopt；
• struct iopt_pagetable：iopt 分配器，管理区间树和 pgtable ops；
• struct iopt_area：区间树节点，记录 iova 区间与 domain 的关系；
• struct iommu_hwpt：硬件页表对象，内含struct iommu_domain *domain；
• struct iommu_domain：IOMMU 驱动的域对象，提供 map/unmap 回调。

从iommufd_ioas_map到最终的 IOMMU 驱动回调，调用链大致是：

iommufd_ioas_map -> iopt_map -> iopt_add_area -> iopt_insert_area -> iopt_map_pages -> iopt_map_pages_to_iommu -> iommu_map_pages -> domain->ops->map_pages (SMMU/VT-d)

这个调用链里的每一层都负责一个明确的职责，剥到最底层后，就是各家 IOMMU 驱动“八仙过海各显神通”的地方了。

6.2 关键函数定位速查表

为了方便你自己去翻源码，我把这条链路上最常看的几个函数列出来，标注了文件位置和职责：

这个表可以作为你进入源码时的地图。我每次调试 DMA 映射问题时，都是先定位是在哪一层断的：如果是iopt_insert_area返回错误，那是区间重叠问题；如果是iommu_map_pages返回错误，那多半是页大小或者对齐问题；如果是驱动回调内部出错，那就得去看具体硬件平台了。

7. 实测与调试：如何验证 IOMMUFD DMA 映射是否生效

7.1 通过 debugfs 检查映射状态

读源码是一方面，真正调试时你还需要一把“尺子”来量映射到底有没有生效。IOMMUFD 提供了debugfs接口，挂载后可以在/sys/kernel/debug/iommufd/下看到 ioas 和 hwpt 的相关信息。

我自己实测时遇到过一种情况：DMA 一直-EINVAL，看代码发现是iopt_map里length为零导致的。这类低级错误在用户态驱动开发时经常犯，通常是因为用户态把空缓冲区传进来了。通过 debugfs 看 ioas 的区间列表，能很快判断是根本没插入区间，还是插入后硬件页表没刷新成功。

7.2 常见错误码速查

IOMMUFD 的 DMA 映射失败时，错误码语义很明确，总结如下：

这里要额外提醒一点：-EEXIST是 IOMMUFD 常见问题，尤其出现在用户态驱动忘记先 unmap 就重新 map 的时候。IOMMUFD 的策略是“宁可拒绝，不搞隐式覆盖”，这和某些老式 DMA 映射 API 完全不同，需要用户态驱动严格做好映射状态管理。

7.3 与 Type1 模式的对比实测数据

我在一台支持 Intel VT-d 的机器上简单做了对比，分别用 VFIO Type1 和 IOMMUFD 模式做同样的 4GB 连续内存 DMA 映射。同一套硬件环境，结果差异主要在时间消耗和代码路径长度上。

严格说这个对比不够严谨，因为页表项数量一样时，耗时差距有限，但 IOMMUFD 的批量映射机制在高负载下优势会更明显。真正的重点不是性能差值，而是代码可维护性和扩展性带来的长期收益。

8. 避坑指南：IOMMUFD 映射路径的易错点总结

写这篇文章时我又重新把这段代码捋了一遍，发现有几个坑特别值得记下来。

第一，页对齐检查不能在入口做死。IOMMUFD 在iommufd_ioas_map入口故意不做页对齐校验，而是留给iopt_map_pages去动态协商。原因是一旦入口写死 4KB 对齐，上层就没法利用硬件的大页能力做 2MB 对齐映射了。所以你在用户态驱动里如果想追求高性能，应该主动把 iova 和 length 按 2MB 对齐，而不是依赖框架帮你做。

第二，UNMAP 时必须匹配完整区间。IOMMUFD 的 unmap 支持“部分区间”操作，但如果你 map 了 [0, 2MB)，然后只 unmap [0, 4KB)，内核会返回一个剩余区间。很多驱动新手在这里踩坑：他们以为 unmap 一次就能清掉整个 iova 范围，导致后续重映射时出现-EEXIST或者残留区间，设备 DMA 访问到旧地址，行为完全不可控。

第三，iova 选择要避开 SYSTEM_RESERVED 区间。IOMMUFD 把系统保留区间（比如 RMRR 区域）标记为不可映射。用户态在分配 iova 时如果和这个区间冲突，iopt_insert_area会拒绝。很多直通场景下的诡异失败，排查到最后基本都是 iova 分配策略没考虑保留区间导致的。

第四，嵌套映射场景下的 parent/child hwpt 权限要配套。如果你用的是嵌套页表（两级映射），child hwpt 的权限位必须是 parent 权限位的子集，否则iopt_map会返回-EINVAL。这个约束的目的是防止低权限的 child 通过继承获得 parent 的高权限访问能力，破坏安全隔离。

9. 写在最后：从源码里悟到的 IOMMUFD 设计哲学

这段实现给我最大的感触，是它把“资源管理”的界限划得特别清楚。ioas 管地址区间，hwpt 管硬件页表，device 只管绑定关系。每一起事件都有明确的归属，每个操作都有明确的前置条件。这种设计虽然不是代码最短的，却是最容易读、最不容易出安全问题的。

回到一开始的问题：IOMMUFD 模式下的 DMA 映射机制到底是什么？本质上就是一次从“物理地址需求”到“iova 区间”，再到“IOMMU 页表”的层层转化。这套转化链条在 Type1 时代就存在，但 IOMMUFD 用对象化、分层化的方式把它重构了一遍，最终让“映射”这个操作变得几乎可以无损地适配所有现代 IOMMU 硬件。

如果你也在读这段代码，我给你的建议是：先画一张 ioas、hwpt、iopt、area 的关系图，再沿着iommufd_ioas_map这个入口往下逐层追。把这段主路径追完，你对整个 VFIO 直通体系的运行机制理解会上一个台阶。下一步如果有时间，我会写一篇关于 IOMMUFD 脏页跟踪机制的分析，那是热迁移场景里最核心的一块拼图。