WdfInterruptCreate-Funktion (wdfinterrupt.h)
[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
);
Parameter
[in] Device
Ein Handle für ein Framework-Geräteobjekt.
[in] Configuration
Ein Zeiger auf eine WDF_INTERRUPT_CONFIG-Struktur , die durch einen Aufruf von WDF_INTERRUPT_CONFIG_INIT initialisiert wurde.
[in, optional] Attributes
Ein Zeiger auf eine WDF_OBJECT_ATTRIBUTES-Struktur , die Objektattribute für das Framework-Interruptobjekt angibt. (Weitere Informationen finden Sie unter Hinweise.) Dieser Parameter ist optional und kann WDF_NO_OBJECT_ATTRIBUTES werden.
[out] Interrupt
Ein Zeiger auf eine Position, die ein Handle auf 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 |
|---|---|
|
Die Größe der WDF_INTERRUPT_CONFIG-Struktur ist falsch. |
|
Ein ungültiger Parameter wurde angegeben. |
|
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 aufruft , wobei die Member InterruptRaw und InterruptTranslated der WDF_INTERRUPT_CONFIG Struktur auf NULL festgelegt sind. |
|
Es war nicht genügend Arbeitsspeicher vorhanden. |
|
In KMDF-Version 1.9 oder früher hat der Treiber einen Wert nicht NULL für das ParentObject-Element 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. |
|
Das AutomaticSerialization-Element der WDF_INTERRUPT_CONFIG-Struktur ist auf TRUE festgelegt, und zwar auf:
|
|
Der Treiber hat die Behandlung von Unterbrechungen auf passiver Ebene auf einer Plattform früher als Windows 8 angefordert. |
Eine Liste mit anderen Rückgabewerten, die von der WdfInterruptCreate-Methode möglicherweise zurückgegeben werden, finden Sie unter Fehler beim Erstellen von Frameworkobjekten.
Diese Methode kann auch andere NTSTATUS-Werte zurückgeben.
Eine Fehlerüberprüfung tritt auf, wenn der Treiber ein ungültiges Objekthandle bereitstellt.
Hinweise
Treiber rufen in der Regel die WdfInterruptCreate-Methode von einer EvtDriverDeviceAdd-Rückruffunktion auf. Ab KMDF Version 1.11 und UMDF Version 2.0 können Treiber WdfInterruptCreate von EvtDevicePrepareHardware aufrufen. Wenn der Treiber WdfInterruptCreate von EvtDriverDeviceAdd aufruft, müssen die Member InterruptRaw und InterruptTranslated der WDF_INTERRUPT_CONFIG-Struktur NULL sein. Wenn der Treiber WdfInterruptCreate von EvtDevicePrepareHardware aufruft, müssen beide Elemente gültig sein.
Wenn Sie ein Wake-fähiges Interruptobjekt erstellen, wie unter Verwenden eines Interrupts zum Reaktivieren eines Geräts beschrieben, müssen Sie WdfInterruptCreate von EvtDevicePrepareHardware aufrufen.
Ihr Treiber muss WdfInterruptCreate einmal für jeden Interruptvektor aufrufen, den sein Gerät benötigt. Wenn das Gerät MSI (Message-Signaled Interrupts) unterstützt, muss der Treiber ein Interruptobjekt für jede Nachricht erstellen, die das Gerät unterstützen kann.
Nachdem der PnP-Manager dem Gerät Systemressourcen zugewiesen hat, speichert das Framework Informationen zu den dem Gerät zugewiesenen Interruptressourcen in den Interruptobjekten, die der Treiber erstellt hat. (Treiber, die Plug & Play nicht unterstützen, können keine Interruptobjekte verwenden.)
Das System weist möglicherweise nicht alle Interruptressourcen zu, die ein Gerät unterstützen kann. Ein Treiber würde beispielsweise 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 Ihr Treiber interruptspezifische Informationen, z. B. den kopierten Inhalt von Geräteunterbrechungsregistern, im Kontextbereich des Interruptobjekts speichern. Die WDF_OBJECT_ATTRIBUTES Struktur, die der Treiber an WdfInterruptCreate übergibt, sollte den Kontextraum beschreiben.
Bei Treibern mit Frameworkversion 1.9 und früher 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-Element der WDF_OBJECT_ATTRIBUTES-Struktur muss NULL sein. Ab Version 1.11 kann ParentObject ein Framework- oder Warteschlangenobjekt sein. Wenn der Treiber ein übergeordnetes Element angibt, muss der Treiber das Element AutomaticSerialization der Konfigurationsstruktur auf TRUE festlegen. Der Treiber kann sowohl für Interrupts auf DIRQL als auch für Interrupts auf passiver Ebene ein übergeordnetes Element angeben.
Wenn Ihr Treiber EvtCleanupCallback - oder EvtDestroyCallback-Rückruffunktionen für das Framework-Interruptobjekt bereitstellt, beachten Sie, dass das Framework diese Rückruffunktionen unter IRQL = PASSIVE_LEVEL aufruft.
Weitere Informationen zum Behandeln von Interrupts in frameworkbasierten Treibern finden Sie unter Behandeln von Hardwareunterbrechungen.
Beispiele
Im folgenden Codebeispiel werden eine WDF_INTERRUPT_CONFIG-Struktur und eine WDF_OBJECT_ATTRIBUTES-Struktur initialisiert und dann WdfInterruptCreate aufgerufen.
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 |
| KMDF-Mindestversion | 1.0 |
| UMDF-Mindestversion | 2.0 |
| Kopfzeile | wdfinterrupt.h (einschließen von Wdf.h) |
| Bibliothek | Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF) |
| IRQL | <=DISPATCH_LEVEL |
| DDI-Complianceregeln | DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf) |