NdisReset

NdisReset

VOID
   NdisReset(
       OUT PNDIS_STATUS Status,
       IN NDIS_HANDLE NdisBindingHandle
       );

NdisReset forwards a reset request to an underlying driver.

Parameters

Status

Points to a caller-supplied variable that is set on return from this function. The underlying driver determines which NDIS_STATUS_XXX is returned, but it is usually one of the following values:

NDIS_STATUS_SUCCESS

The underlying driver reset its NIC (or virtual NIC) to its initial state.

NDIS_STATUS_PENDING

The request is being handled asynchronously, and the caller’s ProtocolResetComplete function will be called when it is completed.

NDIS_STATUS_RESET_IN_PROGRESS

The underlying driver is currently resetting its NIC so this request is superfluous. Moreover, the caller’s ProtocolStatus function was or will be called with NDIS_STATUS_RESET_START to indicate that a reset is in progress.

NDIS_STATUS_NOT_RESETTABLE

The underlying NIC cannot be reset by software commands.

NDIS_STATUS_ADAPTER_REMOVED or NDIS_STATUS_FAILURE

The caller’s binding is already closed so no reset will be attempted for this caller.

NDIS_STATUS_CLOSING

The caller’s binding is currently being closed so no reset will be attempted for this caller.

NDIS_STATUS_SOFT_ERRORS

The underlying NIC driver reset the netcard but one or more recoverable hardware errors occurred during this operation. The NIC driver has logged the error(s).

NDIS_STATUS_HARD_ERRORS

The underlying NIC driver attempted to reset the netcard but one or more unrecoverable hardware errors occurred during this operation. The NIC driver has logged the error(s).

NDIS_STATUS_NOT_ACCEPTED

This value usually is a nonspecific default, returned when none of the more specific NDIS_STATUS_XXX caused NDIS or the underlying NIC driver to fail the request.

NdisBindingHandle

Specifies the handle returned by NdisOpenAdapter that identifies the target NIC or the virtual adapter of the next-lower driver to which the caller is bound.

Comments

When a protocol calls NdisReset, the NDIS library does not call the MiniportReset function of the underlying NIC driver until NDIS has completed any internally queued send requests back to the initiating protocol(s). Only after NDIS has cleared its send queue for the underlying driver does it call that driver’s MiniportReset function.

If the underlying driver queues send packets internally, it also completes any send packets it is currently holding in its queue before attempting to reset its NIC.

Consequently, all protocol drivers bound above the same NIC should hold on to their outstanding send packets during a reset operation. At the start of a reset, NDIS calls the ProtocolStatus function of each bound protocol with NDIS_STATUS_RESET_START and, then, the corresponding ProtocolStatusComplete function. When the reset operation is done, NDIS calls the ProtocolStatus function of each bound protocol again with NDIS_STATUS_RESET_END and, then, the corresponding ProtocolStatusComplete function.

Like any other driver bound above the same NIC, the ProtocolStatus and ProtocolStatusComplete functions of the driver that called NdisReset receive these notifications. However, if NdisReset returns STATUS_PENDING, only the ProtocolResetComplete function of the original caller is notified when the reset operation is done.

A protocol bound to NDISWAN should never call NdisReset.

Callers of NdisReset run at IRQL <= DISPATCH_LEVEL.