MiniportInitialize (Compact 2013)

Articolo
07/31/2017

3/26/2014

This function 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 must perform network I/O operations.

Syntax

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

Parameters

OpenErrorStatus
[out] 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
[out] 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
[in] 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
[in] Specifies the number of elements at MediumArray.

MiniportAdapterHandle
[in] Specifies a handle identifying the miniport's network adapter. This 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 that is 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

Value	Description
NDIS_STATUS_SUCCESS	Configured and set up the network adapter, and it allocated all the resources the driver must perform network I/O operations.
NDIS_STATUS_FAILURE	Could not set up the network adapter to an operational state or could not allocate needed resources.
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	Did not recognize the network adapter either from its description in the registry, by using NdisOpenConfiguration and NdisReadConfiguration, or by probing the network adapter on a particular I/O bus, by 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	Tried to set up a network adapter but was unsuccessful
NDIS_STATUS_NOT_ACCEPTED	Could not make its network adapter to accept the configuration parameters that it obtained from the registry or from a bus-type-specific NdisXXX configuration function.
NDIS_STATUS_RESOURCES	Could not allocate sufficient resources to perform network I/O operations or an try 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.

Remarks

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.

Generally, drivers of ISA network adapters call NdisOpenConfiguration and NdisReadConfiguration to obtain the bus-relative configuration parameters for their network adapters from the registry. Drivers for network adapters on other kinds of I/O buses usually call the appropriate bus-type-specific NdisReadXXX function.

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.

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. This prevents rare but intermittent deadlocks when concurrent send and receive events occur. Therefore, every intermediate driver must be written as a full-duplex driver that can handle 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 should also call NdisMSetAttributesEx with NDIS_ATTRIBUTE_IGNORE_PACKET_TIMEOUT and NDIS_ATTRIBUTE_IGNORE_REQUEST_TIMEOUT set in the AttributeFlags so that NDIS will not try 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.

Therefore, 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. Therefore, 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 can also 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 so that the driver's non-polling 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 that has a polling MiniportTimer function instead of an ISR. Resources shared by other driver functions with MiniportISR or the interrupt object set up when MiniportInitialize calls NdisMRegisterInterrupt and accessed subsequently by calling NdisMSynchronizeWithInterrupt protects MiniportDisableInterrupt, such as network adapter registers.

Any network adapter driver's MiniportInitialize function should test the network adapter to make sure that the hardware is configured correctly to perform 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

Header

externs.h

Condividi tramite

MiniportInitialize (Compact 2013)

Syntax

Parameters

Return Value

Remarks

Requirements

See Also

Reference

Risorse aggiuntive