W_ISR_HANDLER callback function
Note NDIS 5. x has been deprecated and is superseded by NDIS 6. x. For new NDIS driver development, see Network Drivers Starting with Windows Vista. For information about porting NDIS 5. x drivers to NDIS 6. x, see Porting NDIS 5.x Drivers to NDIS 6.0.
The MiniportISR function is required if the driver's NIC generates interrupts.
Syntax
W_ISR_HANDLER MiniportISR;
VOID MiniportISR(
_Out_ PBOOLEAN InterruptRecognized,
_Out_ PBOOLEAN QueueMiniportHandleInterrupt,
_In_ NDIS_HANDLE MiniportAdapterContext
)
{ ... }
Parameters
InterruptRecognized [out]
Pointer to a variable in which MiniportISR returns whether the NIC actually generated the interrupt. MiniportISR sets this to TRUE if it detects that the interrupt came from the NIC designated at MiniportAdapterContext.If its NIC shares an IRQ with other devices on the same bus, MiniportISR should return FALSE as quickly as possible whenever it determines that the NIC did not interrupt.
QueueMiniportHandleInterrupt [out]
Pointer to a variable that MiniportISR sets to TRUE if the MiniportHandleInterrupt function should be called to complete the interrupt-driven I/O operation.MiniportAdapterContext [in]
Specifies the handle to a miniport driver-allocated context area in which the driver maintains per-NIC state, set up by MiniportInitialize.
Return value
None
Remarks
A NIC driver should do as little work as possible in its MiniportISR function, deferring I/O operations for each interrupt that the NIC generates to the MiniportHandleInterrupt function. A NIC driver's ISR is not reentrant, although two instantiations of a MiniportISR function can execute concurrently in SMP machines, particularly if the miniport driver supports full-duplex sends and receives.
When an interrupt occurs on its NIC's bus, the miniport driver's Miniport ISR function is called under the following conditions:
The NIC shares an IRQ with other devices on that bus.
If the NIC shares an IRQ with other devices, the Miniport ISR function must be called to determine whether the NIC generated the interrupt. If the NIC did not generated the interrupt, MiniportISR should return FALSE immediately so that the driver of the device that generated the interrupt is called quickly.
The miniport driver, in its call to NdisMRegisterInterrupt from MiniportInitialize, specified that its MiniportISR function should be called for every interrupt on the bus
Miniports that do not provide MiniportDisable/EnableInterrupt functionality must have their ISRs called on every interrupt.
An interrupt occurs on the NIC while the driver's MiniportInitialize or MiniportHalt function is running.
The MiniportISR function is always called in the case, regardless of whether the miniport's NIC shares an IRQ with another device or whether the miniport driver specified that its MiniportISR function should be called for every interrupt on the bus.
MiniportISR dismisses the interrupt on the NIC, saves whatever state it must about the interrupt, and defers as much of the I/O processing for each interrupt as possible to the MiniportHandleInterrupt function.
After MiniportISR returns control with the variables at InterruptRecognized and QueueMiniportHandleInterrupt set to TRUE, the corresponding MiniportHandleInterrupt function runs at a lower hardware priority (IRQL = DISPATCH_LEVEL) than that of the ISR (DIRQL). As a general rule, MiniportHandleInterrupt should do all the work for interrupt-driven I/O operations except for determining whether the NIC actually generated the interrupt, and, if necessary, preserving the type (receive, send, reset...) of interrupt.
A driver writer should not rely on a one-to-one correspondence between the execution of MiniportISR and MiniportHandleInterrupt. A MiniportHandleInterrupt function should be written to handle the I/O processing for more than one NIC interrupt. Its MiniportISR and MiniportHandleInterrupt functions can run concurrently in SMP machines. Moreover, as soon as MiniportISR acknowledges a NIC interrupt, the NIC can generate another interrupt, while the MiniportHandleInterrupt DPC can be queued for execution once for such a sequence of interrupts.
If MiniportISR shares resources, such as NIC registers or state variables, with another MiniportXxx that runs at lower IRQL, that MiniportXxx must call NdisMSynchronizeWithInterrupt so the driver's MiniportSynchronizeISR function will access those shared resources in a synchronized and multiprocessor-safe manner. Otherwise, while it is accessing the shared resources, that MiniportXxx function can be preempted by MiniportISR, possibly undoing the work just done by MiniportXxx.
A miniport driver can call NdisMDeregisterMiniport from its MiniportInitialize or MiniportHalt function to release resources that it allocated with NdisMRegisterInterrupt. After NdisMDeregisterMiniport returns, NDIS does not call a miniport driver's MiniportISR or MiniportHandleInterrupt functions.
A miniport driver that controls a NIC that supports power management must always keep track of the NIC's power state. If MiniportISR is called when the NIC is in a low-power state, MiniportISR must not access the NIC, claim the interrupt by setting InterruptRecognized to TRUE, or set QueueMiniportHandleInterrupt to TRUE.
MiniportISR runs at DIRQL, in particular at the DIRQL assigned when the driver initialized the interrupt object with NdisMRegisterInterrupt. Therefore, MiniportISR can call only a subset of the NDIS library functions, such as the NdisRawXxx or NdisRead/WriteRegisterXxx functions that are safe to call at any IRQL.
Requirements
Target platform |
Desktop |
Version |
Not supported for NDIS 6.0 drivers in Windows Vista. Use MiniportInterrupt instead. Supported for NDIS 5.1 drivers in Windows Vista and Microsoft Windows XP. |
Header |
Ndis.h (include Ndis.h) |
IRQL |
DIRQL (see Remarks section) |
See also