WDF_POWER_FRAMEWORK_SETTINGS構造体 (wdfdevice.h)

[アーティクル]
08/08/2023

[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

単一コンポーネントデバイス内の唯一のコンポーネントを記述する PO_FX_COMPONENT 構造体へのポインター(NULL)。 NULL の場合、KMDF は既定で F0 に設定され、このコンポーネントに対してのみサポートされます。この構造体は、コンポーネントがサポートする F 状態の数と属性、およびコンポーネントが起動できる最も深い Fx 状態を指定します。

ComponentActiveConditionCallback

ドライバーの ComponentActiveConditionCallback コールバックルーチン (NULL) へのポインター。電源管理フレームワーク (PoFx) は、コンポーネントがアクティブになったときにこのコールバック関数を呼び出します。アクティブ状態では、コンポーネントは F0 であることが保証されます。

ComponentIdleConditionCallback

ドライバーの ComponentIdleConditionCallback コールバック関数へのポインター、または NULL。 PoFx は、コンポーネントがアイドル状態になったときにこのコールバック関数を呼び出します。アイドル状態にある間、コンポーネントは F0 を含む任意の F 状態になります。

ComponentIdleStateCallback

ドライバーの ComponentIdleStateCallback コールバック関数 (NULL) へのポインター。コンポーネントの F 状態が変更されると、PoFx はこのコールバック関数を呼び出します。

PowerControlCallback

クライアントドライバーの PowerControlCallback コールバック関数 (NULL) へのポインター。 PoFx は、このルーチンを呼び出して、電源制御操作の要求をドライバーに直接渡します。ドライバーが電源制御コードをサポートしていない場合は、このパラメーターを NULL に設定します。

PoFxDeviceContext

フレームワークが ComponentActiveConditionCallback、ComponentIdleConditionCallback、ComponentIdleStateCallback、PowerControlCallback に提供するコンテキストポインター。

PoFxDeviceFlags

Directed Power Management Framework に関連する次の値のビットごとの OR を含む ULONGLONG 型の値。このフィールドは、KMDF バージョン 1.33 および UMDF 2.33 以降で使用できます。

PO_FX_DEVICE_FLAG_DFX_CHILDREN_OPTIONAL

デバイスで Directed Power Framework ("DFx") が有効になっている場合、通常は子デバイスでも DFx が有効になります。ただし、場合によっては (純粋なソフトウェアデバイスなど)、子デバイスは電源管理を実装しません。このような子デバイスが DFx をスキップできるようにするには、このフラグを設定します。

子デバイスの代わりにこのフラグを設定するには、親 WDF ドライバーは次の操作を行う必要があります。

DFx にオプトインする
バスドライバーではない
サイドバンドチャネルを介して少なくとも 1 つの仮想子デバイスを作成する (たとえば、SwDeviceCreate を呼び出して作成された上位フィルターまたはデバイス)

v33 WDF より前を対象とするドライバーの場合は、代わりに INF ディレクティブ WdfDirectedPowerTransitionChildrenOptional を指定します。これは、Windows 10 バージョン 1903 以降で使用できます。ドライバーが INF ディレクティブを指定し、このフラグを設定する場合は、INF ディレクティブが優先されます。

PO_FX_DEVICE_FLAG_DISABLE_FAST_RESUME

これは、2 つのデバイス間 で IRP_MN_QUERY_DEVICE_RELATIONS/PowerRelations を実装するために必要です。

既定では、WDF は高速再開を実装します。つまり、システムのウェイクアップ中に、デバイススタックの電源ポリシー所有者は、D0-IRP の要求と完了を待たずに S0-IRP を完了します。これは PowerRelations ではうまく機能しません。

PowerRelations を正常に動作させるには、デバイスが最初に D0 を入力するために別のデバイスに依存している場合、2 番目のデバイスでこのフラグを設定して、高速再開をオプトアウトする必要があります。

場合によっては、このフラグが設定されていない場合でも、グローバルポリシーによって高速再開がグローバルに無効になることがあります。

DirectedPoFxEnabled

デバイスが Directed Power Management Framework (DFx) を有効にするかどうかを示す、WDF_TRI_STATE型の列挙子。 KMDF バージョン 1.33 および UMDF 2.33 以降で使用できます。

WdfTrue - DFx が有効です。 WdfFalse – DFx は無効です。 WdfUseDefault - ドライバーで設定されていない場合の既定値。この値は WdfTrue と同じ意味を持ちます。

Directed PoFx (DFx) は、SystemManagedIdleTimeout または SystemManagedIdleTimeoutWithHint を使用するドライバーのオプションとして、バージョン 1903 Windows 10 以降で使用できます。

v31 より前の WDF を対象とするドライバーの場合は、INF ディレクティブ WdfDirectedPowerTransitionEnable を 1 に設定して DFx にオプトインします。
v31+ WDF を対象とするドライバーの場合、DFx は既定で有効になっています。ドライバーでは、 DFx をオプトアウトする WdfDirectedPowerTransitionEnable を 0 に設定できます。
v33+ WDF を対象とするドライバーの場合、DFx も既定で有効になっています。ドライバーは 、WdfDirectedPowerTransitionEnable を 0 に設定するか、このフィールドを WdfFalse (推奨) に設定して DFx をオプトアウトできます。両方が設定されている場合は、INF ディレクティブが優先されます。

注釈

WDF_POWER_FRAMEWORK_SETTINGS構造体は、WdfDeviceWdmAssignPowerFrameworkSettings への入力を使用します。

WDF_POWER_FRAMEWORK_SETTINGS構造体を初期化するには、ドライバーで WDF_POWER_FRAMEWORK_SETTINGS_INIT を呼び出す必要があります。

UMDF の場合、 Size、 PoFxDeviceFlags、 DirectedPoFxEnabled のみが使用されます。その他のフィールドは無視され、0 に設定する必要があります。フレームワークは、UMDF ドライバーが WDF_POWER_FRAMEWORK_SETTINGS_INITを呼び出すときに自動的にこれを行います。

詳細については、「機能電源状態のサポート」および「 Power Management Framework の概要」を参照してください。

この構造は、複数コンポーネントデバイスの KMDF クライアントドライバーには適用されません。