WdfInterruptCreate function (wdfinterrupt.h)
[Applies to KMDF and UMDF]
The WdfInterruptCreate method creates a framework interrupt object.
Syntax
NTSTATUS WdfInterruptCreate(
[in] WDFDEVICE Device,
[in] PWDF_INTERRUPT_CONFIG Configuration,
[in, optional] PWDF_OBJECT_ATTRIBUTES Attributes,
[out] WDFINTERRUPT *Interrupt
);
Parameters
[in] Device
A handle to a framework device object.
[in] Configuration
A pointer to a WDF_INTERRUPT_CONFIG structure that was initialized by a call to WDF_INTERRUPT_CONFIG_INIT.
[in, optional] Attributes
A pointer to a WDF_OBJECT_ATTRIBUTES structure that specifies object attributes for the framework interrupt object. (See Remarks for additional information.) This parameter is optional and can be WDF_NO_OBJECT_ATTRIBUTES.
[out] Interrupt
A pointer to a location that receives a handle to the new interrupt object.
Return value
WdfInterruptCreate returns STATUS_SUCCESS if the operation succeeds. Otherwise, this method might return one of the following values.
| Return code | Description |
|---|---|
|
The size of the WDF_INTERRUPT_CONFIG structure is incorrect. |
|
An invalid parameter was specified. |
|
WdfInterruptCreate was called after the device was started. WdfInterruptCreate also returns this value if the driver's EVT_WDF_DEVICE_PREPARE_HARDWARE callback routine calls WdfInterruptCreate with the InterruptRaw and InterruptTranslated members of the WDF_INTERRUPT_CONFIG structure set to NULL. |
|
There was insufficient memory. |
|
In KMDF version 1.9 or earlier, the driver specified a non-NULL value for the ParentObject member of the WDF_OBJECT_ATTRIBUTES structure.
In KMDF version 1.11 or later, the driver specified a value other than a framework device or queue for the ParentObject member of the WDF_OBJECT_ATTRIBUTES structure. |
|
The AutomaticSerialization member of the WDF_INTERRUPT_CONFIG structure is set to TRUE and either:
|
|
The driver requested passive-level interrupt handling on a platform earlier than Windows 8. |
For a list of other return values that the WdfInterruptCreate method might return, see Framework Object Creation Errors.
This method also might return other NTSTATUS values.
A bug check occurs if the driver supplies an invalid object handle.
Remarks
Drivers typically call the WdfInterruptCreate method from an EvtDriverDeviceAdd callback function. Starting in KMDF version 1.11 and UMDF version 2.0, drivers can call WdfInterruptCreate from EvtDevicePrepareHardware. If the driver calls WdfInterruptCreate from EvtDriverDeviceAdd, the InterruptRaw and InterruptTranslated members of the WDF_INTERRUPT_CONFIG structure must be NULL. If the driver calls WdfInterruptCreate from EvtDevicePrepareHardware, these members must both be valid.
If you are creating a wake-capable interrupt object, as described in Using an Interrupt to Wake a Device, you must call WdfInterruptCreate from EvtDevicePrepareHardware.
Your driver must call WdfInterruptCreate once for each interrupt vector that its device requires. If the device supports message-signaled interrupts (MSI), the driver must create an interrupt object for each message that the device can support.
After the PnP manager assigns system resources to the device, the framework stores information about the device's assigned interrupt resources in the interrupt objects that the driver has created. (Drivers that do not support Plug and Play cannot use interrupt objects.)
The system might not assign all of the interrupt resources that a device can support. For example, a driver would create eight interrupt objects for a device that is capable of supporting eight MSI messages. However, the system might assign only one message to the device. In that case, seven of the interrupt objects will be unused.
Typically, your driver should store interrupt-specific information, such as the copied contents of device interrupt registers, in the interrupt object's context space. The WDF_OBJECT_ATTRIBUTES structure that the driver passes to WdfInterruptCreate should describe the context space.
For drivers using framework version 1.9 and earlier, the parent of each interrupt object is the device object that the interrupt belongs to. The driver cannot change this parent, and the ParentObject member of the WDF_OBJECT_ATTRIBUTES structure must be NULL. Beginning in version 1.11, ParentObject can be a framework device object or queue object. If the driver specifies a parent, the driver must set the AutomaticSerialization member of the configuration structure to TRUE. The driver can specify a parent for both interrupts at DIRQL and passive-level interrupts.
If your driver provides EvtCleanupCallback or EvtDestroyCallback callback functions for the framework interrupt object, note that the framework calls these callback functions at IRQL = PASSIVE_LEVEL.
For more information about handling interrupts in framework-based drivers, see Handling Hardware Interrupts.
Examples
The following code example initializes a WDF_INTERRUPT_CONFIG structure and a WDF_OBJECT_ATTRIBUTES structure and then calls WdfInterruptCreate.
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
);
Requirements
| Requirement | Value |
|---|---|
| Target Platform | Universal |
| Minimum KMDF version | 1.0 |
| Minimum UMDF version | 2.0 |
| Header | wdfinterrupt.h (include Wdf.h) |
| Library | Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF) |
| IRQL | <=DISPATCH_LEVEL |
| DDI compliance rules | DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf) |