Creating an Interrupt Object

A Windows Driver Frameworks (WDF) driver that handles a device's hardware interrupts must create a framework interrupt object for each interrupt that each device can support. In framework versions 1.11 and later running on Windows 8 or later versions of the operating system, Kernel-Mode Driver Framework (KMDF) and User-Mode Driver Framework (UMDF) drivers can create interrupt objects requiring passive-level handling. Unless you are writing a driver for a System on a Chip (SoC) platform, however, your driver should use DIRQL interrupt objects.

A driver typically creates framework interrupt objects in its EvtDriverDeviceAdd callback function. A driver can also create interrupt objects from its EvtDevicePrepareHardware callback function.

The framework calls the driver's EvtDriverDeviceAdd callback function before the Plug and Play (PnP) manager has assigned system resources, such as interrupt vectors, to the device. After the PnP manager assigns resources, the framework stores interrupt resources in the device's interrupt object. (Drivers that do not support Plug and Play cannot use interrupt objects.)

To create a framework interrupt object, your driver must initialize a WDF_INTERRUPT_CONFIG structure and pass it to the WdfInterruptCreate method.

UMDF supports the following types of interrupts:

• Level-triggered (shared or exclusive)
• Edge-triggered (exclusive only)
• MSI (exclusive by definition)

Note  UMDF does not support shared edge-triggered interrupts.

Starting in UMDF version 2.15, UMDF supports interrupts for simple devices like hardware push-buttons, usually backed by GPIO pins, that you cannot enable or disable explicitly using hardware registers. To support such devices, a UMDF driver must use exclusive edge-triggered interrupts.

Starting in KMDF version 1.15, KMDF also supports interrupts for such devices, without the workaround described in Handling Active-Both Interrupts.

Also in WDF_INTERRUPT_CONFIG, your driver supplies pointers to the following driver-supplied event callback functions:

EvtInterruptEnable
Enables a hardware interrupt.

EvtInterruptDisable
Disables a hardware interrupt.

EvtInterruptIsr
Interrupt service routine (ISR) for the interrupt.

EvtInterruptDpc
Deferred procedure call (DPC) for the interrupt.

EvtInterruptWorkItem
Work item for a passive-level interrupt.

For drivers using framework version 1.11 or later on Windows 8 or later versions of the operating system, the driver can explicitly set the parent of a framework interrupt object (DIRQL or passive) to either a framework device object or a framework queue object. If the driver specifies a parent, the driver must set the AutomaticSerialization member of the interrupt object's WDF_INTERRUPT_CONFIG structure to TRUE. (Recall that if AutomaticSerialization is TRUE, the framework synchronizes execution of the interrupt object's EvtInterruptDpc or EvtInterruptWorkItem callback function with callback functions from other objects that are underneath the interrupt's parent object.)

As an example, a driver might specify a queue as parent of an interrupt to synchronize the queue's callbacks with either the interrupt's EvtInterruptDpc or EvtInterruptWorkItem callback. In this configuration, the framework deletes the queue object when it deletes the device object.

After calling WdfInterruptCreate, the driver can optionally call WdfInterruptSetPolicy or WdfInterruptSetExtendedPolicy to specify additional interrupt parameters. Typically the driver calls these methods from its EvtDriverDeviceAdd callback function.

The framework automatically deletes the interrupt before deleting the interrupt's parent. Optionally, a driver can call WdfObjectDelete to delete the interrupt at an earlier time.

Supporting Message-signaled Interrupts

Message-signaled interrupts (MSIs) are supported starting with Windows Vista. To enable the operating system to support MSIs for your device, your driver's INF file must set some values in the registry. For information about how to set these values, see Enabling Message-Signaled Interrupts in the Registry.

Your driver should create a framework interrupt object for each interrupt vector or MSI message that the device can support. If the PnP manager does not grant the device all of the interrupt resources that the device can support, the extra interrupt objects will not be used and their callback functions will not be called.

In Windows 7, the operating system does not support resource requests for more than 910 interrupt messages per device function. In Windows 8, the operating system does not support resource requests for more than 2048 interrupts per device function.

If the device driver exceeds this limit, the device might fail to start. To operate in a computer that contains many logical processors, the driver should not request more than one interrupt per processor.

A driver must tolerate, without failures, system rebalancing of interrupt resources in which the PnP manager assigns to the device any set of alternative interrupt resources from the resource requirements list. For example, the device might be assigned a smaller number of message interrupts than the driver requested. In the worst case, the driver must be prepared to operate the device with just one line-based interrupt.