GET_IDLE_WAKE_INFO回呼函式 (wdm.h)

發行項
02/27/2024

GetIdleWakeInfo 例程可讓裝置的驅動程式探索裝置可以發出喚醒事件的裝置電源狀態。

語法

GET_IDLE_WAKE_INFO GetIdleWakeInfo;

NTSTATUS GetIdleWakeInfo(
  [in, optional] PVOID Context,
  [in]           SYSTEM_POWER_STATE SystemPowerState,
  [out]          PDEVICE_WAKE_DEPTH DeepestWakeableDstate
)
{...}

參數

[in, optional] Context

介面特定內容資訊的指標。呼叫端會將此參數設定為介面之 D3COLD_SUPPORT_INTERFACE 結構之 Context 成員的值。

[in] SystemPowerState

系統電源狀態。將此參數設定為下列其中一個 SYSTEM_POWER_STATE 列舉值：

PowerSystemWorking
PowerSystemSleeping1
PowerSystemSleeping2
PowerSystemSleeping3
PowerSystemHibernate

這些值代表系統電源狀態 S0 (系統工作狀態) 到 S4。針對呼叫端所提供的 SystemPowerState 值，例程會決定裝置可從中發出喚醒訊號的最深層裝置電源狀態。

[out] DeepestWakeableDstate

最深的可喚醒 Dx 狀態。此參數是 DEVICE_WAKE_DEPTH 變數的指標。如果呼叫成功，例程會將下列其中一個列舉值寫入此變數：

DeviceWakeDepthNotWakeable
DeviceWakeDepthD0
DeviceWakeDepthD1
DeviceWakeDepthD2
DeviceWakeDepthD3hot
DeviceWakeDepthD3cold

DeviceWakeDepthD0 到 DeviceWakeDepthD3cold 範圍中的值，表示當電腦處於 SystemPowerState 參數所指定的系統電源狀態時，裝置可以傳送喚醒訊號的最低電源狀態。 DeviceWakeDepthNotWakeable 指出當計算機處於 SystemPowerState 所指定的系統電源狀態時，裝置可以傳送喚醒訊號的裝置電源狀態。

如果例程無法判斷最深的可喚醒裝置狀態 (，可能是因為平臺韌體未包含此資訊) ，則呼叫會失敗，而例程會傳回錯誤狀態代碼。如果 PowerSystemWorking 至 PowerSystemHibernate 範圍中的任何 SystemPowerState 參數值 GetIdleWakeInfo 呼叫失敗，則所有這類值都會失敗。

傳回值

如果 GetIdleWakeInfo 例程成功擷取最深的可喚醒裝置狀態，則會傳回STATUS_SUCCESS。否則，它會傳回適當的錯誤狀態代碼。

備註

針對呼叫端所指定的系統電源狀態，此例程會嘗試判斷裝置可從中發出喚醒事件訊號給處理器的最低電源狀態。如果成功，例程會將裝置電源狀態寫入 DeepestWakeableDstate 參數所指向的位置，並傳回STATUS_SUCCESS。或者，如果例程判斷裝置無法從任何裝置電源狀態發出喚醒事件訊號，則例程會將 DeviceWakeDepthNotWakeable 值寫入此位置，並傳回STATUS_SUCCESS。

裝置的驅動程式會使用 GetIdleWakeInfo 例程所提供的資訊來判斷裝置可以發出喚醒事件的條件。需要能夠發出特定喚醒事件訊號的裝置不應該進入裝置電源狀態，無法發出這些事件的訊號。針對某些類型的裝置，當計算機處於 S0 (運作) 系統電源狀態時，裝置應該傳送的喚醒訊號與當電腦似乎關閉時應該傳送的裝置不同。

例如，當卡片插入PCI Express記憶卡插槽中，而該位置的PCI Express熱插即用控制器裝置處於 D0 裝置電源狀態時，此裝置會向處理器發出中斷訊號。不過，如果控制器裝置在插入卡片時處於低電源 Dx 狀態，計算機的系統電源狀態可能會判斷此裝置是否應該發出喚醒事件給處理器。在理想情況下，控制器裝置的行為應該如下所示：

如果計算機處於 S0 (運作) 系統電源狀態，裝置應該向處理器發出喚醒事件訊號。
如果計算機處於睡眠狀態 (處於低電源 Sx 狀態) ，裝置不應該發出喚醒事件訊號。

某些較舊的裝置可能不支援這種理想的行為。如果本範例中的PCI Express熱插即用控制器裝置只能在電腦處於 S3 狀態時發出喚醒事件，則驅動程式 (，在此情況下，控制器的收件匣 Pci.sys 驅動程式) ，當電腦處於 S0 (且未準備進入睡眠狀態) 。

此範例中的驅動程式可以呼叫 GetIdleWakeInfo 例程，以判斷在計算機處於 S0 時，熱插即用控制器裝置是否應該保持 D0 狀態。針對此呼叫，驅動程式會設定 SystemPowerState = PowerSystemWorking。當計算機處於 S0) 下列任一情況時，此裝置不應保留 D0 狀態 (：

GetIdleWakeInfo 呼叫會將輸出參數設定為 DeviceWakeDepthNotWakeable 或 DeviceWakeDepthD0，並傳回STATUS_SUCCESS。
GetIdleWakeInfo 呼叫失敗，並傳回錯誤狀態代碼。

驅動程式應該解譯這其中一個結果，表示當計算機處於 S0 時，裝置無法發出喚醒事件訊號。根據這項資訊，驅動程式應該將裝置保留在 D0 中，直到計算機準備結束 S0 為止。

大部分裝置的驅動程式可以處理 DeviceWakeDepthD0 與 DeviceWakeDepthNotWakeable 相同的輸出值。只有少數驅動程式在 D0 裝置處於 D0 時，可能會有理由來提供喚醒訊號。這些是簡單的裝置驅動程式，可監視觸發喚醒訊號的外部事件，不論裝置是否處於 D0 或低電源 Dx 狀態。這類裝置的範例是電腦上的電源按鈕或睡眠按鈕。

GetIdleWakeInfo 例程會查詢基礎總線驅動程式和 ACPI 系統韌體，以判斷裝置可以發出喚醒事件訊號的最低裝置電源狀態。如果總線驅動程式和韌體無法提供這項資訊，例程會失敗並傳回錯誤狀態代碼。

DEVICE_CAPABILITIES 結構包含 DeviceWake 成員，提供類似 GetIdleWakeInfo 例程中可用的資訊。不過， DeviceWake 成員中的資訊僅適用於系統低電源狀態 S1 至 S4。對於某些裝置， DeviceWake 成員中的資訊可能也適用於 S0 系統電源狀態，但驅動程式不應該依賴這類行為。只有 GetIdleWakeInfo 例程可靠地報告裝置在 S0 中時發出喚醒事件的能力。

提供內嵌協助程式函式 MapWakeDepthToDstate，將DEVICE_WAKE_DEPTH輸出值從 GetIdleWakeInfo 例程轉換成可做為 PoRequestPowerIrp 例程輸入參數的DEVICE_POWER_STATE值。