DMA_COMPLETION_ROUTINE Rückruffunktion (wdm.h)

Die DmaCompletionRoutine-Rückrufroutine benachrichtigt den Treiber, der zuvor eine System-DMA-Übertragung angefordert hat, die 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-Kanal 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 treiberbestimmten Kontext für die DmaCompletionRoutine-Routine . Dieser Kontext ist der Parameterwert "CompletionContext ", den der Treiber zuvor an den MapTransferEx-Aufruf übergeben hat, der die System-DMA-Übertragung initiiert hat.

[in] Status

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

Rückgabewert

Keine

Bemerkungen

Als Option kann ein Treiber eine DmaCompletionRoutine-Routine implementieren. Wenn der Treiber eine System-DMA-Ü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 System-DMA-Controller verwendet, der nach Abschluss einer DMA-Übertragung eine Unterbrechung generieren kann. Ein Treiber, der ein Busmaster-DMA-Gerät verwendet oder ein System-DMA-Controller verwendet, der keine Unterbrechungen generiert, muss andere Mittel verwenden, um festzustellen, wann eine DMA-Übertragung abgeschlossen ist. Dieser Treiber kann beispielsweise einen Zeitgeber-Unterbrechung verwenden, um den Status der DMA-Übertragung regelmäßig zu überprüfen.

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

Beispiele

Um eine DmaCompletionRoutine-Rückrufroutine zu definieren, müssen Sie zuerst eine Funktionsdeklaration bereitstellen, die den Typ der Rückrufroutine identifiziert, die Sie definieren. Windows stellt einen Satz von Rückruffunktionstypen für Treiber bereit. Das Deklarieren einer Funktion mithilfe der Rückruffunktionstypen hilft bei der Codeanalyse für Treiber, statischer Treiberüberprüfung (SDV) und anderen Überprüfungstools, Fehler zu finden, und es ist eine Anforderung für das Schreiben von Treibern für das Windows-Betriebssystem.

Um beispielsweise eine DmaCompletionRoutine-Rückrufroutine zu definieren, die benannt MyDmaCompletionRoutinewird, verwenden Sie den DMA_COMPLETION_ROUTINE-Typ wie in diesem Codebeispiel dargestellt:

DMA_COMPLETION_ROUTINE MyDmaCompletionRoutine;

Implementieren Sie dann wie folgt Ihre Rückrufroutine:


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

Der DMA_COMPLETION_ROUTINE Funktionstyp wird in der Wdm.h-Headerdatei definiert. Um Fehler genauer zu identifizieren, wenn Sie die Codeanalysetools ausführen, müssen Sie die Use_decl_annotations Anmerkungen zu Ihrer Funktionsdefinition hinzufügen. Die Use_decl_annotations-Anmerkung stellt sicher, dass die Anmerkungen, die auf den DMA_COMPLETION_ROUTINE Funktionstyp in der Kopfzeilendatei angewendet werden, 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

   
Unterstützte Mindestversion (Client) Ab Windows 8 verfügbar.
Zielplattform Power BI Desktop
Header wdm.h (enthalten Wdm.h, Ntddk.h, Ntifs.h)
IRQL Aufgerufen bei DISPATCH_LEVEL.

Weitere Informationen

BuildScatterGatherListEx

DEVICE_OBJECT

DMA_ADAPTER

DMA_COMPLETION_STATUS

DMA_OPERATIONS

GetScatterGatherListEx

MapTransferEx