DMA_COMPLETION_ROUTINE回调函数 (wdm.h)

项目
02/29/2024

DmaCompletionRoutine 回调例程通知之前请求系统 DMA 传输的驱动程序此传输已完成。

语法

DMA_COMPLETION_ROUTINE DmaCompletionRoutine;

void DmaCompletionRoutine(
  [in] PDMA_ADAPTER DmaAdapter,
  [in] PDEVICE_OBJECT DeviceObject,
  [in] PVOID CompletionContext,
  [in] DMA_COMPLETION_STATUS Status
)
{...}

参数

[in] DmaAdapter

指向 DMA_ADAPTER 结构的指针。此结构是表示驱动程序的系统 DMA 通道的适配器对象。

[in] DeviceObject

指向 DEVICE_OBJECT 结构的指针。此结构是物理设备对象 (PDO) ，表示所请求的 DMA 操作的目标设备。

[in] CompletionContext

指向 DmaCompletionRoutine 例程的驱动程序确定上下文的指针。此上下文是驱动程序之前传递给启动系统 DMA 传输的 MapTransferEx 调用的 CompletionContext 参数值。

[in] Status

DMA 传输的完成状态。此参数是一个 DMA_COMPLETION_STATUS 枚举值，指示 DMA 传输是否成功完成。

返回值

无

备注

作为一个选项，驱动程序可以实现 DmaCompletionRoutine 例程。当驱动程序请求系统 DMA 传输时，驱动程序可以通过请求提供指向此例程的指针。 DMA 传输完成后，会自动调用 DmaCompletionRoutine 例程来通知驱动程序。

仅当驱动程序请求的 DMA 传输使用可在 DMA 传输完成后生成中断的系统 DMA 控制器时，才会调用驱动程序的 DmaCompletionRoutine 例程。使用总线主 DMA 设备或使用不生成中断的系统 DMA 控制器的驱动程序必须使用其他方法来确定 DMA 传输何时完成。例如，此驱动程序可能会使用计时器中断定期轮询 DMA 传输的状态。

驱动程序可以提供指向 DmaCompletionRoutine 例程的指针作为 MapTransferEx 例程的可选参数。

示例

若要定义 DmaCompletionRoutine 回调例程，必须首先提供一个函数声明，用于标识要定义的回调例程的类型。 Windows 为驱动程序提供一组回调函数类型。使用回调函数类型声明函数有助于驱动程序代码分析、静态驱动程序验证程序 (SDV) 和其他验证工具查找错误，并且这是编写适用于 Windows 操作系统的驱动程序的要求。

例如，若要定义名为 MyDmaCompletionRoutine的 DmaCompletionRoutine 回调例程，请使用DMA_COMPLETION_ROUTINE类型，如以下代码示例所示：

DMA_COMPLETION_ROUTINE MyDmaCompletionRoutine;

然后，按如下所示实现回调例程：

_Use_decl_annotations_
VOID
  MyDmaCompletionRoutine(
    PDMA_ADAPTER DmaAdapter,
    PDEVICE_OBJECT DeviceObject,
    PVOID CompletionContext,
    DMA_COMPLETION_STATUS Status
    )
  {
      // Function body
  }

DMA_COMPLETION_ROUTINE函数类型在 Wdm.h 头文件中定义。若要在运行代码分析工具时更准确地识别错误，请务必将 _Use_decl_annotations_ 注释添加到函数定义。注释 _Use_decl_annotations_ 可确保使用应用于头文件中DMA_COMPLETION_ROUTINE函数类型的注释。有关函数声明要求的详细信息，请参阅使用 WDM 驱动程序的函数角色类型声明函数。有关_Use_decl_annotations_的信息，请参阅批注函数行为。

要求

要求	值
最低受支持的客户端	从Windows 8开始可用。
目标平台	桌面
标头	wdm.h（包括 Wdm.h、Ntddk.h、Ntifs.h）
IRQL	在 DISPATCH_LEVEL 调用。