WDF_POWER_FRAMEWORK_SETTINGS結構 (wdfdevice.h)

  • 發行項

[適用於 KMDF 和 UMDF]

WDF_POWER_FRAMEWORK_SETTINGS結構描述單 一 元件裝置 (PoFx) 設定的電源管理架構。

語法

typedef struct _WDF_POWER_FRAMEWORK_SETTINGS {
  ULONG                                         Size;
  PFN_WDFDEVICE_WDM_POST_PO_FX_REGISTER_DEVICE  EvtDeviceWdmPostPoFxRegisterDevice;
  PFN_WDFDEVICE_WDM_PRE_PO_FX_UNREGISTER_DEVICE EvtDeviceWdmPrePoFxUnregisterDevice;
  PPO_FX_COMPONENT                              Component;
  PPO_FX_COMPONENT_ACTIVE_CONDITION_CALLBACK    ComponentActiveConditionCallback;
  PPO_FX_COMPONENT_IDLE_CONDITION_CALLBACK      ComponentIdleConditionCallback;
  PPO_FX_COMPONENT_IDLE_STATE_CALLBACK          ComponentIdleStateCallback;
  PPO_FX_POWER_CONTROL_CALLBACK                 PowerControlCallback;
  PVOID                                         PoFxDeviceContext;
  ULONGLONG                                     PoFxDeviceFlags;
  WDF_TRI_STATE                                 DirectedPoFxEnabled;
} WDF_POWER_FRAMEWORK_SETTINGS, *PWDF_POWER_FRAMEWORK_SETTINGS;

成員

Size

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

EvtDeviceWdmPostPoFxRegisterDevice

驅動程式 EvtDeviceWdmPostPoFxRegisterDevice 事件回呼函式或 NULL 的指標。

EvtDeviceWdmPrePoFxUnregisterDevice

驅動程式 EvtDeviceWdmPrePoFxUnregisterDevice 事件回呼函式或 NULL 的指標。

Component

描述單一元件裝置或 NULL 中唯一元件的 PO_FX_COMPONENT 結構的指標。 如果為 NULL，KMDF 預設為 F0 僅支援此元件。 此結構會指定元件支援的 F 狀態數目和屬性，以及元件可從中喚醒的最深 Fx 狀態。

ComponentActiveConditionCallback

驅動程式 ComponentActiveConditionCallback 回 呼例程或 NULL 的指標。 當元件變成使用中時，電源管理架構 (PoFx) 呼叫此回呼函式。 在作用中條件中，元件保證在 F0 中。

ComponentIdleConditionCallback

驅動程式 ComponentIdleConditionCallback 回 呼函式或 NULL 的指標。 PoFx 會在元件閒置時呼叫此回呼函式。 在閑置條件中，元件可能處於任何 F 狀態，包括 F0。

ComponentIdleStateCallback

驅動程式 ComponentIdleStateCallback 回 呼函式或 NULL 的指標。 PoFx 會在元件的 F 狀態變更時呼叫此回呼函式。

PowerControlCallback

用戶端驅動程式 PowerControlCallback回 呼函式或 NULL 的指標。 PoFx 會呼叫此例程，直接將電源控制作業的要求傳遞至驅動程式。 如果您的驅動程式不支援任何電源控制程式碼，請將此參數設定為NULL。

PoFxDeviceContext

架構提供給 ComponentActiveConditionCallback、 ComponentIdleConditionCallback、 ComponentIdleStateCallback 和 PowerControlCallback 的內容指標。

PoFxDeviceFlags

ULONGLONG 類型的值，其中包含與導向電源管理架構相關的下列值的位 OR。 從 KMDF 1.33 版和 UMDF 2.33 版開始，即可使用此字段。

PO_FX_DEVICE_FLAG_DFX_CHILDREN_OPTIONAL

在裝置上啟用導向 Power Framework (“DFx”) 時，子裝置通常也會啟用 DFx。 不過，在某些情況下， (例如純軟體裝置) ，子裝置不會實作電源管理。 將此旗標設定為允許這類子裝置略過 DFx。

若要代表子裝置設定此旗標，父 WDF 驅動程式必須：

針對以 v33 WDF 為目標的驅動程式，請改為指定 INF 指示詞：WdfDirectedPowerTransitionChildrenOptional，從 Windows 10 1903 版開始提供。 如果驅動程式指定 INF 指示詞並設定此旗標，則 INF 指示詞會優先使用。

PO_FX_DEVICE_FLAG_DISABLE_FAST_RESUME

這需要實作兩個裝置之間的 IRP_MN_QUERY_DEVICE_RELATIONS/PowerRelations。

根據預設，WDF 會實作快速繼續，這表示在系統喚醒期間，裝置堆疊中的電源原則擁有者會完成 S0-IRP，而不需要等待要求並完成 D0-IRP。 這不適用於PowerRelations。

若要讓PowerRelations正常運作，如果裝置相依於另一部裝置先進入 D0，第二個裝置應該將此旗標設定為選擇退出快速繼續。

在某些情況下，即使未設定此旗標，全域原則仍可能會停用全域快速繼續。

DirectedPoFxEnabled

WDF_TRI_STATE型別列舉值，指出裝置是否啟用「導向電源管理架構」 (DFx) 。 從 KMDF 1.33 版和 UMDF 2.33 版開始提供。

WdfTrue - 已啟用 DFx。 WdfFalse – DFx 已停用。 WdfUseDefault - 驅動程式未設定預設值。 這個值的意義與 WdfTrue 相同。

從 Windows 10 1903 版開始，即可使用 DFx (DFx) 作為使用 SystemManagedIdleTimeout 或 SystemManagedIdleTimeoutWithHint 的驅動程式選項。

  • 若為以 v31 WDF 為目標的驅動程式，請將 INF 指示詞 WdfDirectedPowerTransitionEnable 設定為 1，以選擇加入 DFx。
  • 針對以 v31+ WDF 為目標的驅動程式，預設會啟用 DFx。 驅動程式可以將 WdfDirectedPowerTransitionEnable 設定為零，以退出 DFx。
  • 針對以 v33+ WDF 為目標的驅動程式，預設也會啟用 DFx。 驅動程式可以將 WdfDirectedPowerTransitionEnable 設定為零，或將此字段設定為 WdfFalse (建議) 退出 DFx。 如果兩者都已設定，則 INF 指示詞優先。

備註

WDF_POWER_FRAMEWORK_SETTINGS 結構是使用 WdfDeviceWdmAssignPowerFrameworkSettings 的輸入。

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

針對 UMDF，只會使用 Size、 PoFxDeviceFlags 和 DirectedPoFxEnabled 。 其他欄位會被忽略，而且必須設定為零。 當 UMDF 驅動程式呼叫 WDF_POWER_FRAMEWORK_SETTINGS_INIT時，架構會自動執行此動作。

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

此結構不適用於多元件裝置的 KMDF 用戶端驅動程式。

規格需求

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

另請參閱

EvtDeviceWdmPostPoFxRegisterDevice

EvtDeviceWdmPrePoFxUnregisterDevice

WDF_POWER_FRAMEWORK_SETTINGS_INIT

WdfDeviceWdmAssignPowerFrameworkSettings