Edit

Creating and Initializing a DMA Transaction

  • Article

[Applies to KMDF only]

Before your driver can send an I/O request to a DMA device, the driver must:

  1. Call WdfDmaTransactionCreate to create a DMA transaction object for the request.

  2. Call WdfDmaTransactionInitializeUsingRequest, WdfDmaTransactionInitialize, or WdfDmaTransactionInitializeUsingOffset to initialize the transaction object.

Typically, your driver creates a DMA transaction because a request handler has received a framework request object and must pass the request to the hardware. In this case, the driver should call WdfDmaTransactionInitializeUsingRequest, which accepts a request object handle as input and extracts the request's address parameters from the request object.

If your driver must create a DMA transaction that is not based on a framework request object that the driver received, the driver can call either WdfDmaTransactionInitialize or WdfDmaTransactionInitializeUsingOffset. Both methods accept address parameters that the driver provides.

All three initialization methods require the address of an EvtProgramDma event callback function as an input parameter. This callback function programs the device, and the framework calls the callback function each time a DMA transfer is available.

When your driver calls WdfDmaEnablerCreate to create a DMA enabler object, the driver supplies a WDF_DMA_ENABLER_CONFIG structure that contains the device's maximum transfer length. The framework uses this value as the default maximum length for all DMA transfers.

For some types of DMA transactions, you might need to specify a maximum transfer length that is different from the device's default maximum length. You can use WdfDmaTransactionSetMaximumLength to set a maximum transfer length for an individual transaction. The framework uses the specified maximum transfer length only while it processes the specified transaction.

Note that the maximum transfer length is limited by the number of map registers that the operating system makes available to the DMA enabler object. To determine the maximum transfer length that is available, your driver can call WdfDmaEnablerGetFragmentLength. If the value that WdfDmaEnablerGetFragmentLength returns is less than the maximum transfer length that the driver supplied to WdfDmaEnablerCreate, the framework uses the smaller value.

After your driver creates and initializes a DMA transaction, the driver must start the transaction.