WdfDmaTransactionAllocateResources function

Description

[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.

Parameters

DmaTransaction [in]

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

DmaDirection [in]

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.

RequiredMapRegisters [in]

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.

EvtReserveDmaFunction [in]

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

EvtReserveDmaContext [in]

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.

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 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.

See also

EvtDevicePrepareHardware

WdfDmaEnablerCreate

WdfDmaTransactionCreate

WdfDmaTransactionExecute

WdfDmaTransactionFreeResources

WdfDmaTransactionSetImmediateExecution