MiniportReset (Compact 2013)

Article
07/31/2017

3/26/2014

This required function issues a hardware reset to the network adapter, and resets the driver's software state.

Syntax

NDIS_STATUS MiniportReset(
  PBOOLEAN AddressingReset,
  NDIS_HANDLE MiniportAdapterContext
);

Parameters

AddressingReset
[out] Points to a variable that MiniportReset sets to TRUE if the NDIS library should call MiniportSetInformation to restore addressing information to the current values.

MiniportAdapterContext
[in] Specifies the handle to a miniport-allocated context area in which the driver maintains per-network adapter state, set up by MiniportInitialize.

Return Value

Values	Description
NDIS_STATUS_SUCCESS	Successfully reset the network adapter to an operational state.
NDIS_STATUS_PENDING	The driver will complete the reset operation asynchronously by calling NdisMResetComplete when the operation is completed.
NDIS_STATUS_NOT_RESETTABLE	The network adapter does not provide reset capabilities under software control.
NDIS_STATUS_RESET_IN_PROGRESS	Determined that the network adapter was currently being reset. Therefore, this call is superfluous.
NDIS_STATUS_SOFT_ERRORS	Successfully reset the network adapter but a recoverable error occurred during the operation. MiniportReset has called NdisWriteErrorLogEntry with more information about the error.
NDIS_STATUS_HARD_ERRORS	Tried to reset the network adapter but an unrecoverable error occurred during the operation. MiniportReset has called NdisWriteErrorLogEntry with more information about the error.

Remarks

MiniportReset can reset the parameters of its network adapter. If a reset causes a change in the network adapter's station address, the miniport automatically restores the station address following the reset to its prior value. Any multicast or functional addressing masks reset by the hardware do not have to be reset in this function.

If other information, such as multicast or functional addressing information or the look-ahead size, is changed by a reset, MiniportReset must set the variable at AddressingReset to TRUE before it returns control. This causes NDIS to call the MiniportSetInformation function to restore the information.

Generally, the MiniportReset function of an NDIS intermediate driver should always set AddressingReset to TRUE. Until the underlying network adapter driver resets its network adapter, such an intermediate driver cannot determine whether it must restore addressing information for its virtual network adapter. Because an intermediate driver disables the NDIS library's timing out of queued sends and requests to itself with an initialization-time call to NdisMSetAttributesEx, such a driver's MiniportReset function is called only when a reset request is directed to the underlying network adapter driver.

Intermediate drivers that layer themselves above other kinds of device drivers must also have a MiniportReset function. Such a MiniportReset function must handle reset requests initiated by protocol drivers' calls to NdisReset. If the intermediate driver also has a MiniportCheckForHang function, its MiniportReset function will be called when MiniportCheckForHang returns TRUE.

It is unnecessary for a driver to complete outstanding requests before MiniportReset begins resetting the network adapter or updating its software state. NDIS submits no additional requests to the miniport for the network adapter designated by the MiniportAdapterContext handle when NDIS has called MiniportReset until the reset operation is completed. A miniport does not have to call NdisMIndicateStatus to signal the start and finish of each reset operation because NDIS notifies bound protocols when a reset begins and ends.

If MiniportReset must wait for state changes in the network adapter during reset operations, it can call NdisStallExecution. However, a MiniportReset function should never call NdisStallExecution with an interval greater than 50 microseconds.

If MiniportReset returns NDIS_STATUS_PENDING, the driver must complete the original request subsequently with a call to NdisMResetComplete.

MiniportReset can be pre-empted by an interrupt.

If a network adapter driver supplies a MiniportCheckForHang function, the NDIS library calls it periodically to determine whether to call the driver's MiniportReset function. When requests that NDIS submitted to the MiniportQueryInformation, MiniportSetInformation, MiniportSend, or MiniportWanSend functions appear to have timed out, the NDIS library calls a network adapter driver's MiniportReset function. By default, NDIS-determined time-out interval for outstanding sends and requests is around four seconds. If this default is too short, a network adapter driver can make an initialization-time call to NdisMSetAttributesEx, instead of NdisMSetAttributes, to lengthen the time-out interval to suit its network adapter.

Every NDIS intermediate driver should call NdisMSetAttributesEx from MiniportInitialize and disable the NDIS tries to time out requests and sends in the intermediate driver. NDIS runs an intermediate driver's MiniportCheckForHang function, if any, approximately every two seconds.

NDIS cannot determine whether a network adapter might be unresponsive receives. Therefore, supplying a MiniportCheckForHang function allows a driver to monitor its network adapter for this condition and to force a reset if it occurs.

Requirements

Header

externs.h

Share via

MiniportReset (Compact 2013)

Syntax

Parameters

Return Value

Remarks

Requirements

See Also

Reference

Additional resources