DXGKDDI_NOTIFY_SURPRISE_REMOVAL回呼函式 (dispmprt.h)

發行項
02/25/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 的值，可識別意外移除事件的類型。

傳回值

如果針對 RemovalType = DxgkRemovalHibernation 清除軟體資源，則會傳回STATUS_SUCCESS。如果驅動程式改為傳回錯誤碼，操作系統會嘗試重新啟動系統，如下列一節所述。

備註

Windows 顯示驅動程式模型 (WDDM) 1.2 和更新版本顯示迷你埠驅動程式，可以選擇性地實作此回呼。

注意

只有在顯示迷你埠驅動程式將 DXGK_DRIVERCAPS 結構的 SupportSurpriseRemovnation 成員設定為 1，操作系統才會呼叫 DxgkDdiNotifySurpriseRemovalRemoval。

當 OS 偵測到意外移除時，它會儘快通知驅動程式。 DxgkDdiNotifySurpriseRemoval 是層級零 DDI 函式，這表示當驅動程式有擱置的 GPU 工作負載和/或在其他 DDI 函式內執行時，可以呼叫它。由於呼叫此函式表示圖形硬體已實際移除或從系統消失，因此任何進一步存取硬體的嘗試都可能會導致問題，例如硬式停止回應。

OS 會將意外移除分類如下：

當系統和圖形裝置處於低電源狀態時，就會發生意外移除，例如睡眠或休眠。當 OS 從低電源狀態繼續時，它會偵測到此意外移除，並立即呼叫驅動程式的 DxgkDdiNotifySurpriseRemoval 回呼，並搭配 RemovalType = DxgkRemovalHibernation 呼叫。在此情況下，沒有任何擱置的 GPU 工作或 DDI 呼叫，因此驅動程式應該相當安全且容易處理。傳回狀態詳細資料如下所示：
- OS 預期驅動程式會正確處理 DxgkDdiNotifySurpriseRemoval 呼叫，並傳回 STATUS_SUCCESS。
- 如果已移除的圖形裝置是開機的自我測試 (POST) 裝置，則無論傳回的狀態為何，OS 都會嘗試正常重新啟動系統。
- 對於非 POST 裝置，如果驅動程式失敗呼叫，且僅支援其DXGK_DRIVERCAPS中的 SupportSurpriseRemovalInHibernation，OS 會正常重新啟動系統。如果支援 DXGK_DRIVERCAPS 中的 SupportSurpriseRemoval，OS 將會忽略傳回狀態並繼續停止圖形裝置。請參閱下方的其他傳回附注。
圖形裝置在仍在執行時會意外移除/取消叢集。當 OS 偵測到這種類型的意外移除時，它會使用 RemovalType = DxgkRemovalPnPNotify 立即呼叫驅動程式的 DxgkDdiNotifySurpriseRemoval 回呼。在此情況下，仍有一些擱置的 GPU 工作或 DDI 呼叫要完成。當驅動程式收到此通知並可以處理此意外移除時，驅動程式應該立即將此裝置標示為自己的裝置內容中的意外移除，以避免任何硬體存取，然後將STATUS_SUCCESS傳回 OS。 OS 會繼續呼叫其他 DDI 函式來清除資源並停止圖形裝置。如以下所述，驅動程式應該只釋放或清除軟體資源，而且不得觸碰或存取這些 DDI 呼叫中的任何硬體。如果驅動程式無法處理此意外移除，它應該會將適當的失敗傳回給OS。針對任何失敗，OS 會立即檢查系統，以避免任何進一步的硬體或數據損毀。

如果顯示迷你埠驅動程式傳回 STATUS_SUCCESS，DirectX 圖形核心子系統會繼續從圖形堆疊移除外部顯示器適配卡，並呼叫其他驅動程序實作 的 DxgkDdiXxx 核心模式函式以釋放所有資源。在此情況下，驅動程式必須完成軟體資源的清除，以回應來自操作系統的呼叫，但不得觸控或清除任何硬體設定。如果沒有其他硬體使用驅動程式，操作系統將會卸除驅動程式。

如果驅動程式傳回錯誤碼，則不會設定 DXGK_DRIVERCAPS。SupportSurpriseRemovalInHibernation 或未實作此函式，DirectX 圖形核心子系統不會呼叫任何其他驅動程序實作 的 DxgkDdiXxx 函式，而且會嘗試重新啟動系統。在此情況下，不會釋放在外部顯示裝置中斷連線之前配置的資源。