DriverEntry of NDIS Miniport Drivers

DriverEntry of NDIS Miniport Drivers

NDIS_STATUS
   DriverEntry(
       IN PVOID Argument1,
       IN PVOID Argument2
       );

DriverEntry is a required function, which the system calls first in any NDIS driver.

Parameters

Argument1

Points to a system-supplied parameter. For Windows NT drivers, this points to a driver object, which is opaque to any NDIS driver that exports only MiniportXxx functions.

Argument2

Points to a second system-supplied parameter. For Windows NT drivers, this points to a registry path, which is opaque to any NDIS driver that exports only MiniportXxx functions.

Return Value

DriverEntry returns the value returned by NdisMRegisterMiniport or NdisIMRegisterLayeredMiniport.

Comments

NDIS miniports and intermediate drivers carry out two basic tasks in their DriverEntry functions:

1.Call NdisMInitializeWrapper to notify the NDIS library that the driver is about to register itself as a miniport.

NDIS sets up the state it needs to track the driver and returns an NdisWrapperHandle, which the driver saves for subsequent calls to NdisXxx configuration and initialization functions.

2.Fill in an NDISXX_MINIPORT_CHARCTERISTICS structure with the appropriate version numbers and the entry points for driver-supplied MiniportXxx functions and, then, call NdisMRegisterMiniport or NdisIMRegisterLayeredMiniport.

Usually, NIC drivers call NdisMRegisterMiniport, as do intermediate drivers that export only a set of MiniportXxx functions. Usually, NDIS intermediate drivers call NdisIMRegisterLayeredMiniport, which effectively defers the initialization of such a driver’s virtual NIC until the driver calls NdisIMInitializeDeviceInstance from its ProtocolBindAdapter function.

DriverEntry can allocate the NDISXX_MINIPORT_CHARACTERISTICS structure on the stack since the NDIS library copies the relevant information to its own storage. DriverEntry should clear the memory for this structure with NdisZeroMemory before setting any driver-supplied values in its members. The current MajorNdisVersion is 0x04, and the current MinorNdisVersion is 0x00. In each XxxHandler member of the characteristics structure, DriverEntry must set the name of a driver-supplied MiniportXxx function, or the member must be NULL.

Calling NdisMRegisterMiniport causes the driver's MiniportInitialize function to run in the context of NdisMRegisterMiniport. Calling NdisIMRegisterLayeredMiniport defers the call to MiniportInitialize until the driver calls NdisIMInitializeDeviceInstance.

Drivers that call NdisMRegisterMiniport must be prepared for an immediate call to their MiniportInitialize functions. Such a driver must have sufficient installation and configuration information stored in the registry or available from calls to an NdisXxx bus-type-specific configuration function to set up any NIC-specific resources the driver will need to carry out network I/O operations.

Drivers that call NdisIMRegisterLayeredMiniport defer the call to their MiniportInitialize functions to another driver-supplied function that makes a call to NdisIMInitializeDeviceInstance. NDIS intermediate drivers usually register a ProtocolBindAdapter function and call NdisIMRegisterLayeredMiniport so that NDIS will call the ProtocolBindAdapter function after all underlying NIC drivers have initialized. This strategy gives such an NDIS intermediate driver, which makes the call to NdisIMInitializeDeviceInstance from ProtocolBindAdapter, the advantage of having its MiniportInitialize function configure driver-allocated resources for the intermediate's virtual NIC to the features of the underlying NIC driver to which the intermediate has already bound itself.

If NdisMRegisterMiniport or NdisIMRegisterLayeredMiniport does not return NDIS_STATUS_SUCCESS, DriverEntry must release any resources it allocated, such as memory to hold the NdisWrapperHandle, and must call NdisTerminateWrapper before it returns control. The driver will not be loaded if this occurs.

By default, DriverEntry runs at IRQL PASSIVE_LEVEL in a system-thread context.