本附录按调用环节汇总专栏中讨论过的 DMA 相关接口范围涵盖内核 dma-mapping 接口、散列表、dma-buf 与 P2PDMA、用户页面与 HMM、IOMMU 内核接口以及 VFIO、iommufd、io_uring 与 RDMA verbs 等用户态接口。接口名称以本专栏所依据的内核源码树为准成对出现的接口映射与解除映射、分配与释放合并为一行。接口在不同内核版本中的签名可能变化使用时应以目标内核的头文件为准。一、设备寻址能力声明驱动在探测阶段向 dma-mapping 层声明设备的寻址能力与分段约束后续的分配与映射均以此为依据。接口作用与要点dma_set_mask()/dma_set_coherent_mask()分别设置流式映射与一致性分配所用的 DMA 地址掩码平台无法满足时返回错误驱动应回退到更窄的掩码dma_set_mask_and_coherent()同时设置上述两种掩码是多数驱动的常用写法dma_get_required_mask()返回覆盖系统全部内存所需的掩码供驱动判断是否有必要启用更宽的寻址模式dma_addressing_limited()判断设备掩码能否覆盖全部内存返回真表示部分映射可能经由 swiotlb 反弹dma_set_max_seg_size()声明设备单个 DMA 段的最大长度约束散列表合并的结果dma_set_seg_boundary()声明 DMA 段不得跨越的地址边界dma_set_min_align_mask()要求 swiotlb 反弹时保留原地址在该掩码范围内的低位偏移dma_max_mapping_size()返回单次映射允许的最大长度启用 swiotlb 时受反弹缓冲区段长限制dma_opt_mapping_size()返回不致明显降低映射效率的建议长度供驱动确定传输粒度dma_get_merge_boundary()返回 IOMMU 能够合并相邻段的边界粒度返回 0 表示不支持合并二、一致性分配一致性缓冲区在其生命周期内由 CPU 与设备同时访问无需显式同步适用于描述符环、完成队列等小数据量、且生命周期较长的控制结构。接口作用与要点dma_alloc_coherent()/dma_free_coherent()分配一致性缓冲区同时返回 CPU 虚拟地址与 DMA 地址在非一致平台上通常以不可缓存映射实现dma_alloc_attrs()/dma_free_attrs()带属性的通用分配接口dma_alloc_coherent()是其不带属性的形式dmam_alloc_coherent()托管版本驱动解除绑定时自动释放dma_mmap_attrs()把一致性缓冲区映射到用户态地址空间dma_pool_create()/dma_pool_alloc()/dma_pool_free()/dma_pool_destroy()在一致性内存上切分固定大小的小块可指定对齐与不得跨越的边界适用于大量小型描述符三、非一致与非连续分配此类接口分配的内存可被 CPU 缓存访问所有权交接须由驱动显式同步。接口作用与要点dma_alloc_noncoherent()/dma_free_noncoherent()分配可缓存的 DMA 缓冲区返回 CPU 虚拟地址访问前后须调用dma_sync_single_for_*()dma_alloc_pages()/dma_free_pages()与上一行语义相同但返回struct page便于纳入页面管理dma_alloc_noncontiguous()/dma_free_noncontiguous()分配物理上可不连续的内存以sg_table返回IOMMU 处于翻译模式时可获得连续的 IOVA四、流式映射流式映射把已有的内核内存临时交给设备访问映射期间缓冲区归设备所有结束后必须解除映射。接口作用与要点dma_map_single()/dma_unmap_single()映射一段线性映射区内的内核虚拟地址不适用于 vmalloc 地址dma_map_page()/dma_unmap_page()以页面与页内偏移指定缓冲区可映射高端内存页dma_map_phys()/dma_unmap_phys()以物理地址指定缓冲区是流式映射的统一入口其余单段映射接口均可归结到此配合DMA_ATTR_MMIO可映射没有struct page的 MMIO 区域dma_map_resource()/dma_unmap_resource()映射设备 MMIO 物理地址用于设备访问另一设备的 BAR不执行 cache 维护dma_mapping_error()检查映射返回的 DMA 地址是否有效每次单段映射后都必须调用五、散列表散列表描述由多段内存组成的缓冲区。映射后的 DMA 段数可能少于原始段数遍历时须使用映射后的段数。接口作用与要点sg_alloc_table()分配并初始化sg_tabledma_map_sg()/dma_unmap_sg()映射散列表返回映射后的 DMA 段数失败时返回 0解除映射时须传入映射前的原始段数dma_map_sgtable()/dma_unmap_sgtable()以sg_table为参数的版本成功返回 0、失败返回负的错误码并把映射后的段数记录在表中可避免两种段数混用for_each_sg()/for_each_sgtable_dma_sg()遍历散列表后者按映射后的 DMA 段遍历sg_dma_address()/sg_dma_len()读取段的 DMA 地址与长度二者只在映射后有效不可与 CPU 侧的页面与长度混用六、同步与所有权交接流式映射与非一致分配的缓冲区在 CPU 与设备之间交接所有权时须调用同步接口完成必要的 cache 维护或 swiotlb 拷贝。接口作用与要点dma_sync_single_for_cpu()/dma_sync_single_for_device()把单段缓冲区的所有权交还 CPU 或交给设备dma_sync_single_range_for_cpu()/dma_sync_single_range_for_device()只同步映射中的一个子区间用于接收缓冲区按实际长度同步dma_sync_sg_for_cpu()/dma_sync_sg_for_device()散列表版本dma_sync_sgtable_for_cpu()/dma_sync_sgtable_for_device()以sg_table为参数的散列表版本dma_need_sync()判断某一映射是否需要同步返回假时驱动可在热路径上省略同步调用page_pool的PP_FLAG_DMA_MAP/PP_FLAG_DMA_SYNC_DEV由 page_pool 代为完成页面的 DMA 映射以及页面回收时交给设备的同步使映射在页面循环使用期间保持有效七、两步 IOVA 映射两步接口把 IOVA 分配与页表填充分开使多段物理内存映射到一段连续 IOVA并只做一次 IOTLB 同步。接口作用与要点dma_iova_try_alloc()预分配一段 IOVA设备不经 IOMMU 翻译时返回假调用者应回退到逐段流式映射dma_iova_link()/dma_iova_unlink()把一段物理内存映射到已分配 IOVA 的指定偏移或解除该映射dma_iova_sync()对已建立的全部链接一次完成 IOMMU 映射同步dma_use_iova()判断当前状态是否使用了两步 IOVA 映射供解除映射路径选择对应的处理八、方向与属性接口作用与要点DMA_TO_DEVICE/DMA_FROM_DEVICE/DMA_BIDIRECTIONAL数据流向决定映射与同步时执行写回还是失效映射与同步、解除映射须使用相同方向DMA_ATTR_SKIP_CPU_SYNC映射或解除映射时跳过 cache 维护由驱动在合适时机自行同步DMA_ATTR_WEAK_ORDERING允许平台对该映射的访问放宽排序在 PCIe 上对应宽松排序DMA_ATTR_WRITE_COMBINE一致性分配时以写合并属性建立 CPU 映射DMA_ATTR_NO_KERNEL_MAPPING一致性分配时不建立内核虚拟映射适用于 CPU 不访问的大缓冲区DMA_ATTR_FORCE_CONTIGUOUS要求分配物理连续的内存DMA_ATTR_NO_WARN分配或映射失败时不输出告警适用于设有回退路径的调用DMA_ATTR_MMIO表明被映射的物理地址不是普通系统内存通常为 MMIOdma-mapping 层不对其执行 cache 维护用于点对点映射PCI 设备须先经 P2PDMA 接口判定是否适用九、内存屏障接口作用与要点dma_wmb()保证 CPU 对一致性内存的写入先于后续写入对设备可见典型用法是在置位描述符所有权位之前dma_rmb()保证读到设备写回的状态位之后再读取同一描述符的其余字段十、跨设备共享与点对点接口作用与要点dma_buf_export()/dma_buf_fd()导出方把缓冲区封装为 dma-buf并取得可交给用户态的文件描述符dma_buf_get()/dma_buf_put()导入方由文件描述符取得 dma-buf 引用或释放该引用dma_buf_attach()/dma_buf_detach()静态导入方挂接到 dma-buf映射期间缓冲区保持固定dma_buf_dynamic_attach()动态导入方挂接提供dma_buf_attach_ops在缓冲区即将移动时经invalidate_mappings()接收通知dma_buf_map_attachment()/dma_buf_unmap_attachment()取得导入设备视角下的sg_table其中的 DMA 地址由导出方按导入设备生成dma_buf_pin()/dma_buf_unpin()动态导入方固定缓冲区使导出方在解除固定之前不再移动它仅限扫描输出等有限场景dma_buf_begin_cpu_access()/dma_buf_end_cpu_access()界定 CPU 访问 dma-buf 的区间由导出方完成相应的 cache 维护dma_buf_vmap()/dma_buf_vunmap()取得 dma-buf 的内核虚拟映射pci_p2pdma_distance()计算 P2P 内存提供方与各访问方之间的拓扑距离返回负值表示不支持点对点传输十一、用户页面与设备页表镜像接口作用与要点pin_user_pages()/pin_user_pages_fast()/pin_user_pages_remote()固定用户态页面供 DMA 访问长期固定须带FOLL_LONGTERMhmm_range_fault()读取进程页表在指定区间的快照必要时触发缺页供设备页表镜像使用mmu_interval_notifier_insert()/mmu_interval_read_begin()/mmu_interval_read_retry()注册区间失效通知并以序列号检测快照期间是否发生了页表变化migrate_vma_setup()/migrate_vma_pages()/migrate_vma_finalize()在系统内存与设备私有内存之间分三步迁移页面十二、IOMMU 内核接口接口作用与要点iommu_map()/iommu_unmap()在指定 IOMMU 域中建立或解除 IOVA 到物理地址的映射由 dma-iommu 层或 VFIO 等直接管理域的使用者调用iommu_sva_bind_device()/iommu_sva_unbind_device()把设备绑定到进程地址空间使设备以进程虚拟地址发起 DMAiommu_sva_get_pasid()取得绑定对应的 PASID由驱动写入设备的工作描述符十三、用户态接口接口作用与要点VFIO_GROUP_SET_CONTAINER传统 VFIO 接口中把 IOMMU group 加入容器VFIO_IOMMU_MAP_DMA/VFIO_IOMMU_UNMAP_DMA在容器的 IOMMU 域中建立或解除用户态虚拟地址到 IOVA 的映射内核同时固定对应页面VFIO_DEVICE_BIND_IOMMUFD把 VFIO 设备文件绑定到 iommufdIOMMU_IOAS_MAPiommufd 中在 I/O 地址空间对象内建立映射IORING_REGISTER_BUFFERS向 io_uring 预先注册缓冲区页面固定一次避免每次 I/O 重复固定IORING_OP_SEND_ZC零拷贝发送第一个完成事件只表示数据已交给协议栈缓冲区须在收到带IORING_CQE_F_NOTIF标志的通知之后才能复用IORING_REGISTER_ZCRX_IFQ注册零拷贝接收所用的网络接口队列与内存区域ibv_reg_mr()注册 RDMA 内存区域固定页面并取得本地与远端访问密钥ibv_reg_dmabuf_mr()以 dma-buf 文件描述符注册内存区域用于网卡直接访问 GPU 显存ibv_post_send()/ibv_post_recv()向队列对提交发送或接收工作请求十四、典型调用顺序一致性缓冲区dma_set_mask_and_coherent()→dma_alloc_coherent()→ CPU 与设备共同访问必要处以dma_wmb()/dma_rmb()排序 →dma_free_coherent()。发送方向的流式映射CPU 填充数据 →dma_map_single()或dma_map_page()→dma_mapping_error()→ 设备读取 → 完成中断 →dma_unmap_single()或dma_unmap_page()。接收方向的循环缓冲区dma_map_page()DMA_FROM_DEVICE→ 设备写入 →dma_sync_single_for_cpu()→ CPU 处理 →dma_sync_single_for_device()→ 缓冲区重新交给设备直至最终dma_unmap_page()。散列表sg_alloc_table()并填充 →dma_map_sgtable()→for_each_sgtable_dma_sg()以sg_dma_address()/sg_dma_len()填写设备描述符 → 设备访问 →dma_unmap_sgtable()。系列导航上一篇《附录 A 术语表》