WdfDmaTransactionInitialize function (wdfdmatransaction.h)

[Applies to KMDF only]

The WdfDmaTransactionInitialize method initializes a specified DMA transaction.

Syntax

NTSTATUS WdfDmaTransactionInitialize(
  [in] WDFDMATRANSACTION   DmaTransaction,
  [in] PFN_WDF_PROGRAM_DMA EvtProgramDmaFunction,
  [in] WDF_DMA_DIRECTION   DmaDirection,
  [in] PMDL                Mdl,
  [in] PVOID               VirtualAddress,
  [in] size_t              Length
);

Parameters

[in] DmaTransaction

A handle to a DMA transaction object that the driver obtained from a previous call to WdfDmaTransactionCreate.

[in] EvtProgramDmaFunction

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

[in] DmaDirection

A WDF_DMA_DIRECTION-typed value.

[in] Mdl

A pointer to a memory descriptor list (MDL) that describes the buffer that will be used for the DMA transaction. See more information in Remarks.

[in] VirtualAddress

The virtual address of the buffer that will be used for the DMA transaction.

[in] Length

The number of bytes to be transferred.

Return value

WdfDmaTransactionInitialize returns STATUS_SUCCESS if the operation succeeds. Otherwise, the method might return one of the following values.

This method also might return other NTSTATUS values.

A bug check occurs if the driver supplies an invalid object handle.

Remarks

The WdfDmaTransactionInitialize method prepares a DMA operation for execution, by performing initialization operations such as allocating a transaction's scatter/gather list. After your driver calls WdfDmaTransactionInitialize, the driver must call WdfDmaTransactionExecute to begin executing the transaction.

Framework-based drivers typically call WdfDmaTransactionInitialize from within an I/O queue event callback function.

If you are creating a DMA transaction that is based on information that a framework request object contains, your driver should call WdfDmaTransactionInitializeUsingRequest. If you are creating a DMA transaction that is not based on a request object, use either WdfDmaTransactionInitialize or WdfDmaTransactionInitializeUsingOffset.

The driver can specify an MDL chain in the Mdl parameter of this method. An MDL chain is a sequence of MDL structures that the driver chained together using the Next member of the MDL structure. In framework versions prior to 1.11, only scatter/gather DMA transfers can use MDL chains. Starting in version 1.11, if the driver is using DMA version 3, single-packet transfers can also use chained MDLs.

If the buffer that the driver specifies is larger than the maximum transfer length that your driver specified when it called WdfDmaEnablerCreate or WdfDmaTransactionSetMaximumLength, the framework breaks the transaction into multiple transfers.

For more information about DMA transactions, see Creating and Initializing a DMA Transaction.

Examples

The following code example is from the PLX9x5x sample driver. First, the example initializes a WDF_OBJECT_ATTRIBUTES structure and creates a DMA transaction object. Next, it obtains an MDL that represents a received I/O request's input buffer, and it obtains the virtual address and length of the buffer. Finally, the example calls WdfDmaTransactionInitialize to initialize the transaction.

WDF_OBJECT_ATTRIBUTES  attributes;
PMDL  mdl;
PVOID  virtualAddress;
ULONG  length;
NTSTATUS  status;

WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(
                                        &attributes,
                                        TRANSACTION_CONTEXT
                                        );

status = WdfDmaTransactionCreate(
                                 devExt->DmaEnabler,
                                 &attributes,
                                 &dmaTransaction
                                 );
if(!NT_SUCCESS(status)) {
    goto CleanUp;
}

status = WdfRequestRetrieveInputWdmMdl(
                                       Request,
                                       &mdl
                                       );
if (!NT_SUCCESS(status)) {
    goto CleanUp;
}

virtualAddress = MmGetMdlVirtualAddress(mdl);
length = MmGetMdlByteCount(mdl);

status = WdfDmaTransactionInitialize(
                                     dmaTransaction,
                                     PLxEvtProgramWriteDma,
                                     WdfDmaDirectionWriteToDevice,
                                     mdl,
                                     virtualAddress,
                                     length
                                     );
if(!NT_SUCCESS(status)) {
    goto CleanUp;
}

Requirements

See also

EvtProgramDma

MmGetMdlByteCount

MmGetMdlVirtualAddress

WDF_DMA_DIRECTION

WdfDmaEnablerSetMaximumScatterGatherElements

WdfDmaTransactionCreate

WdfDmaTransactionExecute

WdfDmaTransactionInitializeUsingRequest