MINIPORT_INITIALIZE回调函数 (ndis.h)

项目
09/02/2023

NDIS 调用微型端口驱动程序的 MiniportInitializeEx 函数来初始化用于网络 I/O 操作的微型端口适配器。

注意必须使用 MINIPORT_INITIALIZE 类型声明函数。有关详细信息，请参阅以下示例部分。

语法

MINIPORT_INITIALIZE MiniportInitialize;

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

参数

[in] NdisMiniportHandle

NDIS 提供的句柄，用于标识微型端口驱动程序应初始化的微型端口适配器。

[in] MiniportDriverContext

驱动程序分配的上下文区域的句柄，驱动程序在其中维护状态和配置信息。微型端口驱动程序将此上下文区域传递给 NdisMRegisterMiniportDriver 函数。

[in] MiniportInitParameters

指向的指针 NDIS_MINIPORT_INIT_PARAMETERS 结构，用于定义微型端口适配器的初始化参数。

返回值

MiniportInitializeEx 可以返回以下状态值之一：

返回代码	说明
NDIS_STATUS_SUCCESS	MiniportInitializeEx 配置并设置微型端口适配器，并分配了驱动程序执行网络 I/O 操作所需的所有资源。
NDIS_STATUS_NOT_ACCEPTED	MiniportInitializeEx 无法获取微型端口适配器以接受 MiniportInitializeEx 从注册表获取的配置参数。
NDIS_STATUS_RESOURCES	MiniportInitializeEx 无法分配资源来执行网络 I/O 操作。 MiniportInitializeEx 应调用 NdisWriteErrorLogEntry 函数，以确定资源冲突 (，例如 I/O 端口范围、中断矢量、设备内存范围，视情况而定) 。提供错误日志记录会向用户或系统管理员提供可用于重新配置计算机以避免此类硬件资源冲突的信息。
NDIS_STATUS_FAILURE	MiniportInitializeEx 由于上述列表中的原因以外的原因而失败。驱动程序应使用指定失败原因的参数调用 NdisWriteErrorLogEntry 。

注解

NDIS 调用 MiniportInitializeEx 作为系统 PnP 操作的一部分。驱动程序通过调用指定 MiniportInitializeEx 入口点DriverEntry 例程中的 NdisMRegisterMiniportDriver 函数。 NDIS 可以在 DriverEntry 返回后调用 MiniportInitializeEx。有关详细信息，请参阅 NDIS 微型端口驱动程序的 DriverEntry。

对于 NDIS 中间驱动程序，NDIS 可以在的上下文中调用 MiniportInitializeEx NdisIMInitializeDeviceInstanceEx 函数或返回后。此类驱动程序的 ProtocolBindAdapterEx 函数通常调用 NdisIMInitializeDeviceInstanceEx。

驱动程序可以注册为组合微型端口驱动程序和中间驱动程序 (请参阅 NdisMRegisterMiniportDriver) 。此类微型端口-中间驱动程序的功能类似于在物理微型端口驱动程序上分层的中间驱动程序。对于微型端口中间驱动程序的每个虚拟或物理设备实例，如果 IMMiniport 注册表项设置为 DWORD：0x0000001，NDIS 将调用驱动程序为虚拟设备注册的 MiniportInitializeEx 函数。否则，NDIS 会调用驱动程序为物理设备注册的驱动程序的 MiniportInitializeEx 函数。

在 MiniportInitializeEx 返回之前，NDIS 不会提交任何要初始化的微型端口适配器的请求。微型端口适配器处于 初始化 状态。

若要获取微型端口适配器的配置信息，驱动程序会调用 NdisOpenConfigurationEx 和 NdisReadConfiguration 函数。驱动程序可以调用 NdisMGetBusData 函数来获取特定于总线的信息。

微型端口驱动程序必须调用 NdisMSetMiniportAttributes 函数，并提供 NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES 包含以下属性的结构：

驱动程序分配的上下文区域的句柄。
适当的属性标志。
调用其的超时间隔 MiniportCheckForHangEx 函数。
接口类型。

微型端口驱动程序传递 NdisMSetMiniportAttributes NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES 的 MiniportAdapterContext 成员的句柄。驱动程序维护此上下文区域中指定微型端口适配器的状态信息。 NDIS 将此句柄作为输入参数传递给其他 MiniportXxx 函数。

微型端口驱动程序必须在在 NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES结构中设置注册属性之后以及设置任何其他属性之前，NDIS_MINIPORT_ADAPTER_GENERAL_ATTRIBUTES结构。

MiniportInitializeEx 还可以分配如下所示的资源：

非分页池内存
NET_BUFFER 和 NET_BUFFER_LIST 结构池
旋转锁
计时器
IO 端口
DMA
共享内存
中断

如果驱动程序指示接收了 NdisMIndicateReceiveNetBufferLists 函数， MiniportInitializeEx 函数应调用 NdisAllocateNetBufferListPool 和 NdisAllocateNetBufferPool 函数并保存这些 NDIS 函数返回的句柄。通常，驱动程序随后使用 NdisMIndicateReceiveNetBufferLists 指示的网络数据引用随分配的结构 NdisAllocateNetBufferAndNetBufferList 函数。驱动程序还可以使用通过 NdisAllocateNetBuffer 分配的结构，以及 NdisAllocateNetBufferList 函数。

如果驱动程序函数（除 MiniportInterrupt 函数之外）共享资源， MiniportInitializeEx 应调用 NdisAllocateSpinLock 函数来设置同步对此类共享资源的访问所需的任何旋转锁。其他驱动程序函数与 MiniportInterrupt 共享的资源（例如 NIC 寄存器）受驱动程序使用设置的中断对象保护 NdisMRegisterInterruptEx 函数。驱动程序函数通过调用来访问这些资源 NdisMSynchronizeWithInterruptEx 函数。

MiniportInitializeEx 可以使用驱动程序提供的 NetTimerCallback 函数和指向计时器对象的驱动程序分配的内存的指针调用 NdisAllocateTimerObject 函数。驱动程序可以设置多个 NetTimerCallback 函数，每个函数都有自己的计时器对象。驱动程序可以调用 NdisSetTimerObject 函数来启用定期 NetTimerCallback 函数。驱动程序还可以调用 NdisSetTimerObject 函数来启用一次性 NetTimerCallback 函数。

MiniportInitializeEx 必须调用 NdisMSetMiniportAttributes 函数在调用任何 NdisMXxx 函数（如 NdisMRegisterIoPortRange 或 NdisMMapIoSpace 函数）之前，该函数会声明微型端口适配器的硬件资源。 MiniportInitializeEx 必须在尝试为 DMA 操作分配资源之前调用 NdisMSetMiniportAttributes 。

如果设备支持总线主 DMA，MiniportInitializeEx 必须调用 NdisMRegisterScatterGatherDma 函数在调用 NdisMSetMiniportAttributes 之后和调用之前 NdisMAllocateSharedMemory 函数。如果设备支持从属 DMA， 则 MiniportInitializeEx 必须先调用 NdisMSetMiniportAttributes ，然后才能调用 NdisMRegisterDmaChannel 函数。

在 MiniportInitializeEx 调用之后 NdisMRegisterInterruptEx 函数，NDIS 可以调用驱动程序的 MiniportInterrupt 函数。如果 NIC 生成中断，或者如果与 NIC 共享中断的任何其他设备生成中断，则 NDIS 调用 MiniportInterrupt 。请注意，微型端口驱动程序可以在调用 NdisMRegisterInterruptEx 后立即收到中断，并一直获得中断，直到调用 NdisMDeregisterInterruptEx 函数返回。

MiniportInitializeEx 应测试 NIC，以确保正确配置硬件。如果驱动程序必须等待硬件中发生状态更改， MiniportInitializeEx 可以使用 NdisWaitEvent 函数或 NdisMSleep 函数。

在 MiniportInitializeEx 成功返回后，微型端口适配器将处于 Paused 状态。 NDIS 可以调用 MiniportRestart 函数，将微型端口适配器转换为 “正在运行” 状态。

如果 MiniportInitializeEx 返回NDIS_STATUS_SUCCESS，驱动程序应在 MiniportHaltEx 函数中释放微型端口适配器的所有资源。

如果驱动程序返回NDIS_STATUS_SUCCESS，驱动程序必须调用 NdisMSetMiniportAttributes 并在NDIS_MINIPORT_ADAPTER_ATTRIBUTES结构中设置 GeneralAttributes。

如果 MiniportInitializeEx 失败， MiniportInitializeEx 必须释放它分配的所有资源，然后才能返回，微型端口适配器将返回到 “已停止” 状态。

NDIS 在 IRQL = PASSIVE_LEVEL 调用 MiniportInitializeEx 。

示例

若要定义 MiniportInitializeEx 函数，必须首先提供一个函数声明，用于标识要定义的函数类型。 Windows 为驱动程序提供一组函数类型。使用函数类型声明函数可帮助驱动程序的代码分析、静态驱动程序验证程序 (SDV) 和其他验证工具查找错误，并且这是编写 Windows 操作系统驱动程序的要求。

例如，若要定义名为“ MyInitializeEx ”的 MiniportInitializeEx 函数，请使用 MINIPORT_INITIALIZE 类型，如以下代码示例所示：

MINIPORT_INITIALIZE MyInitializeEx;

然后，按如下所示实现函数：

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

MINIPORT_INITIALIZE函数类型在 Ndis.h 头文件中定义。若要在运行代码分析工具时更准确地识别错误，请务必将 Use_decl_annotations 注释添加到函数定义。 Use_decl_annotations批注可确保使用应用于头文件中MINIPORT_INITIALIZE函数类型的注释。有关函数声明要求的详细信息，请参阅使用 NDIS 驱动程序的函数角色类型声明函数。

有关 Use_decl_annotations的信息，请参阅批注函数行为。