MINIPORT_ISR callback function (ndis.h)

Article
10/21/2021

NDIS calls the MiniportInterrupt function when a NIC, or another device that shares the interrupt with the NIC, generates an interrupt.

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

Syntax

MINIPORT_ISR MiniportIsr;

BOOLEAN MiniportIsr(
  [in]  NDIS_HANDLE MiniportInterruptContext,
  [out] PBOOLEAN QueueDefaultInterruptDpc,
  [out] PULONG TargetProcessors
)
{...}

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.

[out] QueueDefaultInterruptDpc

A pointer to a BOOLEAN variable that the miniport driver sets before it returns from this call. A miniport driver sets this value to TRUE to indicate that the driver requires a DPC on the default (current) CPU. If this value is set to TRUE, NDIS ignores the value of the TargetProcessors parameter. If it is set to FALSE, NDIS uses the value of the TargetProcessors parameter to schedule DPCs. If QueueDefaultInterruptDpc is TRUE, NDIS will schedule a DPC regardless of the return value from MiniportInterrupt.

[out] TargetProcessors

A bitmask that indicates the target processors for which NDIS should schedule a DPC. This bitmask represents the first 32 processors in processor group 0. Each bit in the bitmask identifies a CPU. If the caller sets bit 0, NDIS schedules a DPC for CPU 0. If the caller sets bit 1, NDIS schedules a DPC for CPU 1, and so on. If QueueDefaultInterruptDpc is set to FALSE and TargetProcessors is set to zero, NDIS will not schedule any DPCs. Otherwise, NDIS will schedule DPCs regardless of the return value from MiniportInterrupt.

Note NDIS 6.20 and later drivers should not use this parameter to schedule DPCs. Instead, they should set this parameter to zero and use the NdisMQueueDpcEx function to schedule DPCs.

Return value

MiniportInterrupt returns one of the following values:

Return code	Description
TRUE	MiniportInterrupt determined that the underlying NIC generated the interrupt.
FALSE	MiniportInterrupt determined that the underlying NIC did not generate the interrupt.

Note NDIS will queue DPCs based on the values that are specified in the QueueDefaultInterruptDpc and TargetProcessors parameters regardless of the value that MiniportInterrupt returns. However, MiniportInterrupt must still return the correct value.

Remarks

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

A miniport driver should do as little work as possible in its MiniportInterrupt function. It should defer I/O operations for the interrupts that the NIC generates to the MiniportInterruptDPC function.

When an interrupt occurs on a NIC's interrupt line, NDIS calls the miniport driver's MiniportInterrupt function.

All NICs can share line-based interrupts with other devices on the I/O bus. If the NIC did not generate the interrupt, MiniportInterrupt should return FALSE immediately so that the system can call the driver of the device that generated the interrupt. If the QueueDefaultInterruptDpc is set to FALSE and the TargetProcessors parameter is set to zero, NDIS will not schedule any DPCs. Otherwise, NDIS will schedule DPCs regardless of the reMiniportInterruptturn value from MiniportInterrupt.

If the interrupt is for the NIC, MiniportInterrupt dismisses the interrupt on the NIC, saves whatever state it must about the interrupt, and defers as much of the I/O processing as possible to the MiniportInterruptDPC function.

If the underlying NIC generated the specified interrupt and the miniport driver will request deferred procedure calls (DPCs), the miniport driver should disable all further interrupts from the NIC and reenable the interrupts after all the DPCs are finished.

The miniport driver should set QueueDefaultInterruptDpc to TRUE to schedule a DPC for the default CPU only. The driver could do this, for example, if:

The NIC generated the interrupt to signal the completion of a send operation, or any other request that doesn't run on other CPUs.
The NIC generated the interrupt to signal received data and the miniport driver cannot process received packets in separate DPCs.
The interrupt indicates received packets and the miniport driver can process received packets in separate DPCs, but receive side scaling (RSS) is not enabled for the miniport driver. For more information, see OID_GEN_RECEIVE_SCALE_CAPABILITIES and OID_GEN_RECEIVE_SCALE_PARAMETERS.

If a miniport driver processes received packets in separate DPCs, the driver sets the QueueDefaultInterruptDpc parameter to FALSE. The miniport driver should set the TargetProcessors bit for the CPU that is associated with each nonempty receive queue. NDIS will schedule a DPC on each of the indicated CPUs.

If MiniportInterrupt shares resources, such as NIC registers or state variables, with another MiniportXxx function that runs at a lower IRQL, that MiniportXxx function must call the NdisMSynchronizeWithInterruptEx function. This ensures that the driver's MiniportSynchronizeInterrupt function accesses the shared resources in a synchronized and multiprocessor-safe manner.

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 MiniportInterrupt at the DIRQL of the interrupt that the miniport driver registered in a previous call to NdisMRegisterInterruptEx. Therefore, MiniportInterrupt must call the subset of the NDIS functions, such as the NdisRawXxx or NdisRead/WriteRegisterXxx functions, that are safe to call at any IRQL.

Examples

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

MINIPORT_ISR MyInterrupt;

Then, implement your function as follows:

_Use_decl_annotations_
BOOLEAN
 MyInterrupt(
    NDIS_HANDLE  MiniportInterruptContext,
    PBOOLEAN  QueueDefaultInterruptDpc,
    PULONG  TargetProcessors
    )
  {...}

The MINIPORT_ISR 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_ISR 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	See Remarks section