MINIPORT_CHECK_FOR_HANG回调函数 (ndis.h)

项目
02/26/2024

警告

不建议对所有 NDIS 6.83 及更高版本的驱动程序使用 MiniportCheckForHangEx 和 MiniportResetEx 回调函数。有关详细信息，请参阅 NDIS 6.83 及更高版本中的 Check-for-Hang 和 Reset 操作。

NDIS 调用微型端口驱动程序的 MiniportCheckForHangEx 函数来检查微型端口适配器的操作状态，该适配器表示网络接口卡 (NIC) 。

注意微型端口驱动程序可以使用 MINIPORT_CHECK_FOR_HANG 类型声明此函数。

注意从 NDIS 6.30 开始，不得为在低功率 SoC 平台上运行的驱动程序注册此函数，以避免定期 Check-for-Hang 活动对电源造成负面影响。

语法

MINIPORT_CHECK_FOR_HANG MiniportCheckForHang;

BOOLEAN MiniportCheckForHang(
  [in] NDIS_HANDLE MiniportAdapterContext
)
{...}

参数

[in] MiniportAdapterContext

微型端口驱动程序在其 MiniportInitializeEx 函数中分配的上下文区域的句柄。微型端口驱动程序使用此上下文区域来维护微型端口适配器的状态信息。

返回值

如果驱动程序确定 NIC 未运行，并且 NDIS 应调用驱动程序的 MiniportResetEx 函数，则 MiniportCheckForHangEx 返回 TRUE。有关详细信息，请参阅“备注”部分。

备注

微型端口驱动程序在调用时指定 MiniportCheckForHangEx 入口点 NdisMRegisterMiniportDriver 函数。

MiniportCheckForHangEx 对于中间驱动程序不是必需的。

MiniportCheckForHangEx 只检查 NIC 的内部状态，如果检测到 NIC 未正常运行，则返回 TRUE。

默认情况下，NDIS 大约每两秒调用 一次 MiniportCheckForHangEx 。因此，微型端口驱动程序的 MiniportCheckForHangEx 函数应尽快返回。

注意从 NDIS 6.30 开始，高容差的可合并计时器用于测量对 MiniportCheckForHangEx 的调用之间的间隔。因此，不应将此例程用于任何时间敏感操作。

如果 MiniportCheckForHangEx 返回 TRUE，NDIS 将调用微型端口驱动程序的 MiniportResetEx 函数。

如果微型端口驱动程序在对 MiniportCheckForHangEx 的两次连续调用中未完成 OID 请求，则 NDIS 可以调用驱动程序的 MiniportResetEx 函数。但是，为了避免不必要的重置，驱动程序的 MiniportInitializeEx 函数可以通过在调用时设置适当的 CheckForHangTimeInSeconds 值来延长检查挂起超时间隔 NdisMSetMiniportAttributes 函数。

有关设置 CheckForHangTimeInSeconds 超时值的详细信息，请参阅微型端口适配器检查挂起和重置操作。

注意从 NDIS 6.30 开始，如果微型端口驱动程序检测到 NIC 在超时期限到期之前未完成挂起的发送请求， MiniportCheckForHangEx 必须返回 TRUE 。超时期限特定于驱动程序，但我们建议使用 2 秒的超时期限。

MiniportCheckForHangEx 可能会被中断抢占。

NDIS 在 IRQL = PASSIVE_LEVEL 调用 MiniportCheckForHangEx 。

示例

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

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

MINIPORT_CHECK_FOR_HANG MyCheckForHangEx;

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

_Use_decl_annotations_
BOOLEAN
 MyCheckForHangEx(
    NDIS_HANDLE  MiniportAdapterContext
    )
  {...}

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

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