MiniportHaltEx (Compact 2013)

3/26/2014

NDIS calls a miniport driver's MiniportHaltEx function to deallocate resources when a miniport adapter is removed, and to stop the hardware.

Syntax

VOID MiniportHaltEx(
    NDIS_HANDLE  MiniportAdapterContext,
    NDIS_HALT_ACTION  HaltAction
); 

Parameters

• MiniportAdapterContext
  [in] A handle to a context area that the miniport driver allocated in its MiniportInitializeEx function. The miniport driver uses this context area to maintain state information for a miniport adapter.

• HaltAction
  [in] The reason for halting the miniport adapter. It can be one of the following values:

  • NdisHaltDeviceDisabled
    NDIS is halting the miniport adapter in response to a Plug and Play (PnP) remove message.
  • NdisHaltDeviceInstanceDeInitialized
    NDIS is halting the miniport adapter in response to an intermediate driver calling the NdisIMDeInitializeDeviceInstance function.
  • NdisHaltDevicePoweredDown
    NDIS is halting the miniport adapter because the system will a sleeping state.
  • NdisHaltDeviceSurpriseRemoved
    The miniport adapter has been surprise removed and the hardware is not present.
  • NdisHaltDeviceFailed
    The miniport adapter is being removed because of a hardware failure. Either the miniport driver called the NdisMRemoveMiniport function or a bus driver did not turn on the NIC on resume.
  • NdisHaltDeviceInitializationFailed
    NDIS could not initialize the miniport adapter for an unknown reason after the MiniportInitializeEx function completed successfully.
  • NdisHaltDeviceStopped
    NDIS is halting the miniport adapter in response to a PnP stop device message.

Return Value

None

Remarks

A driver specifies the MiniportHaltEx entry point when it calls the NdisMRegisterMiniportDriver function.

NDIS can call MiniportHaltEx at any time after a driver's MiniportInitializeEx function returns successfully. If the driver controls a physical NIC, MiniportHaltEx should stop the NIC. If an NDIS intermediate driver calls the NdisIMDeInitializeDeviceInstance function, NDIS calls the MiniportHaltEx function for the driver's virtual device.

MiniportHaltEx releases the resources that were allocated in MiniportInitializeEx for a device. MiniportHaltEx also releases any other resources that the driver allocated in later operations for that device. The driver must call the reciprocals of the NdisXxx functions with which it originally allocated the resources. Generally, a MiniportHaltEx function should call the reciprocal NdisXxx functions in reverse order to the calls the driver made from MiniportInitializeEx.

If a NIC generates interrupts, a miniport driver's MiniportHaltEx function can be preempted by the driver's MiniportInterrupt function until the MiniportHaltEx call to the NdisMDeregisterInterruptEx function returns. Such a driver's MiniportHaltEx function should disable interrupts, and call NdisMDeregisterInterruptEx as soon as possible. Note that a driver can keep getting interrupts until NdisMDeregisterInterruptEx returns. NdisMDeregisterInterruptEx does not return until the driver finishes all the scheduled DPCs.

If the driver has a NetTimerCallback function that is associated with a timer object that could be in the system timer queue, MiniportHaltEx should call the NdisCancelTimerObject function. If NdisCancelTimerObject fails, the timer could have already fired. In this case, the driver should wait for the timer function to complete before the driver returns from MiniportHaltEx.

NDIS does not call MiniportHaltEx if there are outstanding OID requests or send requests. NDIS submits no additional requests for the affected device after NDIS calls MiniportHaltEx.

If the driver must wait for any operation to complete, MiniportHaltEx can use the NdisWaitEvent function or the NdisMSleep function.

NDIS calls MiniportHaltEx at IRQL = PASSIVE_LEVEL.

See Also

Reference

NDIS Miniport Driver Functions
MiniportInitializeEx
NdisCancelTimerObject
NdisIMDeInitializeDeviceInstance
NdisMDeregisterInterruptEx
NdisMRegisterMiniportDriver
NdisMRemoveMiniport
NdisMSleep
NdisWaitEvent
NetTimerCallback