WdfDmaTransactionDmaCompleted 函式 (wdfdmatransaction.h)

發行項
02/29/2024

[僅適用於 KMDF]

WdfDmaTransactionDmaCompleted 方法會通知架構裝置的 DMA 傳輸作業已完成。

語法

BOOLEAN WdfDmaTransactionDmaCompleted(
  [in]  WDFDMATRANSACTION DmaTransaction,
  [out] NTSTATUS          *Status
);

參數

[in] DmaTransaction

驅動程式從先前呼叫 WdfDmaTransactionCreate 取得的 DMA 交易物件的句柄。

[out] Status

接收 DMA 傳輸狀態之位置的指標。如需詳細資訊，請參閱接下來的＜備註＞一節。

傳回值

WdfDmaTransactionDmaCompleted 會傳回 FALSE ，如果需要額外的傳輸才能完成 DMA 交易， 則會STATUS_MORE_PROCESSING_REQUIRED狀態 。如果不需要額外的傳輸，此方法會傳回 TRUE 。

如果驅動程式提供無效的物件句柄，就會發生錯誤檢查。

備註

架構型驅動程式必須在 DMA 傳輸完成時呼叫下列其中一種方法：

一般而言，驅動程式會在裝置中斷表示完成 DMA 傳輸作業之後，從 EvtInterruptDpc 事件回呼函式內呼叫這些方法。系統模式 DMA 裝置的驅動程式可能會從 EvtDmaTransactionDmaTransferComplete 事件回呼函式內呼叫這些方法。

架構可能會將 DMA 交易分割成數個 DMA 傳輸作業。因此，驅動程式必須檢查方法的傳回值，以判斷是否需要額外的傳輸。

如果方法傳回 FALSE， 則狀態 位置會收到STATUS_MORE_PROCESSING_REQUIRED，而且需要額外的 DMA 作業才能完成交易。一般而言， EvtInterruptDpc 事件回呼函式目前不會執行任何其他動作。相反地，架構會呼叫驅動程式的 EvtProgramDma 事件回呼函式，因此回呼函式可以開始下一次傳輸。

如果方法傳回 TRUE，則不會再針對指定的交易進行傳輸。在此情況下， 狀態值STATUS_SUCCESS 表示架構未發生任何錯誤，且 DMA 交易已完成。

如果驅動程式在呼叫 WdfDmaTransactionDmaCompleted 之前呼叫 WdfDmaTransactionStopSystemTransfer，則 WdfDmaTransactionDmaCompleted 會傳回 TRUE，而 Status 值為 STATUS_CANCELLED。

針對針對單一傳輸所設定的交易， WdfDmaTransactionDmaCompleted 會傳回 TRUE ，如果硬體無法在單一傳輸中完成交易，即使初始化成功，仍會傳回 status 值 STATUS_WDF_TOO_MANY_TRANSFERS 。針對報告每個 DMA 作業剩餘傳輸的硬體，可能會發生這種情況。例如，驅動程式會將裝置程式撰寫為 64KB，但裝置只會寫入 60KB。在此情況下，驅動程式可能會重複 DMA 作業或重設裝置。

Status 的任何其他值表示架構偵測到錯誤，而且 DMA 交易可能尚未完成。

當 WdfDmaTransactionDmaCompleted 傳回 TRUE 時，驅動程式通常會執行下列動作：

分別呼叫 WdfObjectDelete 或 WdfDmaTransactionRelease 來刪除或重複使用交易物件。
如果 DMA 交易與 I/O 要求相關聯，則完成 I/O 要求。 (驅動程式藉由呼叫 WdfRequestComplete 或 WdfRequestCompleteWithInformation.) 來完成要求

如需完成 DMA 傳輸的詳細資訊，請參閱完成 DMA 傳輸。

範例

下列程式代碼範例來自 AMCC5933 範例驅動程式。此範例顯示 EvtInterruptDpc 回呼函式。此範例會通知架構 DMA 傳輸已完成。如果架構指出此傳輸是 DMA 交易的最後一項，程式代碼會刪除 DMA 交易物件，並完成相關聯的 I/O 要求。

VOID
AmccPciEvtInterruptDpc(
    IN WDFINTERRUPT  WdfInterrupt,
    IN WDFOBJECT  WdfDevice
    )
{
    PAMCC_DEVICE_EXTENSION  devExt;
    WDFREQUEST  request;
    REQUEST_CONTEXT  *transfer;
    NTSTATUS  status;
    size_t  transferred;
    BOOLEAN  transactionComplete;

    UNREFERENCED_PARAMETER( WdfInterrupt );

    //
    // Retrieve request and transfer.
    //
    devExt = AmccPciGetDevExt(WdfDevice);
    request  = devExt->CurrentRequest;
    transfer = GetRequestContext(request);

    //
    // Check to see if the request has been canceled. 
    //
    if (WdfRequestIsCanceled(request)) {
        TraceEvents(
                    TRACE_LEVEL_ERROR,
                    AMCC_TRACE_IO,
                    "Aborted DMA transaction 0x%p",
                    request
                    );
        WdfObjectDelete( transfer->DmaTransaction );
        devExt->CurrentRequest = NULL;
        WdfRequestComplete(
                           request,
                           STATUS_CANCELLED
                           );
        return;
    }
 
    //
    // Notify the framework that a DMA transfer has completed.
    //
    transactionComplete = WdfDmaTransactionDmaCompleted(
                                                    transfer->DmaTransaction,
                                                    &status
                                                    );
    if (transactionComplete) {
        ASSERT(status != STATUS_MORE_PROCESSING_REQUIRED);

        //
        // No more data. The request is complete.
        //
        TraceEvents(
                    TRACE_LEVEL_INFORMATION,
                    AMCC_TRACE_IO,
                    "Request %p completed: status %X",  
                    request,
                    status
                    );

        //
        // Get the byte count.
        //
        transferred =
                WdfDmaTransactionGetBytesTransferred(transfer->DmaTransaction);

        TraceEvents(
                    TRACE_LEVEL_INFORMATION,
                    AMCC_TRACE_IO,
                    "Bytes transferred %d",
                    (int) transferred
                    );

        //
        // Delete this DmaTransaction object.
        //
        WdfObjectDelete(transfer->DmaTransaction);

        //
        // Clean up the device context for this request.
        //
        devExt->CurrentRequest = NULL;

        //
        // Complete this I/O request.
        //
        WdfRequestCompleteWithInformation(
                                          request, 
                                          status,
                                          (NT_SUCCESS(status)) ? transferred : 0
                                          );
    }
}

規格需求

需求	值
目標平台	Universal
最低 KMDF 版本	1.0
標頭	wdfdmatransaction.h (包含 Wdf.h)
程式庫	Wdf01000.sys (請參閱 Framework Library Versioning.)
IRQL	<=DISPATCH_LEVEL
DDI 合規性規則	DriverCreate (kmdf) 、 KmdfIrql (kmdf) 、 KmdfIrql2 (kmdf) 、 KmdfIrqlExplicit (kmdf)