3.2 Initialization Function

MiniportInitialize is the first NIC driver function called after DriverEntry. MiniportInitialize is called once for each adapter in the machine that is supported by the miniport NIC driver. If a miniport has one adapter to manage, its MiniportInitialize is called once, if it has two, it is called twice, and so on. The miniport is called only for those adapters of a type it supports; that is, the miniport will not be called for an adapter it does not know how to manage.

If a new NIC supported by a previously loaded miniport is plugged into the system, that miniport’s MiniportInitialize function will be called to initialize the newly installed device. A consequence is that a MiniportInitialize function and any functions it calls, all of which run at IRQL PASSIVE_LEVEL, can be specified as pageable. Code is specified as pageable by using the NDIS_PAGABLE_FUNCTION macro. Initialization code cannot be specified with the NDIS_INIT_FUNCTION macro, since code marked this way is no longer mapped once the initial system boot is complete. Only the DriverEntry function and any functions only called from DriverEntry can be passed to the NDIS_INIT_FUNCTION macro. For more information about specifying code as pageable or as initialization-only code, see The Programmer’s Guide.

The declaration of the initialization function is as follows:

NDIS_STATUS
    MiniportInitialize (
        OUT PNDIS_STATUS  OpenErrorStatus,
        OUT PUINT SelectedMediumIndex,
        IN PNDIS_MEDIUM MediumArray,
        IN UINT MediumArraySize,
        IN NDIS_HANDLE MiniportAdapterHandle,
        IN NDIS_HANDLE ConfigurationHandle
        );

The following arguments are passed to MiniportInitialize.

• An array of NdisMediumXxx at MediumArray. The miniport must choose the medium it supports or prefers and return the index of that medium in SelectedMediumIndex. If the miniport does not find a medium it can support in MediumArray, it must return a failure status of NDIS_STATUS_UNSUPPORTED_MEDIA.

• A handle, MiniportAdapterHandle, that NDIS uses to refer to the miniport. The miniport must retain this handle so that it can pass it in subsequent calls to NDIS, for instance, in such calls as NdisMRegisterAdapterShutdownHandler and NdisMInitializeTimer.

• A configuration handle that identifies the registry key containing NIC-specific information associated with this miniport. The miniport must retain and pass this handle to NdisOpenConfiguration to open the Parameters subkey of the registry that describes the miniport’s adapter. The installation script for a NIC driver, at a minimum, must store a NIC’s I/O bus type and, if not an ISA bus, bus number in this subkey.

Experimental Medium Types

NDIS media types and associated identifiers are contained in the registry key HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\NDIS
\MediaTypes. This key contains a current list of the system-defined media types. Only media found in this key will be passed to MiniportInitialize at MediumArray. To specify a currently unsupported experimental media type and identifier for an under-development miniport, the experimental media type can be added to the registry as already described in Part 1, Chapter 3.