UID

title

description

old-location

tech.root

ms.date

keywords

ms.keywords

req.header

req.include-header

req.target-type

req.target-min-winverclnt

req.target-min-winversvr

req.kmdf-ver

req.umdf-ver

req.ddi-compliance

req.unicode-ansi

req.idl

req.max-support

req.namespace

req.assembly

req.type-library

req.lib

req.dll

req.irql

targetos

req.typenames

f1_keywords

topic_type

api_type

api_location

api_name

NC:ndis.MINIPORT_INITIALIZE

MINIPORT_INITIALIZE (ndis.h)

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

netvista\miniportinitializeex.htm

netvista

05/02/2018

MINIPORT_INITIALIZE callback function

MINIPORT_INITIALIZE, MINIPORT_INITIALIZE callback, MiniportInitializeEx, MiniportInitializeEx callback function [Network Drivers Starting with Windows Vista], miniport_functions_ref_d98605bf-4032-4cfe-8529-2d0bebc9e29e.xml, ndis/MiniportInitializeEx, netvista.miniportinitializeex

ndis.h

Ndis.h

Windows

Supported in NDIS 6.0 and later.

PASSIVE_LEVEL

Windows

MINIPORT_INITIALIZE

ndis/MINIPORT_INITIALIZE

APIRef

kbSyntax

UserDefined

Ndis.h

MINIPORT_INITIALIZE

MINIPORT_INITIALIZE callback function

-description

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

Note You must declare the function by using the MINIPORT_INITIALIZE type. For more information, see the following Examples section.

-parameters

-param NdisMiniportHandle [in]

An NDIS-supplied handle that identifies the miniport adapter that the miniport driver should initialize.

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

-param MiniportInitParameters [in]

A pointer to an NDIS_MINIPORT_INIT_PARAMETERS structure that defines the initialization parameters for the miniport adapter.

-returns

MiniportInitializeEx can return one of the following status values:

Return code	Description
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 computer to avoid such hardware resource conflicts.
NDIS_STATUS_FAILURE	MiniportInitializeEx failed for reasons other than those in the preceding 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 an 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:

Non-paged 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 subsequently 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 NIC 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 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 NIC generates an interrupt or if any other device with which the NIC shares an interrupt generates an interrupt. Note 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 NIC 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.

The driver must call NdisMSetMiniportAttributes and set the GeneralAttributes in the NDIS_MINIPORT_ADAPTER_ATTRIBUTES structure if it returns NDIS_STATUS_SUCCESS.

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.

Examples

To define a MiniportInitializeEx function, you must first provide a function declaration that identifies the type of function you're defining. Windows provides a set of function types for drivers. Declaring a function using the function types helps Code Analysis for Drivers, Static Driver Verifier (SDV), and other verification tools find errors, and it's a requirement for writing drivers for the Windows operating system.

For example, to define a MiniportInitializeEx function that is named "MyInitializeEx", use the MINIPORT_INITIALIZE type as shown in this code example:

MINIPORT_INITIALIZE MyInitializeEx;

Then, implement your function as follows:

_Use_decl_annotations_
NDIS_STATUS
 MyInitializeEx(
    NDIS_HANDLE  NdisMiniportHandle,
    NDIS_HANDLE  MiniportDriverContext,
    PNDIS_MINIPORT_INIT_PARAMETERS  MiniportInitParameters
    )
  {...}

The MINIPORT_INITIALIZE function type is defined in the Ndis.h header file. To more accurately identify errors when you run the code analysis tools, be sure to add the Use_decl_annotations annotation to your function definition. The Use_decl_annotations annotation ensures that the annotations that are applied to the MINIPORT_INITIALIZE function type in the header file are used. For more information about the requirements for function declarations, see Declaring Functions by Using Function Role Types for NDIS Drivers.