DriverEntry of NDIS Protocol Drivers

DriverEntry of NDIS Protocol Drivers

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

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

Parameters

DriverObject

Points to the driver object representing this driver.

RegistryPath

Points to a driver-specific path specification for the \Registry\Machine
\System\CurrentControlSet\Services\DriverName\Parameters key.

Return Value

DriverEntry returns NTSTATUS_SUCCESS, or its equivalent NDIS_STATUS_SUCCESS, if the driver registered as an NDIS protocol and, possibly, initialized itself 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 NTSTATUS_PENDING or its equivalent NDIS_STATUS_PENDING.

Comments

A driver that exports only NDIS-defined driver functions, such as an NDIS intermediate driver that translates an underlying NIC driver’s native frame format into another format for higher-level protocols, simply passes its input parameters, 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

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. Its ProtocolBindAdapter function will be called later to complete driver initialization and to bind the intermediate driver to an underlying NIC miniport.

In effect, the DriverEntry function of such an NDIS intermediate driver can ignore theRegistryPath 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. Such an NDIS intermediate driver binds itself 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.

If an NDIS intermediate driver calls NdisMRegisterMiniport from its DriverEntry function, the driver must set up sufficient static binding and configuration information in the registry to set up one or more virtual NICs corresponding to each underlying NIC driver to which the NDIS intermediate driver will bind itself. The MiniportInitialize function of such an intermediate driver will be called in the context of its call to NdisMRegisterMiniport, so such a driver cannot query the underlying NIC driver(s) when its MiniportInitialize function runs.

Any NDIS intermediate driver that registers ProtocolBindAdapter and ProtocolUnbindAdapter functions makes itself Plug-and-Play-ready, as well as deferring the creation of its virtual NIC(s) until the driver has bound itself to the underlying NIC driver(s). This strategy allows the 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.

A driver that exports ProtocolXxx but not MiniportXxx functions must call NdisRegisterProtocol to register its ProtocolXxx functions with the NDIS library. Such a driver can call certain other NdisXxx configuration and initialization functions from DriverEntry if it has no ProtocolBindAdapter function, such as NdisOpenProtocolConfiguration and NdisReadConfiguration to retrieve network configuration information, set up by the driver’s installation script, from the registry. For more information about driver installation scripts, see the Programmer’s Guide.

A 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. For more information about the functionality of such a protocol’s DriverEntry function, see the Kernel-Mode Driver Design Guide. For more information about the TdiDispatchXxx routines exported by TDI transport protocols, see Part 2.

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 NTSTATUS_SUCCESS or NDIS_STATUS_SUCCESS.

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