WDF_INTERRUPT_CONFIG structure (wdfinterrupt.h)
[Applies to KMDF and UMDF]
The WDF_INTERRUPT_CONFIG structure contains configuration information for a device interrupt.
Syntax
typedef struct _WDF_INTERRUPT_CONFIG {
ULONG Size;
WDFSPINLOCK SpinLock;
WDF_TRI_STATE ShareVector;
BOOLEAN FloatingSave;
BOOLEAN AutomaticSerialization;
PFN_WDF_INTERRUPT_ISR EvtInterruptIsr;
PFN_WDF_INTERRUPT_DPC EvtInterruptDpc;
PFN_WDF_INTERRUPT_ENABLE EvtInterruptEnable;
PFN_WDF_INTERRUPT_DISABLE EvtInterruptDisable;
PFN_WDF_INTERRUPT_WORKITEM EvtInterruptWorkItem;
PCM_PARTIAL_RESOURCE_DESCRIPTOR InterruptRaw;
PCM_PARTIAL_RESOURCE_DESCRIPTOR InterruptTranslated;
WDFWAITLOCK WaitLock;
BOOLEAN PassiveHandling;
WDF_TRI_STATE ReportInactiveOnPowerDown;
BOOLEAN CanWakeDevice;
} WDF_INTERRUPT_CONFIG, *PWDF_INTERRUPT_CONFIG;
Members
Size
The size, in bytes, of this structure.
SpinLock
The handle to a framework spin-lock object, obtained by a previous call to WdfSpinLockCreate, or NULL. If this parameter is NULL, the framework uses an internal spin-lock object. The framework acquires the spin lock before it calls the driver's EvtInterruptSynchronize event callback function and when the driver calls WdfInterruptAcquireLock. For passive-level interrupt handling, set to NULL.
Starting with UMDF version 2.0, UMDF always uses passive-level interrupt handling. In this case, set this member to NULL.
ShareVector
A WDF_TRI_STATE-typed value. If this value is WdfTrue, the interrupt vector can be shared. If the value is WdfFalse, the interrupt vector cannot be shared. If the value is WdfDefault, the PnP manager uses the bus driver's value.
FloatingSave
A Boolean value that, if TRUE, indicates that the system will save the processor's floating point and MMX state when the device interrupts. If FALSE, the system does not save the floating point and MMX state. A driver should set this value to TRUE only if its EvtInterruptIsr callback function must use floating point or MMX registers. For more information about saving floating point and MMX state, see Using Floating Point or MMX in a WDM Driver.
This member is ignored starting in UMDF version 2.0.
AutomaticSerialization
A Boolean value that, if TRUE, indicates that the framework will synchronize 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. For more information, see the following Remarks section.
EvtInterruptIsr
A pointer to the driver's EvtInterruptIsr callback function. This pointer cannot be NULL.
EvtInterruptDpc
A pointer to the driver's EvtInterruptDpc callback function, or NULL. The driver can provide EvtInterruptWorkItem or EvtInterruptDpc, but not both.
EvtInterruptEnable
A pointer to the driver's EvtInterruptEnable callback function, or NULL.
EvtInterruptDisable
A pointer to the driver's EvtInterruptDisable callback function, or NULL.
EvtInterruptWorkItem
A pointer to the driver's EvtInterruptWorkItem callback function, or NULL. The driver can provide EvtInterruptWorkItem or EvtInterruptDpc, but not both. The EvtInterruptWorkItem member is available in version 1.11 and later versions of KMDF.
InterruptRaw
A pointer to the CM_PARTIAL_RESOURCE_DESCRIPTOR structure that describes the raw resources that the system assigned to the interrupt. This member is only used if the interrupt is created in the EvtDevicePrepareHardware callback. The InterruptRaw member is available in version 1.11 and later versions of KMDF.
InterruptTranslated
A pointer to the CM_PARTIAL_RESOURCE_DESCRIPTOR structure that describes the translated resources that the system assigned to the interrupt. This member is only used if the interrupt is created in the EvtDevicePrepareHardware callback. The InterruptTranslated member is available in version 1.11 and later versions of KMDF.
WaitLock
A handle to a framework wait-lock object, obtained by a previous call to WdfWaitLockCreate, or NULL. If WaitLock is non-NULL, PassiveHandling must be set to TRUE. The WaitLock member is available in version 1.11 and later versions of KMDF. For more information about WaitLock, see Remarks.
PassiveHandling
Set to FALSE for interrupt handling at the device's IRQL (DIRQL). Set to TRUE for passive-level interrupt handling. The PassiveHandling member is available in version 1.11 and later versions of KMDF. Starting in UMDF version 2.0, WDF_INTERRUPT_CONFIG_INIT always sets this member to TRUE.
ReportInactiveOnPowerDown
This member applies to KMDF only.
A WDF_TRI_STATE-typed value that applies only if the driver has not called WdfDeviceInitSetPowerNotPageable. This member can have one of the following values:
WdfTrue - KMDF reports the interrupt inactive when the device transitions to a low-power (Dx) state. In operating systems prior to Windows 8, the framework's behavior matches that described for WdfFalse.
WdfFalse - KMDF disconnects the interrupt when the device transitions to a low-power (Dx) state.
WdfDefault - On ARM-based platforms, the framework's behavior matches that described for WdfTrue. On other platforms, the framework's behavior matches that described for WdfFalse.
The ReportInactiveOnPowerDown member is available in version 1.11 and later versions of KMDF. It is not available in UMDF version 2.0.
For more information about reporting an interrupt inactive, see Making an ISR Active or Inactive.
CanWakeDevice
A Boolean value that indicates whether the interrupt is used to wake the device from a low-power state. If FALSE, the interrupt is not used to wake the device. If TRUE, the interrupt is used to wake the device. The CanWakeDevice member is available starting in KMDF version 1.13 and UMDF version 2.0.
Remarks
The WDF_INTERRUPT_CONFIG structure is used as input to WdfInterruptCreate.
To initialize a WDF_INTERRUPT_CONFIG structure, your driver must first call WDF_INTERRUPT_CONFIG_INIT and then fill in structure members that WDF_INTERRUPT_CONFIG_INIT does not initialize.
If AutomaticSerialization is TRUE, the following rules apply:
- If the execution level of the interrupt's parent object is WdfExecutionLevelPassive, the driver can supply EvtInterruptWorkItem, but should not supply EvtInterruptDpc in this configuration structure.
- If the execution level of the interrupt's parent object is WdfExecutionLevelDispatch, the driver can supply EvtInterruptDpc, but should not supply EvtInterruptWorkItem in this configuration structure. In this second case, the interrupt object itself can still be passive.
For more information about AutomaticSerialization and synchronizing driver callback functions, see Synchronization Techniques for Framework-Based Drivers.
By default, KMDF function drivers are power pageable. A driver calls WdfDeviceInitSetPowerNotPageable to specify that it is non-power pageable.
In KMDF versions earlier than 1.11, the framework always disconnects interrupts of power pageable drivers when the device transitions into a low-power (Dx) state. Starting in KMDF version 1.11, you can change this behavior by setting the ReportInactiveOnPowerDown member of this structure. For non-power pageable drivers, interrupts remain connected when Dx state transitions occur, regardless of the value set in ReportInactiveOnPowerDown.
If a UMDF driver sets ReportInactiveOnPowerDown, the value is ignored.
For more information about handling interrupts in framework-based drivers, see Handling Hardware Interrupts.
The driver can use this structure's CanWakeDevice member to create an interrupt that can be used to bring the device from a low-power Dx state back to D0. The driver's EvtInterruptIsr callback routine is scheduled to run at IRQL = PASSIVE_LEVEL after the device enters D0.
For more information, see Using an Interrupt to Wake a Device.
Requirements
| Requirement | Value |
|---|---|
| Minimum KMDF version | 1.0 |
| Minimum UMDF version | 2.0 |
| Header | wdfinterrupt.h (include Wdf.h) |