WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS 結構 (wdfdevice.h)

  • 發行項

[適用於 KMDF 和 UMDF]

WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS結構包含驅動程式提供的資訊，當裝置閑置且系統處於系統運作狀態 (S0) 時，架構會使用此資訊。

語法

typedef struct _WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS {
  ULONG                                 Size;
  WDF_POWER_POLICY_S0_IDLE_CAPABILITIES IdleCaps;
  DEVICE_POWER_STATE                    DxState;
  ULONG                                 IdleTimeout;
  WDF_POWER_POLICY_S0_IDLE_USER_CONTROL UserControlOfIdleSettings;
  WDF_TRI_STATE                         Enabled;
  WDF_TRI_STATE                         PowerUpIdleDeviceOnSystemWake;
  WDF_POWER_POLICY_IDLE_TIMEOUT_TYPE    IdleTimeoutType;
  WDF_TRI_STATE                         ExcludeD3Cold;
} WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS, *PWDF_DEVICE_POWER_POLICY_IDLE_SETTINGS;

成員

Size

這個 結構的大小，以位元組為單位。

IdleCaps

WDF_POWER_POLICY_S0_IDLE_CAPABILITIES型別的列舉值，可識別裝置在設定為低電源狀態之後自行喚醒的能力，而系統仍維持在其運作中 (S0) 狀態。

DxState

DEVICE_POWER_STATE型別的列舉值，可識別裝置在閑置逾時期間結束後將進入的低裝置電源狀態。 DEVICE_POWER_STATE 值是在 wdm.h 中定義。

IdleTimeout

裝置在架構置於 DxState 提供的低電源狀態之前，裝置會保持閑置的時間量，以毫秒為單位。 若要使用架構的默認閑置逾時值，請指定 IdleTimeoutDefaultValue。 如需架構將裝置視為閑置狀態的詳細資訊，請參閱支援閑置電源。

UserControlOfIdleSettings

WDF_POWER_POLICY_S0_IDLE_USER_CONTROL型別列舉值，指出使用者是否可以修改裝置的閑置設定。

Enabled

WDF_TRI_STATE型別列舉值，指出當裝置保持閑置且系統電源為S0時，裝置是否會關閉電源。 此成員可以有下列其中一個值：

WdfTrue - 已啟用關閉電源。

WdfFalse - 關閉電源已停用。

WdfUseDefault - 一開始會啟用關閉電源;但如果 UserControlOfIdleSettings 成員設定為 IdleAllowUserControl， 則使用者的設定或驅動程式的 INF 檔案 會覆寫初始值。

如果電源關閉已啟用，裝置具有喚醒功能，且閑置逾時值到期，架構會在裝置進入低電源狀態之前呼叫驅動程式的 EvtDeviceArmWakeFromS0 回呼函式。

PowerUpIdleDeviceOnSystemWake

WDF_TRI_STATE型別列舉值，指出當系統回到其運作 ( S0) 狀態時，裝置是否會回到其工作 (D0) 狀態。 只有當驅動程式將 IdleCaps 成員設定為 IdleCannotWakeFromS0時，此成員才有效。 PowerUpIdleDeviceOnSystemWake 成員可以有下列其中一個值：

WdfTrue - 如果裝置和系統都處於低電源狀態，當系統回到其工作狀態時，裝置會回到其工作狀態。

WdfFalse - 如果裝置和系統都處於低電源狀態，當系統回到其工作狀態時，裝置會維持在低電源狀態。

WdfUseDefault - 如果驅動程式未設定不同的值，架構所使用的預設值。 這個值的意義與 WdfFalse 相同。

如果 PowerUpIdleDeviceOnSystemWake 成員設定為 WdfFalse 或 WdfUseDefault，則只有在軟體存取裝置時，裝置才會回到其工作狀態，例如當應用程式將 I/O 要求傳送至裝置時。 如需詳細資訊，請參閱 裝置返回其工作狀態。

PowerUpIdleDeviceOnSystemWake 成員可在 1.9 版和更新版本的 KMDF 中使用，從 UMDF 2.0 版開始。

IdleTimeoutType

指出IdleTimeout成員使用方式的WDF_POWER_POLICY_IDLE_TIMEOUT_TYPE型別列舉值。

IdleTimeoutType 成員可在 1.11 版和更新版本的 KMDF 中使用，從 UMDF 2.0 版開始。 請參閱中的其他資訊。

ExcludeD3Cold

WDF_TRI_STATE型別列舉值，指出 D3cold 電源狀態是否應為裝置在閒置逾時期限到期時所輸入的低電源狀態允許選擇。 ExcludeD3Cold 成員可以有下列其中一個值：

WdfTrue - 當閒置逾時期限到期時，架構會將裝置移至低電源 D 狀態。 如果該 D 狀態為 D3，裝置將會移至 D3hot。 如果 ExcludeD3Cold 設定為 WdfTrue，則不允許從 D3hot 進一步轉換至 D3cold。

WdfFalse - 如果符合下列所有準則，裝置可能會在閒置逾時期限到期時進入 D3cold 電源狀態：

  • 這個結構的 DxState 成員會指定 PowerDeviceD3 或 PowerDeviceMaximum。
  • ACPI 韌體表示裝置支援 D3cold 電源狀態。
  • 如果驅動程式在此結構的IdleCaps成員中指定IdleCanWakeFromS0或IdleUsbSelectiveSuspend，裝置可以在處於 D3cold 電源狀態時回應外部喚醒事件。 否則，此需求不適用。
WdfUseDefault - 架構會檢查 DDInstall。 驅動程式 INF 檔案的 HW 區段。 如果出現下列幾行，這個值就與 WdfFalse 具有相同的意義：
Include = machine.inf
Needs = PciD3ColdSupported
否則，這個值的意義與 WdfTrue 相同。

ExcludeD3Cold 成員可從 KMDF 1.11 版開始，以及從 UMDF 2.0 版開始，而且在操作系統早於 Windows 8 時會被忽略。 請參閱中的其他資訊。

備註

WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS 結構會當做 WdfDeviceAssignS0IdleSettings 的輸入使用。

驅動程式第一次呼叫 WdfDeviceAssignS0IdleSettings 時，會發生下列動作：

  • 架構會儲存所有 WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS 結構成員的值。
  • 如果 UserControlOfIdleSettings 成員設定為 IdleAllowUserControl ，而且 Enabled 成員設定為 WdfUseDefault，架構會讀取登錄，以了解使用者是否已在閑置時關閉裝置電源。
在後續呼叫 WdfDeviceAssignS0IdleSettings 期間，架構只會儲存 DxState、 IdleTimeout 和 Enabled 成員的值。 此外，在 KMDF 1.9 和更早版本中，除非值為 IdleUsbSelectiveSuspend，否則架構會儲存 IdleCaps 成員的值。 因此，驅動程式必須使用下列規則：
  • 如果驅動程式指定 IdleUsbSelectiveSuspend 作為 IdleCaps 成員的值，它必須執行此動作，第一次呼叫 WdfDeviceAssignS0IdleSettings，而且後續無法變更該值。
  • 如果驅動程式在第一次呼叫 WdfDeviceAssignS0IdleSettings 時指定 IdleCanWakeFromS0 或 IdleCannotWakeFromS0，則後續可以再次呼叫 WdfDeviceAssignS0IdleSettings 來變更該值 (但無法將值變更為 IdleUsbSelectiveSuspend) 。

從 KMDF 1.11 和 UMDF 2.0 開始，KMDF 驅動程式可以隨時在 IdleUsbSelectiveSuspend 和 IdleCannotWakeFromS0 之間切換。

從 Windows 8 開始，將IdleTimeoutType成員設定為 SystemManagedIdleTimeout 或 SystemManagedIdleTimeoutWithHint 會導致架構向電源管理架構註冊， (PoFx) 。

如果驅動程式正在實作多元件裝置的功能電源狀態支援，驅動程式必須將 IdleTimeoutType 設定為 DriverManagedIdleTimeout， 或完全不呼叫 WdfDeviceAssignS0IdleSettings 。

如需詳細資訊，請參閱 支援功能電源狀態 和 Power Management Framework 概觀。

下列規則適用於您為 DxState 成員指定的值：

  • 此值不可為 PowerDeviceD0。
  • 針對 USB 裝置，此值不能是 PowerDeviceD0 或 PowerDeviceD3。
  • 如果您指定 PowerDeviceMaximum，架構會使用驅動程式在其WDF_DEVICE_POWER_CAPABILITIES結構之 DeviceWake 成員中提供之裝置總線的值。
  • 如果 IdleCaps 成員的值是 IdleCanWakeFromS0，您就無法在總線驅動程式WDF_DEVICE_POWER_CAPABILITIES結構的 DeviceWake 成員中指定低於裝置電源狀態的裝置電源狀態。 (換句話說，如果總線驅動程式的 DeviceWake 值為 PowerDeviceD2，則函式驅動程式的 DxState 值不能是 PowerDeviceD3.)
在早於 Windows 8 的操作系統中，D3 電源狀態表示裝置處於低電源狀態，但仍會維護總線的一些電源。 從 Windows 8 開始，前一個 D3 電源狀態稱為 D3hot，而且有新的電源狀態 (D3cold) 可用。 當系統處於運作中狀態時，裝置可以進入 D3cold 狀態， (S0) 狀態或處於低電源狀態。 當裝置處於 D3cold 電源狀態時，總線處於非作用中狀態，而且當外部動作 (例如插入網路纜線) 造成硬體事件時，裝置必須觸發自己的喚醒訊號。

從 KMDF 1.11 和 UMDF 2.0 開始， 支援閑置電源 的裝置可以使用此結構的 ExcludeD3Cold 成員來指定 D3cold 電源狀態是否應是裝置在閒置逾時期間結束之後所輸入低 裝置電源狀態 的允許選擇。

如需控制裝置閑置功能之登錄專案的資訊，請參閱 裝置閑置和喚醒行為的使用者控制。

若要初始化其 WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS 結構，您的驅動程式應該呼叫 WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS_INIT。

規格需求

需求 值
最低 KMDF 版本 1.0
最低UMDF版本 2.0
標頭 wdfdevice.h (包含 Wdf.h)