WdfDmaTransactionAllocateResources function (wdfdmatransaction.h)

Article
04/18/2022

[Applies to KMDF only]

The WdfDmaTransactionAllocateResources method reserves a single-packet or system-mode DMA enabler for exclusive (and repeated) use with the specified transaction object. The driver can initialize and initiate the transaction multiple times while holding reserved resources.

Syntax

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

Parameters

[in] DmaTransaction

A handle to the DMA transaction object for which DMA resources should be reserved.

[in] DmaDirection

A WDF_DMA_DIRECTION-typed value specifying the DMA transfer direction for which the resources are being reserved. If the driver did not specify a duplex profile, the framework ignores this value.

[in] RequiredMapRegisters

The number of map registers the driver wants to reserve. If zero, the framework derives the required number of map registers from the initialized transaction.

[in] EvtReserveDmaFunction

A pointer to the driver's EvtReserveDma event callback function.

[in] EvtReserveDmaContext

A pointer to a buffer containing the context to be provided to the driver's EvtReserveDma event callback function.

Return value

WdfDmaTransactionAllocateResources returns STATUS_SUCCESS if the operation succeeds. Otherwise, this method returns one of the following values.

Return code	Description
STATUS_INVALID_PARAMETER	The DmaDirection parameter contains an invalid value.
STATUS_INSUFFICIENT_RESOURCES	The number of map register requests exceeds the number assigned to the enabler, or the driver previously called WdfDmaTransactionSetImmediateExecution and the resources needed for the request are unavailable.
STATUS_INVALID_DEVICE_REQUEST	DMA version 3 or later is not enabled, or the driver called this method for a scatter-gather DMA enabler.

Remarks

WdfDmaTransactionAllocateResources sends a request for map registers to the system DMA engine. When the request has been fulfilled, the framework calls the driver's EvtReserveDma event callback function. For more information about reserving resources, see Reserving DMA Resources.

Framework-based drivers typically call WdfDmaTransactionAllocateResources from within an I/O request handler. A driver can also call WdfDmaTransactionAllocateResources from its EvtDriverDeviceAdd callback function, after creating a DMA enabler object.

When called with a scatter/gather DMA enabler, WdfDmaTransactionAllocateResources causes a verifier bug check.

The driver must create the transaction specified by DmaTransaction prior to calling WdfDmaTransactionAllocateResources. After calling WdfDmaTransactionAllocateResources, the driver initializes and initiates the transaction. The driver can reinitialize and reinitiate the same transaction object multiple times, avoiding the delay that would otherwise occur between transactions as map registers were freed back to the HAL and then reallocated.

A driver could call WdfDmaTransactionAllocateResources in the following situations:

The driver receives a set of DMA channels in its EvtDevicePrepareHardware callback function. In EvtDevicePrepareHardware, the driver initializes a DMA transaction and calls WdfDmaTransactionAllocateResources to reserve the enabler for exclusive use with this transaction. Alternatively, the driver can call WdfDmaTransactionAllocateResources from a request handler and then initiate the transaction multiple times.
The driver needs to perform a series of transactions on the enabler. The driver reserves the enabler, initializes and initiates multiple transactions using the same transaction object, and then releases the enabler.

Before calling WdfDmaTransactionAllocateResources, the driver must determine the number of map registers needed for any transaction that it will initiate using this reservation. To do so, the driver can call either the [ADDRESS_AND_SIZE_TO_SPAN_PAGES](../wdm/nf-wdm-address_and_size_to_span_pages.md) macro or WdfDmaTransactionGetTransferInfo.

When calling WdfDmaTransactionAllocateResources, the driver should not request more map registers than it requested when it created the enabler.

To call WdfDmaTransactionAllocateResources in a non-blocking manner, the driver should first call WdfDmaTransactionSetImmediateExecution.

WdfDmaTransactionAllocateResources requires DMA version 3. To select DMA version 3, set the WdmDmaVersionOverride member of WDF_DMA_ENABLER_CONFIG to 3.

Requirements

Requirement	Value
Target Platform	Universal
Minimum KMDF version	1.11
Header	wdfdmatransaction.h (include Wdf.h)
Library	Wdf01000.sys (see Framework Library Versioning.)
IRQL	<=DISPATCH_LEVEL
DDI compliance rules	DriverCreate(kmdf)