Skip to content

Latest commit

 

History

History
149 lines (95 loc) · 7.12 KB

nf-wdfdmatransaction-wdfdmatransactioninitializeusingrequest.md

File metadata and controls

149 lines (95 loc) · 7.12 KB
Raw
UID title description old-location tech.root ms.date keywords ms.keywords req.header req.include-header req.target-type req.target-min-winverclnt req.target-min-winversvr req.kmdf-ver req.umdf-ver req.ddi-compliance req.unicode-ansi req.idl req.max-support req.namespace req.assembly req.type-library req.lib req.dll req.irql targetos req.typenames f1_keywords topic_type api_type api_location api_name
NF:wdfdmatransaction.WdfDmaTransactionInitializeUsingRequest
WdfDmaTransactionInitializeUsingRequest function (wdfdmatransaction.h)
The WdfDmaTransactionInitializeUsingRequest method initializes a specified DMA transaction by using the parameters of a specified I/O request.
wdf\wdfdmatransactioninitializeusingrequest.htm
wdf
02/26/2018
WdfDmaTransactionInitializeUsingRequest function
DFDmaObjectRef_b61c1d2b-b62e-4f04-b7ff-53a8e819062a.xml, WdfDmaTransactionInitializeUsingRequest, WdfDmaTransactionInitializeUsingRequest method, kmdf.wdfdmatransactioninitializeusingrequest, wdf.wdfdmatransactioninitializeusingrequest, wdfdmatransaction/WdfDmaTransactionInitializeUsingRequest
wdfdmatransaction.h
Wdf.h
Universal
1.0
DeferredRequestCompleted, DriverCreate, KmdfIrql, KmdfIrql2, RequestCompleted, RequestCompletedLocal
Wdf01000.sys (see Framework Library Versioning.)
<=DISPATCH_LEVEL
Windows
WdfDmaTransactionInitializeUsingRequest
wdfdmatransaction/WdfDmaTransactionInitializeUsingRequest
APIRef
kbSyntax
LibDef
Wdf01000.sys
Wdf01000.sys.dll
WdfDmaTransactionInitializeUsingRequest

WdfDmaTransactionInitializeUsingRequest function

-description

[Applies to KMDF only]

The WdfDmaTransactionInitializeUsingRequest method initializes a specified DMA transaction by using the parameters of a specified I/O request.

-parameters

-param DmaTransaction [in]

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

-param Request [in]

A handle to a framework request object.

-param EvtProgramDmaFunction [in]

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

-param DmaDirection [in]

A WDF_DMA_DIRECTION-typed value that specifies the direction of the DMA transfer.

-returns

WdfDmaTransactionInitializeUsingRequest returns STATUS_SUCCESS if the operation succeeds. Otherwise, the method might return one of the values described in the Return values section of WdfDmaTransactionInitialize.

This method also might return other NTSTATUS values.

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

-remarks

The WdfDmaTransactionInitializeUsingRequest method prepares a DMA operation for execution, by performing initialization operations such as setting up a transaction's scatter/gather list. After your driver calls WdfDmaTransactionInitializeUsingRequest, the driver must call WdfDmaTransactionExecute.

The driver can call WdfRequestGetParameters to obtain a request's type. The value that the driver specifies for the DmaDirection parameter must be appropriate for the request type, as follows:

  • The DmaDirection value must be WdfDmaDirectionReadFromDevice if:
    • The request type is WdfRequestTypeRead
    • The request type is WdfRequestTypeDeviceControl or WdfRequestTypeDeviceControlInternal and the I/O control code specifies a transfer type of METHOD_OUT_DIRECT
  • The DmaDirection value must be WdfDmaDirectionWriteToDevice if:
    • The request type is WdfRequestTypeWrite
    • The request type is WdfRequestTypeDeviceControl or WdfRequestTypeDeviceControlInternal and the I/O control code specifies a transfer type of METHOD_IN_DIRECT
For more information about transfer types for I/O control codes, see Defining I/O Control Codes.

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

Your driver should call WdfDmaTransactionInitializeUsingRequest if you are creating a DMA transaction that is based on information that a framework request object contains. Use WdfDmaTransactionInitialize if you are creating a DMA transaction that is not based on a request object.

If the buffer that the request object describes 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

For a code example that uses WdfDmaTransactionInitializeUsingRequest, see WdfDmaTransactionExecute.

-see-also

EvtProgramDma

WDF_DMA_DIRECTION

WdfDmaEnablerSetMaximumScatterGatherElements

WdfDmaTransactionCreate

WdfDmaTransactionExecute

WdfDmaTransactionInitialize