MINIPORT_MESSAGE_INTERRUPT_DPC callback function (ndis.h)

Article
10/21/2021

A miniport driver must provide a MiniportMessageInterruptDPC handler if the driver calls the NdisMRegisterInterruptEx function to register an interrupt.

Note You must declare the function by using the MINIPORT_MESSAGE_INTERRUPT_DPC type. For more information, see the following Examples section.

Syntax

MINIPORT_MESSAGE_INTERRUPT_DPC MiniportMessageInterruptDpc;

void MiniportMessageInterruptDpc(
  [in] NDIS_HANDLE MiniportInterruptContext,
  [in] ULONG MessageId,
  [in] PVOID MiniportDpcContext,
  [in] PVOID ReceiveThrottleParameters,
       PVOID NdisReserved2 PULONG NdisReserved1,
  [in] PULONG NdisReserved2
)
{...}

Parameters

[in] MiniportInterruptContext

A handle to a block of interrupt context information. The miniport driver supplied this handle in the MiniportInterruptContext parameter that the miniport driver passed to the NdisMRegisterInterruptEx function.

[in] MessageId

A message-signaled interrupt (MSI) message identifier. MessageId is an index to an IO_INTERRUPT_MESSAGE_INFO_ENTRY structure inside a IO_INTERRUPT_MESSAGE_INFO structure. NDIS passes a pointer to the associated IO_INTERRUPT_MESSAGE_INFO structure in the MessageInfoTable member when the driver successfully registers for MSI with the NdisMRegisterInterruptEx function.

[in] MiniportDpcContext

A pointer to a context area that the miniport driver supplied when it called the NdisMQueueDpcEx or NdisMQueueDpc function. If NDIS called MiniportMessageInterruptDPC because the miniport driver returned a bitmask in the TargetProcessors parameter of the MiniportMessageInterrupt function, then MiniportDpcContext is NULL.

[in] ReceiveThrottleParameters

A pointer to an NDIS_RECEIVE_THROTTLE_PARAMETERS structure specifies the maximum number of NET_BUFFER_LIST structures that a miniport driver should indicate in a DPC.

Note In NDIS 6.1 and earlier, this parameter is named NdisReserved1, its datatype is PULONG, and it is reserved for NDIS.

NdisReserved1

Reserved for NDIS.

[in] NdisReserved2

Reserved for NDIS.

Note In NDIS 6.1 and earlier, this parameter's datatype is PULONG.

Return value

None

Remarks

Miniport drivers that register a message-signaled interrupt with the NdisMRegisterInterruptEx function must provide a MiniportMessageInterruptDPC function.

NDIS calls MiniportMessageInterruptDPC to complete the deferred processing of an interrupt. The miniport driver can call the NdisMQueueDpcEx or NdisMQueueDpc function to request additional deferred procedure calls (DPCs) for other processors.

Miniport drivers determine the source of each interrupt and take appropriate action. For example, if an interrupt indicates the completion of a transmit operation, the miniport driver completes a pending send request. If the cause of the interrupt is a change in link state, the miniport driver indicates the new link status to NDIS. If there are outstanding receive packets, the miniport driver indicates the packets to NDIS.

A miniport driver that supports receive side scaling (RSS), and has the feature enabled, examines its receive queues in MiniportMessageInterruptDPC. The NIC could have already queued received packets on separate queues based on hash values, if the NIC provides such capabilities. Otherwise, the miniport driver can sort the packets into separate queues in MiniportMessageInterruptDPC.

MiniportMessageInterruptDPC calls the NdisMIndicateReceiveNetBufferLists function to indicate the packets on the current processor. MiniportMessageInterruptDPC can determine processing that is required for other CPUs and request NDIS to schedule DPCs on CPUs where a DPC is not outstanding.

If the current DPC is running on the same CPU as the MiniportMessageInterrupt function, the miniport driver should indicate all of the packets that could not be mapped to a CPU. If this DPC is the last scheduled DPC and it will not request additional DPCs, MiniportMessageInterruptDPC should reenable the interrupts on the NIC, for the specified message, before it returns.

Before NDIS calls MiniportMessageInterruptDPC, interrupts for the specified message on the NIC, have typically been disabled in the MiniportMessageInterrupt function. Before it returns control, MiniportMessageInterruptDPC can reenable interrupts. If the miniport driver queued additional DPCs while interrupts were disabled, the driver should enable the interrupts after the last DPC executes.

Note For better performance, miniport drivers should only disable interrupts for specific messages. They should not disable all message-signaled interrupts.

Miniport drivers should limit the number of the receive buffers that they indicate while they are processing an interrupt DPC batch to complete within the required time limit. An interrupt DPC batch is the collection of all the DPCs that run after the ISR and before the interrupts are reenabled.

A miniport driver can call NdisMDeregisterInterruptEx from its MiniportInitializeEx or MiniportHaltEx function to release resources that it allocated with NdisMRegisterInterruptEx. After NdisMDeregisterInterruptEx returns, NDIS does not call a miniport driver's MiniportMessageInterrupt or MiniportMessageInterruptDPC function.

NDIS calls MiniportMessageInterruptDPC at IRQL = DISPATCH_LEVEL.

Examples

To define a MiniportMessageInterruptDPC function, you must first provide a function declaration that identifies the type of function you're defining. Windows provides a set of function types for drivers. Declaring a function using the 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 MiniportMessageInterruptDPC function that is named "MyMessageInterruptDPC", use the MINIPORT_MESSAGE_INTERRUPT_DPC type as shown in this code example:

MINIPORT_MESSAGE_INTERRUPT_DPC MyMessageInterruptDPC;

Then, implement your function as follows:

_Use_decl_annotations_
VOID
 MyMessageInterruptDPC(
    NDIS_HANDLE  MiniportInterruptContext,
    ULONG  MessageId,
    PVOID  MiniportDpcContext,
    PVOID  ReceiveThrottleParameters,
    PVOID  NdisReserved2
    )
  {...}

The MINIPORT_MESSAGE_INTERRUPT_DPC function type is defined in the Ndis.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 MINIPORT_MESSAGE_INTERRUPT_DPC 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 NDIS Drivers.

For information about Use_decl_annotations, see Annotating Function Behavior.

Requirements

Requirement	Value
Minimum supported client	Supported in NDIS 6.0 and later.
Target Platform	Windows
Header	ndis.h (include Ndis.h)
IRQL	DISPATCH_LEVEL