W_RESET_HANDLER callback function
Note NDIS 5. x has been deprecated and is superseded by NDIS 6. x. For new NDIS driver development, see Network Drivers Starting with Windows Vista. For information about porting NDIS 5. x drivers to NDIS 6. x, see Porting NDIS 5.x Drivers to NDIS 6.0.
MiniportReset is a required function that issues a hardware reset to the NIC and/or resets the driver's software state.
Syntax
W_RESET_HANDLER MiniportReset;
NDIS_STATUS MiniportReset(
_Out_ PBOOLEAN AddressingReset,
_In_ NDIS_HANDLE MiniportAdapterContext
)
{ ... }
Parameters
AddressingReset [out]
Pointer to a variable that MiniportReset sets to TRUE if the NDIS library should call MiniportSetInformation after the reset has completed to restore addressing and other configuration settings to the current values . MiniportReset should set this variable to FALSE if the miniport driver will restore this information after the reset has completed.For more information, see Hardware Reset (NDIS 5.1).
MiniportAdapterContext [in]
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:
| Return code | Description |
|---|---|
| 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. |
Remarks
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 driver must restore such information after the reset has completed.
If AddressingReset is set to TRUE, NDIS restores the Wake on Lan (WoL) pattern list by calling OID_PNP_ADD_WAKE_UP_PATTERN. The driver should free the WoL pattern list from its adapter context because the hardware list is already reset.
If an intermediate driver has a MiniportReset function, the 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.
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 or OID requests that were pending but not completed before the reset.
A miniport driver does not need to 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 enables a driver to monitor its NIC for this condition and to force a reset if it occurs.
Requirements
Target platform |
Desktop |
Version |
Not supported for NDIS 6.0 drivers in Windows Vista. Use MiniportResetEx instead. Supported for NDIS 5.1 drivers in Windows Vista and Microsoft Windows XP. |
Header |
Ndis.h (include Ndis.h) |
IRQL |
<= DISPATCH_LEVEL |
See also