Chapter 1 NDIS Driver Upper-Edge Functions

This describes, in alphabetic order, the system-defined functions implemented in NIC drivers and in intermediate drivers that export a set of NDIS upper-edge functions.

Two types of NDIS drivers have some or all of the functions described here:

1.NDIS miniports, whether for LAN or WAN NICs, export the DriverEntry and MiniportXxx functions described here.

NIC drivers for WAN media export the same functions as NIC drivers for LAN media with one exception: a MiniportWanSend function replaces the MiniportSendPackets or MiniportSend function of LAN NIC miniports. Each of these MiniportXxx functions is described later.

2.Intermediate drivers export a subset of the MiniportXxx functions described here and a DriverEntry function that fulfills the initialization-time requirements of the NDIS library.

Intermediate drivers also can export a set of the NDIS Driver Lower-Edge Functions, described later, or they can use another interface to communicate with underlying drivers of devices other than a NIC.

NDIS intermediate drivers export both ProtocolXxx and MiniportXxx functions, but they need not have certain functions, such as MiniportISR or MiniportTimer, that any NIC driver must have to communicate with and control its NIC.

Driver Function Names

All NDIS driver functions with the prefix Miniport have been given metanames describing their respective basic functionality in the alphabetical references that follow.

Except for the DriverEntry function, NDIS driver functions can have any name the driver writer chooses. For easy debugging, most system-supplied miniports simply substitute a driver-specific prefix for the Miniport prefix used in this documentation.

The initial entry point of any Windows NT kernel-mode driver has the explicit name DriverEntry in order to be loaded. For more information about the general requirements for and functionality of Windows NT DriverEntry routines, see also the Kernel-Mode Driver Design Guide.

Calling NdisXxx Functions at Appropriate IRQLs

NDIS drivers' functions run, by default, at one of the following IRQLs, shown in order of increasing priority:
PASSIVE_LEVEL < DISPATCH_LEVEL < DIRQL.

NDIS intermediate drivers' functions run, by default, at either of the preceding lower priority IRQLs. Only drivers of NICs that generate interrupts have functions that run at device IRQL.

Any driver function running at IRQL PASSIVE_LEVEL can be pre-empted by a thread of execution running at a higher priority IRQL. Any driver function running at PASSIVE_LEVEL or DISPATCH_LEVEL can be pre-empted by an interrrupt, that is, by an interrupt service routine or by a synchronization routine that also runs at DIRQL.

Each of the following DriverEntry and MiniportXxx descriptions specifies the default IRQL at which that function runs. The default IRQLs of certain MiniportXxx effectively restrict the set of NdisXxx functions that these MiniportXxx can call. For example, it is a fatal error for a MiniportISR function, which runs at DIRQL, to call any NdisXxx function that requires calls from IRQL <= DISPATCH_LEVEL.

For specific information about the range of valid IRQLs for calls to each NdisXxx function, see Chapter 3.

Initialization-Only and Pageable Driver Code

NDIS miniport and intermediate drivers mark their DriverEntry functions as initialization-only code, using the NDIS_INIT_FUNCTION macro. This causes DriverEntry to be discarded after it returns control.

Other driver functions can be marked as pageable code, using the NDIS_PAGABLE_FUNCTION macro. 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 always at IRQL < DISPATCH_LEVEL.