HW_MESSAGE_SIGNALED_INTERRUPT_ROUTINE callback function (storport.h)

Article
02/22/2024

The HwMSInterruptRoutine routine handles a message signaled interrupt (MSI).

Syntax

HW_MESSAGE_SIGNALED_INTERRUPT_ROUTINE HwMessageSignaledInterruptRoutine;

BOOLEAN HwMessageSignaledInterruptRoutine(
  IN PVOID HwDeviceExtension,
  IN ULONG MessageId
)
{...}

Parameters

HwDeviceExtension

A pointer to the hardware device extension for the host bus adapter (HBA).

MessageId

The identifier of the message.

Return value

HwMSInterruptRoutine returns TRUE if it determines that the HBA generated the MSI. If the HBA did not generate the MSI, HwMSInterruptRoutine returns FALSE.

Remarks

A miniport driver's HwMSInterruptRoutine routine processes message signaled interrupts (MSIs) that are generated by the HBA. A miniport driver indicates that its HBA generates MSIs by setting the HwMSInterruptRoutine member of the PORT_CONFIGURATION_INFORMATION structure to point to the HwMSInterruptRoutine routine. If the HBA does not generate MSIs, a miniport driver should set HwMSInterruptRoutine to NULL.

If the InterruptSynchronizationMode member of the PORT_CONFIGURATION_INFORMATION structure is set to InterruptSynchronizeAll, the Storport driver synchronizes all MSIs that originate with the adapter it manages or the devices connected to the adapter. When an interrupt occurs, the Storport driver calls the miniport driver's HwMSInterruptRoutine routine at DIRQL after acquiring the interrupt spin lock.

If the InterruptSynchronizationMode member of the PORT_CONFIGURATION_INFORMATION structure is set to InterruptSynchronizePerMessage, the Storport driver calls the miniport driver's HwMSInterruptRoutine routine at IRQL = DIRQL, holding the interrupt spin lock that corresponds to the message identifier (ID) indicated in the MessageID parameter. The HBA can interrupt the HwMSInterruptRoutine routine for interrupts for other message IDs, so the Storport driver might make nested calls to HwMSInterruptRoutine, or run different instances of HwMSInterruptRoutine simultaneously on different processors. To synchronize access to sensitive data by different instances of HwMSInterruptRoutine, the miniport must call the StorPortAcquireMSISpinLock and StorPortReleaseMSISpinLock routines to acquire and release the spin locks for message IDs other than the ID in MessageID.

A miniport driver can retrieve additional information about the message by calling the StorPortGetMSIInfo routine.

It should not call the StorPortGetMSIInfo routine from inside the HwMSInterruptRoutine routine.

The name HwMSInterruptRoutine is just a placeholder. The actual prototype for this routine is defined in Storport.h as follows:

typedef
BOOLEAN
  HW_MESSAGE_SIGNALED_INTERRUPT_ROUTINE (
    _In_ PVOID  HwDeviceExtension,
    _In_ ULONG  MessageId
    );

Examples

To define an HwMSInterruptRoutine 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 a HwMSInterruptRoutine callback routine that is named MyHwMSIRoutine, use the HW_MESSAGE_SIGNALED_INTERRUPT_ROUTINE type as shown in this code example:

HW_MESSAGE_SIGNALED_INTERRUPT_ROUTINE MyHwMSIRoutine;

Then, implement your callback routine as follows:

_Use_decl_annotations_
BOOLEAN
MyHwMSIRoutine (
  _In_ PVOID  DeviceExtension,
  _In_ ULONG  MessageId
  );
  {
      ...
  }

The HW_MESSAGE_SIGNALED_INTERRUPT_ROUTINE function type is defined in the Storport.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 HW_MESSAGE_SIGNALED_INTERRUPT_ROUTINE function type in the header file are used. For more information about the requirements for function declarations, see Declaring Functions Using Function Role Types for Storport Drivers. For information about Use_decl_annotations, see Annotating Function Behavior.

Requirements

Requirement	Value
Target Platform	Universal
Header	storport.h (include Storport.h)
IRQL	DIRQL