W_INITIALIZE_HANDLER callback function

Article
06/19/2017

Note NDIS 5. x has been deprecated and is superseded by NDIS 6. x. For new NDIS driver development, see Network Drivers Starting with Windows Vista. For information about porting NDIS 5. x drivers to NDIS 6. x, see Porting NDIS 5.x Drivers to NDIS 6.0.

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

Syntax

W_INITIALIZE_HANDLER MiniportInitialize;

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 [out]
Pointer 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 [out]
Pointer to a variable in which MiniportInitialize sets the index of the MediumArray element that specifies the medium type the driver or its NIC uses.
MediumArray [in]
Specifies an array of NdisMediumXxx values from which MiniportInitialize selects one that its NIC supports or that the driver supports as an interface to higher-level drivers.
MediumArraySize [in]
Specifies the number of elements at MediumArray.
MiniportAdapterHandle [in]
Specifies a handle identifying the miniport's NIC, which is assigned by the NDIS library. MiniportInitialize should save this handle; it is a required parameter in subsequent calls to NdisXxx functions.
WrapperConfigurationContext [in]
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 value

MiniportInitialize can return either of the following:

Return code	Description
NDIS_STATUS_SUCCESS	MiniportInitialize configured and set up the NIC, and it allocated all the resources the driver needs to carry out network I/O operations.
NDIS_STATUS_FAILURE	MiniportInitialize failed for reasons other than those provided in the following list. MiniportInitialize called NdisWriteErrorLogEntry with parameters specifying the configuration or resource allocation failure.

MiniportInitialize can return one of the following values, if appropriate, when it fails an initialization:

Return code	Description
NDIS_STATUS_UNSUPPORTED_MEDIA	The values at the location specified in the MediumArray parameter did not include a medium the driver (or its NIC) can support.
NDIS_STATUS_OPEN_ERROR	MiniportInitialize attempted to set up a NIC but was unsuccessful.
NDIS_STATUS_NOT_ACCEPTED	MiniportInitialize could not get its NIC to accept the configuration parameters that it got from the registry.
NDIS_STATUS_RESOURCES	MiniportInitialize could not allocate resources to carry out network I/O operations. MiniportInitialize should call NdisWriteErrorLogEntry to record the particular resource conflict (I/O port range, interrupt vector, device memory range, as appropriate). Supplying an error log record gives the user or system administrator information that can be used to reconfigure the machine to avoid such hardware resource conflicts.

Remarks

NDIS calls MiniportInitialize as part of a system PnP operation. Miniport drivers call NdisMRegisterMiniport from their DriverEntry functions to register their MiniportXxx functions. NDIS can call MiniportInitialize after NdisMRegisterMiniport returns.

An NDIS intermediate driver's ProtocolBindAdapter function usually calls NdisIMInitializeDeviceInstance. NDIS can call MiniportInitialize in the context of NdisIMInitializeDeviceInstance.

NDIS submits no requests to a driver until MiniportInitialize returns.

A miniport driver obtains advanced configuration information for its NIC by calling NdisOpenConfiguration and NdisReadConfiguration. The NIC driver obtains bus-specific information by calling the appropriate bus-specific function:

Bus	Function for Obtaining Bus-Specific Information
PCI	NdisReadPciSlotInformation
PC Card	NdisReadPcmciaAttributeMemory

Miniport drivers obtain information about the hardware resources for a NIC by calling NdisMQueryAdapterResources.

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 NIC. If the miniport driver is emulating a medium type, its emulation must be transparent to NDIS.

The MiniportInitialize function of a NIC driver must call NdisMSetAttributes or NdisMSetAttributesEx before it calls any NdisXxx function, such as NdisMRegisterIoPortRange or NdisMMapIoSpace, that claims hardware resources. MiniportInitialize must call NdisMSetAttributes(Ex) before it attempts to allocate resources for DMA operations as well. If the NIC is a bus master, MiniportInitialize must call NdisMAllocateMapRegisters or NdisMInitializeScatterGatherDma following its call to NdisMSetAttributesEx and before it calls NdisMAllocateSharedMemory. If the NIC is a subordinate, MiniportInitialize must call NdisMSetAttributesEx before it calls NdisMRegisterDmaChannel.

Intermediate driver MiniportInitialize functions must call NdisMSetAttributesEx with NDIS_ATTRIBUTE_INTERMEDIATE_DRIVER set in the AttributeFlags argument. 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.

An intermediate driver must operate as a deserialized driver and must register itself as such by setting the NDIS_ATTRIBUTE_DESERIALIZE flag in the AttributeFlags parameter passed to NdisMSetAttributesEx. A deserialized driver serializes the operation of its MiniportXxx functions and queues internally all incoming send packets rather than relying on NDIS to maintain its send queue.

An intermediate driver must also set the NDIS_ATTRIBUTE_NO_HALT_ON_SUSPEND flag in the AttributeFlags parameter passed to NdisMSetAttributesEx. Setting this flag prevents NDIS from halting the driver before the underlying miniport driver transitions to a low-power state.

If the NDIS library's default two-second time-out interval for calling MiniportCheckForHang is too short for the driver's NIC, MiniportInitialize can call NdisMSetAttributesEx to extend the interval.

The call to NdisMSetAttributes or NdisMSetAttributesEx includes a MiniportAdapterContext handle to a driver-allocated context area, in which the miniport driver maintains run-time 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-NIC context area.

After MiniportInitialize calls NdisMRegisterInterrupt, the driver's MiniportISR function is called if the driver's NIC generates an interrupt or if any other device, with which the NIC shares an interrupt, generates an interrupt. If the NIC shares interrupts, the driver must first determine whether its NIC generated the interrupt; if it did not, the miniport driver must return FALSE as soon as possible. Note that a miniport driver can get an interrupt as soon as it calls NdisMRegisterInterrupt and keeps getting interrupts until its call to NdisMDeregisterInterrupt returns.

MiniportInitialize can call NdisMInitializeTimer with a driver-supplied MiniportTimer function and a pointer to driver-allocated memory for a timer object. Drivers can set up one or more MiniportTimer functions, each with its own timer object. A driver can call NdisMSetPeriodicTimer to enable a periodic MiniportTimer function. A driver can call NdisMSetTimer to set a nonperiodic MiniportTimer function.

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. Resources shared by other driver functions with MiniportISR or MiniportDisableInterrupt, such as NIC registers, are protected by the interrupt object set up when MiniportInitialize calls NdisMRegisterInterrupt and accessed subsequently by calling NdisMSynchronizeWithInterrupt.

Any NIC driver's MiniportInitialize function should test the NIC 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 either can call NdisWaitEvent with the pointer to a driver-initialized event object, or it can call NdisMSleep.

For NDIS version 5.0 and earlier versions, unless the MiniportInitialize function of a NIC driver will return an error status, it should call NdisMRegisterAdapterShutdownHandler with a driver-supplied MiniportShutdown function. For NDIS version 5.1 and later versions, drivers supply a MiniportShutdown function in the characteristics structure that they pass to NdisMRegisterMiniport.

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

Target platform	Desktop
Version	Not supported for NDIS 6.0 drivers in Windows Vista. Use MiniportInitializeEx instead. Supported for NDIS 5.1 drivers in Windows Vista and Microsoft Windows XP.
Header	Ndis.h (include Ndis.h)
IRQL	PASSIVE_LEVEL