MiniportReset (Windows Embedded CE 6.0)

Article
01/05/2012

1/6/2010

This function is a required function that issues a hardware reset to the network adapter and/or 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

The following table shows the status values that MiniportReset can return.

Values	Description
NDIS_STATUS_SUCCESS	MiniportReset 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 done.
NDIS_STATUS_NOT_RESETTABLE	The network adapter does not provide reset capabilities under software control.
NDIS_STATUS_RESET_IN_PROGRESS	MiniportReset determined that the network adapter was currently being reset, so this call is superfluous.
NDIS_STATUS_SOFT_ERRORS	MiniportReset 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	MiniportReset attempted 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.

As a general rule, 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 types of device drivers also must 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 whenever 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 further 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 need not 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. Whenever 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, rather than 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 attempts 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 hung on receives, so 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
Windows Embedded CE	Windows CE .NET 4.0 and later

MiniportReset (Windows Embedded CE 6.0)

Syntax

Parameters

Return Value

Remarks

Requirements

See Also

Reference

Additional resources