Miniport Adapter Check-for-Hang and Reset Operations
Overview
Warning
Check-for-Hang (CFH) and Reset operations are discouraged for all NDIS 6.83 and later drivers. For more information, see Check-for-Hang and Reset operations in NDIS 6.83 and later.
NDIS calls an NDIS miniport driver's MiniportCheckForHangEx function to check the operational state of an NDIS adapter that represents a network interface card (NIC). MiniportCheckForHangEx checks the internal state of the adapter and returns TRUE if it detects that the adapter is not operating correctly.
By default, NDIS calls MiniportCheckForHangEx approximately every 2 seconds. If MiniportCheckForHangEx returns TRUE, NDIS calls the NDIS miniport driver's MiniportResetEx function. If the default time-out value of 2 seconds is too small, your miniport driver can set a different value at initialization time as follows:
- Set the CheckForHangTimeInSeconds member of the NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES structure to a nonzero value.
- Pass the NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES structure in the MiniportAttributes parameter of the NdisMSetMiniportAttributes function.
For more information about setting driver attributes, see Initializing an Adapter. The value of CheckForHangTimeInSeconds should be greater than the initialize time of your miniport driver. However, if your driver takes longer than CheckForHangTimeInSeconds seconds to initialize, this time-out expires, causing NDIS to call your driver's MiniportCheckForHangEx function. If MiniportCheckForHangEx returns TRUE, NDIS will then call your driver's MiniportResetEx function. For this reason, you should synchronize your driver's MiniportCheckForHangEx function with driver initialization so that MiniportCheckForHangEx will not return TRUE if the driver has not finished initializing.
If your miniport driver does not complete an OID request within two successive calls to MiniportCheckForHangEx, NDIS can call the driver's MiniportResetEx function. For some OID requests, NDIS calls MiniportResetEx if the driver does not complete the request within four successive calls to MiniportCheckForHangEx.
The reset operation does not affect miniport adapter operational states. Also, the state of the adapter might change while a reset operation is in progress. For example, NDIS might call a driver's MiniportPause function when there is a reset operation in progress. In this case, the driver can complete either the reset or the pause operation in any order while following the normal requirements for each operation.
For a reset operation, the driver can fail transmit request packets or it can keep them queued and complete them later. However, you should note that an overlying driver cannot complete a pause operation while its transmit packets are pending.
A miniport driver can complete a reset request synchronously by returning a success or failure status. The driver can complete a reset request asynchronously by returning NDIS_STATUS_PENDING. In this case, the driver must call NdisMResetComplete to complete the operation.
Check-for-Hang and Reset operations in NDIS 6.83 and later
In versions of NDIS before 6.83, Check-for-Hang (CFH) and Reset operations were discouraged for Always On, Always Connected (AOAC) systems due to battery life issues. However, drivers could still use CFH on other non-AOAC Windows systems by implementing the optional MiniportCheckForHangEx and MiniportResetEx callback functions.
Starting in NDIS 6.83, these callback functions are discouraged on all Windows systems regardless of power capabilities. Although it is not a logo test violation to use CFH in NDIS 6.83 and later, NDIS drivers should use the following table for guidance about its usage.
| Caller | Recommendation | Notes |
|---|---|---|
| Drivers targeting AOAC systems | Must not implement | Causes battery life issues due to periodic check-for-hang activity |
| Drivers targeting Windows Server systems | Must not implement | Causes issues when the CPU is stressed |
| Virtual (software-only) miniport drivers | Must not implement | Reset not possible without hardware |
| Other new NDIS 6.83 and later drivers | Should not implement | |
| Other existing NDIS 6.82 and earlier code | Not required to change, but should consider removing Check-for-Hang and Reset in future rework |