MINIPORT_HALT function

NDIS calls a miniport driver's MiniportHaltEx function to free resources when a miniport adapter is removed, and to stop the hardware. This function puts the miniport into the Halted state, where no other callback can occur (including MiniportShutdownEx). For more information about miniport driver states, see Miniport Adapter States and Operations.

Syntax

MINIPORT_HALT MiniportHalt;

void MiniportHalt(
  NDIS_HANDLE MiniportAdapterContext,
  NDIS_HALT_ACTION HaltAction
)
{...}

Parameters

MiniportAdapterContext

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

The reason for halting the miniport adapter. It can be one of the following values:

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 must free all resources that were allocated in MiniportInitializeEx for a device. MiniportHaltEx also frees any other resources that the driver allocated in subsequent operations for that device. The driver must call the reciprocals of the NdisXxx functions with which it originally allocated the resources. As a general rule, 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 (see the MiniportInterruptDPC function for more information).

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 further 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.

To define a MiniportHaltEx function, you must first provide a function declaration that identifies the type of function you're defining. Windows provides a set of function types for drivers. Declaring a function using the function types helps Code Analysis for Drivers, Static Driver Verifier (SDV), and other verification tools find errors, and it's a requirement for writing drivers for the Windows operating system.

For example, to define a MiniportHaltEx function that is named "MyHaltEx", use the MINIPORT_HALT type as shown in this code example:

Then, implement your function as follows:

The MINIPORT_HALT function type is defined in the Ndis.h header file. To more accurately identify errors when you run the code analysis tools, be sure to add the Use_decl_annotations annotation to your function definition. The Use_decl_annotations annotation ensures that the annotations that are applied to the MINIPORT_HALT function type in the header file are used. For more information about the requirements for function declarations, see Declaring Functions by Using Function Role Types for NDIS Drivers.

For information about Use_decl_annotations, see Annotating Function Behavior.

Requirements

   
Windows Driver kit version
Target platform Windows
Minimum KMDF version
Minimum UMDF version
Header ndis.h (include Ndis.h)
Library
IRQL PASSIVE_LEVEL
DDI compliance rules WlanAssociation, WlanConnectionRoaming, WlanDisassociation, WlanTimedAssociation, WlanTimedConnectionRoaming, WlanTimedConnectRequest, WlanTimedLinkQuality, WlanTimedScan

See Also

MiniportInitializeEx
MiniportInterrupt
MiniportInterruptDPC
MiniportReturnNetBufferLists
NdisCancelTimerObject
NdisIMDeInitializeDeviceInstance
NdisMDeregisterInterruptEx
NdisMRegisterMiniportDriver
NdisMRemoveMiniport
NdisMSleep
NdisWaitEvent
NetTimerCallback
Adapter States of a Miniport Driver
Halting a Miniport Adapter
Miniport Adapter States and Operations
Miniport Driver Reset and Halt Functions

Send comments about this topic to Microsoft