MacReset

MacReset

NDIS_STATUS
MacReset(
IN NDIS_HANDLE MacBindingHandle
);

MacReset is called when a bound protocol driver calls NdisReset.

Parameters

MacBindingHandle

Specifies the handle that the NIC driver associates with the binding.

Return Value

MacReset can return the following status codes:

NDIS_STATUS_FAILURE
NDIS_STATUS_HARD_ERRORS
NDIS_STATUS_NOT_ACCEPTED
NDIS_STATUS_NOT_RESETTABLE
NDIS_STATUS_PENDING
NDIS_STATUS_RESET_IN_PROGRESS
NDIS_STATUS_SOFT_ERRORS
NDIS_STATUS_SUCCESS

Comments

NdisReset instructs the NIC driver to issue a hardware reset to its NIC and to reset its own software state. A call to NdisReset should not alter NIC parameters as viewed by a protocol driver, such as the packet filter and lookahead size that are in effect before the reset operation.

If a hardware reset changes the current station address, the NIC driver automatically restores the address following the reset operation. MacReset reprograms any multicast or functional addressing masks that it resets before it returns control by calling the appropriate filter library functions.

During reset processing, the NIC driver calls NdisIndicateStatus twice for each bound protocol driver. At the beginning of the reset, it calls NdisIndicateStatus with the general status code NDIS_STATUS_RESET_START. At the end of the reset, it must call NdisIndicateStatus with the general status code NDIS_STATUS_RESET_END.

The NIC driver must ensure that NdisIndicateStatus delivers NDIS_STATUS_RESET_START to all currently bound protocol drivers.

In some circumstances, the NIC driver can return NDIS_STATUS_SUCCESS or NDIS_STATUS_PENDING shortly after the NDIS_STATUS_RESET_START indication.

MacReset completes synchronously if it finishes the reset operation before it returns control with a status code other than NDIS_STATUS_PENDING.

If the NIC does not support a reset under software control, MacReset returns with NDIS_STATUS_NOT_RESETTABLE. If the NIC driver attempts a reset and finds recoverable hardware errors, MacReset logs the error(s) and completes successfully with NDIS_STATUS_SOFT_ERRORS. If the NIC resets with unrecoverable hardware errors, this function again logs the error(s) and returns NDIS_STATUS_HARD_ERRORS. Only if the NIC reset has no errors does MacReset return NDIS_STATUS_SUCCESS.

If it cannot complete reset operations before it returns control, MacReset returns NDIS_STATUS_PENDING. The NIC driver eventually calls NdisCompleteReset, which, in turn, calls the ProtocolResetComplete function of the driver that initiated the reset operation. This asynchronous completion allows protocol postprocessing of the reset request.

While MacReset is executing, other NIC driver functions must reject all incoming requests with NDIS_STATUS_RESET_IN_PROGRESS. During the reset operation, the NIC driver cancels pending requests with NDIS_STATUS_REQUEST_ABORTED and blocks new requests with NDIS_STATUS_RESET_IN_PROGRESS. These are the only status codes the driver can issue until it determines the reset operation is complete. When this occurs, the driver calls NdisIndicateStatus, which issues NDIS_STATUS_RESET_END to all bound protocol drivers. At this point, the NIC driver ceases to block incoming requests.

Exceptions to the preceding rules are calls to the driver's MacOpenAdapter and MacCloseAdapter functions. These NIC driver functions usually return NDIS_STATUS_PENDING during resets and complete the open/close operation asynchronously.