MiniportReset

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

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

Parameters

AddressingReset

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

Specifies the handle to a miniport-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.

Comments

MiniportReset can reset the parameters of its NIC. If a reset causes a change in the NIC’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 lookahead 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 NIC driver resets its NIC, such an intermediate driver cannot determine whether it must restore addressing information for its virtual NIC. 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 NIC 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 NIC or updating its software state. NDIS submits no further requests to the miniport for the NIC 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 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 pre-empted 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 NDIS submitted to the MiniportQueryInformation, MiniportSetInformation, MiniportSendPackets, MiniportSend, or MiniportWanSend function seem 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.

By default, MiniportReset runs at IRQL DISPATCH_LEVEL.

See Also

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