EvtInterruptIsr function

[Applies to KMDF and UMDF]

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

Syntax


EVT_WDF_INTERRUPT_ISR EvtInterruptIsr;

BOOLEAN EvtInterruptIsr(
  _In_  WDFINTERRUPT Interrupt,
  _In_  ULONG MessageID
)
{ ... }

Parameters

Interrupt [in]

A handle to a framework interrupt object.

MessageID [in]

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.

Return value

The EvtInterruptIsr callback function must return TRUE if the function services the hardware interrupt. Otherwise, this function must return FALSE.

Remarks

To register an EvtInterruptIsr callback function, your driver must place the callback function's address in a WDF_INTERRUPT_CONFIG structure before calling WdfInterruptCreate.

The EvtInterruptIsr callback function is a framework-based driver's interrupt service routine (ISR), which is called when a hardware interrupt occurs.

If the interrupt is not from the hardware that this EvtInterruptIsr callback function services, the driver must return FALSE. If the interrupt vector is being shared, the system calls another interrupt service routine.

If the driver has not requested passive-level handling for an interrupt object, then before calling the EvtInterruptIsr callback function, the framework raises the processor's IRQL to the device's IRQL (DIRQL) and acquires the spin lock that the driver specified in the interrupt object's WDF_INTERRUPT_CONFIG structure.

Because the EvtInterruptIsr callback function executes at a relatively high IRQL, it can call very few framework object methods or system routines. Additionally, this callback function cannot access pageable code.

Typically, the EvtInterruptIsr callback function clears the hardware interrupt and saves any information that might be lost after the callback function returns and the system lowers the IRQL (because lowering the IRQL allows additional interrupts to occur). Framework-based drivers save information about the interrupt in the interrupt object's context space.

Drivers typically provide an EvtInterruptDpc callback function to process the saved information at a lower IRQL. (A few drivers provide one or more EvtDpcFunc callback functions instead of an EvtInterruptDpc callback function.) For information about scheduling an EvtInterruptDpc callback function for execution, see Servicing an Interrupt.

The EvtInterruptIsr callback function must be able to service several interrupts before the EvtInterruptDpc callback function executes. Therefore, the driver might have to store interrupt data from several interrupts, and the EvtInterruptIsr andEvtInterruptDpc callback functions might have to determine which interrupt data has been completely processed by the driver and which has not.

Beginning with version 1.11 of KMDF, your driver can provide passive-level interrupt handling. If the driver has requested passive-level handling for an interrupt object, then before calling that interrupt's EvtInterruptIsr callback function at IRQL = PASSIVE_LEVEL, the framework acquires the passive-level interrupt lock that the driver configured in the interrupt object's WDF_INTERRUPT_CONFIG structure. As with interrupt handling at DIRQL, the driver's EvtInterruptIsr function should still save information about the interrupt for later processing.

Drivers that support passive-level interrupt handling can provide either an EvtInterruptWorkItem or an EvtInterruptDpc callback function to process the saved information.

For more information about handling interrupts in framework-based drivers, see Handling Hardware Interrupts.

Examples

To define an EvtInterruptIsr callback function, you must first provide a function declaration that identifies the type of callback function you’re defining. Windows provides a set of callback function types for drivers. Declaring a function using the callback function types helps Code Analysis for Drivers, Static Driver Verifier (SDV), and other verification tools find errors, and it’s a requirement for writing drivers for the Windows operating system.

For example, to define an EvtInterruptIsr callback function that is named MyInterruptIsr, use the EVT_WDF_INTERRUPT_ISR type as shown in this code example:


EVT_WDF_INTERRUPT_ISR  MyInterruptIsr;

Then, implement your callback function as follows.


_Use_decl_annotations_
BOOLEAN
 MyInterruptIsr (
    WDFINTERRUPT  Interrupt,
    ULONG  MessageID
    )
  {...}

The EVT_WDF_INTERRUPT_ISR function type is defined in the Wdfinterrupt.h header file. To more accurately identify errors when you run the code analysis tools, be sure to add the _Use_decl_annotations_ annotation to your function definition. The _Use_decl_annotations_ annotation ensures that the annotations that are applied to the EVT_WDF_INTERRUPT_ISR function type in the header file are used. For more information about the requirements for function declarations, see Declaring Functions by Using Function Role Types for KMDF Drivers. For information about _Use_decl_annotations_, see Annotating Function Behavior.

Requirements

Minimum KMDF version

1.0

Minimum UMDF version

2.0

Header

Wdfinterrupt.h (include Wdf.h)

IRQL

(See Remarks section.)

See also

WdfInterruptCreate
WdfInterruptGetDevice
WdfInterruptGetInfo
WdfInterruptWdmGetInterrupt
WDF_INTERRUPT_CONFIG
EvtDpcFunc
EvtInterruptDpc

 

 

Send comments about this topic to Microsoft

Mostrar:
© 2014 Microsoft