MiniportInitialize

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
);

MiniportInitialize 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.

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 NIC uses.

MediumArray

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

Specifies the number of elements at MediumArray.

MiniportAdapterHandle

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

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:

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 could not set up the NIC to an operational state or could not allocate needed resources. MiniportInitialize called NdisWriteErrorLogEntry with parameters specifying the configuration or resource allocation failure.

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 NIC) can support.

NDIS_STATUS_ADAPTER_NOT_FOUND

MiniportInitialize did not recognize the NIC either from its description in the registry, using NdisOpenConfiguration and NdisReadConfiguration, or by probing the NIC 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 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 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 NIC failed. This return can be propagated from the miniport's call to an NdisXxx function.

If another device has already claimed a resource in the registry that its NIC needs, MiniportInitialize also 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.

Comments

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

In NIC 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.

For NIC drivers, NDIS must find at least the NIC's I/O bus interface type and, if it is not an ISA bus, the bus number already installed in the registry by the driver's installation script. For more information about installing Windows NT drivers, see the Programmer's Guide.

In general, drivers of ISA NICs call NdisOpenConfiguration and NdisReadConfiguration to get the bus-relative configuration parameters for their NICs from the registry. Drivers for NICs on other types of I/O buses usually call the appropriate bus-type-specific NdisReadXxx function. Drivers of PCMCIA NICs should call NdisMQueryAdapterResources 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 NIC. If the miniport 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 NdisRegisterIoPortRange or NdisMMapIoSpace, that claims hardware resources in the registry for the NIC. MiniportInitialize must call NdisMSetAttributes(Ex) before it attempts to allocate resources for DMA operations as well. If the NIC is a busmaster, MiniportInitialize must call NdisMAllocateMapRegisters following its call to NdisMSetAttributes(Ex) and before it calls NdisMAllocateSharedMemory. If the NIC 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 NIC, 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-NIC 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 NIC. The NIC driver can no longer call the NdisImmediateRead/WritePortXxx functions. Similarly, after a call to NdisMMapIoSpace, a NIC driver can no longer call NdisImmediateRead/WriteSharedMemory.

After it has claimed any bus-relative hardware resources for its NIC 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 NIC generates an interrupt or if any other device with which the NIC 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 NIC generates. If the NIC shares an IRQ, the driver must first determine whether its NIC generated the interrupt; if not, the miniport must return FALSE as soon as possible.

If the NIC 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 NICs 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 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.

Unless the MiniportInitialize function of a NIC 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.

By default, MiniportInitialize runs at IRQL PASSIVE_LEVEL and in the context of a system thread.