NDIS Driver Lower-Edge Functions
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.
This section describes, in alphabetic order, the system-defined functions implemented in NDIS drivers layered above an underlying NIC driver that exports a set of NDIS upper-edge (MiniportXxx) functions.
Five types of NDIS drivers have at least some of the functions described here:
NDIS transport protocols that export a set of the ProtocolXxx functions described here and communicate with their clients through the Transport Driver Interface (TDI).
NDIS intermediate drivers that export the ProtocolXxx functions described here, along with a set of the MiniportXxx functions, described earlier in NDIS Driver Upper Edge Functions.
Intermediate NDIS drivers appear to be miniport drivers to higher-level NDIS drivers that layered themselves above such an intermediate driver by establishing a binding. Intermediate NDIS drivers appear to be protocols to the NDIS drivers below them, including NIC drivers. To the NDIS library, such an intermediate driver appears to be both a protocol and a miniport driver.
Connection-oriented clients that export some of the ProtocolXxx functions, along with the ProtocolCoXxx and ProtocolClXxx functions, described here. Such a client protocol also might communicate with its own clients through the TDI interface described later in Part 3 or, as the lowest component in a transport stack, with its own client(s) through a transport protocol-specific interface.
Connection-oriented, stand-alone call managers that export some of the ProtocolXxx functions, along with the ProtocolCoXxx and ProtocolCmXxx functions, described here.
Drivers of connection-oriented NICs with integrated call-management support. Such a miniport driver, sometimes called an MCM driver, exports the ProtocolCmXxx functions described here, along with a set of the MiniportXxx and MiniportCoXxx functions, described earlier in NDIS Driver Upper Edge Functions.
Driver Function Names
All NDIS driver functions with the prefix "Protocol" have been given metanames describing their respective basic functionality in the references that follow.
Except for the DriverEntryfunction, NDIS-defined driver functions can have any name the driver writer chooses. For easy debugging, most system-supplied protocols simply substitute a driver-specific prefix for the Protocol prefix used in this documentation.
The initial entry point of any kernel-mode driver has the explicit name DriverEntryin order to be loaded automatically by the system. For more information about the general requirements for and functionality of DriverEntryroutines, see Writing a DriverEntry Routine.
Calling NdisXxx Functions at Appropriate IRQLs
NDIS lower-edge driver functions run at one of the following IRQLs, which are shown in order of increasing priority:
IRQL = PASSIVE_LEVEL or IRQL = DISPATCH_LEVEL.
Any driver function can be preempted by a thread of execution that is running at a higher priority IRQL. For example, every ProtocolXxx function can be preempted by device drivers' ISRs that run at DIRQL when interrupts occur or by a system clock interrupt.
Each of the following DriverEntry and ProtocolXxx descriptions contains information about the possible range of IRQLs at which that function runs. For certain ProtocolXxx functions, the IRQL range effectively restricts the set of NdisXxx functions that these ProtocolXxx functions can call. For example, if a call is made to NdisCopyBufferfrom a ProtocolXxx function running at IRQL = DISPATCH_LEVEL, or while the ProtocolXxx function is holding a spin lock, a fatal page fault can result.
Initialization-Only and Pageable Driver Code
NDIS protocols mark their DriverEntryfunctions as initialization-only code, using the NDIS_INIT_FUNCTIONmacro.
Other driver functions can be marked as pageable code, using the NDIS_PAGEABLE_FUNCTIONmacro. However, a driver function can be pageable code if and only if it never runs at IRQL >= DISPATCH_LEVEL. This restriction implies the following:
A function marked pageable cannot acquire any spin lock and should not call other functions that do.
A function marked pageable cannot be called by any function that is holding a spin lock when the call occurs.
A function marked pageable must run exclusively at IRQL < DISPATCH_LEVEL.
Most of the ProtocolXxx functions described here except ProtocolBindAdapter, ProtocolOpenAdapterComplete, ProtocolUnbindAdapter, ProtocolCoAfRegisterNotify, and ProtocolCloseAdapterCompletecan be called by NDIS at IRQL = DISPATCH_LEVEL.