DriverEntry of NDIS Miniport Drivers (NDIS 5.1) function

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.

The DriverEntry function is required and is the first function that the system calls in any NDIS driver.

Syntax

ULONG DriverEntry(
  _In_ PVOID Argument1,
  _In_ PVOID Argument2
);

Parameters

• Argument1 [in]
  Pointer to a system-supplied parameter. For Windows 2000 and later drivers, this points to a driver object, which is opaque to any NDIS driver that exports only MiniportXxx functions.

• Argument2 [in]
  Pointer to a second system-supplied parameter. For Windows 2000 and later 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.

Remarks

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 driver.

   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 NDIS_MINIPORT_CHARACTERISTICS 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 NDIS XX_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 0x05, 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.

Requirements

See also

DriverEntry of NDIS Protocol Drivers

NdisIMInitializeDeviceInstance

MiniportInitialize

NdisIMRegisterLayeredMiniport

NdisMInitializeWrapper

NdisMRegisterMiniport

NdisTerminateWrapper

NdisZeroMemory

ProtocolBindAdapter

Send comments about this topic to Microsoft