PINITIALIZE_DMA_TRANSFER_CONTEXT回调函数 (wdm.h)

项目
02/27/2024

InitializeDmaTransferContext 例程初始化不透明的 DMA 传输上下文，该上下文用于跟踪 DMA 资源的挂起分配。

语法

PINITIALIZE_DMA_TRANSFER_CONTEXT PinitializeDmaTransferContext;

NTSTATUS PinitializeDmaTransferContext(
  [in]  PDMA_ADAPTER DmaAdapter,
  [out] PVOID DmaTransferContext
)
{...}

参数

[in] DmaAdapter

指向 DMA_ADAPTER 结构的指针。此结构是适配器对象，表示驱动程序的总线主 DMA 设备或系统 DMA 通道。调用方从对 IoGetDmaAdapter 例程的上一次调用中获取了此指针。

[out] DmaTransferContext

指向调用方分配的缓冲区的指针， InitializeDmaTransferContext 在其中写入 DMA 传输上下文的初始值。此上下文对调用方是不透明的。调用方必须分配足够大的缓冲区，以包含 DMA 传输上下文。此上下文的大小（以字节为单位）由 Wdm.h 头文件中 的 DMA_TRANSFER_CONTEXT_SIZE_V1 常量指定。

返回值

如果调用成功，InitializeDmaTransferContext 将返回STATUS_SUCCESS。可能的错误返回值包括以下状态代码。

返回代码	说明
STATUS_INVALID_PARAMETERS	由于调用方传递的参数值无效，此例程失败。

注解

InitializeDmaTransferContext 不是可以直接按名称调用的系统例程。此例程只能由DMA_OPERATIONS结构中返回的地址中的指针调用 。驱动程序通过调用 IoGetDmaAdapter（DeviceDescription 参数的 Version 成员设置为 DEVICE_DESCRIPTION_VERSION3）来获取此例程的地址。如果 IoGetDmaAdapter 返回 NULL，则例程在平台上不可用。

必须将初始化的 DMA 传输上下文作为参数提供给 AllocateAdapterChannelEx、 GetScatterGatherListEx 或 BuildScatterGatherListEx 例程。其中每个例程都会将请求的 DMA 资源分配的相关信息写入 DMA 传输上下文。此信息对调用方是不透明的。若要取消挂起的分配请求，调用方必须将请求的 DMA 传输上下文提供给 CancelAdapterChannel 例程。

提供给 AllocateAdapterChannelEx、 GetScatterGatherListEx 或 BuildScatterGatherListEx 的 DMA 传输上下文在所有适配器分配请求中必须是唯一的。

要求

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