WdfDmaTransactionDmaCompleted-Funktion (wdfdmatransaction.h)

[Gilt nur für KMDF]

Die WdfDmaTransactionDmaCompleted--Methode benachrichtigt das Framework, dass der DMA-Übertragungsvorgang eines Geräts abgeschlossen ist.

Syntax

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

Die Parameter

[in] DmaTransaction

Ein Handle für ein DMA-Transaktionsobjekt, das der Treiber aus einem vorherigen Aufruf von WdfDmaTransactionCreateabgerufen hat.

[out] Status

Ein Zeiger auf eine Position, die den Status der DMA-Übertragung empfängt. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".

Rückgabewert

WdfDmaTransactionDmaCompleted gibt FALSE- zurück und Status erhält STATUS_MORE_PROCESSING_REQUIRED, wenn zusätzliche Übertragungen erforderlich sind, um die DMA-Transaktion abzuschließen. Die Methode gibt TRUE- zurück, wenn keine zusätzlichen Übertragungen erforderlich sind.

Wenn der Treiber ein ungültiges Objekthandle bereitstellt, tritt eine Fehlerüberprüfung auf.

Bemerkungen

Frameworkbasierte Treiber müssen eine der folgenden Methoden aufrufen, wenn eine DMA-Übertragung abgeschlossen ist abgeschlossen ist:

• WdfDmaTransactionDmaCompleted-

• WdfDmaTransactionDmaCompletedWithLength

• WdfDmaTransactionDmaCompletedFinal-

Das Framework kann eine DMA-Transaktion in mehrere DMA-Übertragungen unterteilen. Daher muss der Treiber den Rückgabewert der Methode überprüfen, um festzustellen, ob zusätzliche Übertragungen erforderlich sind.

Wenn die Methode FALSE-zurückgibt, empfängt der Status Standort STATUS_MORE_PROCESSING_REQUIRED und zusätzliche DMA-Vorgänge sind erforderlich, um die Transaktion abzuschließen. In der Regel führt die EvtInterruptDpc Ereignisrückruffunktion an diesem Punkt nichts anderes aus. Stattdessen ruft das Framework die EvtProgramDma Ereignisrückruffunktion auf, sodass die Rückruffunktion die nächste Übertragung starten kann.

Wenn die Methode TRUEzurückgibt, treten für die angegebene Transaktion keine weiteren Übertragungen auf. In diesem Fall bedeutet ein Status Werts von STATUS_SUCCESS, dass das Framework keine Fehler aufweist und die DMA-Transaktion abgeschlossen ist.

Wenn der Treiber WdfDmaTransactionStopSystemTransfer aufruft, bevor WdfDmaTransactionDmaCompletedaufgerufen wird, gibt WdfDmaTransactionDmaCompletedTRUE und einen Status Wert von STATUS_CANCELLEDzurück.

Bei Transaktionen, die für einzelne Übertragungfestgelegt wurden, gibt WdfDmaTransactionDmaCompletedTRUE und einen Status Wert von STATUS_WDF_TOO_MANY_TRANSFERS zurück, wenn die Hardware die Transaktion in einer einzelnen Übertragung nicht abschließen kann, auch wenn die Initialisierung erfolgreich war. Dies kann für Hardware passieren, die Restübertragungen für jeden DMA-Vorgang meldet. Beispielsweise programmiert der Treiber das Gerät, um 64 KB zu schreiben, das Gerät schreibt jedoch nur 60 KB. In diesem Fall kann der Treiber den DMA-Vorgang wiederholen oder das Gerät zurücksetzen.

Jeder andere Wert für Status bedeutet, dass das Framework einen Fehler festgestellt hat und die DMA-Transaktion möglicherweise nicht abgeschlossen wurde.

Wenn WdfDmaTransactionDmaCompletedTRUE-zurückgibt, führt der Treiber in der Regel folgendes aus:

• Ruft WdfObjectDelete oder WdfDmaTransactionRelease- auf, um das Transaktionsobjekt zu löschen oder wiederzuverwenden.
• Schließt die E/A-Anforderung ab, wenn die DMA-Transaktion einer E/A-Anforderung zugeordnet ist. (Treiber erfüllen Anforderungen durch Aufrufen von WdfRequestComplete oder WdfRequestCompleteWithInformation.)

Beispiele

Das folgende Codebeispiel stammt aus dem AMCC5933 Beispieltreiber. Dieses Beispiel zeigt eine EvtInterruptDpc- Rückruffunktion. Im Beispiel wird das Framework benachrichtigt, dass eine DMA-Übertragung abgeschlossen wurde. Wenn das Framework angibt, dass diese Übertragung der letzte für die DMA-Transaktion ist, löscht der Code das DMA-Transaktionsobjekt und schließt die zugeordnete E/A-Anforderung ab.

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
                                          );
    }
}

Anforderungen

Siehe auch

EvtInterruptDpc

EvtProgramDma

WdfDmaTransactionCreate

WdfDmaTransactionDmaCompletedFinal-

WdfDmaTransactionDmaCompletedWithLength

WdfDmaTransactionRelease

WdfObjectDelete-

WdfRequestComplete-

WdfRequestCompleteWithInformation-