WUDF_INTERRUPT_ISR callback function (wudfinterrupt.h)

Article
08/12/2022

Warning

UMDF 2 is the latest version of UMDF and supersedes UMDF 1. All new UMDF drivers should be written using UMDF 2. No new features are being added to UMDF 1 and there is limited support for UMDF 1 on newer versions of Windows 10. Universal Windows drivers must use UMDF 2. For more info, see Getting Started with UMDF.

A driver's OnInterruptIsr event callback function services a hardware interrupt.

Syntax

typedef
BOOLEAN
_Function_class_(WUDF_INTERRUPT_ISR)
WUDF_INTERRUPT_ISR(
    _In_
    IWDFInterrupt* Interrupt,
    _In_
    ULONG MessageID,
    _In_
    ULONG Reserved
    );

typedef WUDF_INTERRUPT_ISR *PFN_WUDF_INTERRUPT_ISR;

Parameters

[in] Interrupt

A pointer to the IWDFInterrupt interface.

[in] MessageID

If the device is using message-signaled interrupts (MSIs), this parameter is the message number that identifies the device's hardware interrupt message. Otherwise, this value is 0.

[in] Reserved

Reserved for system use.

Return value

None

Remarks

Returns TRUE if the driver acknowledges ownership of the interrupt, and has stopped and acknowledged the interrupt on its device. Otherwise, returns FALSE.

To register an OnInterruptIsr callback function, your driver must place the callback function's address in a WUDF_INTERRUPT_CONFIG structure before calling IWDFDevice3::CreateInterrupt.

The OnInterruptIsr callback function is a UMDF driver's interrupt service routine (ISR), which is called at PASSIVE_LEVEL when a hardware interrupt occurs.

For an edge-triggered interrupt or message-signaled interrupt (MSI), the framework calls OnInterruptIsr outside of the operating system's interrupt dispatch context. This is because UMDF allows only non-shared edge-triggered or MSI interrupts, and the driver does not need to interact with its hardware within this context.

For a level-triggered interrupt, the framework calls OnInterruptIsr in the context of the operating system's interrupt dispatch. As a result, the operating system's interrupt dispatch thread is blocked in kernel-mode waiting for a response from the driver.

Typically, OnInterruptIsr saves any volatile information that might be lost and clears the hardware interrupt. For a level-triggered interrupt, the driver should stop and acknowledge the interrupt on the device and then return TRUE if it owns the interrupt. The driver should do any further processing in an OnInterruptWorkItem callback. To queue a work item, the driver calls the IWDFInterrupt::QueueWorkItemForIsr method.

For more information about handling interrupts in UMDF drivers, see Accessing Hardware and Handling Interrupts.

Examples

The function type is declared in Wudfinterrupt.h, as follows.

typedef
BOOLEAN
WUDF_INTERRUPT_ISR(
    _In_
    IWDFInterrupt* Interrupt,
    _In_
    ULONG MessageID,
    _In_
    ULONG Reserved
    );

typedef WUDF_INTERRUPT_ISR *PFN_WUDF_INTERRUPT_ISR;

To define an OnInterruptIsr callback function that is named MyInterruptIsr, you must first provide a function declaration that SDV and other verification tools require, as follows:

WUDF_INTERRUPT_NOTIFY  MyInterruptIsr;

Then, implement your callback function as follows:

BOOLEAN
  MyInterruptIsr (
    IN IWDFInterrupt*  Interrupt,
    IN ULONG  MessageID,
    IN ULONG Reserved
    )
  {…}

Requirements

Requirement	Value
End of support	Unavailable in UMDF 2.0 and later.
Target Platform	Desktop
Minimum UMDF version	1.11
Header	wudfinterrupt.h

Share via