KDEFERRED_ROUTINE Rückruffunktion (wdm.h)

Artikel
02/27/2024

Die Rückrufroutine führt aktionen aus, nachdem ein InterruptService zurückgegeben wurde, für einen DPC mit Thread,

Die CustomDpc-Routine beendet die Wartung eines E/A-Vorgangs, nachdem eine InterruptService-Routine zurückgegeben wird.

Die CustomThreadedDpc-Routine führt die Aktion eines Threaded-DPC aus. Das System führt diese Routine aus, wenn der threaded DPC ausgeführt wird.

Die CustomTimerDpc-Routine wird nach Ablauf des Zeitintervalls eines Zeitgeberobjekts ausgeführt.

Syntax

KDEFERRED_ROUTINE KdeferredRoutine;

void KdeferredRoutine(
  [in]           _KDPC *Dpc,
  [in, optional] PVOID DeferredContext,
  [in, optional] PVOID SystemArgument1,
  [in, optional] PVOID SystemArgument2
)
{...}

Parameter

[in] Dpc

Vom Aufrufer bereitgestellter Zeiger auf eine KDPC-Struktur , die das DPC-Objekt darstellt, das dieser Rückrufroutine zugeordnet ist.

[in, optional] DeferredContext

Für CustomDpc ist ein vom Aufrufer bereitgestellter Zeiger auf vom Treiber definierte Kontextinformationen, die in einem vorherigen Aufruf von KeInitializeDpc angegeben wurden.

Gibt für CustomThreadedDpc vom Treiber definierte Kontextinformationen an. Bei der Initialisierung des DPC-Objekts hat der Treiber diesen Wert als DeferredContext-Parameter für KeInitializeThreadedDpc angegeben.

Vom Aufrufer bereitgestellter Zeiger auf eine KDPC-Struktur , die das DPC-Objekt darstellt, das dieser CustomTimerDpc-Routine zugeordnet ist.

[in, optional] SystemArgument1

Vom Aufrufer bereitgestellter Zeiger auf vom Treiber bereitgestellte Informationen, die in einem vorherigen Aufruf von KeInsertQueueDpc angegeben wurden. Als er den DPC der DPC-Warteschlange hinzugefügt hat, hat der Treiber diesen Wert als SystemArgument1-Parameter für KeInsertQueueDpc angegeben.

Für CustomTimerDpc wird dieser Wert nicht verwendet.

[in, optional] SystemArgument2

Gibt vom Treiber definierte Kontextinformationen an. Als er den DPC der DPC-Warteschlange hinzugefügt hat, hat der Treiber diesen Wert als SystemArgument2-Parameter für KeInsertQueueDpc angegeben.

Für CustomTimerDpc wird dieser Wert nicht verwendet.

Rückgabewert

Keine

Bemerkungen

Um ein DPC-Objekt zu erstellen und eine CustomDpc-Routine für dieses Objekt zu registrieren, muss ein Treiber KeInitializeDpc aufrufen. (Wenn Sie nur eine DPC-Routine benötigen, können Sie eine DpcForIsr-Routine und das systemseitig zugewiesene DPC-Objekt verwenden.)

Um eine CustomDpc-Routine für die Ausführung in die Warteschlange zu stellen, muss die InterruptService-Routine eines Treibers KeInsertQueueDpc aufrufen.

Mindestens eine CustomDpc-Routine kann anstelle oder in Verbindung mit einer DpcForIsr-Routine verwendet werden. Ein Treiber, der mehrere interne IRP-Warteschlangen verwaltet, stellt normalerweise eine CustomDpc-Routine für jede Warteschlange bereit. Jede CustomDpc-Routine ist in der Regel für mindestens die folgenden Aufgaben verantwortlich:

Abschließen des E/A-Vorgangs, der von der aktuellen IRP beschrieben wird.
Trennen der nächsten IRP aus einer der IRP-Warteschlangen des Treibers. (Treiber, die die vom System bereitgestellte IRP-Warteschlange zusammen mit einem StartIo-Routineaufruf IoStartNextPacket verwenden.)
Festlegen des E/A-status-Blocks im aktuellen IRP und Aufrufen von IoCompleteRequest für die abgeschlossene Anforderung.

Eine CustomDpc-Routine kann auch einen fehlgeschlagenen Vorgang wiederholen oder die nächste Übertragung für eine große E/A-Anforderung einrichten, die in kleinere Teile unterteilt wurde.

Weitere Informationen zu CustomDpc-Routinen finden Sie unter DPC-Objekte und DPCs.

Ein Treiber registriert einen CustomThreadedDpc für ein DPC-Objekt, indem Er KeInitializeThreadedDpc aufruft. Um den DPC tatsächlich der DPC-Warteschlange hinzuzufügen, damit die CustomThreadedDpc-Routine ausgeführt wird, rufen Sie KeInsertQueueDpc auf.

Weitere Informationen zur Verwendung von CustomThreadedDpc-Routinen finden Sie unter Einführung in Threaded DPCs.

Eine CustomThreadedDpc-Routine kann unter IRQL = DISPATCH_LEVEL oder mit IRQL = PASSIVE_LEVEL in einem Echtzeitthread ausgeführt werden.

Um ein DPC-Objekt zu erstellen und eine CustomTimerDpc-Routine für dieses Objekt zu registrieren, muss ein Treiber KeInitializeDpc aufrufen.

Um eine CustomTimerDpc-Routine für die Ausführung in die Warteschlange zu stellen, muss eine Treiberroutine KeSetTimer oder KeSetTimerEx aufrufen und einen von KeInitializeDpc zurückgegebenen DPC-Objektzeiger bereitstellen. Das System ruft die CustomTimerDpc-Routine auf, wenn das Zeitgeberintervall abläuft.

Weitere Informationen zu CustomTimerDpc-Routinen finden Sie unter Timer-Objekte und DPCs.

Beispiele

Um eine Rückrufroutine zu definieren, müssen Sie zunächst eine Funktionsdeklaration bereitstellen, die den Typ der von Ihnen definierten Rückrufroutine identifiziert. 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 Anforderung zum Schreiben von Treibern für das Windows-Betriebssystem.

Um beispielsweise eine CustomDpc-Rückrufroutine mit dem Namen MyCustomDpczu definieren, verwenden Sie den typ KDEFERRED_ROUTINE, wie in diesem Codebeispiel gezeigt:

KDEFERRED_ROUTINE MyCustomDpc;

Implementieren Sie dann Ihre Rückrufroutine wie folgt:

_Use_decl_annotations_
VOID
  MyCustomDpc(
    struct _KDPC  *Dpc,
    PVOID  DeferredContext,
    PVOID  SystemArgument1,
    PVOID  SystemArgument2
    )
  {
      // Function body
  }