Expand Minimize

WdfDmaTransactionDmaCompletedFinal method

[Applies to KMDF only]

The WdfDmaTransactionDmaCompletedFinal method notifies the framework that a device's DMA transfer operation has completed with an underrun condition and supplies the length of the completed transfer.

Syntax


BOOLEAN WdfDmaTransactionDmaCompletedFinal(
  [in]   WDFDMATRANSACTION DmaTransaction,
  [in]   size_t FinalTransferredLength,
  [out]  NTSTATUS *Status
);

Parameters

DmaTransaction [in]

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

FinalTransferredLength [in]

The number of bytes that the device transferred.

Status [out]

A pointer to a location that receives the status of the DMA transfer. For more information, see the Remarks section for WdfDmaTransactionDmaCompleted.

Return value

WdfDmaTransactionDmaCompletedFinal returns FALSE if the driver supplies an invalid input parameter. Otherwise, WdfDmaTransactionDmaCompletedFinal always returns TRUE, which indicates that the framework will not attempt to transfer any more bytes for the DMA transaction that the DmaTransaction parameter specified.

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

Remarks

A driver typically calls WdfDmaTransactionDmaCompletedFinal from within its EvtInterruptDpc callback. A driver for a system-mode DMA device might call WdfDmaTransactionDmaCompletedFinal from within an EvtDmaTransactionDmaTransferComplete event callback function.

In the PLX9x5x sample, the driver calls WdfDmaTransactionDmaCompletedFinal from its EvtProgramDma callback function.

The WdfDmaTransactionDmaCompletedFinal method behaves the same as WdfDmaTransactionDmaCompleted, except that drivers typically call WdfDmaTransactionDmaCompletedFinal if the hardware reports an underrun condition. An underrun condition means that the hardware could not transfer all of the bytes that were specified for the last DMA transfer. A call to WdfDmaTransactionDmaCompletedFinal stops the framework from starting any more DMA transfers for the specified DMA transaction.

When your driver calls WdfDmaTransactionDmaCompletedFinal, the driver supplies the number of bytes that were transferred. The return value is always TRUE, because the framework will not attempt to transfer any more bytes for the specified transaction.

For more information about completing DMA transfers, see Completing a DMA Transfer.

Examples

The following code example notifies the framework that a device's DMA transfer operation has completed with an underrun condition.


BOOLEAN  success;
NTSTATUS  status;

success = WdfDmaTransactionDmaCompletedFinal(
                                             DmaTransaction,
                                             transferLength,
                                             &status
                                             );

Requirements

Minimum KMDF version

1.0

Header

Wdfdmatransaction.h (include Wdf.h)

Library

Wdf01000.sys (see Framework Library Versioning.)

IRQL

<=DISPATCH_LEVEL

DDI compliance rules

DriverCreate, KmdfIrql, KmdfIrql2

See also

WdfDmaTransactionCreate
WdfDmaTransactionDmaCompleted
WdfDmaTransactionDmaCompletedWithLength

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft