📚 课程目录第4章驱动中的DMA编程模型

4、驱动中的DMA编程模型

直接内存访问（DMA）是高性能驱动实现零拷贝数据传输的核心机制。在 Windows 驱动框架中，WDM 与 WDF 提供了两套差异显著的 DMA 编程模型。理解这两种模型的结构、API 及数据流，是分析 BugCheck 0xD1（DRIVER_IRQL_NOT_LESS_OR_EQUAL） 在 DMA 路径上触发原因的前提。

  关键认知： 绝大多数与 DMA 相关的 0xD1 蓝屏，根源在于驱动在错误的 IRQL 级别调用了分页内存访问，或 DMA 缓冲区映射/同步顺序错误。WDF 通过内置的 DMA 事务抽象，显著降低了此类错误的发生概率。

4.1 WDM 驱动 DMA 模型

WDM（Windows Driver Model）下的 DMA 编程是“手动挡”模式。驱动开发者需要直接与内存管理器、I/O 管理器以及总线驱动交互，管理适配器对象、映射寄存器、散列/聚合列表（Scatter/Gather List）等底层资源。

4.1.1 核心对象与流程

适配器对象（Adapter Object）： 通过 IoGetDmaAdapter 获取，代表物理 DMA 通道。驱动需指定设备描述（DEVICE_DESCRIPTION）来协商传输宽度、速度等参数。
映射寄存器（Map Register）： 系统有限的硬件资源，用于将虚拟地址锁定并映射到物理地址，供 DMA 引擎直接访问。
散列/聚合列表（S/G List）： 描述不连续物理缓冲区的结构体数组，支持一次 DMA 操作跨越多个内存页。

WDM DMA 典型步骤：

调用 IoGetDmaAdapter 获取适配器对象。
调用 AllocateAdapterChannel 分配映射寄存器。
在回调中调用 MapTransfer 构建 S/G List。
启动 DMA 硬件传输。
在 ISR/DpcForIsr 中调用 FlushAdapterBuffers 并释放映射寄存器。

4.1.2 常见 WDM DMA API

API 名称	功能	IRQL 要求
`IoGetDmaAdapter`	获取 DMA 适配器对象指针	PASSIVE_LEVEL
`AllocateAdapterChannel`	分配映射寄存器并调用回调	DISPATCH_LEVEL
`MapTransfer`	构建散列/聚合列表	DISPATCH_LEVEL
`FlushAdapterBuffers`	刷新适配器内部缓存，保证数据一致性	DISPATCH_LEVEL
`FreeAdapterChannel`	释放适配器通道和映射寄存器	DISPATCH_LEVEL

0xD1 高发陷阱： 在 WDM 模型中，MapTransfer 返回的物理地址指向的缓冲区在映射寄存器释放前是锁定的。如果驱动在 FreeAdapterChannel 之后仍尝试访问该缓冲区，或是在 DISPATCH_LEVEL 以上错误地访问了可分页内存，将直接触发 BugCheck 0xD1。

4.2 WDF 驱动 DMA 模型

WDF（Windows Driver Frameworks）将 DMA 操作封装为 DMA 事务（DMA Transaction） 和 DMA 公共缓冲区（Common Buffer） 等高阶抽象。驱动开发者只需描述传输意图，框架自动管理映射寄存器、S/G List 和 IRQL 升降。

4.2.1 核心对象与流程

WDFDMAENABLER： DMA 启用器对象，在初始化时配置设备 DMA 属性（如传输宽度、缓存一致性）。
WDFDMATRANSACTION： DMA 事务对象，代表一次完整的 DMA 传输请求。框架自动拆分大传输为多个包。
WDFCOMMONBUFFER： 公共缓冲区对象，分配连续物理内存，适合设备直接读写。

WDF DMA 典型步骤：

在 EvtDriverDeviceAdd 中调用 WdfDmaEnablerCreate。
在 I/O 请求处理中调用 WdfDmaTransactionCreate。
调用 WdfDmaTransactionInitialize 设置回调。
调用 WdfDmaTransactionExecute 启动传输。
在 EvtProgramDma 回调中编写硬件编程逻辑。

4.2.2 常见 WDF DMA API

API 名称	功能	调用时机
`WdfDmaEnablerCreate`	创建 DMA 启用器，配置最大传输长度	PASSIVE_LEVEL
`WdfDmaTransactionCreate`	创建 DMA 事务对象	PASSIVE_LEVEL
`WdfDmaTransactionInitialize`	初始化事务，绑定 EvtProgramDma 回调	PASSIVE_LEVEL
`WdfDmaTransactionExecute`	执行事务，框架自动提升 IRQL 并调用回调	PASSIVE_LEVEL
`WdfCommonBufferCreate`	分配连续物理内存公共缓冲区	PASSIVE_LEVEL

4.3 WDM 与 WDF DMA 模型对比

对比维度	WDM DMA	WDF DMA
抽象层次	底层，直接操作适配器对象	高层，事务化抽象
映射寄存器管理	手动分配/释放	框架自动管理
IRQL 管理	驱动负责在 DISPATCH_LEVEL 调用	框架自动升降 IRQL
错误率（0xD1）	较高，易出现 IRQL 违规	较低，框架提供保护
灵活性	高，可精细控制硬件时序	中，受限于框架回调模型

4.4 常见 DMA API 速查表

以下 API 在调试 BugCheck 0xD1 时经常出现在调用栈中，需要重点掌握其 IRQL 约束和错误返回码。

API	所属框架	典型错误返回	0xD1 关联场景
`IoGetDmaAdapter`	WDM	STATUS_INSUFFICIENT_RESOURCES	适配器对象为空，后续调用崩溃
`AllocateAdapterChannel`	WDM	STATUS_INSUFFICIENT_RESOURCES	映射寄存器耗尽，回调未执行
`MapTransfer`	WDM	STATUS_UNSUCCESSFUL	返回无效物理地址，设备访问错误内存
`WdfDmaTransactionExecute`	WDF	STATUS_INVALID_DEVICE_STATE	事务重复执行，导致双重编程
`WdfCommonBufferCreate`	WDF	STATUS_INSUFFICIENT_RESOURCES	分配失败，后续 DMA 使用空指针

  调试建议： 当遇到 BugCheck 0xD1 且调用栈包含上述 API 时，应优先检查：

是否在正确的 IRQL 调用了 API（WDM 尤其关键）。

映射寄存器是否在中断处理完成后及时释放。

WDF 事务是否在同一个请求中重复执行。