MINIPORT_INITIALIZE callback function (ndis.h)

Artikel
11/24/2022

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.

Syntax

MINIPORT_INITIALIZE MiniportInitialize;

NDIS_STATUS MiniportInitialize(
  [in] NDIS_HANDLE NdisMiniportHandle,
  [in] NDIS_HANDLE MiniportDriverContext,
  [in] PNDIS_MINIPORT_INIT_PARAMETERS MiniportInitParameters
)
{...}

Parameters

[in] NdisMiniportHandle

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

[in] MiniportDriverContext

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.

[in] MiniportInitParameters

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:

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.

For information about Use_decl_annotations, see Annotating Function Behavior.

Requirements

Requirement	Value
Minimum supported client	Supported in NDIS 6.0 and later.
Target Platform	Windows
Header	ndis.h (include Ndis.h)
IRQL	PASSIVE_LEVEL

Delen via