NdisMRegisterInterrupt (Windows Embedded CE 6.0)

Article
01/05/2012

1/6/2010

This function sets up a mapping between an 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(
  PNDIS_MINIPORT_INTERRUPT Interrupt,
  NDIS_HANDLE MiniportAdapterHandle,
  UINT InterruptVector,
  UINT InterruptLevel,
  BOOLEAN RequestIsr,
  BOOLEAN SharedInterrupt,
  NDIS_INTERRUPT_MODE InterruptMode
);

Parameters

Interrupt
[out] Pointer to caller-allocated resident memory containing an opaque interrupt object, which this function initializes and for which it returns a handle that the miniport uses in subsequent calls to the NdisMSynchronizeWithInterrupt function.

MiniportAdapterHandle
[in] Handle input to the MiniportInitialize function.

InterruptVector
[in] Specifies the bus-relative vector number used by the NIC.

InterruptLevel
[in] Ignored.

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 has already claimed the specified interrupt vector in the registry, this function fails.

InterruptMode
[in] Ignored.

Return Value

The following table shows the return values for this function.

Value	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 specified 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 this function.
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. This function 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

An NIC driver must call this function from its MiniportInitialize function if its NIC generates interrupts. The driver of an NIC that does not generate interrupts calls the NdisMInitializeTimer and NdisMSetPeriodicTimer functions instead of this function.

MiniportInitialize must call NdisMSetAttributes or NdisMSetAttributesEx before calling this function.

MiniportInitialize obtains the bus-relative values passed to this function either from the registry or by calling a bus-type-specific NdisXXX configuration function.

If its call to this function fails, MiniportInitialize releases all resources that it already allocated for its NIC, and then fails initialization for that NIC.

This function distinguishes between the InterruptVector and the InterruptLevel. The InterruptVector is the interrupt line that the card asserts to interrupt the system, and the InterruptLevel is ignored on Windows Embedded CE. 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 controls multiple NICs that share resources in the current platform.

If a SYSINTR value is not specified in the registry, NDIS will use the IOCTL_HAL_REQUEST_SYSINTR IOCTL to convert the InterruptVector value that is passed to NDISMRegisterInterrupt into a SYSINTR value. If a SYSINTR value is specified in the registry, NDIS will ignore the InterruptLevel parameter and use the SYSINTR registry value in its place. For more information about system interrupts, see Interrupts.

If its NIC can share an IRQ with other devices on the I/O bus, the caller of this function must set both the SharedInterrupt and RequestIsr parameters to TRUE. On CE, the MiniportISR will execute as an IST. As a result, it cannot be part of a chain of ISRs attached to a shared interrupt. To share interrupts requires using an installable ISR. For additional information, see Installable ISRs and Device Drivers. CE NDIS supports this model. The following registry settings for an adapter will be used by NDIS to configure its shared interrupts:

"IsrDll"="<dllfilename>"
Specifies the name of the dll containing the shared ISR
"IsrHandler"="<funcname>"
Specifies the name of the ISR function

In addition, if the <dllfilename> is "giisr.dll", the generic shared ISR handler then the following registry settings can be used to configure the settings for the handler:

"PortIsIO"=dword
Specifies whether the port to be read is IO or memory space
"PortOffset"=dword
Specifies the port offset from the IOBase or MemBase
"PortSize"=dword
Specifies the byte size of the port (1, 2, or 4)
"PortMask"=dword
A bitmask specifying which bits are of interest in the port
"UseMaskReg"=dword
Set to 1 to enable the use of a mask register
"MaskOffset"=dword
Offset from IOBase or MemBase to the mask register

When interrupts are enabled on the NIC, a driver's MiniportISR function can be called at any time following a successful call to this function, even during initialization. Such a driver's MiniportInitialize function should not call this function until it has set up all state that 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, MiniportISR seldom runs except, possibly, during driver initialization. Such a miniport sets RequestIsr to FALSE when MiniportInitialize calls this function, 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 re-enables interrupts on the NIC itself.

Whether a miniport with an ISR sets RequestIsr to TRUE when it calls this function or not, NDIS acknowledges the interrupt to the operating system so that interrupts from other devices are not blocked.

If a miniport sets RequestIsr to TRUE when it calls this function, it must dismiss the interrupt on its NIC by setting the state of the NIC so that it 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.

When a miniport 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 from being entered while a device-reset operation is occurring.

If a miniport does not support full-duplex sends and receives, NDIS serializes all calls to the MiniportISR or the MiniportDisableInterrupt function for any NIC that the miniport controls. While such a driver's MiniportISR or MiniportDisableInterrupt function is processing a particular NIC interrupt, it is not called to handle a second interrupt from the same NIC on another processor in a symmetric multiprocessor (SMP) platform.

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 can also be accessed from MiniportISR or MiniportDisableInterrupt, the other function must call NdisMSynchronizeWithInterrupt to synchronize access to the shared resources.

Requirements

Header	ndis.h
Library	ndis.dll
Windows Embedded CE	Windows CE .NET 4.0 and later

NdisMRegisterInterrupt (Windows Embedded CE 6.0)

Syntax

Parameters

Return Value

Remarks

Requirements

See Also

Reference

Concepts

Additional resources