MINIPORT_PNP_IRP回调函数 (ndis.h)

项目
08/07/2023

MiniportPnpIrp 函数使微型端口驱动程序可以选择性地管理其即插即用 (PnP) 资源。 MiniportPnpIrp 本身永远不会由微型端口驱动程序直接定义。相反，它被定义为 MiniportFilterResourceRequirements 或 MiniportStartDevice。

如果定义为 MiniportFilterResourceRequirements，则此函数使微型端口驱动程序能够修改设备的资源要求。如果定义为 MiniportStartDevice，则此函数使微型端口驱动程序能够删除它在中添加的资源 MiniportFilterResourceRequirements 函数。

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

语法

MINIPORT_PNP_IRP MiniportPnpIrp;

NDIS_STATUS MiniportPnpIrp(
  [in] NDIS_HANDLE MiniportAddDeviceContext,
  [in] PIRP Irp
)
{...}

参数

[in] MiniportAddDeviceContext

微型端口驱动程序在 MiniportAddDevice 函数中向 NDIS 注册的驱动程序分配上下文区域的句柄。

[in] Irp

如果此函数定义为 MiniportFilterResourceRequirements，则此参数是指向驱动程序要处理的 IRP_MN_FILTER_RESOURCE_REQUIREMENTS 的指针。

如果此函数定义为 MiniportStartDevice，则此参数是指向 IRP_MN_START_DEVICE IRP 的指针。

返回值

MiniportPnpIrp 返回以下值之一：

返回代码	说明
NDIS_STATUS_SUCCESS	微型端口驱动程序已成功处理启动设备请求。
NDIS_STATUS_RESOURCES	由于资源不足，微型端口驱动程序无法处理启动设备请求。
NDIS_STATUS_FAILURE	MiniportFilterResourceRequirements 因资源不足以外的其他原因失败。

注解

MiniportFilterResourceRequirements 备注

MiniportFilterResourceRequirements 函数是一个可选函数。微型端口驱动程序应注册此函数（如果它们支持 MSI-X，并且至少存在以下其中一项）：

驱动程序需要能够更改每个 MSI-X 消息的中断相关性。
驱动程序将在中注册基于行的中断 MiniportInitializeEx 函数。

若要注册 MiniportFilterResourceRequirements，请在中指定入口点 NDIS_MINIPORT_PNP_CHARACTERISTICS 结构。

NDIS 在 NDIS 收到后调用 MiniportFilterResourceRequirements 函数 IRP_MN_FILTER_RESOURCE_REQUIREMENTS网络接口的 IRP 卡 (NIC) 。 NDIS 在设备堆栈中的基础函数驱动程序完成 IRP 的处理后调用 MiniportFilterResourceRequirements 。

微型端口驱动程序必须准备好在 MiniportAddDevice 函数返回NDIS_STATUS_SUCCESS后立即处理来自 MiniportFilterResourceRequirements 的IRP_MN_FILTER_RESOURCE_REQUIREMENTS。

微型端口驱动程序可以为描述 MSI-X 消息的 CmResourceTypeInterrupt 类型的每个资源设置关联策略。如果关联策略请求针对一组特定处理器，微型端口驱动程序还会在IO_RESOURCE_DESCRIPTOR结构中的 Interrupt.TargetedProcessors 成员处设置 KAFFINITY 掩码。

如果 NDIS 6.1 或更高版本微型端口驱动程序需要更多消息中断资源，它可以将更多消息中断资源添加到资源列表。如果操作系统可以提供更多消息中断资源，微型端口适配器会在启动时接收添加的消息中断资源。

为列表中的每个消息中断资源分配一个消息编号，该消息编号对应于它在资源列表中的顺序。消息的编号从 0 到消息中断资源总数减 1。

若要在运行时将 MSI-X 表条目分配给 CPU，微型端口驱动程序可以调用 NdisMConfigMSIXTableEntry 函数。

微型端口驱动程序可以删除作为消息中断资源的所有 CmResourceTypeInterrupt 类型资源。然后，驱动程序可以在 MiniportInitializeEx 函数中注册基于行的中断。如果微型端口驱动程序不删除这些消息中断资源，则如果驱动程序尝试在 MiniportInitializeEx 中注册基于行的中断，操作系统将失败。

若要为新的资源要求列表分配内存，请使用 NdisAllocateMemoryWithTagPriority 函数。微型端口驱动程序可以使用 NdisFreeMemory 函数释放旧资源要求列表的内存。 PnP 管理器在关联的 IRP 完成后释放任何驱动程序分配的内存。

微型端口驱动程序不应修改其他资源，例如 CmResourceTypeMemory 和 CmResourceTypePort 资源。微型端口驱动程序应避免将新资源添加到资源列表。但是，微型端口驱动程序可以添加更多消息中断资源。如果微型端口驱动程序添加了更多消息中断资源，则驱动程序不得将其从 MiniportStartDevice 函数中删除。

如果微型端口驱动程序从 MiniportFilterResourceRequirements 返回NDIS_STATUS_RESOURCES或NDIS_STATUS_FAILURE，则 NDIS 将使用父总线驱动程序指定的资源要求。

在 NDIS 调用 MiniportRemoveDevice 函数之前，NDIS 可以多次调用 MiniportFilterResourceRequirements。但仅当设备处于停止状态时，NDIS 才会调用 MiniportFilterResourceRequirements 。

NDIS 在 IRQL = PASSIVE_LEVEL 调用 MiniportFilterResourceRequirements 。

MiniportFilterResourceRequirements 示例

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

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

MINIPORT_FILTER_RESOURCE_REQUIREMENTS MyFilterResourceRequirements;

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

_Use_decl_annotations_
NDIS_STATUS
 MyFilterResourceRequirements(
    NDIS_HANDLE  MiniportAddDeviceContext,
    PIRP  Irp
    )
  {...}

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

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

MiniportStartDevice 备注

MiniportStartDevice 是一个可选函数。支持 MSI-X 的微型端口驱动程序可以在中指定此函数的入口点 NDIS_MINIPORT_PNP_CHARACTERISTICS 结构。当 NDIS 收到来自即插即用 (PnP) 管理器的请求以启动设备时，NDIS 会调用 MiniportStartDevice 函数（如果有）。如果微型端口驱动程序在中添加新资源 MiniportFilterResourceRequirements 函数，它应提供 MiniportStartDevice 函数来删除资源。

如果微型端口驱动程序修改资源的方式使基础总线驱动程序无法识别资源，则驱动程序应提供 MiniportStartDevice 函数来删除资源。如果基础总线驱动程序无法识别微型端口驱动程序在 MiniportFilterResourceRequirements 中添加的资源，则启动设备请求可能会失败。如果微型端口驱动程序添加消息中断资源，则不得将其从 MiniportStartDevice 中删除。

NDIS 在将启动设备请求转发到基础驱动程序之前调用 MiniportStartDevice 。如果基础驱动程序成功完成请求，NDIS 将调用 MiniportInitializeEx 函数来初始化微型端口适配器。

NDIS 在 IRQL = PASSIVE_LEVEL 调用 MiniportStartDevice 。

MiniportStartDevice 示例

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

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

MINIPORT_START_DEVICE MyStartDevice;

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

_Use_decl_annotations_
NDIS_STATUS
 MyStartDevice(
    NDIS_HANDLE  MiniportAddDeviceContext,
    PIRP  Irp
    )
  {...}

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

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