InterruptMessageService routine

An InterruptMessageService routine services a message-signaled interrupt.

Syntax


KMESSAGE_SERVICE_ROUTINE InterruptMessageService;

BOOLEAN InterruptMessageService(
  _In_ struct _KINTERRUPT *Interrupt,
  _In_ PVOID              ServiceContext,
  _In_ ULONG              MessageId
)
{ ... }

Parameters

Interrupt [in]

A pointer to the KINTERRUPT structure for the interrupt. The driver received this pointer in the call to the IoConnectInterruptEx routine that registered the driver's InterruptMessageService routine.

ServiceContext [in]

The ServiceContext value that the driver passed to IoConnectInterruptEx when the InterruptMessageService routine was registered.

MessageId [in]

The message ID for the interrupt. This value is the index for the interrupt's entry in the MessageInfo member array in the IO_INTERRUPT_MESSAGE_INFO structure that describes the driver's message-signaled interrupts.

Return value

The InterruptMessageService routine returns TRUE if the interrupt is one handled by the InterruptMessageService routine. Otherwise, it returns FALSE.

Remarks

Drivers use IoConnectInterruptEx to register an InterruptMessageService routine to handle their message-signaled interrupts. A driver can subsequently unregister the routine by calling IoDisconnectInterruptEx. Message-signaled interrupts are supported starting with Windows Vista.

The system can call an InterruptMessageService routine even when the routine's interrupt has not occurred. For example, if a message-signaled interrupt is shared, InterruptMessageService can be called for interrupts belonging to other devices. The routine must check whether the value for the ServiceContext parameter matches the value passed to IoConnectInterruptEx. If the value does match, InterruptMessageService handles the interrupt and returns TRUE. Otherwise, InterruptMessageService does not handle the interrupt and returns FALSE.

Note that if the system receives multiple identical interrupts over a short time interval, it can combine these into a single call to InterruptMessageService. The routine must be written to handle multiple identical interrupts within a single call.

Message-signaled interrupts are similar in behavior to edge-triggered interrupts. The device sends an interrupt request but does not receive any hardware acknowledgment that the request was received.

An InterruptMessageService executes at an IRQL greater than or equal to the maximum device IRQL (DIRQL) for every interrupt the routine handles.

Examples

To define an InterruptMessageService callback routine, you must first provide a function declaration that identifies the type of callback routine 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 InterruptMessageService callback routine that is named MyInterruptMessageService, use the KMESSAGE_SERVICE_ROUTINE type as shown in this code example:


KMESSAGE_SERVICE_ROUTINE MyInterruptMessageService;

Then, implement your callback routine as follows:


_Use_decl_annotations_
BOOLEAN
  MyInterruptMessageService(
    struct _KINTERRUPT  *Interrupt,
    PVOID  ServiceContext,
    ULONG  MessageId 
    )
  {
      // Function body
  }

The KMESSAGE_SERVICE_ROUTINE function type is defined in the Wdm.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 KMESSAGE_SERVICE_ROUTINE 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 WDM Drivers. For information about _Use_decl_annotations_, see Annotating Function Behavior.

Requirements

Target platform

Desktop

Version

See Remarks section.

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)

IRQL

See Remarks section.

See also

IO_INTERRUPT_MESSAGE_INFO
IoConnectInterruptEx
IoDisconnectInterruptEx

 

 

Send comments about this topic to Microsoft

Show:
© 2015 Microsoft