DMA_COMPLETION_ROUTINE Rückruffunktion (wdm.h)

Artikel
02/27/2024

Die DmaCompletionRoutine-Rückrufroutine benachrichtigt den Treiber, der zuvor eine DMA-Systemübertragung angefordert hat, dass diese Übertragung abgeschlossen ist.

Syntax

DMA_COMPLETION_ROUTINE DmaCompletionRoutine;

void DmaCompletionRoutine(
  [in] PDMA_ADAPTER DmaAdapter,
  [in] PDEVICE_OBJECT DeviceObject,
  [in] PVOID CompletionContext,
  [in] DMA_COMPLETION_STATUS Status
)
{...}

Parameter

[in] DmaAdapter

Ein Zeiger auf eine DMA_ADAPTER-Struktur . Diese Struktur ist das Adapterobjekt, das den DMA-Systemkanal des Treibers darstellt.

[in] DeviceObject

Ein Zeiger auf eine DEVICE_OBJECT-Struktur . Diese Struktur ist das physische Geräteobjekt (PDO), das das Zielgerät für den angeforderten DMA-Vorgang darstellt.

[in] CompletionContext

Ein Zeiger auf einen vom Treiber bestimmten Kontext für die DmaCompletionRoutine-Routine . Dieser Kontext ist der CompletionContext-Parameterwert , den der Treiber zuvor an den MapTransferEx-Aufruf übergeben hat, der die DMA-Systemübertragung initiiert hat.

[in] Status

Der Abschluss status der DMA-Übertragung. Dieser Parameter ist ein DMA_COMPLETION_STATUS Enumerationswert, der angibt, ob die DMA-Übertragung erfolgreich abgeschlossen wurde.

Rückgabewert

Keine

Bemerkungen

Optional kann ein Treiber eine DmaCompletionRoutine-Routine implementieren. Wenn der Treiber eine DMA-Systemübertragung anfordert, kann der Treiber mit der Anforderung einen Zeiger auf diese Routine bereitstellen. Nach Abschluss der DMA-Übertragung wird die DmaCompletionRoutine-Routine automatisch aufgerufen, um den Treiber zu benachrichtigen.

Die DmaCompletionRoutine-Routine eines Treibers wird nur aufgerufen, wenn die vom Treiber angeforderte DMA-Übertragung einen DMA-Systemcontroller verwendet, der nach Abschluss einer DMA-Übertragung einen Interrupt generieren kann. Ein Treiber, der ein Bus-master DMA-Gerät verwendet oder ein System-DMA-Controller verwendet, der keine Interrupts generiert, muss andere Mittel verwenden, um zu bestimmen, wann eine DMA-Übertragung abgeschlossen ist. Beispielsweise kann dieser Treiber einen Timer-Interrupt verwenden, um die status der DMA-Übertragung regelmäßig abzufragen.

Ein Treiber kann einen Zeiger auf eine DmaCompletionRoutine-Routine als optionalen Parameter für die MapTransferEx-Routine bereitstellen.

Beispiele

Um eine DmaCompletionRoutine-Rückrufroutine zu definieren, müssen Sie zunächst eine Funktionsdeklaration bereitstellen, die den Typ der Rückrufroutine identifiziert, die Sie definieren. Windows bietet eine Reihe von Rückruffunktionstypen für Treiber. Das Deklarieren einer Funktion mithilfe der Rückruffunktionstypen hilft der Codeanalyse für Treiber, der statischen Treiberüberprüfung (Static Driver Verifier , SDV) und anderen Überprüfungstools, Fehler zu finden, und es ist eine Voraussetzung für das Schreiben von Treibern für das Windows-Betriebssystem.

Um beispielsweise eine DmaCompletionRoutine-Rückrufroutine mit dem Namen MyDmaCompletionRoutinezu definieren, verwenden Sie den typ DMA_COMPLETION_ROUTINE, wie in diesem Codebeispiel gezeigt:

DMA_COMPLETION_ROUTINE MyDmaCompletionRoutine;

Implementieren Sie dann Ihre Rückrufroutine wie folgt:

_Use_decl_annotations_
VOID
  MyDmaCompletionRoutine(
    PDMA_ADAPTER DmaAdapter,
    PDEVICE_OBJECT DeviceObject,
    PVOID CompletionContext,
    DMA_COMPLETION_STATUS Status
    )
  {
      // Function body
  }

Der DMA_COMPLETION_ROUTINE Funktionstyp ist in der Wdm.h-Headerdatei definiert. Um Fehler beim Ausführen der Codeanalysetools genauer zu identifizieren, fügen Sie die _Use_decl_annotations_ Anmerkung ihrer Funktionsdefinition hinzu. Die _Use_decl_annotations_ Anmerkung stellt sicher, dass die Anmerkungen verwendet werden, die auf den DMA_COMPLETION_ROUTINE Funktionstyp in der Headerdatei angewendet werden. Weitere Informationen zu den Anforderungen für Funktionsdeklarationen finden Sie unter Deklarieren von Funktionen mithilfe von Funktionsrollentypen für WDM-Treiber. Informationen zu _Use_decl_annotations_ finden Sie unter Annotating Function Behavior.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Verfügbar ab Windows 8.
Zielplattform	Desktop
Header	wdm.h (einschließlich Wdm.h, Ntddk.h, Ntifs.h)
IRQL	Wird bei DISPATCH_LEVEL aufgerufen.