WdfDmaTransactionAllocateResources 函数 (wdfdmatransaction.h)

项目
08/08/2023

[仅适用于 KMDF]

WdfDmaTransactionAllocateResources 方法保留一个单数据包或系统模式 DMA 启用器，用于独占 (和重复) 与指定的事务对象一起使用。驱动程序可以在保留保留资源时多次初始化和启动事务。

语法

NTSTATUS WdfDmaTransactionAllocateResources(
  [in] WDFDMATRANSACTION   DmaTransaction,
  [in] WDF_DMA_DIRECTION   DmaDirection,
  [in] ULONG               RequiredMapRegisters,
  [in] PFN_WDF_RESERVE_DMA EvtReserveDmaFunction,
  [in] PVOID               EvtReserveDmaContext
);

参数

[in] DmaTransaction

应为其保留 DMA 资源的 DMA 事务对象的句柄。

[in] DmaDirection

一个WDF_DMA_DIRECTION类型的值，指定要为其保留资源的 DMA 传输方向。如果驱动程序未指定双工配置文件，框架将忽略此值。

[in] RequiredMapRegisters

驱动程序要保留的映射注册数。如果为零，框架将从初始化的事务派生所需数量的映射寄存器。

[in] EvtReserveDmaFunction

指向驱动程序的 EvtReserveDma 事件回调函数的指针。

[in] EvtReserveDmaContext

指向缓冲区的指针，该缓冲区包含要提供给驱动程序的 EvtReserveDma 事件回调函数的上下文。

返回值

如果操作成功，WdfDmaTransactionAllocateResources 将返回STATUS_SUCCESS。否则，此方法返回以下值之一。

返回代码	说明
STATUS_INVALID_PARAMETER	DmaDirection 参数包含无效值。
STATUS_INSUFFICIENT_RESOURCES	映射寄存器请求数超过了分配给启用程序的数量，或者以前称为 WdfDmaTransactionSetImmediateExecution 的驱动程序，并且请求所需的资源不可用。
STATUS_INVALID_DEVICE_REQUEST	未启用 DMA 版本 3 或更高版本，或者调用此方法的驱动程序为散点收集 DMA 启用程序。

注解

WdfDmaTransactionAllocateResources 将映射寄存器的请求发送到系统 DMA 引擎。满足请求后，框架将调用驱动程序的 EvtReserveDma 事件回调函数。有关保留资源的详细信息，请参阅预留 DMA 资源。

基于框架的驱动程序通常从 I/O 请求处理程序中调用 WdfDmaTransactionAllocateResources。创建 DMA 启用程序对象后，驱动程序还可以从其 EvtDriverDeviceAdd 回调函数调用 WdfDmaTransactionAllocateResources。

使用散点/收集 DMA 启用程序调用时，WdfDmaTransactionAllocateResources 会导致验证程序 bug 检查。

在调用 WdfDmaTransactionAllocateResources 之前，驱动程序必须创建由 DmaTransaction 指定的事务。调用 WdfDmaTransactionAllocateResources 后，驱动程序初始化并启动事务。驱动程序可以多次重新初始化和重新初始化同一事务对象，从而避免在映射寄存器释放回 HAL 然后重新分配时在事务之间发生的延迟。

驱动程序可以在以下情况下调用 WdfDmaTransactionAllocateResources ：

驱动程序在其 EvtDevicePrepareHardware 回调函数中接收一组 DMA 通道。在 EvtDevicePrepareHardware 中，驱动程序初始化 DMA 事务并调用 WdfDmaTransactionAllocateResources ，以保留此启用程序供此事务独占使用。或者，驱动程序可以从请求处理程序调用 WdfDmaTransactionAllocateResources，然后多次启动事务。
驱动程序需要对启用程序执行一系列事务。驱动程序保留启用程序，使用同一事务对象初始化和启动多个事务，然后释放启用程序。

在调用 WdfDmaTransactionAllocateResources 之前，驱动程序必须确定将使用此预留启动的任何事务所需的映射寄存器数。为此，驱动程序可以调用 [ADDRESS_AND_SIZE_TO_SPAN_PAGES] (./wdm/nf-wdm-address_and_size_to_span_pages.md) 宏或 WdfDmaTransactionGetTransferInfo。

调用 WdfDmaTransactionAllocateResources 时，驱动程序请求的映射寄存器不应超过创建启用程序时请求的映射寄存器数。

若要以非阻塞方式调用 WdfDmaTransactionAllocateResources ，驱动程序应首先调用 WdfDmaTransactionSetImmediateExecution。

WdfDmaTransactionAllocateResources 需要 DMA 版本 3。若要选择 DMA 版本 3，请将 WDF_DMA_ENABLER_CONFIG 的 WdmDmaVersionOverride 成员设置为 3。

要求

要求	值
目标平台	通用
最低 KMDF 版本	1.11
标头	wdfdmatransaction.h (包括 Wdf.h)
Library	Wdf01000.sys (请参阅框架库版本控制.)
IRQL	<=DISPATCH_LEVEL
DDI 符合性规则	DriverCreate (kmdf)