WdfInterruptCreate-Funktion (wdfinterrupt.h)

Artikel
03/22/2025

[Gilt für KMDF und UMDF]

Die WdfInterruptCreate-Methode erstellt ein Framework-Interruptobjekt.

Syntax

NTSTATUS WdfInterruptCreate(
  [in]           WDFDEVICE              Device,
  [in]           PWDF_INTERRUPT_CONFIG  Configuration,
  [in, optional] PWDF_OBJECT_ATTRIBUTES Attributes,
  [out]          WDFINTERRUPT           *Interrupt
);

Die Parameter

[in] Device

Ein Handle zu einem Framework-Geräteobjekt.

[in] Configuration

Ein Zeiger auf eine WDF_INTERRUPT_CONFIG Struktur, die durch einen Aufruf von WDF_INTERRUPT_CONFIG_INITinitialisiert wurde.

[in, optional] Attributes

Ein Zeiger auf eine WDF_OBJECT_ATTRIBUTES Struktur, die Objektattribute für das Framework-Interruptobjekt angibt. (Weitere Informationen finden Sie in den Hinweisen.) Dieser Parameter ist optional und kann WDF_NO_OBJECT_ATTRIBUTES werden.

[out] Interrupt

Ein Zeiger auf eine Position, die ein Handle für das neue Interruptobjekt empfängt.

Rückgabewert

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

Rückgabecode	BESCHREIBUNG
STATUS_INFO_LENGTH_MISMATCH	Die Größe der WDF_INTERRUPT_CONFIG Struktur ist falsch.
STATUS_INVALID_PARAMETER	Es wurde ein ungültiger Parameter angegeben.
STATUS_INVALID_DEVICE_STATE	WdfInterruptCreate wurde aufgerufen, nachdem das Gerät gestartet wurde. WdfInterruptCreate gibt diesen Wert auch zurück, wenn die EVT_WDF_DEVICE_PREPARE_HARDWARE Rückrufroutine des Treibers WdfInterruptCreate mit dem InterruptRaw und InterruptTranslated Member der WDF_INTERRUPT_CONFIG-Struktur auf NULL-festgelegt ist.
STATUS_INSUFFICIENT_RESOURCES	Nicht genügend Arbeitsspeicher vorhanden.
STATUS_WDF_PARENT_ASSIGNMENT_NOT_ALLOWED	In KMDF, Version 1.9 oder einer früheren Version, hat der Treiber einen Wert ohneNULL für das ParentObject Member der WDF_OBJECT_ATTRIBUTES Struktur angegeben. In KMDF, Version 1.11 oder höher, hat der Treiber einen anderen Wert als ein Frameworkgerät oder eine Warteschlange für das ParentObject-element der WDF_OBJECT_ATTRIBUTES-Struktur angegeben.
STATUS_WDF_INCOMPATIBLE_EXECUTION_LEVEL	Die AutomaticSerialization- Member der WDF_INTERRUPT_CONFIG-Struktur wird auf TRUE- und eines der folgenden Elemente festgelegt: Die Ausführungsebene des übergeordneten Objekts des Interrupts ist WdfExecutionLevelPassive und der Treiber hat EvtInterruptDpcangegeben. Die Ausführungsebene des übergeordneten Objekts des Interrupts ist WdfExecutionLevelDispatch und der Treiber hat EvtInterruptWorkItem-angegeben. Weitere Informationen finden Sie unter WDF_INTERRUPT_CONFIG.
STATUS_NOT_SUPPORTED	Der Treiber hat die Behandlung von Unterbrechungen auf passiver Ebene auf einer Plattform vor Windows 8 angefordert.

Eine Liste mit anderen Rückgabewerten, die die WdfInterruptCreate Methode möglicherweise zurückgeben, finden Sie unter Framework Object Creation Errors.

Diese Methode kann auch andere NTSTATUS-Wertezurückgeben.

Wenn der Treiber ein ungültiges Objekthandle bereitstellt, tritt eine Fehlerüberprüfung auf.

Bemerkungen

Treiber rufen in der Regel die WdfInterruptCreate-Methode aus einer EvtDriverDeviceAdd- Rückruffunktion auf. Ab KMDF Version 1.11 und UMDF, Version 2.0, können Treiber WdfInterruptCreate von EvtDevicePrepareHardwareaufrufen. Wenn der Treiber WdfInterruptCreate von EvtDriverDeviceAddaufruft, muss die InterruptRaw und InterruptTranslated Member der WDF_INTERRUPT_CONFIG Struktur NULL sein. Wenn der Treiber WdfInterruptCreate von EvtDevicePrepareHardwareaufruft, müssen beide Elemente gültig sein.

Wenn Sie ein Wake-fähiges Interruptobjekt erstellen, wie in Using an Interrupt to Wake a Devicebeschrieben, müssen Sie WdfInterruptCreate von EvtDevicePrepareHardwareaufrufen.

Ihr Treiber muss WdfInterruptCreate einmal für jeden von seinem Gerät benötigten Interruptvektor aufrufen. Wenn das Gerät Nachrichtensignalunterbrechungen (MSI) unterstützt, muss der Treiber für jede Nachricht, die das Gerät unterstützen kann, ein Interruptobjekt erstellen.

Nachdem der PnP-Manager dem Gerät Systemressourcen zuweist, speichert das Framework Informationen zu den zugewiesenen Interruptressourcen des Geräts in den interrupt-Objekten, die der Treiber erstellt hat. (Treiber, die plug and Play nicht unterstützen, können keine Unterbrechungsobjekte verwenden.)

Das System weist möglicherweise nicht alle Unterbrechungsressourcen zu, die ein Gerät unterstützen kann. Beispielsweise würde ein Treiber acht Interruptobjekte für ein Gerät erstellen, das acht MSI-Nachrichten unterstützen kann. Das System weist dem Gerät jedoch möglicherweise nur eine Nachricht zu. In diesem Fall werden sieben der Interruptobjekte nicht verwendet.

In der Regel sollte der Treiber interruptspezifische Informationen speichern, z. B. den kopierten Inhalt von Geräteunterbrechungsregistern, im Kontextbereich des Interruptobjekts. Die WDF_OBJECT_ATTRIBUTES Struktur, die der Treiber an WdfInterruptCreate übergibt, sollte den Kontextbereich beschreiben.

Bei Treibern, die Framework Version 1.9 und früher verwenden, ist das übergeordnete Element jedes Interruptobjekts das Geräteobjekt, zu dem der Interrupt gehört. Der Treiber kann dieses übergeordnete Element nicht ändern, und das ParentObject Member der WDF_OBJECT_ATTRIBUTES Struktur muss NULL-sein. Ab Version 1.11 kann ParentObject- ein Framework-Geräteobjekt oder Warteschlangenobjekt sein. Wenn der Treiber ein übergeordnetes Element angibt, muss der Treiber die AutomaticSerialization Element der Konfigurationsstruktur auf TRUE festlegen. Der Treiber kann ein übergeordnetes Element für beide Interrupts bei DIRQL und passiven Unterbrechungenangeben.

Wenn Ihr Treiber EvtCleanupCallback oder EvtDestroyCallback- Rückruffunktionen für das Framework-Interruptobjekt bereitstellt, beachten Sie, dass das Framework diese Rückruffunktionen bei IRQL = PASSIVE_LEVEL aufruft.

Weitere Informationen zum Behandeln von Unterbrechungen in frameworkbasierten Treibern finden Sie unter Behandeln von Hardware-Interrupts.

Beispiele

Im folgenden Codebeispiel wird eine WDF_INTERRUPT_CONFIG Struktur und eine WDF_OBJECT_ATTRIBUTES Struktur initialisiert und anschließend WdfInterruptCreateaufgerufen.

NTSTATUS  status;
WDF_INTERRUPT_CONFIG  interruptConfig;
WDF_OBJECT_ATTRIBUTES  interruptAttributes;

WDF_INTERRUPT_CONFIG_INIT(
                          &interruptConfig,
                          MyEvtInterruptIsr,
                          MyEvtInterruptDpc
                          );
WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(
                                        &interruptAttributes,
                                        INTERRUPT_DATA
                                        );
status = WdfInterruptCreate(
                            device,
                            &interruptConfig,
                            &interruptAttributes,
                            &devExt->WdfInterrupt
                            );

Anforderungen

Anforderung	Wert
Zielplattform	universell
Minimale KMDF-Version	1.0
Mindest-UMDF-Version	2.0
Kopfzeile	wdfinterrupt.h (einschließen Wdf.h)
Bibliothek	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
DDI-Complianceregeln	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)