MINIPORT_MESSAGE_INTERRUPT回调函数 (ndis.h)

项目
08/07/2023

当 NIC 生成基于消息的中断时，NDIS 调用 MiniportMessageInterrupt 函数。

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

语法

MINIPORT_MESSAGE_INTERRUPT MiniportMessageInterrupt;

BOOLEAN MiniportMessageInterrupt(
  [in]  NDIS_HANDLE MiniportInterruptContext,
  [in]  ULONG MessageId,
  [out] PBOOLEAN QueueDefaultInterruptDpc,
  [out] PULONG TargetProcessors
)
{...}

参数

[in] MiniportInterruptContext

中断上下文信息块的句柄。微型端口驱动程序在微型端口驱动程序传递给的 MiniportInterruptContext 参数中提供了此句柄 NdisMRegisterInterruptEx 函数。

[in] MessageId

MSI) 消息标识符 (消息信号中断。 MessageId 是指向的索引 IO_INTERRUPT_MESSAGE_INFO_ENTRY 结构 IO_INTERRUPT_MESSAGE_INFO 结构。当驱动程序向 NdisMRegisterInterruptEx 函数成功注册 MSI 时，NDIS 将传递指向 MessageInfoTable 成员处关联的 IO_INTERRUPT_MESSAGE_INFO 结构的指针。

[out] QueueDefaultInterruptDpc

指向微型端口驱动程序在从此调用返回之前设置的布尔变量的指针。微型端口驱动程序将此值设置为 TRUE ，以指示驱动程序需要在默认 (当前) CPU 上使用 DPC。如果设置为 TRUE，NDIS 将忽略 TargetProcessors 参数的值。如果设置为 FALSE，NDIS 将使用 TargetProcessors 参数的值来计划 DPC。

[out] TargetProcessors

一个位掩码，指示 NDIS 应为其计划 DPC 的目标处理器。此位掩码表示处理器组 0 中的前 32 个处理器。位掩码中的每个位标识一个 CPU。如果调用方设置位 0，NDIS 会为 CPU 0 计划 DPC。如果调用方设置位 1，则 NDIS 会为 CPU 1 计划 DPC，依此安排。

注意 NDIS 6.20 及更高版本的驱动程序不应使用此参数来计划 DPC。相反，他们应将此参数设置为零，并使用 NdisMQueueDpcEx 函数来计划 DPC。

返回值

如果基础 NIC 生成了中断，MiniportMessageInterrupt 将返回 TRUE;否则返回 FALSE。

注解

通过 NdisMRegisterInterruptEx 函数注册消息信号中断 (MSI) 支持的微型端口驱动程序必须提供 MiniportMessageInterrupt 函数。

微型端口驱动程序应在其 MiniportMessageInterrupt 函数中尽可能少地执行工作。它应将 NIC 生成的中断的 I/O 操作延迟到 MiniportMessageInterruptDPC 函数。

当 NIC 生成 MSI 时，NDIS 会调用微型端口驱动程序的 MiniportMessageInterrupt 函数。

MiniportMessageInterrupt 保存有关中断的所需状态信息，并将尽可能多的 I/O 处理延迟到 MiniportMessageInterruptDPC 函数。

如果微型端口驱动程序请求对指定消息) (DPC 的延迟过程调用，则微型端口驱动程序应禁用该消息的所有进一步中断，并在所有 DPC 完成后重新启用中断。

微型端口驱动程序应将 QueueDefaultInterruptDpc 设置为 TRUE ，以便仅为默认 CPU 计划 DPC。驱动程序可以执行此操作，例如，如果：

NIC 生成了中断，以指示发送操作或未在其他 CPU 上运行的任何其他请求完成。
NIC 生成中断以发出接收的数据信号，微型端口驱动程序无法在单独的 DPC 中处理收到的数据包。
中断指示收到的数据包，微型端口驱动程序可以在单独的 DPC 中处理收到的数据包，但接收方缩放 (RSS) 未为微型端口驱动程序启用。有关详细信息，请参阅 OID_GEN_RECEIVE_SCALE_CAPABILITIES 和 OID_GEN_RECEIVE_SCALE_PARAMETERS。
已为微型端口驱动程序启用接收方缩放，微型端口驱动程序可以在每个接收队列上生成不同的消息。

如果微型端口驱动程序在单独的 DPC 中处理收到的数据包，微型端口驱动程序会将 QueueDefaultInterruptDpc 参数设置为 FALSE。微型端口驱动程序应设置与每个非空接收队列关联的 CPU 的 TargetProcessors 位。 NDIS 将在处理器组 0 中每个指示的 CPU 上计划一个 DPC。

如果 MiniportMessageInterrupt 将指定消息的资源（如 NIC 寄存器或状态变量）与另一个以较低 IRQL 运行的 MiniportXxx 函数共享，则 MiniportXxx 函数必须调用 NdisMSynchronizeWithInterruptEx 函数。这可确保驱动程序的 MiniportSynchronizeMessageInterrupt 函数以同步且多处理器安全的方式访问共享资源。

微型端口驱动程序可以调用 NdisMDeregisterInterruptEx 函数从其 MiniportInitializeEx 或 MiniportHaltEx 函数释放它使用 NdisMRegisterInterruptEx 分配的资源。 在 NdisMDeregisterInterruptEx 返回后，NDIS 不会调用微型端口驱动程序的 MiniportMessageInterrupt 或 MiniportMessageInterruptDPC 函数。

NDIS 在微型端口驱动程序在上一次对 NdisMRegisterInterruptEx 的调用中注册的 MSI 的 DIRQL 调用 MiniportMessageInterrupt。因此， MiniportMessageInterrupt 必须调用 NDIS 函数的子集，例如 NdisRawXxx 或 NdisRead/WriteRegisterXxx 函数，这些函数在任何 IRQL 下都可安全调用。

示例

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

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

MINIPORT_MESSAGE_INTERRUPT MyMessageInterrupt;

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

_Use_decl_annotations_
BOOLEAN
 MyMessageInterrupt(
    NDIS_HANDLE  MiniportInterruptContext,
    ULONG  MessageId,
    PBOOLEAN  QueueDefaultInterruptDpc,
    PULONG  TargetProcessors
    )
  {...}

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

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

要求

要求	值
最低受支持的客户端	在 NDIS 6.0 及更高版本中受支持。
目标平台	Windows
标头	ndis.h (包括 Ndis.h)
IRQL	请参阅“备注”部分