MiniportInitialize

Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

MiniportInitializeis 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 MiniportInitializesets to an NDIS_STATUS_ XXXcode specifying additional information about the error if MiniportInitializewill return NDIS_STATUS_OPEN_ERROR.

SelectedMediumIndex

Points to a variable in which MiniportInitializesets the index of the MediumArrayelement that specifies the medium type the driver or its network adapter uses.

MediumArray

Specifies an array of NdisMedium XXXvalues from which MiniportInitializeselects 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. MiniportInitializeshould save this handle; it is a required parameter in subsequent calls to Ndis XXXfunctions.

WrapperConfigurationContext

Specifies a handle used only during initialization for calls to Ndis XXXconfiguration and initialization functions. For example, this handle is a required parameter to NdisOpenConfigurationand the NdisImmediateRead XXXand NdisImmediateWrite XXXfunctions.

Return Values

MiniportInitializecan return either of the following:

NDIS_STATUS_SUCCESS

MiniportInitializeconfigured 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

MiniportInitializecould not set up the network adapter to an operational state or could not allocate needed resources.

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

NDIS_STATUS_UNSUPPORTED_MEDIA

The values at MediumArraydid notinclude a medium the driver (or its network adapter) can support.

NDIS_STATUS_ADAPTER_NOT_FOUND

MiniportInitializedid not recognize the network adapter either from its description in the registry, using NdisOpenConfigurationand NdisReadConfiguration, or by probing the network adapter on a particular I/O bus, using one of the NdisImmediate XXXor bus-type-specific Ndis XXXconfiguration functions. This return can be propagated from the miniport's call to certain Ndis XXXfunctions, such as NdisOpenConfiguration.

NDIS_STATUS_OPEN_ERROR

MiniportInitializeattempted to set up a network adapter but was unsuccessful.

NDIS_STATUS_NOT_ACCEPTED

MiniportInitializecould not get its network adapter to accept the configuration parameters that it got from the registry or from a bus-type-specific Ndis XXXconfiguration function.

NDIS_STATUS_RESOURCES

Either MiniportInitializecould 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 Ndis XXXfunction.

Comments

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

In network adapter and intermediate drivers that call NdisMRegisterMiniportfrom their DriverEntryfunctions, NDIS calls MiniportInitializein 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 ProtocolXXXand Miniport XXXfunctions and that call NdisIMRegisterLayeredMiniportfrom their DriverEntryfunctions, NDIS calls MiniportInitializein the context of NdisIMInitializeDeviceInstance. Such a driver's ProtocolBindAdapterfunction usually makes the call to NdisIMInitializeDeviceInstance.

In general, drivers of ISA network adapters call NdisOpenConfigurationand NdisReadConfigurationto 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 NdisRead XXXfunction. Drivers of PCMCIA network adapters should call NdisReadConfigurationto 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 NdisMedium XXXvalues. MiniportInitializereads 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 MiniportInitializefunction of a network adapter driver must call NdisMSetAttributesor NdisMSetAttributesExbefore it calls any Ndis XXXfunction, such as NdisMRegisterIoPortRangeor NdisMMapIoSpace, that claims hardware resources in the registry for the network adapter. MiniportInitializemust call NdisMSetAttributes(Ex)before it attempts to allocate resources for DMA operations as well. If the network adapter is a busmaster, MiniportInitializemust call NdisMAllocateMapRegistersfollowing its call to NdisMSetAttributes(Ex)and before it calls NdisMAllocateSharedMemory. If the network adapter is a subordinate device, MiniportInitializemust call NdisMSetAttributes(Ex)before it calls NdisMRegisterDmaChannel.

Intermediate driver MiniportInitializefunctions must call NdisMSetAttributesExwith NDIS_ATTRIBUTE_INTERMEDIATE_DRIVER set in the AttributeFlagsargument. 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, MiniportInitializecan call NdisMSetAttributesExto extend the interval. Every intermediate driver also should call NdisMSetAttributesExwith NDIS_ATTRIBUTE_IGNORE_PACKET_TIMEOUT and NDIS_ATTRIBUTE_IGNORE_REQUEST_TIMEOUT set in the AttributeFlagsso that NDIS will not attempt to time out sends and requests that NDIS holds queued to the intermediate driver.

The call to NdisMSetAttributesor NdisMSetAttributesExincludes a MiniportAdapterContexthandle to a driver-allocated context area, in which the miniport maintains runtime state information. NDIS subsequently passes the supplied MiniportAdapterContexthandle as an input parameter to other Miniport XXXfunctions.

Consequently, the MiniportInitializefunction of an intermediate driver must call NdisMSetAttributesExto set up the MiniportAdapterContexthandle for a driver-allocated per-virtual-network adapter context area. Otherwise, NDIS would pass a NULL MiniportAdapterContexthandle in its subsequent calls to the intermediate driver's other Miniport XXXfunctions.

After a call to NdisMRegisterIoPortRange, a miniport must call the NdisRaw XXXfunctions with the PortOffsetvalue returned by NdisMRegisterIoPortRangeto communicate with its network adapter. The network adapter driver can no longer call the NdisImmediateRead/WritePort XXXfunctions. 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 NdisRead XXXfunction.

After MiniportInitializecalls NdisMRegisterInterrupt, the driver's MiniportISRfunction 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 MiniportDisableInterruptand MiniportEnableInterruptfunctions, 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, MiniportInitializeshould call NdisMInitializeTimerwith a driver-supplied polling MiniportTimerfunction 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 MiniportTimerfunctions, each with its own timer object. MiniportInitializeusually calls NdisMSetPeriodicTimerto enable a polling MiniportTimerfunction; a driver calls NdisMSetTimersubsequently when conditions occur such that the driver's nonpolling MiniportTimerfunction should be run.

If the driver subsequently indicates receives with NdisMIndicateReceivePacket, the MiniportInitializefunction should call NdisAllocatePacketPooland NdisAllocateBufferPooland save the handles returned by these NDIS functions. The packets that the driver subsequently indicates with NdisMIndicateReceivePacketmust reference descriptors that were allocated with NdisAllocatePacketand NdisAllocateBuffer.

If driver functions other than MiniportISRor MiniportDisableInterruptshare resources, MiniportInitializeshould call NdisAllocateSpinLockto 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 MiniportTimerfunction rather than an ISR. Resources shared by other driver functions with MiniportISRor MiniportDisableInterrupt, such as network adapter registers, are protected by the interrupt object set up when MiniportInitializecalls NdisMRegisterInterruptand accessed subsequently by calling NdisMSynchronizeWithInterrupt.

Any network adapter driver's MiniportInitializefunction 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, MiniportInitializecan call NdisMSleep.

Unless the MiniportInitializefunction of a network adapter driver will return an error status, it should call NdisMRegisterAdapterShutdownHandlerwith a driver-supplied MiniportShutdownfunction.

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

If MiniportInitializereturns NDIS_STATUS_OPEN_ERROR, NDIS can examine the value returned at OpenErrorStatusto obtain more information about the error.

When MiniportInitializereturns NDIS_STATUS_SUCCESS, the NDIS library calls the driver's MiniportQueryInformationfunction 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.