MINIPORT_INITIALIZE回调函数 (ndis.h)

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

指向 a 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 不会提交要初始化的微型端口适配器的请求。 微型端口适配器处于 初始化 状态。

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

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

  • 驱动程序分配的上下文区域的句柄。
  • 相应的属性标志。
  • 调用超时间隔 MiniportCheckForHangEx 函数。
  • 接口类型。
微型端口驱动程序通过 NdisMSetMiniportAttributes NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES MiniportAdapterContext 成员处的句柄。 驱动程序在此上下文区域中维护指定微型端口适配器的状态信息。 NDIS 将此句柄作为输入参数传递给其他 MiniportXxx 函数。

Miniport drivers must set the attributes in the NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES结构中设置注册属性以及设置任何其他属性之前,NDIS_MINIPORT_ADAPTER_GENERAL_ATTRIBUTES结构。

MiniportInitializeEx 还可以分配如下资源:

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

如果驱动程序函数(除了 MiniportInterrupt 函数之外)共享资源、 MiniportInitializeEx 应调用 NdisAllocateSpinLock 函数来设置同步对此类共享资源的访问所需的任何旋转锁。 其他驱动程序函数与 MiniportInterrupt 共享的资源(如 NIC 寄存器)受驱动程序使用 设置的中断对象保护 NdisMRegisterInterruptEx 函数。 Driver functions access these resources by calling the NdisMSynchronizeWithInterruptEx 函数。

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

MiniportInitializeEx 必须调用 NdisMSetMiniportAttributes 函数在调用任何 NdisMXxx 函数(例如 NdisMRegisterIoPortRangeNdisMMapIoSpace 函数)之前,该函数会声明微型端口适配器的硬件资源。 MiniportInitializeEx 必须先调用 NdisMSetMiniportAttributes ,然后才能尝试为 DMA 操作分配资源。

如果设备支持总线主 DMA, MiniportInitializeEx 必须调用 NdisMRegisterScatterGatherDma 函数在调用 NdisMSetMiniportAttributes 之前调用 NdisMAllocateSharedMemory 函数。 如果设备支持从属 DMA, MiniportInitializeEx 必须在调用 NdisMSetMiniportAttributes 之前调用 NdisMRegisterDmaChannel 函数。

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

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

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

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

如果 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的信息,请参阅 批注函数行为

要求

   
最低受支持的客户端 在 NDIS 6.0 及更高版本中受支持。
目标平台 Windows
标头 ndis.h (包括 Ndis.h)
IRQL PASSIVE_LEVEL

另请参阅

DriverEntry

MiniportCheckForHangEx

MiniportHaltEx

MiniportInterrupt

MiniportRestart

NDIS_MINIPORT_ADAPTER_GENERAL_ATTRIBUTES NDIS_MINIPORT_ADAPTER_REGISTRATION_ATTRIBUTES

NDIS_MINIPORT_INIT_PARAMETERS

NET_BUFFER

NET_BUFFER_LIST

NdisAllocateNetBuffer

NdisAllocateNetBufferAndNetBufferList

NdisAllocateNetBufferList

NdisAllocateNetBufferListPool

NdisAllocateNetBufferPool

NdisAllocateSpinLock

NdisAllocateTimerObject

NdisMAllocateSharedMemory

NdisMDeregisterInterruptEx

NdisMGetBusData

NdisMIndicateReceiveNetBufferLists

NdisMMapIoSpace

NdisMRegisterDmaChannel

NdisMRegisterInterruptEx

NdisMRegisterIoPortRange

NdisMRegisterMiniportDriver

NdisMRegisterScatterGatherDma

NdisMSetMiniportAttributes

NdisMSleep

NdisMSynchronizeWithInterruptEx

NdisOpenConfigurationEx

NdisReadConfiguration

NdisSetTimerObject

NdisWaitEvent

NdisWriteErrorLogEntry

NetTimerCallback

ProtocolBindAdapterEx