KMESSAGE_SERVICE_ROUTINE callback function (wdm.h)

Article
02/28/2023

An InterruptMessageService routine services a message-signaled interrupt.

Syntax

KMESSAGE_SERVICE_ROUTINE KmessageServiceRoutine;

BOOLEAN KmessageServiceRoutine(
  [in] _KINTERRUPT *Interrupt,
  [in] PVOID ServiceContext,
       ULONG MessageID
)
{...}

Parameters

[in] Interrupt

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.

[in] ServiceContext

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

MessageID

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.

A driver that uses MSI (PCI 2.2) must examine the MessageID parameter to distinguish between the different messages generated by the device, since they all share the same interrupt resource (and therefore the same InterruptMessageService> callback).

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

Requirement	Value
Minimum supported client	See Remarks section.
Target Platform	Desktop
Header	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
IRQL	See Remarks section.