DriverEntry of NDIS Protocol Drivers

The DriverEntry function is required and is the first function that the system calls in any NDIS protocol or intermediate driver, including connection-oriented clients and stand-alone call managers.

NTSTATUS
  DriverEntry(
    IN PDRIVER_OBJECT  DriverObject,
    IN PUNICODE_STRING  RegistryPath
    );

Parameters

DriverObject

Pointer to the driver object representing this driver.

RegistryPath

Pointer to a driver-specific registry path specification set up by the driver's installation script (.inf). For more information about driver installation scripts, see Device Installation Overview.

Return Value

DriverEntry returns STATUS_SUCCESS, or its equivalent NDIS_STATUS_SUCCESS, if the driver registered as an NDIS protocol successfully. If DriverEntry fails initialization by propagating an error status returned by an NdisXxx or by a kernel-mode support routine, the driver will not remain loaded. DriverEntry must execute synchronously; that is, it cannot return STATUS_PENDING or its equivalent NDIS_STATUS_PENDING.

Headers

Declared in Ndis.h. Include Ndis.h.

Comments

The DriverEntry function of every type of NDIS protocol driver must call NdisRegisterProtocol to register the driver's ProtocolXxx entry points with the NDIS library. All types of NDIS protocols should register fully functional ProtocolBindAdapter and ProtocolUnbindAdapter functions to support plug and play. In general, a DriverEntry function should call NdisRegisterProtocol just before it returns control with STATUS_SUCCESS or NDIS_STATUS_SUCCESS.

Any protocol driver that exports a set of standard kernel-mode driver routines in addition to its NDIS-defined ProtocolXxx functions must set the entry points for those driver routines in the given driver object passed in to its DriverEntry function. For more information about the functionality of such a protocol’s DriverEntry function, see Writing a DriverEntry Routine. For more information about the TdiDispatchXxx routines exported by TDI transport protocols, see TDI Transport Driver Dispatch Routines.

If an attempt to allocate resources that the driver needs to carry out network I/O operations fails, DriverEntry should release all resources it already allocated before it returns control with a status other than STATUS_SUCCESS or NDIS_STATUS_SUCCESS.

After calling NdisRegisterProtocol, connection-oriented client protocols subsequently call NdisClOpenAddressFamily from their ProtocolCoAfRegisterNotify functions to register their ProtocolClXxx functions with NDIS. Similarly, connection-oriented call managers and MCM drivers subsequently call NdisCmRegisterAddressFamily from their ProtocolBindAdapter functions or NdisMCmRegisterAddressFamily from their MiniportInitialize functions, respectively, to register their ProtocolCmXxx functions.

An NDIS intermediate driver, such as one that translates an underlying NIC driver’s native frame format into another format for higher level protocols, simply passes the input parameters to its DriverEntry function, uninterpreted, to certain NdisXxx functions.

Usually, the DriverEntry function of such an NDIS intermediate driver calls the following NdisXxx functions in the following order:

1. NdisMInitializeWrapper to notify the NDIS library that the driver is about to register as a miniport driver
2. NdisIMRegisterLayeredMiniport to register the driver’s MiniportXxx functions
3. NdisRegisterProtocol to register the driver’s ProtocolXxx functions

   Such an intermediate driver must register ProtocolBindAdapter and ProtocolUnbindAdapter functions with the NDIS library when it calls NdisRegisterProtocol. Its ProtocolBindAdapter function will be called later to complete driver initialization and to bind the intermediate driver to an underlying miniport driver.

In effect, the DriverEntry function of an NDIS intermediate driver can ignore the RegistryPath pointer after passing it to NdisMInitializeWrapper. Such a driver also can ignore the DriverObject pointer after passing it to NdisIMRegisterLayeredMiniport. However, the driver should save the DriverHandle returned by NdisIMRegisterLayeredMiniport and the NdisProtocolHandle returned by NdisRegisterProtocol for subsequent calls to NdisXxx functions. The intermediate driver's ProtocolBindAdapter function binds the driver to each underlying NIC driver before its MiniportInitialize function is called to initialize the intermediate driver's virtual NIC, and still higher level protocols subsequently bind themselves to the virtual NIC it creates. This strategy allows an NDIS intermediate driver to allocate resources at the creation of the virtual NIC according to the features of the underlying NIC driver to which it is bound.

DriverEntry runs at IRQL = PASSIVE_LEVEL.

See Also

NdisClOpenAddressFamily, NdisCmRegisterAddressFamily, NdisIMRegisterLayeredMiniport, NdisMCmRegisterAddressFamily, NdisMInitializeWrapper, NdisRegisterProtocol, NdisOpenProtocolConfiguration, NdisReadConfiguration, ProtocolBindAdapter, ProtocolUnbindAdapter