DriverEntry of NDIS Intermediate Drivers (Compact 2013)

  • Article

3/26/2014

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

Syntax

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

Parameters

  • DriverObject
    A pointer to the driver object that represents this driver.
  • RegistryPath
    A pointer to a driver-specific registry path specification that is set up by the driver's protocol installation file (.inf).

Return Value

DriverEntry returns STATUS_SUCCESS, or its equivalent NDIS_STATUS_SUCCESS, if the driver registered as an NDIS protocol driver successfully. If DriverEntry fails initialization by propagating an error status that was returned by an NdisXxx function 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.

Remarks

To register the intermediate driver with NDIS, the DriverEntry routine must, at a minimum:

  1. Call the NdisMRegisterMiniportDriver function with the NDIS_INTERMEDIATE_DRIVER flag set to register the driver's MiniportXxx functions.
  2. Call the NdisRegisterProtocolDriver function to register the driver's ProtocolXxx functions if the driver later binds itself to an underlying NDIS driver.
  3. Call the NdisIMAssociateMiniport function to inform NDIS about the association between the driver's miniport upper edge and protocol lower edge.

If an error occurs in DriverEntry after NdisMRegisterMiniportDriver returns successfully, the driver must call the NdisMDeregisterMiniportDriver function before DriverEntry returns. If DriverEntry succeeds, the driver must call NdisMDeregisterMiniportDriver from its MiniportDriverUnload function.

Intermediate drivers share most of the DriverEntry requirements of protocol drivers and miniport drivers. For more information about the DriverEntry function for protocol drivers and miniport drivers, see DriverEntry of NDIS Protocol Drivers and DriverEntry of NDIS Miniport Drivers.

The initialization of an intermediate driver's virtual miniport occurs when the driver calls the NdisIMInitializeDeviceInstanceEx function from its ProtocolBindAdapterEx function.

NDIS calls the ProtocolBindAdapterEx function after all underlying miniport drivers have initialized.

In effect, the DriverEntry function of an NDIS intermediate driver can ignore the RegistryPath pointer after passing it to NdisMRegisterMiniportDriver. Such a driver can also ignore the DriverObject pointer after passing it to NdisMRegisterMiniportDriver. However, the driver should save the miniport driver handle value that is returned by NdisMRegisterMiniportDriver at NdisMiniportDriverHandle and the protocol handle value that is returned by NdisRegisterProtocolDriver at NdisProtocolHandle for later calls to NdisXxx functions. The intermediate driver's ProtocolBindAdapterEx function binds the driver to each underlying miniport driver before its MiniportInitializeEx function is called to initialize the intermediate driver's virtual miniport. And still higher level protocol drivers subsequently bind themselves to the virtual miniport that it creates. This strategy enables an NDIS intermediate driver to allocate resources at creating the virtual miniport according to the features of the underlying miniport driver that it is bound to.

See Also

Reference

NDIS Intermediate Driver Functions
DriverEntry
MiniportDriverUnload
NdisIMAssociateMiniport
NdisMDeregisterMiniportDriver
NdisMRegisterMiniportDriver
NdisRegisterProtocolDriver
ProtocolBindAdapterEx