W_HALT_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 MiniportHalt function is a required function that deallocates resources when the NIC is removed and halts the NIC.
Syntax
W_HALT_HANDLER MiniportHalt;
VOID MiniportHalt(
_In_ NDIS_HANDLE MiniportAdapterContext
)
{ ... }
Parameters
- 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
MiniportHalt should stop the NIC, if it controls a physical NIC, and must free all resources that the driver allocated for its NIC before MiniportHalt returns control. In effect, MiniportHalt undoes everything that was done by MiniportInitialize for a particular NIC.
If the NIC driver allocated memory, claimed an I/O port range, mapped on-board device memory to host memory, initialized timer(s) and/or spin lock(s), allocated map registers or claimed a DMA channel, and registered an interrupt, that driver must call the reciprocals of the NdisXxx functions with which it originally allocated these resources.
As a general rule, a MiniportHalt function should call reciprocal NdisXxx functions in inverse order to the calls the driver made from MiniportInitialize. That is, if a NIC driver's MiniportInitialize function called NdisMRegisterAdapterShutdownHandler just before it returned control, its MiniportHalt function would call NdisMDeregisterAdapterShutdownHandler first.
If its NIC generates interrupts, a NIC driver's MiniportHalt function can be preempted by the driver's MiniportISR or MiniportHandleInterrupt function until MiniportHalt's call to NdisMDeregisterInterrupt returns. Such a driver's MiniportHalt function usually disables interrupts on the NIC, and calls NdisMDeregisterInterrupt as soon as it can. Note that a miniport driver can keep getting interrupts until NdisMDeregisterInterrupt returns.
If the driver has a MiniportTimer function associated with any timer object that might be in the system timer queue, MiniportHalt should call NdisMCancelTimer. If NdisMCancelTimer fails, the timer could have already fired. In this case, the driver should wait for the timer handler to complete before returning from MiniportHalt.
Otherwise, it is unnecessary for the miniport driver to complete outstanding requests to its NIC before MiniportHalt begins releasing allocated resources. NDIS submits no further requests to the miniport driver for the NIC designated by the MiniportAdapterContext handle when NDIS has called MiniportHalt.
If the miniport driver has any outstanding receive packets (packets that it has indicated up to NDIS but which NDIS has not yet returned), the miniport driver must not return from its MiniportHalt function until such packets are returned to the miniport driver's MiniportReturnPacket function.
An NDIS intermediate driver's call to NdisIMDeinitializeDeviceInstance causes a call to its MiniportHalt function.
Requirements
Target platform |
Desktop |
Version |
Not supported for NDIS 6.0 drivers in Windows Vista. Use MiniportHaltEx instead. Supported for NDIS 5.1 drivers in Windows Vista and Microsoft Windows XP. |
Header |
Ndis.h (include Ndis.h) |
IRQL |
PASSIVE_LEVEL |
See also
NdisIMDeinitializeDeviceInstance
NdisMDeregisterAdapterShutdownHandler