MiniportInitializeEx (Compact 2013)

Article
07/31/2017

3/26/2014

NDIS calls a miniport driver's MiniportInitializeEx function to initialize a miniport adapter for network I/O operations.

Syntax

NDIS_STATUS  MiniportInitializeEx(
    NDIS_HANDLE MiniportAdapterHandle,
    NDIS_HANDLE MiniportDriverContext,
    PNDIS_MINIPORT_INIT_PARAMETERS MiniportInitParameters
);

Parameters

MiniportAdapterHandle
[in] An NDIS-supplied handle that identifies the miniport adapter that the miniport driver should initialize.

MiniportDriverContext
[in] A handle to a driver-allocated context area where the driver maintains state and configuration information. The miniport driver passed this context area to the NdisMRegisterMiniportDriver function.

MiniportInitParameters
[in] A pointer to an NDIS_MINIPORT_INIT_PARAMETERS structure that defines the initialization parameters for the miniport adapter.

Return Value

MiniportInitializeEx can return one of the following status values:

NDIS_STATUS_SUCCESS
MiniportInitializeEx configured and set up the miniport adapter, and allocated all the resources that the driver must have to perform network I/O operations.

NDIS_STATUS_NOT_ACCEPTED
MiniportInitializeEx could not get the miniport adapter to accept the configuration parameters that MiniportInitializeEx obtained from the registry.

NDIS_STATUS_RESOURCES
MiniportInitializeEx could not allocate resources to perform network I/O operations. MiniportInitializeEx should call the NdisWriteErrorLogEntry function to identify the resource conflict (for example, 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 device to avoid such hardware resource conflicts.

NDIS_STATUS_FAILURE
MiniportInitializeEx failed for reasons other than those in the previous list. The driver should call NdisWriteErrorLogEntry with parameters that specify the reason for the failure.

Remarks

NDIS calls MiniportInitializeEx as part of a system PnP operation. Drivers specify the MiniportInitializeEx entry point by calling the NdisMRegisterMiniportDriver function from the DriverEntry routine. NDIS can call MiniportInitializeEx after DriverEntry returns. For more information, see DriverEntry of NDIS Miniport Drivers.

For NDIS intermediate drivers, NDIS can call MiniportInitializeEx in the context of the NdisIMInitializeDeviceInstanceEx function or after it returns. Such a driver's ProtocolBindAdapterEx function usually calls NdisIMInitializeDeviceInstanceEx.

Drivers can register as a combined miniport driver and intermediate driver (see NdisMRegisterMiniportDriver). Such a miniport-intermediate driver functions similarly to an intermediate driver layered over a physical miniport driver. For each virtual or physical device instance of a miniport-intermediate driver, if the IMMiniport registry key is set to DWORD:0x0000001, NDIS calls the MiniportInitializeEx function that the driver registered for the virtual device. Otherwise, NDIS calls the driver's MiniportInitializeEx function that the driver registered for the physical device.

Until MiniportInitializeEx returns, NDIS submits no requests for the miniport adapter being initialized. The miniport adapter is in the initializing state.

To obtain configuration information for the miniport adapter, a driver calls the NdisOpenConfigurationEx and NdisReadConfiguration functions. The driver can call the NdisMGetBusData function to obtain bus-specific information.

Miniport drivers must call the NdisMSetMiniportAttributes function and provide a NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES structure which contains the following attributes:

A handle to a driver-allocated context area.
Appropriate attributes flags.
The time-out interval for calling its MiniportCheckForHangEx function.
The interface type.

The miniport driver passes NdisMSetMiniportAttributes a handle at the MiniportAdapterContext member of NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES. The driver maintains state information for the specified miniport adapter in this context area. NDIS passes this handle as an input parameter to other MiniportXxx functions.

Miniport drivers must set the attributes in the NDIS_MINIPORT_ADAPTER_GENERAL_ATTRIBUTES structure after they set the registration attributes in the NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES structure and before they set any additional attributes.

MiniportInitializeEx can also allocate resources such as the following:

Nonpaged pool memory
NET_BUFFER and NET_BUFFER_LIST structure pools
Spin locks
Timers
IO ports
DMA
Shared memory
Interrupts

If the driver indicates receives with the NdisMIndicateReceiveNetBufferLists function, the MiniportInitializeEx function should call the NdisAllocateNetBufferListPool and NdisAllocateNetBufferPool functions and save the handles returned by these NDIS functions. Typically, the network data that the driver later indicates with NdisMIndicateReceiveNetBufferLists references structures that were allocated with the NdisAllocateNetBufferAndNetBufferList function. A driver can also use structures that were allocated with the NdisAllocateNetBuffer, and NdisAllocateNetBufferList functions.

If driver functions, other than the MiniportInterrupt function, share resources, MiniportInitializeEx should call the NdisAllocateSpinLock function to set up any spin locks necessary to synchronize access to such shared resources. Resources that other driver functions share with MiniportInterrupt, such as network adapter registers, are protected by the interrupt object that the driver set up with the NdisMRegisterInterruptEx function. Driver functions access these resources by calling the NdisMSynchronizeWithInterruptEx function.

MiniportInitializeEx can call the NdisAllocateTimerObject function with a driver-supplied NetTimerCallback function and a pointer to driver-allocated memory for a timer object. Drivers can set up multiple NetTimerCallback functions, each with its own timer object. A driver can call the NdisSetTimerObject function to enable a periodic NetTimerCallback function. A driver can also call the NdisSetTimerObject function to enable a one-time NetTimerCallback function.

MiniportInitializeEx must call the NdisMSetMiniportAttributes function before it calls any NdisMXxx function, such as the NdisMRegisterIoPortRange or NdisMMapIoSpace functions, that claims hardware resources for the miniport adapter. MiniportInitializeEx must call NdisMSetMiniportAttributes before it tries to allocate resources for DMA operations.

If the device supports bus-master DMA, MiniportInitializeEx must call the NdisMRegisterScatterGatherDma function after it calls NdisMSetMiniportAttributes and before it calls the NdisMAllocateSharedMemory function. If the device supports subordinate-mode DMA, MiniportInitializeEx must call NdisMSetMiniportAttributes before it calls the NdisMRegisterDmaChannel function.

After MiniportInitializeEx calls the NdisMRegisterInterruptEx function, NDIS can call the driver's MiniportInterrupt function. NDIS calls MiniportInterrupt if the network adapter generates an interrupt or if any other device with which the network adapter shares an interrupt generates an interrupt. Be aware that a miniport driver can get an interrupt as soon as it calls NdisMRegisterInterruptEx and keeps getting interrupts until its call to the NdisMDeregisterInterruptEx function returns.

MiniportInitializeEx should test the network adapter to make sure that the hardware is configured correctly. If the driver must wait for state changes to occur in the hardware, MiniportInitializeEx can use the NdisWaitEvent function or the NdisMSleep function.

After MiniportInitializeEx returns successfully, the miniport adapter is in the Paused state. NDIS can call the MiniportRestart function to transition the miniport adapter to the Running state.

If MiniportInitializeEx returns NDIS_STATUS_SUCCESS, the driver should release all the resources for the miniport adapter in the MiniportHaltEx function.

If MiniportInitializeEx failed, MiniportInitializeEx must release all resources that it allocated before it returns and the miniport adapter returns to the Halted state.

NDIS calls MiniportInitializeEx at IRQL = PASSIVE_LEVEL.

MiniportInitializeEx (Compact 2013)

Syntax

Parameters

Return Value

Remarks

See Also

Reference

Additional resources