Edit

Reserving DMA Resources

  • Article

[Applies to KMDF only]

Typically, framework-based drivers do not reserve map registers ahead of time. However, in certain circumstances, drivers may need to reserve these resources in advance.

Framework-based drivers running on Windows 8 or later can reserve a specified number of map registers for a DMA enabler that specifies a packet or system profile. To do so, the driver calls WdfDmaTransactionAllocateResources and registers an EvtReserveDma callback function.

The framework calls the driver's EvtReserveDma function when it has reserved the map registers and the WDM DMA adapter's lock. The driver can then initialize and initiate the transaction multiple times using the same transaction object before finally releasing the transaction object. To release the DMA resources back to the system, the driver calls WdfDmaTransactionFreeResources.

To determine the number of map registers required for a transaction, the driver can call WdfDmaTransactionGetTransferInfo before calling WdfDmaTransactionAllocateResources. The driver must initialize the transaction before calling WdfDmaTransactionGetTransferInfo.

The following steps demonstrate how a driver can reserve and release a DMA enabler for exclusive use with a specified transaction:

  1. The driver receives an I/O request.

  2. The driver's request handler calls WdfDmaTransactionCreate to create a DMA transaction object for the request.

  3. The driver's request handler calls WdfDmaTransactionAllocateResources to reserve resources.

  4. The framework calls EvtReserveDma when it has reserved the requested resources.

  5. In EvtReserveDma, the driver calls WdfDmaTransactionInitializeUsingRequest or WdfDmaTransactionInitialize to initialize the transaction object.

  6. In EvtReserveDma, the driver calls the WdfDmaTransactionExecute method to start the transaction. Because the transaction has reserved resources, the framework immediately calls the driver's EvtProgramDma callback function.

  7. From EvtInterruptDpc or EvtDmaTransactionDmaTransferComplete, the driver calls WdfDmaTransactionDmaCompleted, WdfDmaTransactionDmaCompletedWithLength, or WdfDmaTransactionDmaCompletedFinal, followed by WdfObjectDelete or WdfDmaTransactionRelease. The driver must not delete or release the transaction until the transaction has been completed or canceled. After the completion of this step, the map registers remain reserved.

  8. The driver can repeat steps 5–7 as many times as necessary.

    When the driver no longer needs the reservation, the driver calls WdfDmaTransactionFreeResources from EvtInterruptDpc or EvtDmaTransactionDmaTransferComplete. Alternatively, the driver can call WdfDmaTransactionFreeResources from its EvtReserveDma event callback function.