MiniportReset

MiniportReset is a required function that issues a hardware reset to the NIC and/or resets the driver’s software state.

NDIS_STATUS 
  MiniportReset(
    OUT PBOOLEAN  AddressingReset,
    IN NDIS_HANDLE  MiniportAdapterContext
    );

Parameters

AddressingReset

Pointer to a variable that MiniportReset sets to TRUE if the NDIS library should call MiniportSetInformation after the reset has completed to restore multicast addresses and registered address filters. MiniportReset should set this variable to FALSE if the miniport will restore this information after the reset has completed.

MiniportAdapterContext

Specifies the handle to a miniport driver-allocated context area in which the driver maintains per-NIC state, set up by MiniportInitialize.

Return Value

MiniportReset can return one of the following:

NDIS_STATUS_SUCCESS

MiniportReset successfully reset the NIC 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 NIC does not provide reset capabilities under software control.

NDIS_STATUS_RESET_IN_PROGRESS

MiniportReset determined that the NIC was currently being reset, so this call is superfluous.

NDIS_STATUS_SOFT_ERRORS

MiniportReset successfully reset the NIC 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 NIC but an unrecoverable error occurred during the operation. MiniportReset has called NdisWriteErrorLogEntry with more information about the error.

Headers

Declared in Ndis.h. Include Ndis.h.

Comments

If MiniportReset changes NIC’s station address, the miniport driver automatically restores the station address to its prior value following the reset.

MiniportReset can also reset other information, such as multicast or functional addressing information or the lookahead size. If MiniportReset sets the variable at AddressingReset to TRUE before it returns control, NDIS subsequently calls the MiniportSetInformation function to restore this information. However, if MiniportReset sets the variable at AddressingReset to FALSE, the miniport must restore such information after the reset has completed.

Intermediate drivers 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.

As a general rule, an intermediate driver's MiniportReset function should always set AddressingReset to TRUE. Until the underlying NIC driver resets its NIC, an intermediate driver cannot determine whether it must restore addressing information for its virtual NIC. An intermediate driver, when calling NdisMSetAttributesEx, sets the NDIS_ATTRIBUTE_IGNORE_PACKET_TIMEOUT and NDIS_ATTRIBUTE_IGNORE_REQUEST_TIMEOUT flags to prevent NDIS from timing out send packets and OID requests that NDIS has sent to the driver. .As a result, an intermediate driver’s MiniportReset function is called only when a reset request is directed to the underlying NIC driver.

Before MiniportReset begins resetting the NIC or updating the NIC's software state:

• The miniport driver can optionally complete any pending OID requests. NDIS will submit no further OID requests to the miniport driver for the NIC being reset until the reset operation has finished. After the reset, NDIS will resubmit to the miniport driver any OID requests that were pending but not completed by the miniport driver before the reset.
• A serialized miniport driver should complete any pending send operations. If the miniport driver does not complete all pending send operations before completing the reset, NDIS will complete those operations with a failure status after the reset operation has finished.
• A deserialized miniport driver must complete any pending send operations. NDIS will not requeue pending send packets for a deserialized driver since NDIS does not maintain the send queue for such a driver.

After the reset operation has finished, a miniport driver must not attempt to complete any send operations that were pending but not completed before the reset.

A miniport driver need not call NdisMIndicateStatus or NdisMCoIndicateStatus 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 NIC 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 preempted by an interrupt.

If a NIC driver supplies a MiniportCheckForHang function, the NDIS library calls it periodically to determine whether to call the driver’s MiniportReset function. Otherwise, the NDIS library calls a NIC driver’s MiniportReset function whenever requests that NDIS submitted to the MiniportQueryInformation, MiniportSetInformation, MiniportSendPackets, MiniportSend, or MiniportWanSend function seem to have timed out. (NDIS does not call a deserialized NIC driver's MiniportReset function if the driver's MiniportSend or MiniportSendPackets function seems to have timed out, nor does NDIS call a connection-oriented NIC driver's MiniportReset function if the driver's MiniportCoSendPackets function seems to have timed out.) By default, the NDIS-determined time-out interval for outstanding sends and requests is around four seconds. If this default is too short, a NIC driver can make an initialization-time call to NdisMSetAttributesEx, rather than NdisMSetAttributes, to lengthen the time-out interval to suit its NIC.

Every NDIS intermediate driver should call NdisMSetAttributesEx from MiniportInitialize and disable NDIS’s 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 NIC might be hung on receives, so supplying a MiniportCheckForHang function allows a driver to monitor its NIC for this condition and to force a reset if it occurs.

MiniportReset runs at IRQL = DISPATCH_LEVEL.

See Also

MiniportCheckForHang, MiniportCoSendPackets, MiniportInitialize, MiniportQueryInformation, MiniportSend, MiniportSendPackets, MiniportSetInformation, MiniportWanSend, NdisMIndicateStatus, NdisMResetComplete, NdisMSetAttributesEx, NdisWriteErrorLogEntry