MINIPORT_HALT callback function (ndis.h)

Article
10/21/2021

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.

Note You must declare the function by using the MINIPORT_HALT type. For more information, see the following Examples section.

Syntax

MINIPORT_HALT MiniportHalt;

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

Parameters

[in] 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.

[in] HaltAction

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 is going to 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 power up 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 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.

Examples

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:

MINIPORT_HALT MyHaltEx;

Then, implement your function as follows:

_Use_decl_annotations_
VOID
 MyHaltEx(
    NDIS_HANDLE  MiniportAdapterContext,
    NDIS_HALT_ACTION  HaltAction
    )
  {...}

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

Requirement	Value
Minimum supported client	Supported in NDIS 6.0 and later.
Target Platform	Windows
Header	ndis.h (include Ndis.h)
IRQL	PASSIVE_LEVEL
DDI compliance rules	WlanAssociation, WlanConnectionRoaming, WlanDisassociation, WlanTimedAssociation, WlanTimedConnectionRoaming, WlanTimedConnectRequest, WlanTimedLinkQuality, WlanTimedScan

Share via