NdisIMSwitchToMiniport

BOOLEAN
NdisIMSwitchToMiniport(
IN NDIS_HANDLE MiniportAdapterHandle,
OUT PNDIS_HANDLE SwitchHandle
);

NdisIMSwitchToMiniport allows an intermediate driver function to call NdisMXxx normally called only from MiniportXxx functions, as, for example, to make indications up to higher-level protocols.

Parameters

MiniportAdapterHandle: Specifies the handle input to MiniportInitialize.
SwitchHandle: Points to a variable in which this function returns a handle if the call succeeds.

Return Value

NdisIMSwitchToMiniport returns TRUE if the caller can safely call miniport-only NdisMXxx functions until it makes a reciprocal call to NdisIMRevertBack.

Comments

An intermediate driver must make indications up to higher-level protocols as if from a NIC driver’s MiniportXxx functions. Attempts to simply forward indications to bound protocols directly from an intermediate driver function that receives them will cause deadlocks.

For example, after a successful call to NdisIMSwitchToMiniport, the ProtocolXxx function of an NDIS intermediate driver can safely call NdisMXxx functions commonly called from the MiniportHandleInterrupt or MiniportTimer functions of underlying NIC drivers. In particular, such a ProtocolXxx function can call NdisMXxx functions, such as NdisMIndicateReceivePacket or NdisMIndicateStatus, that indicate up to higher-level protocols bound to the intermediate driver’s virtual NIC.

After a successful call to NdisIMSwitchToMiniport, an intermediate driver should call NdisIMRevertBack as quickly as possible. Until it calls NdisIMRevertBack, the execution of such a ProtocolXxx function prevents other MiniportXxx functions in the same driver from running.

If NdisIMSwitchToMiniport returns FALSE, the intermediate driver should call NdisIMQueueMiniportCallback. The MiniportCallback function passed to NdisIMQueueMiniportCallback should do essentially the same work as the caller’s miniport-only code would have done if its call to NdisIMSwitchToMiniport had succeeded. That is, such a MiniportCallback function replaces the miniport-only code bracketed by calls to NdisIMSwitchToMiniport and NdisIMRevertBack, as well as setting up sufficient state to communicate with the nonminiport code paths of the intermediate driver.

If an NDIS intermediate driver has internal functions called by both its ProtocolXxx and MiniportXxx functions, such an internal driver function cannot call NdisIMSwitchToMiniport, NdisIMRevertBack, or NdisIMQueueMiniportCallback. A call to any of these NdisIMXxx functions from a MiniportXxx code path is a fatal error.

Callers of NdisIMSwitchToMiniport run at IRQL <= DISPATCH_LEVEL.