WdfDmaTransactionDmaCompletedFinal function (wdfdmatransaction.h)

Article
04/18/2022

[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

[in] DmaTransaction

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

[in] FinalTransferredLength

The number of bytes that the device transferred.

[out] Status

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

Requirement	Value
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	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)