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.

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

See also

EvtDriverDeviceAdd

WDF_INTERRUPT_CONFIG

WDF_INTERRUPT_CONFIG_INIT

WDF_OBJECT_ATTRIBUTES

WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE