MINIPORT_RESET回调函数 (ndis.h)

项目
08/07/2023

警告

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

NDIS 调用 NDIS 微型端口驱动程序的 MiniportResetEx 函数来启动网络接口重置卡 (NIC) 。有关详细信息，请参阅微型端口适配器检查挂起和重置操作和微型端口驱动程序硬件重置。

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

语法

MINIPORT_RESET MiniportReset;

NDIS_STATUS MiniportReset(
  [in]  NDIS_HANDLE MiniportAdapterContext,
  [out] PBOOLEAN AddressingReset
)
{...}

参数

[in] MiniportAdapterContext

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

[out] AddressingReset

指向布尔变量的指针。如果 NDIS 应调用 MiniportOidRequest 函数将寻址和其他配置设置还原为当前值，则微型端口驱动程序将此变量设置为 TRUE。有关详细信息，请参阅硬件重置。

返回值

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

返回代码	说明
NDIS_STATUS_SUCCESS	MiniportResetEx 已成功将微型端口适配器重置为运行状态。
NDIS_STATUS_PENDING	操作完成后，驱动程序将通过调用 NdisMResetComplete 函数异步完成重置操作。
NDIS_STATUS_RESET_IN_PROGRESS	MiniportResetEx 确定微型端口适配器当前正在重置，因此此调用是多余的。
NDIS_STATUS_SOFT_ERRORS	MiniportResetEx 已成功重置微型端口适配器，但在操作期间发生了可恢复的错误。 MiniportResetEx 应已调用 NdisWriteErrorLogEntry 函数，并提供有关错误的详细信息。
NDIS_STATUS_HARD_ERRORS	MiniportResetEx 尝试重置微型端口适配器，但在操作期间出现不可恢复的错误。 MiniportResetEx 应已调用 NdisWriteErrorLogEntry ，并提供有关错误的详细信息。

注解

驱动程序在调用时指定 MiniportResetEx 入口点 NdisMRegisterMiniportDriver 函数。

中间驱动程序不需要 MiniportResetEx。

MiniportResetEx 可以重置微型端口适配器的参数。如果重置导致微型端口适配器的工作站地址发生更改，则微型端口驱动程序会在重置完成后自动还原工作站地址的先前值。硬件重置的任何多播或功能寻址掩码不必在此函数中重置。

如果重置操作更改了其他信息（如多播或功能寻址信息）， MiniportResetEx 必须在 AddressingReset 处将变量设置为 TRUE ，然后才能返回。这会导致 NDIS 调用 MiniportOidRequest 函数来还原信息。 NDIS 还通过调用 OID_PNP_ADD_WAKE_UP_PATTERN 还原 LAN 唤醒 (WoL) 模式列表。驱动程序应从其适配器上下文中释放 WoL 模式列表，因为硬件列表已重置。

NDIS 不会中止任何挂起的 OID 请求或发送请求。如果驱动程序可以安全地完成挂起的 OID 或在重置后发送请求，则驱动程序可以保留挂起的 OID 或发送请求，直到重置操作完成。否则，驱动程序应通过调用 NdisMOidRequestComplete 或来完成挂起的 OID 或发送请求 NdisMSendNetBufferListsComplete 函数分别在 MiniportResetEx 返回之前。

注意从 NDIS 6.30 开始，微型端口驱动程序不得保留挂起的 OID 或发送请求，直到重置操作完成。相反，驱动程序必须在重置操作完成之前，通过分别调用 NdisMOidRequestComplete 或 NdisMSendNetBufferListsComplete 函数来完成这些挂起的请求。如果驱动程序异步完成重置操作，则必须在驱动程序调用 NdisMResetComplete 之前完成挂起的 OID 并发送请求。

微型端口驱动程序不应调用 NdisMIndicateStatusEx 函数来指示每个重置操作的开始和完成。当重置开始和结束时，NDIS 会通知绑定协议驱动程序。

如果 MiniportResetEx 必须在重置操作期间等待微型端口适配器的状态更改，它可以调用 NdisStallExecution 函数。但是，
MiniportResetEx 函数不得调用时间间隔大于 50 微秒的 NdisStallExecution 。如果驱动程序必须等待超过 50 微秒 (或者轮询) ，则应改为设置计时器并返回NDIS_STATUS_PENDING。

如果 MiniportResetEx 返回NDIS_STATUS_PENDING，驱动程序必须通过调用 NdisMResetComplete 函数来完成重置。

如果微型端口适配器处于 MediaConnectStateConnected 状态，并且其状态因重置而更改，包括对 MediaConnectStateUnknown 状态的更改，则微型端口驱动程序必须使用 NDIS_STATUS_LINK_STATE 状态指示报告状态更改。在重置后重新建立链接时，微型端口驱动程序还必须指示 MediaConnectStateConnected 状态指示。

MiniportResetEx 可能会被中断抢占。

NDIS 定期调用 MiniportCheckForHangEx 函数，以确定它是否应调用 MiniportResetEx。调用 MiniportCheckForHangEx 的默认超时为 2 秒。如果此默认值太短，则微型端口驱动程序可以在调用时设置更大的 CheckForHangTimeInSeconds 值
初始化期间的 NdisMSetMiniportAttributes 函数。有关详细信息，请参阅微型端口适配器检查挂起和重置操作。

NDIS 无法确定 NIC 是否已停止响应接收操作。为了处理此类故障， MiniportCheckForHangEx 函数可以监视接收操作，并在必要时返回 TRUE 以强制重置。微型端口还可以通过调用 NdisMResetMiniport 来请求重置。

NDIS 在 IRQL <= DISPATCH_LEVEL 调用 MiniportResetEx。

示例

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

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

MINIPORT_RESET MyResetEx;

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

_Use_decl_annotations_
NDIS_STATUS
 MyResetEx(
    NDIS_HANDLE  MiniportAdapterContext,
    PBOOLEAN  AddressingReset
    )
  {...}

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

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