NdisInitializeInterrupt

NdisInitializeInterrupt

VOID
   NdisInitializeInterrupt(
       OUT PNDIS_STATUS Status,
       IN OUT PNDIS_INTERRUPT Interrupt,
       IN NDIS_HANDLE NdisAdapterHandle,
       IN PNDIS_INTERRUPT_SERVICE InterruptServiceRoutine,
       IN PVOID InterruptContext,
       IN PNDIS_DEFERRED_PROCESSING DeferredProcessingRoutine,
       IN UINT InterruptVector,
       IN UINT InterruptLevel,
       IN BOOLEAN SharedInterrupt,
       IN NDIS_INTERRUPT_MODE InterruptMode
       );

NdisInitializeInterrupt is called by the NIC driver to prepare for interrupt processing during driver initialization.

Parameters

Status

Points to the caller-supplied variable in which this function returns the final status of the interrupt initialization. Possible values are:

NDIS_STATUS_FAILURE
NDIS_STATUS_RESOURCE_CONFLICT
NDIS_STATUS_SUCCESS

Interrupt

Points to the caller-supplied variable of type NDIS_INTERRUPT in which this function fills in information about the interrupt. This varible is reserved for use by NDIS.

NdisAdapterHandle

Specifies the handle that the NDIS interface library associates with the network interface card.

InterruptServiceRoutine

Points to the caller’s MacInterruptServiceRoutine.

InterruptContext

Points to a caller-supplied context area. NDIS passes this pointer to the MacInterruptServiceRoutine when the NIC interrupts and to the MacDeferredProcessingRoutine.

DeferredProcessingRoutine

Points to the caller’s MacDeferredProcessingRoutine.

InterruptVector

Specifies the interrupt number that the network interface card uses. This function allows a distinction between InterruptVector and InterruptLevel. However, these parameters are equal for most network interface cards.

InterruptLevel

Specifies the interrupt level for the network interface card. For most NICs, InterruptLevel has the same value as InterruptVector.

SharedInterrupt

Specifies TRUE if the NIC driver shares the IRQ with other drivers. If the value is FALSE and another NIC driver is already registered on the interrupt vector, NdisInitializeInterrupt fails.

InterruptMode

Specifies the type of interrupt generated by the network interface card:

Type	Description
NdisInterruptLatched	Interrupts are latched. In other words, they are triggered by a transition from low to high on the interrupt line.
NdisInterruptLevelSensitive	Interrupts are level-sensitive. In other words, they are active as long as the interrupt line is asserted. If the MacInterruptServiceRoutine does not modify the network interface card registers so they no longer assert the interrupt line, the operating system can call this function again immediately after it returns, before the MacDeferredProcessingRoutine has a chance to run.

Comments

A NIC driver can call NdisInitializeInterrupt only during NIC driver initialization from its DriverEntry or MacAddAdapter function.

NdisInitializeInterrupt associates a NIC interrupt with the caller’s ISR and DPC functions, MacInterruptServiceRoutine and MacDeferredProcessingRoutine, respectively.

The operating system, through NDIS, calls the ISR and DPC functions any time the network interface card generates an interrupt. The MacInterruptServiceRoutine runs at DIRQL immediately after the interrupt. When it returns, the operating system calls the MacDeferredProcessingRoutine, which completes interrupt processing at IRQL DISPATCH_LEVEL.

There is no guarantee of a one-to-one correspondence between calls to the driver’s MacInterruptServiceRoutine and to MacDeferredProcessingRoutine functions. When the ISR returns control, the corresponding DPC is queued and this function typically executes immediately. However, another NIC interrupt can occur before the DPC is run, causing the ISR to run again in a uniprocessor machine. In a multiprocessor platform, the ISR might run concurrently on different processors. In either case, when the second iteration of the ISR returns control, a queued DPC is run once and only once.

The NIC driver is responsible for dismissing an interrupt on the network interface card itself. Dismissal refers to setting the state of the network interface card so the output interrupt line is no longer asserted (does not necessarily mean that further interrupts are enabled). The timing of this dismissal depends on the hardware mode of the network interface card, which is either level-sensitive or latched (also known as edge-triggered). The operating system acknowledges a network interface card interrupt in the host hardware interrupt controller, which allows other host interrupts.

When a level-sensitive interrupt is active, the NIC driver’s MacInterruptServiceRoutine must dismiss the interrupt. Timing for a latched interrupt is not as important as that for a level-sensitive interrupt. If necessary, the NIC driver can leave latched interrupt dismissal to its MacDeferredProcessingRoutine.

Callers of NdisInitializeInterrupt run at IRQL PASSIVE_LEVEL.