WdfDmaTransactionCancel function (wdfdmatransaction.h)

[Applies to KMDF only]

The WdfDmaTransactionCancel method attempts to cancel a DMA transaction that is waiting for the allocation of map registers.

Syntax

BOOLEAN WdfDmaTransactionCancel(
  [in] WDFDMATRANSACTION DmaTransaction
);

Parameters

[in] DmaTransaction

A handle to the DMA transaction object that represents the transaction that is being canceled. This transaction must have already been initialized by the driver.

Return value

WdfDmaTransactionCancel returns TRUE if the framework successfully cancels map register allocation. In this case, no transfers are completed, and the framework makes no additional DMA callbacks on the transaction until it is reinitiated.

The method returns FALSE if another thread is already processing this transaction, or if the driver has not yet called WdfDmaTransactionExecute. In the first case, the framework is currently calling or will call EvtProgramDma or EvtReserveDma. At this point, a driver that specified a system-mode DMA profile might call WdfDmaTransactionStopSystemTransfer.

The method also returns FALSE if called with a transaction that was allocated from a DMA version 2 enabler.

Remarks

The driver might call WdfDmaTransactionCancel from an EvtRequestCancel event callback function that it supplies in a call to WdfRequestMarkCancelableEx. For a code example that shows how to do this, see WdfDmaTransactionStopSystemTransfer.

The driver might also call WdfDmaTransactionCancel from an EvtIoCanceledOnQueue event callback function.

Cancellation can only succeed if the call to WdfDmaTransactionCancel occurs after the call to WdfDmaTransactionExecute, but before the WdfDmaTransactionExecute method has started the DMA allocation. For more information, see Canceling DMA Transactions.

The driver must call WdfDmaTransactionCancel after calling WdfDmaTransactionInitialize, but before calling WdfDmaTransactionRelease or WdfObjectDelete to delete the transaction object.

Do not call WdfDmaTransactionCancel after the framework has called EvtProgramDma or EvtReserveDma.

A driver must request use of DMA version 3 prior to calling WdfDmaTransactionCancel. To select DMA version 3, set the WdmDmaVersionOverride member of WDF_DMA_ENABLER_CONFIG to 3.

If a driver calls WdfDmaTransactionCancel on a transaction that was allocated from a DMA version 2 enabler, the framework generates a verifier error and WdfDmaTransactionCancel returns FALSE. In this case, no attempt is made to cancel the transaction.

Requirements

See also

EvtProgramDma

EvtReserveDma

WdfDmaTransactionStopSystemTransfer