WdfDmaTransactionAllocateResources 函式 (wdfdmatransaction.h)

發行項
02/27/2024

[僅適用於 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

指定保留資源的 DMA 傳輸方向的WDF_DMA_DIRECTION型別值。如果驅動程式未指定雙工配置檔，架構會忽略此值。

[in] RequiredMapRegisters

驅動程式想要保留的地圖緩存器數目。如果為零，架構會從初始化的交易衍生所需的對應緩存器數目。

[in] EvtReserveDmaFunction

驅動程式 EvtReserveDma 事件回呼函式的指標。

[in] EvtReserveDmaContext

緩衝區的指標，其中包含要提供給驅動程式 EvtReserveDma 事件回呼函式的內容。

傳回值

如果作業成功，WdfDmaTransactionAllocateResources 會傳回STATUS_SUCCESS。否則，此方法會傳回下列其中一個值。

傳回碼	Description
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 會導致驗證程序錯誤檢查。

驅動程式必須先建立 DmaTransaction 指定的交易，才能呼叫 WdfDmaTransactionAllocateResources。呼叫 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。

規格需求

需求	值
目標平台	Universal
最小 KMDF 版本	1.11
標頭	wdfdmatransaction.h (包含 Wdf.h)
程式庫	Wdf01000.sys (請參閱 Framework Library Versioning.)
IRQL	<=DISPATCH_LEVEL
DDI 合規性規則	DriverCreate (kmdf)