MiniportInitialize

Article
06/30/2006

MiniportInitialize is a required function that sets up a network adapter (or virtual network adapter) for network I/O operations, claims all hardware resources necessary to the network adapter in the registry, and allocates resources the driver needs to carry out network I/O operations.

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

Parameters

OpenErrorStatus
Points to a variable that MiniportInitialize sets to an NDIS_STATUS_XXX code specifying additional information about the error if MiniportInitialize will return NDIS_STATUS_OPEN_ERROR.
SelectedMediumIndex
Points to a variable in which MiniportInitialize sets the index of the MediumArray element that specifies the medium type the driver or its network adapter uses.
MediumArray
Specifies an array of NdisMediumXXX values from which MiniportInitialize selects one that its network adapter supports or that the driver supports as an interface to higher-level drivers.
MediumArraySize
Specifies the number of elements at MediumArray.
MiniportAdapterHandle
Specifies a handle identifying the miniport's network adapter, which is assigned by the NDIS library. MiniportInitialize should save this handle; it is a required parameter in subsequent calls to NdisXXX functions.
WrapperConfigurationContext
Specifies a handle used only during initialization for calls to NdisXXX configuration and initialization functions. For example, this handle is a required parameter to NdisOpenConfiguration and the NdisImmediateReadXXX and NdisImmediateWriteXXX functions.

Return Values

MiniportInitialize can return either of the following:

NDIS_STATUS_SUCCESS
MiniportInitialize configured and set up the network adapter, and it allocated all the resources the driver needs to carry out network I/O operations.
NDIS_STATUS_FAILURE
MiniportInitialize could not set up the network adapter to an operational state or could not allocate needed resources.

As alternatives to NDIS_STATUS_FAILURE, MiniportInitialize can return one of the following values, as appropriate, when it fails an initialization:

NDIS_STATUS_UNSUPPORTED_MEDIA
The values at MediumArray did not include a medium the driver (or its network adapter) can support.
NDIS_STATUS_ADAPTER_NOT_FOUND
MiniportInitialize did not recognize the network adapter either from its description in the registry, using NdisOpenConfiguration and NdisReadConfiguration, or by probing the network adapter on a particular I/O bus, using one of the NdisImmediateXXX or bus-type-specific NdisXXX configuration functions. This return can be propagated from the miniport's call to certain NdisXXX functions, such as NdisOpenConfiguration.
NDIS_STATUS_OPEN_ERROR
MiniportInitialize attempted to set up a network adapter but was unsuccessful.
NDIS_STATUS_NOT_ACCEPTED
MiniportInitialize could not get its network adapter to accept the configuration parameters that it got from the registry or from a bus-type-specific NdisXXX configuration function.
NDIS_STATUS_RESOURCES
Either MiniportInitialize could not allocate sufficient resources to carry out network I/O operations or an attempt to claim bus-relative hardware resources in the registry for the network adapter failed. This return can be propagated from the miniport's call to an NdisXXX function.

Comments

NDIS submits no requests to a driver until its initialization is completed.

In network adapter and intermediate drivers that call NdisMRegisterMiniport from their DriverEntry functions, NDIS calls MiniportInitialize in the context of NdisMRegisterMiniport. The underlying device driver must initialize before an intermediate driver that depends on that device calls NdisMRegisterMiniport.

For NDIS intermediate drivers that export both ProtocolXXX and MiniportXXX functions and that call NdisIMRegisterLayeredMiniport from their DriverEntry functions, NDIS calls MiniportInitialize in the context of NdisIMInitializeDeviceInstance. Such a driver's ProtocolBindAdapter function usually makes the call to NdisIMInitializeDeviceInstance.

In general, drivers of ISA network adapters call NdisOpenConfiguration and NdisReadConfiguration to get the bus-relative configuration parameters for their network adapters from the registry. Drivers for network adapters on other types of I/O buses usually call the appropriate bus-type-specific NdisReadXXX function. Drivers of PCMCIA network adapters should call NdisReadConfiguration to maintain their binary compatibilty across Microsoft operating systems that support Win32.

When it calls MiniportInitialize, the NDIS library supplies an array of supported media types, specified as system-defined NdisMediumXXX values. MiniportInitialize reads the array elements and provides the index of the medium type that NDIS should use with this driver for its network adapter. If the miniport is emulating a medium type, its emulation must be transparent to NDIS.

The MiniportInitialize function of a network adapter driver must call NdisMSetAttributes or NdisMSetAttributesEx before it calls any NdisXXX function, such as NdisMRegisterIoPortRange or NdisMMapIoSpace, that claims hardware resources in the registry for the network adapter. MiniportInitialize must call NdisMSetAttributes(Ex) before it attempts to allocate resources for DMA operations as well. If the network adapter is a busmaster, MiniportInitialize must call NdisMAllocateMapRegisters following its call to NdisMSetAttributes(Ex) and before it calls NdisMAllocateSharedMemory. If the network adapter is a slave, MiniportInitialize must call NdisMSetAttributes(Ex) before it calls NdisMRegisterDmaChannel.

Intermediate driver MiniportInitialize functions must call NdisMSetAttributesEx with NDIS_ATTRIBUTE_INTERMEDIATE_DRIVER set in the AttributeFlags argument. Setting this flag causes NDIS to treat every intermediate driver as a full-duplex miniport, thereby preventing rare but intermittant deadlocks when concurrent send and receive events occur. Consequently, every intermediate driver must be written as a full-duplex driver capable of handling concurrent sends and indications.

If the NDIS library's default four-second time-out interval on outstanding sends and requests is too short for the driver's network adapter, MiniportInitialize can call NdisMSetAttributesEx to extend the interval. Every intermediate driver also should call NdisMSetAttributesEx with NDIS_ATTRIBUTE_IGNORE_PACKET_TIMEOUT and NDIS_ATTRIBUTE_IGNORE_REQUEST_TIMEOUT set in the AttributeFlags so that NDIS will not attempt to time out sends and requests that NDIS holds queued to the intermediate driver.

The call to NdisMSetAttributes or NdisMSetAttributesEx includes a MiniportAdapterContext handle to a driver-allocated context area, in which the miniport maintains runtime state information. NDIS subsequently passes the supplied MiniportAdapterContext handle as an input parameter to other MiniportXXX functions.

Consequently, the MiniportInitialize function of an intermediate driver must call NdisMSetAttributesEx to set up the MiniportAdapterContext handle for a driver-allocated per-virtual-network adapter context area. Otherwise, NDIS would pass a NULL MiniportAdapterContext handle in its subsequent calls to the intermediate driver's other MiniportXXX functions.

After a call to NdisMRegisterIoPortRange, a miniport must call the NdisRawXXX functions with the PortOffset value returned by NdisMRegisterIoPortRange to communicate with its network adapter. The network adapter driver can no longer call the NdisImmediateRead/WritePortXXX functions. Similarly, after a call to NdisMMapIoSpace, a network adapter driver can no longer call NdisImmediateRead/WriteSharedMemory.

After it has claimed any bus-relative hardware resources for its network adapter in the registry, a miniport should no longer call any bus-type-specific NdisReadXXX function.

After MiniportInitialize calls NdisMRegisterInterrupt, the driver's MiniportISR function is called if the driver's network adapter generates an interrupt or if any other device with which the network adapter shares an IRQ interrupts. NDIS does not call the MiniportDisableInterrupt and MiniportEnableInterrupt functions, if the driver supplied them, during initialization, so it is such a miniport's responsibility to acknowledge and clear any interrupts its network adapter generates. If the network adapter shares an IRQ, the driver must first determine whether its network adapter generated the interrupt; if not, the miniport must return FALSE as soon as possible.

If the network adapter does not generate interrupts, MiniportInitialize should call NdisMInitializeTimer with a driver-supplied polling MiniportTimer function and a pointer to driver-allocated memory for a timer object. Drivers of network adapters that generate interrupts and intermediate drivers also can set up one or more MiniportTimer functions, each with its own timer object. MiniportInitialize usually calls NdisMSetPeriodicTimer to enable a polling MiniportTimer function; a driver calls NdisMSetTimer subsequently when conditions occur such that the driver's nonpolling MiniportTimer function should be run.

If the driver subsequently indicates receives with NdisMIndicateReceivePacket, the MiniportInitialize function should call NdisAllocatePacketPool and NdisAllocateBufferPool and save the handles returned by these NDIS functions. The packets that the driver subsequently indicates with NdisMIndicateReceivePacket must reference descriptors that were allocated with NdisAllocatePacket and NdisAllocateBuffer.

If driver functions other than MiniportISR or MiniportDisableInterrupt share resources, MiniportInitialize should call NdisAllocateSpinLock to set up any spin lock necessary to synchronize access to such a set of shared resources, particularly in a full-duplex driver or in a driver with a polling MiniportTimer function rather than an ISR. Resources shared by other driver functions with MiniportISR or MiniportDisableInterrupt, such as network adapter registers, are protected by the interrupt object set up when MiniportInitialize calls NdisMRegisterInterrupt and accessed subsequently by calling NdisMSynchronizeWithInterrupt.

Any network adapter driver's MiniportInitialize function should test the network adapter to be sure the hardware is configured correctly to carry out subsequent network I/O operations. If it must wait for state changes to occur in the hardware, MiniportInitialize can call NdisMSleep.

Unless the MiniportInitialize function of a network adapter driver will return an error status, it should call NdisMRegisterAdapterShutdownHandler with a driver-supplied MiniportShutdown function.

If MiniportInitialize will fail the initialization, it must release all resources it has already allocated before it returns control.

If MiniportInitialize returns NDIS_STATUS_OPEN_ERROR, NDIS can examine the value returned at OpenErrorStatus to obtain more information about the error.

When MiniportInitialize returns NDIS_STATUS_SUCCESS, the NDIS library calls the driver's MiniportQueryInformation function next.

Requirements

Runs on	Versions	Defined in	Include	Link to
Windows CE OS	2.0 and later	Ndis.h		Ndislib.lib

Note This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.

Last updated on Tuesday, July 13, 2004

MiniportInitialize

Additional resources