Halt Handler (NDIS 5.1)
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.
A miniport driver must supply a MiniportHaltfunction to NdisMRegisterMiniport. The definition of MiniportHaltis:
VOID
MiniportHalt(
IN NDIS_HANDLE MiniportAdapterContext
);
MiniportHaltcan be called:
After the failure of a request to set up multicast addresses or to set MAC_OPTIONS
After the unbinding of all the protocol drivers bound to the miniport driver
During an unload operation; for instance, when a NetStop command has caused an unload operation to be carried out
During system shutdown
MiniportHaltshould undo everything that MiniportInitializedid, including the following:
Free ports
Release all the hardware resources it claimed
Free interrupt resources by calling NdisMDeregisterInterrupt
Free any memory it has allocated
Stop the NIC, unless the MiniportShutdown function has already restored the NIC to its initial state. The following diagram illustrates unloading a miniport driver.
.png)
MiniportHaltshould carry out the operations necessary to unload the driver before returning. If the miniport driver has any outstanding receive packets (packets that it has indicated up to NDIS but which NDIS has not yet returned), MiniportHaltmust not return until such packets are returned to the miniport driver's MiniportReturnPacketfunction.
The preceding figure shows a set of calls that could be made by a MiniportHaltfunction. These calls are only a subset of the calls that could be made. The actual set of calls depends on previous actions of the miniport driver. The miniport driver can make these same calls in MiniportInitializeif it cannot successfully initialize the network adapter because of hardware problems or because it cannot acquire a resource that it needs. In such a case, MiniportInitializeshould unload the driver by undoing its previous actions. Otherwise, MiniportHaltwill undo the actions of MiniportInitialize.
The following lists the calls required to reverse certain actions that have been taken by the miniport driver:
If the miniport driver registered an interrupt, it should call NdisMDeregisterInterrupt.
If the miniport driver registered a shutdown handler, it should call NdisMDeregisterAdapterShutdownHandler.
If the miniport driver set up a timer or timers, it should call NdisMCancelTimer for each timer that it created. If a call to NdisMCancelTimer fails, the timer might have already fired. In this case, the miniport driver should wait for the timer handler to complete before returning from MiniportHalt.
If the miniport driver allocated any memory with NdisAllocateMemoryWithTag, it should call NdisFreeMemory to free that memory.
If the miniport driver allocated any memory with NdisMAllocateSharedMemory, or NdisMAllocateSharedMemoryAsync, it should call NdisMFreeSharedMemory to free that memory.
If the miniport driver allocated and initialized storage for a pool of packet descriptors with NdisAllocatePacketPool, it should call NdisFreePacketPool to free that storage.
If the miniport driver allocated or reserved any hardware resources, these should be returned--for example, by calling NdisMDeregisterIoPortRange or, if the NIC is a bus-master DMA NIC, by calling NdisMFreeMapRegisters. A miniport driver that allocated shared memory must call NdisMFreeSharedMemory before calling NdisMFreeMapRegisters.