DXGKDDI_NOTIFY_SURPRISE_REMOVAL回调函数 (dispmprt.h)

项目
02/26/2024

当用户在未通知系统的情况下断开外部显示设备的连接时，操作系统会调用DXGKDDI_NOTIFY_SURPRISE_REMOVAL。

语法

DXGKDDI_NOTIFY_SURPRISE_REMOVAL DxgkddiNotifySurpriseRemoval;

NTSTATUS DxgkddiNotifySurpriseRemoval(
  [in] PVOID MiniportDeviceContext,
  [in] DXGK_SURPRISE_REMOVAL_TYPE RemovalType
)
{...}

参数

[in] MiniportDeviceContext

与显示适配器关联的上下文块的句柄。显示微型端口驱动程序的 DxgkDdiAddDevice 函数之前向 DirectX 图形内核子系统提供了此句柄。

[in] RemovalType

类型 为 DXGK_SURPRISE_REMOVAL_TYPE 的值，该值标识意外删除事件的类型。

返回值

如果为 RemoveType = DxgkRemovalHibernation 清理了软件资源，则返回STATUS_SUCCESS。如果驱动程序返回错误代码，操作系统将尝试重新启动系统，如以下“备注”部分所述。

注解

Windows 显示驱动程序模型 (WDDM) 1.2 及更高版本的显示微型端口驱动程序可以选择实现此回调。

注意

仅当显示微型端口驱动程序通过将 DXGK_DRIVERCAPS 结构的SupportSurpriseRemovalInHibernation 成员设置为 1 来指示支持时，操作系统才会调用 DxgkDdiNotifySurpriseRemoval。

当 OS 检测到意外删除时，它会尽快通知驱动程序。 DxgkDdiNotifySurpriseRemoval 是一个级别为零的 DDI 函数，这意味着当驱动程序具有挂起的 GPU 工作负载和/或在其他 DDI 函数中运行时，可以调用它。由于调用此函数表示图形硬件已被物理移除或已从系统中消失，因此任何进一步访问硬件的尝试都可能导致硬挂起等问题。

OS 将意外删除分类如下：

当系统和图形设备处于低功耗状态（例如睡眠或休眠）时，会发生意外删除。当 OS 从低功耗状态恢复时，它会检测到此意外删除，并立即调用驱动程序的 DxgkDdiNotifySurpriseRemoval 回调， 其 RemoveType = DxgkRemovalHibernation。在这种情况下，可能不会有任何挂起的 GPU 工作或 DDI 调用，因此驱动程序应相对安全且易于处理。返回状态详细信息如下所示：
- OS 要求驱动程序正确处理 DxgkDdiNotifySurpriseRemoval 调用并返回 STATUS_SUCCESS。
- 如果已删除的图形设备是开机自测试 (POST) 设备，则 OS 将尝试正常重新启动系统，而不考虑返回的状态。
- 对于非 POST 设备，如果驱动程序调用失败，并且在其DXGK_DRIVERCAPS中仅支持 SupportSurpriseRemovalInHibernation，则 OS 将正常重启系统。如果它支持 DXGK_DRIVERCAPS 中的 SupportSurpriseRemoval，则操作系统将忽略返回状态并继续停止图形设备。请参阅下面的其他退货说明。
图形设备在仍在运行时意外移除/拔出电源。当 OS 检测到此类意外删除时，它会立即调用驱动程序的 DxgkDdiNotifySurpriseRemoval 回调， 其 RemoveType = DxgkRemovalPnPNotify。在这种情况下，可能仍有一些挂起的 GPU 工作或 DDI 调用需要完成。当驱动程序收到此通知并可以处理此意外删除时，驱动程序应立即在自己的设备上下文中将此设备标记为意外删除，以避免任何硬件访问，然后将STATUS_SUCCESS返回给 OS。 OS 将继续调用其他 DDI 函数来清理资源并停止图形设备。如下所述，驱动程序应仅释放或清理软件资源，不得触摸或访问这些 DDI 调用中的任何硬件。如果驱动程序无法处理此意外删除，则应将适当的故障返回给 OS。对于任何故障，OS 将立即对系统进行 bug 检查，以避免任何进一步的硬件或数据损坏。

如果显示微型端口驱动程序 返回STATUS_SUCCESS，则 DirectX 图形内核子系统将继续从图形堆栈中删除外部显示适配器，并将调用其他驱动程序实现的 DxgkDdiXxx 内核模式函数来释放所有资源。在这种情况下，驱动程序必须完成软件资源的清理以响应来自操作系统的调用，但不得触摸或清理任何硬件设置。如果没有其他硬件正在使用驱动程序，操作系统将卸载该驱动程序。

如果驱动程序返回错误代码，则不会设置 DXGK_DRIVERCAPS。SupportSurpriseRemovalInHibernation，或者不实现此函数，DirectX 图形内核子系统将不会再调用驱动程序实现的 DxgkDdiXxx 函数，并且将尝试重新启动系统。在这种情况下，不会释放在外部显示设备断开连接之前分配的资源。