WDF_INTERRUPT_CONFIG-Struktur (wdfinterrupt.h)

Artikel
08/08/2023

[Gilt für KMDF und UMDF]

Die WDF_INTERRUPT_CONFIG-Struktur enthält Konfigurationsinformationen für einen Geräteunterbrechung.

Syntax

typedef struct _WDF_INTERRUPT_CONFIG {
  ULONG                           Size;
  WDFSPINLOCK                     SpinLock;
  WDF_TRI_STATE                   ShareVector;
  BOOLEAN                         FloatingSave;
  BOOLEAN                         AutomaticSerialization;
  PFN_WDF_INTERRUPT_ISR           EvtInterruptIsr;
  PFN_WDF_INTERRUPT_DPC           EvtInterruptDpc;
  PFN_WDF_INTERRUPT_ENABLE        EvtInterruptEnable;
  PFN_WDF_INTERRUPT_DISABLE       EvtInterruptDisable;
  PFN_WDF_INTERRUPT_WORKITEM      EvtInterruptWorkItem;
  PCM_PARTIAL_RESOURCE_DESCRIPTOR InterruptRaw;
  PCM_PARTIAL_RESOURCE_DESCRIPTOR InterruptTranslated;
  WDFWAITLOCK                     WaitLock;
  BOOLEAN                         PassiveHandling;
  WDF_TRI_STATE                   ReportInactiveOnPowerDown;
  BOOLEAN                         CanWakeDevice;
} WDF_INTERRUPT_CONFIG, *PWDF_INTERRUPT_CONFIG;

Member

Size

Die Größe (in Bytes) dieser Struktur.

SpinLock

Das Handle für ein Framework-Spin-Lock-Objekt, das durch einen vorherigen Aufruf von WdfSpinLockCreate oder NULL abgerufen wurde. Wenn dieser Parameter NULL ist, verwendet das Framework ein internes Spin-Lock-Objekt. Das Framework ruft die Drehsperre ab, bevor es die Ereignisrückruffunktion EvtInterruptSynchronize des Treibers aufruft und WdfInterruptAcquireLock aufruft. Legen Sie für die Behandlung von Interrupts auf passiver Ebene auf NULL fest.

Ab UMDF-Version 2.0 verwendet UMDF immer die Behandlung von Interrupts auf passiver Ebene. Legen Sie in diesem Fall diesen Member auf NULL fest.

ShareVector

Ein WDF_TRI_STATE typisierter Wert. Wenn dieser Wert WdfTrue ist, kann der Interruptvektor freigegeben werden. Wenn der Wert WdfFalse ist, kann der Interruptvektor nicht freigegeben werden. Wenn der Wert WdfDefault ist, verwendet der PnP-Manager den Wert des Bustreibers.

FloatingSave

Ein boolescher Wert, der bei TRUE angibt, dass das System den Gleitkomma- und MMX-Zustand des Prozessors speichert, wenn das Gerät unterbrochen wird. Bei FALSE speichert das System den Gleitkomma- und MMX-Zustand nicht. Ein Treiber sollte diesen Wert nur dann auf TRUE festlegen, wenn seine EvtInterruptIsr-Rückruffunktion Gleitkomma- oder MMX-Register verwenden muss. Weitere Informationen zum Speichern von Gleitkomma und MMX-Zustand finden Sie unter Verwenden von Gleitkomma oder MMX in einem WDM-Treiber.

Dieser Member wird ab UMDF-Version 2.0 ignoriert.

AutomaticSerialization

Ein boolescher Wert, der bei TRUE angibt, dass das Framework die Ausführung der Rückruffunktion EvtInterruptDpc oder EvtInterruptWorkItem des Interruptobjekts mit Rückruffunktionen von anderen Objekten synchronisiert, die sich unterhalb des übergeordneten Objekts des Interrupts befinden. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".

EvtInterruptIsr

Ein Zeiger auf die Rückruffunktion EvtInterruptIsr des Treibers. Dieser Zeiger darf nicht NULL sein.

EvtInterruptDpc

Ein Zeiger auf die EvtInterruptDpc-Rückruffunktion des Treibers oder NULL. Der Treiber kann EvtInterruptWorkItem oder EvtInterruptDpc bereitstellen, aber nicht beides.

EvtInterruptEnable

Ein Zeiger auf die EvtInterruptEnable-Rückruffunktion des Treibers oder NULL.

EvtInterruptDisable

Ein Zeiger auf die Rückruffunktion EvtInterruptDisable des Treibers oder NULL.

EvtInterruptWorkItem

Ein Zeiger auf die EvtInterruptWorkItem-Rückruffunktion des Treibers oder NULL. Der Treiber kann EvtInterruptWorkItem oder EvtInterruptDpc bereitstellen, aber nicht beides. Das EvtInterruptWorkItem-Element ist in Version 1.11 und höheren Versionen von KMDF verfügbar.

InterruptRaw

Ein Zeiger auf die CM_PARTIAL_RESOURCE_DESCRIPTOR Struktur, die die Rohressourcen beschreibt, die das System dem Interrupt zugewiesen hat. Dieser Member wird nur verwendet, wenn der Interrupt im EvtDevicePrepareHardware-Rückruf erstellt wird. Der InterruptRaw-Member ist in Version 1.11 und höheren Versionen von KMDF verfügbar.

InterruptTranslated

Ein Zeiger auf die CM_PARTIAL_RESOURCE_DESCRIPTOR-Struktur , die die übersetzten Ressourcen beschreibt, die das System dem Interrupt zugewiesen hat. Dieser Member wird nur verwendet, wenn der Interrupt im EvtDevicePrepareHardware-Rückruf erstellt wird. Das InterruptTranslated-Element ist in Version 1.11 und höheren Versionen von KMDF verfügbar.

WaitLock

Ein Handle für ein Framework-Wait-Lock-Objekt, das durch einen vorherigen Aufruf von WdfWaitLockCreate oder NULL abgerufen wurde. Wenn WaitLock nicht NULL ist, muss PassiveHandling auf TRUE festgelegt werden. Das WaitLock-Element ist in Version 1.11 und höheren Versionen von KMDF verfügbar. Weitere Informationen zu WaitLock finden Sie unter Hinweise.

PassiveHandling

Legen Sie für die Interruptbehandlung am IRQL (DIRQL) des Geräts auf FALSE fest. Legen Sie für die Behandlung von Interrupts auf passiver Ebene auf TRUE fest. Der PassiveHandling-Member ist in Version 1.11 und höheren Versionen von KMDF verfügbar. Ab UMDF-Version 2.0 legt WDF_INTERRUPT_CONFIG_INIT diesen Member immer auf TRUE fest.

ReportInactiveOnPowerDown

Dieser Member gilt nur für KMDF.

Ein WDF_TRI_STATE typisierter Wert, der nur gilt, wenn der Treiber WdfDeviceInitSetPowerNotPageable nicht aufgerufen hat. Dieser Member kann einen der folgenden Werte aufweisen:

WdfTrue : KMDF meldet den Interrupt inaktiv, wenn das Gerät in einen Low-Power-Zustand (Dx) wechselt. In Betriebssystemen vor Windows 8 stimmt das Verhalten des Frameworks mit dem für WdfFalse beschrieben überein.

Hinweis Wenn CanWakeDevice auf TRUE und ReportInactiveOnPowerDown auf WdfTrue festgelegt ist, meldet das Framework den Interrupt nicht inaktiv, wenn das Gerät in einen Energiesparzustand wechselt.

WdfFalse : KMDF trennt den Interrupt, wenn das Gerät in einen Zustand mit niedriger Leistung (Dx) wechselt.

WdfDefault : Auf ARM-basierten Plattformen entspricht das Verhalten des Frameworks dem für WdfTrue beschriebenen Verhalten. Auf anderen Plattformen stimmt das Verhalten des Frameworks mit dem für WdfFalse beschrieben überein.

Das ReportInactiveOnPowerDown-Element ist in Version 1.11 und höheren Versionen von KMDF verfügbar. Sie ist in UMDF-Version 2.0 nicht verfügbar.

Weitere Informationen zum Melden eines Interrupts inaktiv finden Sie unter Aktivieren oder Inaktivieren einer ISR.

CanWakeDevice

Ein boolescher Wert, der angibt, ob der Interrupt verwendet wird, um das Gerät aus einem Energiesparzustand zu reaktivieren. Bei FALSE wird der Interrupt nicht verwendet, um das Gerät zu reaktivieren. Wenn TRUE, wird der Interrupt verwendet, um das Gerät zu reaktivieren. Das CanWakeDevice-Element ist ab KMDF-Version 1.13 und UMDF-Version 2.0 verfügbar.

Hinweise

Die WDF_INTERRUPT_CONFIG-Struktur wird als Eingabe für WdfInterruptCreate verwendet.

Um eine WDF_INTERRUPT_CONFIG-Struktur zu initialisieren, muss Ihr Treiber zuerst WDF_INTERRUPT_CONFIG_INIT aufrufen und dann Strukturmember ausfüllen, die WDF_INTERRUPT_CONFIG_INIT nicht initialisiert.

Wenn AutomaticSerialization den Wert TRUE aufweist, gelten die folgenden Regeln:

Wenn die Ausführungsebene des übergeordneten Objekts des Interrupts WdfExecutionLevelPassive ist, kann der Treiber EvtInterruptWorkItem bereitstellen, sollte aber evtInterruptDpc in dieser Konfigurationsstruktur nicht bereitstellen.
Wenn die Ausführungsebene des übergeordneten Objekts des Interrupts WdfExecutionLevelDispatch ist, kann der Treiber EvtInterruptDpc angeben, sollte aber EvtInterruptWorkItem in dieser Konfigurationsstruktur nicht bereitstellen. In diesem zweiten Fall kann das Interruptobjekt selbst noch passiv sein.

Der Treiber kann den WaitLock-Member dieser Struktur verwenden, um eine eigene Interruptsperre für die Behandlung von Interrupts auf passiver Ebene bereitzustellen. Wenn der Treiber PassiveHandling auf TRUE festlegt, aber keinen WaitLock bereitstellt, erstellt das Framework intern eine Interruptsperre. Das Framework ruft die Interruptsperre auf passiver Ebene ab, bevor die folgenden Rückruffunktionen aufgerufen werden:

EvtInterruptEnable

EvtInterruptDisable

EvtInterruptSynchronize

EvtInterruptIsr

Weitere Informationen zur AutomaticSerialisierung und zur Synchronisierung von Treiberrückruffunktionen finden Sie unter Synchronisierungstechniken für Framework-Based-Treiber.

Standardmäßig sind KMDF-Funktionstreiber power pageable. Ein Treiber ruft WdfDeviceInitSetPowerNotPageable auf, um anzugeben, dass er nicht ausgelagert werden kann.

In KMDF-Versionen vor 1.11 trennt das Framework unterbrechungsfreie Treiber immer, wenn das Gerät in einen Dx-Zustand (Low-Power) wechselt. Ab KMDF-Version 1.11 können Sie dieses Verhalten ändern, indem Sie den ReportInactiveOnPowerDown-Member dieser Struktur festlegen. Bei Treibern, die keine Energie ausgelagert werden können, bleiben Unterbrechungen verbunden, wenn Dx-Zustandsübergänge auftreten, unabhängig vom in ReportInactiveOnPowerDown festgelegten Wert.

Wenn ein UMDF-Treiber ReportInactiveOnPowerDown festlegt, wird der Wert ignoriert.

Weitere Informationen zur Behandlung von Interrupts in frameworkbasierten Treibern finden Sie unter Behandeln von Hardwareunterbrechungen.

Der Treiber kann den CanWakeDevice-Member dieser Struktur verwenden, um einen Interrupt zu erstellen, der verwendet werden kann, um das Gerät aus einem Dx-Low-Power-Zustand wieder zu D0 zu bringen. Die EvtInterruptIsr-Rückrufroutine des Treibers ist für die Ausführung bei IRQL = PASSIVE_LEVEL geplant, nachdem das Gerät D0 eingegeben hat.

Weitere Informationen finden Sie unter Verwenden eines Interrupts zum Aktivieren eines Geräts.