MINIPORT_INTERRUPT_DPC callback function (ndis.h)

Article
10/21/2021

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

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

Syntax

MINIPORT_INTERRUPT_DPC MiniportInterruptDpc;

void MiniportInterruptDpc(
  [in] NDIS_HANDLE MiniportInterruptContext,
  [in] PVOID MiniportDpcContext,
  [in] PVOID ReceiveThrottleParameters,
  [in] PVOID 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] MiniportDpcContext

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

[in] ReceiveThrottleParameters

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

[in] NdisReserved2

Reserved for NDIS.

Return value

None

Remarks

Miniport drivers that register an interrupt with the NdisMRegisterInterruptEx function must provide a MiniportInterruptDPC function.

NDIS calls MiniportInterruptDPC 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 source 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 MiniportInterruptDPC. 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 MiniportInterruptDPC.

MiniportInterruptDPC calls the NdisMIndicateReceiveNetBufferLists function to indicate packets on the current processor. MiniportInterruptDPC can identify 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 MiniportInterrupt function, the miniport driver should indicate all 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, MiniportInterruptDPC should reenable the interrupts on the NIC before it returns.

Interrupts are typically disabled already on the NIC in the MiniportInterrupt function before NDIS calls MiniportInterruptDPC. Before it returns control, MiniportInterruptDPC can reenable interrupts. If the miniport driver queued additional DPCs while interrupts were disabled, the driver should enable the interrupts before the last DPC returns.

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 the NdisMDeregisterInterruptEx function 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 MiniportInterrupt or MiniportInterruptDPC function.

NDIS calls MiniportInterruptDPC at IRQL = DISPATCH_LEVEL.

Examples

To define a MiniportInterruptDPC 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 MiniportInterruptDPC function that is named "MyInterruptDPC", use the MINIPORT_INTERRUPT_DPC type as shown in this code example:

MINIPORT_INTERRUPT_DPC MyInterruptDPC;

Then, implement your function as follows:

_Use_decl_annotations_
VOID
 MyInterruptDPC(
    NDIS_HANDLE  MiniportInterruptContext,
    PVOID  MiniportDpcContext,
    PVOID  ReceiveThrottleParameters,
    PVOID  NdisReserved2
    )
  {...}

The MINIPORT_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_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