NdisMRegisterInterrupt 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.
NdisMRegisterInterrupt sets up a mapping between a NIC driver's MiniportISR and MiniportHandleInterrupt functions, already registered with NdisMRegisterMiniport, and the bus-relative vector and level on which its NIC interrupts.
Syntax
NDIS_STATUS NdisMRegisterInterrupt(
_Out_ PNDIS_MINIPORT_INTERRUPT Interrupt,
_In_ NDIS_HANDLE MiniportAdapterHandle,
_In_ UINT InterruptVector,
_In_ UINT InterruptLevel,
_In_ BOOLEAN RequestIsr,
_In_ BOOLEAN SharedInterrupt,
_In_ NDIS_INTERRUPT_MODE InterruptMode
);
Parameters
Interrupt [out]
Pointer to caller-allocated resident memory containing an opaque interrupt object, which NdisMRegisterInterrupt initializes and for which it returns a handle the miniport driver uses in subsequent calls to NdisMSynchronizeWithInterrupt.MiniportAdapterHandle [in]
Specifies the handle input to MiniportInitialize.InterruptVector [in]
Specifies the bus-relative vector number used by the NIC.InterruptLevel [in]
Specifies the bus-relative DIRQL for the interrupt. This value is almost always the same as that of InterruptVector.RequestIsr [in]
Specifies TRUE if the MiniportISR function should be called each time the NIC interrupts. If the NIC can share an interrupt with other devices on the I/O bus, this parameter must be set to TRUE.SharedInterrupt [in]
Specifies TRUE if other devices on the I/O bus can use this interrupt line. If this parameter is set to FALSE and another device already claimed the given interrupt vector in the registry, NdisMRegisterInterrupt will fail.InterruptMode [in]
Specifies the type of interrupt that the NIC generates as one of the following values:NdisInterruptLatched
Interrupts are triggered by a transition from low to high on the interrupt line.NdisInterruptLevelSensitive
Interrupts are active as long as the interrupt line is asserted.
Return value
NdisMRegisterInterrupt can return one of the following:
| Return code | Description |
|---|---|
| NDIS_STATUS_SUCCESS | NDIS initialized the interrupt object and returned a valid Interrupt handle, claimed hardware resources in the registry for the NIC, such as the given vector if the NIC does not share an IRQ, and set up the MiniportISR(or MiniportDisableInterrupt) and associated MiniportHandleInterrupt functions to be called when an interrupt occurs as requested in the call to NdisMRegisterInterrupt. |
| NDIS_STATUS_RESOURCE_CONFLICT | An attempt to claim the vector or level in the registry has failed, possibly because another driver already claimed the interrupt for its device. NdisMRegisterInterrupt logs an error if this occurs. |
| NDIS_STATUS_RESOURCES | NDIS could not allocate sufficient memory to claim resources in the registry for the NIC. |
| NDIS_STATUS_FAILURE | The attempt to initialize the interrupt object failed, possibly due to another driver's prior claim on the InterruptVector or InterruptLevel in the registry. |
Remarks
A NIC driver must call NdisMRegisterInterrupt from its MiniportInitialize function if its NIC generates interrupts. The driver of a NIC that does not generate interrupts calls NdisMInitializeTimer and NdisMSetPeriodicTimer instead of NdisMRegisterInterrupt.
MiniportInitialize must call NdisMSetAttributes or NdisMSetAttributesEx before calling NdisMRegisterInterrupt.
MiniportInitialize obtained the bus-relative values passed to NdisMRegisterInterrupt either from the registry or by calling a bus-type-specific NdisXxx configuration function.
If its call to NdisMRegisterInterrupt fails, MiniportInitialize should release all resources it already allocated for its NIC and, then, fail initialization for that NIC.
NdisMRegisterInterrupt distinguishes between the InterruptVector(the interrupt line that the card asserts to interrupt the system) and the InterruptLevel(the hardware priority, that is, the DIRQL, of that interrupt assigned by the system). Usually, these values can be assumed to be equal, unless the driver writer knows that they are different for a particular NIC or unless the miniport driver controls more than one NIC that share resources in the current platform.
If its NIC can share an IRQ with other devices on the I/O bus, the caller of NdisMRegisterInterrupt must set both the SharedInterrupt and RequestIsr parameters to TRUE. Such a NIC driver's MiniportISR can be called when no interrupt for the NIC is outstanding. In these circumstances, MiniportISR should return FALSE as soon as possible, indicating that the interrupt was not recognized and should leave interrupts enabled on its NIC.
When interrupts are enabled on the NIC, a driver's MiniportISR can be called at any time following a successful call to NdisMRegisterInterrupt, even during initialization. Such a driver's MiniportInitialize function should not call NdisMRegisterInterrupt until it has set up all state the driver needs to handle an interrupt. The MiniportHandleInterrupt function is not queued for subsequent execution if the driver's MiniportInitialize function is currently executing and an interrupt occurs.
For most drivers of NICs that do not share an IRQ, the MiniportISR function seldom runs except, possibly, during driver initialization. Such a miniport driver sets RequestIsr to FALSE when MiniportInitialize calls NdisMRegisterInterrupt, and such a driver has a MiniportDisableInterrupt function and, possibly, a MiniportEnableInterrupt function. The NDIS library then calls the driver's MiniportDisableInterrupt function when an interrupt occurs on the NIC and the driver's MiniportHandleInterrupt function does most of the I/O processing for the interrupt. Before MiniportHandleInterrupt returns control, either NDIS calls MiniportEnableInterrupt or MiniportHandleInterrupt reenables interrupts on the NIC itself.
Whether a miniport driver with an ISR sets RequestIsr to TRUE when it calls NdisMRegisterInterrupt or not, NDIS acknowledges the interrupt to the operating system so that interrupts from other devices are not blocked.
If a miniport driver sets RequestIsr to TRUE when it calls NdisMRegisterInterrupt, it must dismiss the interrupt on its NIC by setting the state of the network interface card so that the NIC no longer asserts the interrupt. Interrupts can remain enabled on the NIC following the dismissal of the interrupt, or they can be disabled, depending on the design of the driver. The timing of such a dismissal depends on the InterruptMode specified when the driver called NdisMRegisterInterrupt, as follows:
For NdisInterruptLevelSensitive interrupts, MiniportISR must dismiss each interrupt as its NIC generates that interrupt. Otherwise, the interrupt is reasserted on the NIC as soon as MiniportISR returns control. If MiniportISR determines that the NIC did not generate a particular interrupt, it should return control with FALSE as soon as possible so that the ISRs for other devices on the same bus can be called promptly to dismiss the interrupt on the device that actually generated that interrupt.
For NdisInterruptLatched interrupts, dismissing an interrupt on the NIC is not as time-critical as it is for shared interrupts. If the miniport driver is designed such that each call to MiniportISR causes a subsequent call to the associated MiniportHandleInterrupt function, MiniportHandleInterrupt can dismiss the interrupt on the NIC. As an alternative, such a driver can set RequestIsr to FALSE when it calls NdisMRegisterInterrupt and supply a MiniportDisableInterrupt function, which will be called instead of MiniportISR unless MiniportHalt or MiniportInitialize is currently executing.
When a miniport driver supports full-duplex sends and receives, NDIS serializes calls to its MiniportISR or MiniportDisableInterrupt function for sends. NDIS separately serializes calls to its MiniportISR or MiniportDisableInterrupt function for all other operations that can cause an interrupt. Calls to the MiniportReset function are both synchronized and synchronous; NDIS prevents all other code paths in a full-duplex miniport driver from being entered while a device-reset operation is occurring.
If a miniport driver does not support full-duplex sends and receives, NDIS serializes all calls to the MiniportISR or MiniportDisableInterrupt function for any NIC the miniport driver controls. While such a driver's MiniportISR or MiniportDisableInterrupt function is processing a particular NIC interrupt, it will not be called to handle a second interrupt from the same NIC on another processor in an SMP machine.
However, the ISR (or MiniportDisableInterrupt function) of any driver that controls more than one device can run concurrently in SMP platforms if two of that driver's devices happen to generate interrupts almost simultaneously and interrupts are enabled on the NIC.
If it is possible that an interrupt can occur while another driver function is accessing resources that also can be accessed from MiniportISR or MiniportDisableInterrupt, the other function must call NdisMSynchronizeWithInterrupt to have the driver-supplied MiniportSynchronizeISR function access the shared resources at DIRQL.
Requirements
Target platform |
Universal |
Version |
Not supported for NDIS 6.0 drivers in Windows Vista. Use NdisMRegisterInterruptExinstead. Supported for NDIS 5.1 drivers in Windows Vista and Windows XP. |
Header |
Ndis.h (include Ndis.h) |
Library |
Ndis.lib |
IRQL |
PASSIVE_LEVEL |
See also