Espandi Riduci a icona

WdfDmaTransactionInitialize method

[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

DmaTransaction [in]

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

EvtProgramDmaFunction [in]

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

DmaDirection [in]

A WDF_DMA_DIRECTION-typed value.

Mdl [in]

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.

VirtualAddress [in]

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

Length [in]

The number of bytes to be transferred.

Return value

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

Return codeDescription
STATUS_INVALID_PARAMETER

An invalid parameter was detected.

STATUS_INSUFFICIENT_RESOURCES

A scatter/gather list could not be allocated.

STATUS_WDF_TOO_FRAGMENTED

The number of scatter/gather elements that was needed to handle the transaction was greater than the value that the driver's call to WdfDmaEnablerSetMaximumScatterGatherElements specified. For more information, see the following Remarks section.

 

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.

If the buffer that the driver specifies is too fragmented (that is, it requires more scatter/gather elements than the device can handle), WdfDmaTransactionInitialize returns STATUS_WDF_TOO_FRAGMENTED. The driver can specify a smaller memory buffer and call WdfDmaTransactionInitialize again.

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

Target platform

Universal

Minimum KMDF version

1.0

Header

Wdfdmatransaction.h (include Wdf.h)

Library

Wdf01000.sys (see Framework Library Versioning.)

IRQL

<=DISPATCH_LEVEL

DDI compliance rules

DeferredRequestCompleted, DriverCreate, KmdfIrql, KmdfIrql2, MdlAfterReqCompletedIntIoctlA, MdlAfterReqCompletedIoctlA, MdlAfterReqCompletedReadA, MdlAfterReqCompletedWriteA, RequestCompleted, RequestCompletedLocal

See also

EvtProgramDma
MmGetMdlByteCount
MmGetMdlVirtualAddress
WDF_DMA_DIRECTION
WdfDmaEnablerSetMaximumScatterGatherElements
WdfDmaTransactionCreate
WdfDmaTransactionExecute
WdfDmaTransactionInitializeUsingRequest

 

 

Send comments about this topic to Microsoft

Mostra:
© 2015 Microsoft