GET_IDLE_WAKE_INFO回呼函式（wdm.h）

發行項
02/07/2025

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 結構內容成員的值。

[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 所指定的系統電源狀態時，裝置無法傳送喚醒訊號的裝置電源狀態。

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

傳回值

如果 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 時，應該將控制器保留在 D0 中（且未準備進入睡眠狀態）。

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

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

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

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

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

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

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