WdfDmaTransactionExecute-Funktion (wdfdmatransaction.h)

Artikel
02/29/2024

[Gilt nur für KMDF]

Die WdfDmaTransactionExecute-Methode beginnt mit der Ausführung einer angegebenen DMA-Transaktion.

Syntax

NTSTATUS WdfDmaTransactionExecute(
  [in]           WDFDMATRANSACTION DmaTransaction,
  [in, optional] WDFCONTEXT        Context
);

Parameter

[in] DmaTransaction

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

[in, optional] Context

Vom Treiber definierte Kontextinformationen. Das Framework übergibt den für Context angegebenen Wert, der ein Zeiger sein kann, an die EvtProgramDma-Ereignisrückruffunktion des Treibers. Dieser Parameter ist optional und kann NULL sein.

Rückgabewert

WdfDmaTransactionExecute gibt STATUS_SUCCESS zurück, wenn der Vorgang erfolgreich ist. Andernfalls gibt die -Methode möglicherweise einen der folgenden Werte zurück.

Rückgabecode	Beschreibung
STATUS_INSUFFICIENT_RESOURCES	Der Treiber, der zuvor als WdfDmaTransactionSetImmediateExecution bezeichnet wurde, und die für die Anforderung erforderlichen Ressourcen sind nicht verfügbar.
STATUS_INVALID_DEVICE_REQUEST	Dem Aufruf von WdfDmaTransactionExecute war kein Aufruf von WdfDmaTransactionInitialize oder WdfDmaTransactionInitializeUsingRequest vorangestellt.
STATUS_WDF_BUSY	Das Gerät führt Einzelpaketübertragungen und den Treiber mit dem Namen WdfDmaTransactionExecute aus, während eine andere Transaktion ausgeführt wurde.
STATUS_WDF_TOO_FRAGMENTED	Die Anzahl der Scatter-/Gather-Elemente, die das Betriebssystem zur Verarbeitung der angegebenen Übertragungsgröße benötigt, war größer als der Wert, den der Aufruf des Treibers für WdfDmaEnablerSetMaximumScatterGatherElements angegeben hat. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".

Diese Methode kann auch andere NTSTATUS-Werte zurückgeben.

Eine Fehlerüberprüfung tritt auf, wenn der Treiber ein ungültiges Objekthandle bereitstellt.

Hinweise

Die WdfDmaTransactionExecute-Methode initialisiert die Scatter/Gather-Liste einer Transaktion für die erste DMA-Übertragung , die der angegebenen DMA-Transaktion zugeordnet ist. (Bei Übertragungen mit einzelnen Paketen enthält die Scatter-/Gather-Liste ein einzelnes Element.) Anschließend ruft die -Methode die EvtProgramDma-Ereignisrückruffunktion des Treibers auf, und die Rückruffunktion kann das Gerät so programmieren, dass die Übertragung gestartet wird.

Frameworkbasierte Treiber rufen WdfDmaTransactionExecute in der Regel innerhalb einer E/A-Warteschlangenereignisrückruffunktion auf.

Nachdem ein Treiber WdfDmaTransactionInitialize oder WdfDmaTransactionInitializeUsingRequest aufgerufen hat, um eine DMA-Transaktion zu initialisieren, muss der Treiber WdfDmaTransactionExecute nur einmal aufrufen, bevor die DMA-Transaktion abgeschlossen wird.

Wenn WdfDmaTransactionInitializeXxx erfolgreich zurückgibt, WdfDmaTransactionExecute jedoch einen Fehlerwert zurückgibt, muss Ihr Treiber WdfDmaTransactionRelease aufrufen.

In Frameworkversionen vor 1.11 kann das Betriebssystem jeweils nur eine DMA-Transaktion ausführen, wenn das Gerät Einzelpaketübertragungen durchführt. In diesem Fall gibt WdfDmaTransactionExecute STATUS_WDF_BUSY zurück, wenn eine andere Transaktion ausgeführt wird.

In Frameworkversionen 1.11 und höher kann das Betriebssystem mehrere DMA-Transaktionen in einer internen Warteschlange speichern, wenn der Treiber DMA-Version 3 zum Durchführen von Einzelpaketübertragungen verwendet. In diesem Fall kann der Treiber WdfDmaTransactionExecute aufrufen, während eine andere Transaktion ausgeführt wird. Um DMA-Version 3 auszuwählen, legen Sie das WdmDmaVersionOverride-Element von WDF_DMA_ENABLER_CONFIG auf 3 fest.

Wenn das Gerät Punkt-/Gather-Übertragungen durchführt, kann das Betriebssystem mehrere DMA-Transaktionen gleichzeitig ausführen. In diesem Fall kann der Treiber WdfDmaTransactionExecute aufrufen, während eine andere Transaktion ausgeführt wird.

Wenn der Treiber WdfDmaTransactionDmaCompletedWithLength aufruft , um eine Teilübertragung zu melden, und wenn der Treiber den Datenpuffer der DMA-Transaktion mithilfe von MDLs angegeben hat, die er verkettet hat (unter Verwendung des Next-Elements der MDL-Struktur ), kann WdfDmaTransactionExecute STATUS_WDF_TOO_FRAGMENTED zurückgeben, da das Framework möglicherweise die Anzahl und Größe der Fragmente neu berechnet und die Anzahl der zulässigen Fragmente überschreitet.

WdfDmaTransactionExecute gibt STATUS_SUCCESS zurück, wenn die Transaktion erfolgreich gestartet wurde. Um festzustellen, ob das Framework erfolgreich alle Übertragungen der Transaktion an die EvtProgramDma-Rückruffunktion des Treibers gesendet hat, muss der Treiber WdfDmaTransactionDmaCompleted, WdfDmaTransactionDmaCompletedWithLength oder WdfDmaTransactionDmaCompletedFinal aufrufen.

Wenn der Wert, den der Context-Parameter bereitstellt, ein Zeiger oder Handle ist, muss der Speicher, auf den er verweist, in der EvtProgramDma-Ereignisrückruffunktion des Treibers unter IRQL = DISPATCH_LEVEL zugänglich sein. Sie können den Frameworkobjektkontext verwenden, um diese Anforderung zu erfüllen.

Der Treiber kann WdfDmaTransactionExecute nicht blockierend aufrufen, wenn er zuvor WdfDmaTransactionSetImmediateExecution aufgerufen hat.

Weitere Informationen zu DMA-Transaktionen finden Sie unter Starten einer DMA-Transaktion.

Beispiele

Das folgende Codebeispiel stammt aus dem PCIDRV-Beispieltreiber . In diesem Beispiel wird eine DMA-Übertragung erstellt und initialisiert und mit deren Ausführung begonnen.

NTSTATUS
NICInitiateDmaTransfer(
    IN PFDO_DATA  FdoData,
    IN WDFREQUEST  Request
    )
{
    WDFDMATRANSACTION  dmaTransaction;
    NTSTATUS  status;
    BOOLEAN  bCreated = FALSE;
 
    do {
        status = WdfDmaTransactionCreate(
                                         FdoData->WdfDmaEnabler,
                                         WDF_NO_OBJECT_ATTRIBUTES,
                                         &dmaTransaction
                                         );
        if(!NT_SUCCESS(status)) {
            TraceEvents(TRACE_LEVEL_ERROR, DBG_WRITE, 
                        "WdfDmaTransactionCreate failed %X\n", status);
            break;
        }

        bCreated = TRUE;

        status = WdfDmaTransactionInitializeUsingRequest( 
                                     dmaTransaction,
                                     Request,
                                     NICEvtProgramDmaFunction,
                                     WdfDmaDirectionWriteToDevice
                                     );
        if(!NT_SUCCESS(status)) {
            TraceEvents(
                        TRACE_LEVEL_ERROR,
                        DBG_WRITE, 
                        "WdfDmaTransactionInitalizeUsingRequest failed %X\n", 
                        status
                        );
            break;
        }

        status = WdfDmaTransactionExecute(
                                          dmaTransaction,
                                          dmaTransaction
                                          );

        if(!NT_SUCCESS(status)) {
            TraceEvents(
                        TRACE_LEVEL_ERROR,
                        DBG_WRITE, 
                        "WdfDmaTransactionExecute failed %X\n",
                        status
                        );
            break;
        }
    } while (FALSE);

    if(!NT_SUCCESS(status)){
 
        if(bCreated) {
            WdfObjectDelete(dmaTransaction);
        }
    }
    return status;
}

Anforderungen

Anforderung	Wert
Zielplattform	Universell
KMDF-Mindestversion	1.0
Kopfzeile	wdfdmatransaction.h (include Wdf.h)
Bibliothek	Wdf01000.sys (siehe Versionsverwaltung der Frameworkbibliothek).)
IRQL	<=DISPATCH_LEVEL
DDI-Complianceregeln	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)