PO_FX_DEVICE_V3 構造体 (wdm.h)

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

PO_FX_DEVICE_V3構造では、電源管理フレームワーク (PoFx)、DFx (Directed PoFx) に対するデバイスの電源属性について説明します。

構文

typedef struct _PO_FX_DEVICE_V3 {
  ULONG                                      Version;
  ULONGLONG                                  Flags;
  PPO_FX_COMPONENT_ACTIVE_CONDITION_CALLBACK ComponentActiveConditionCallback;
  PPO_FX_COMPONENT_IDLE_CONDITION_CALLBACK   ComponentIdleConditionCallback;
  PPO_FX_COMPONENT_IDLE_STATE_CALLBACK       ComponentIdleStateCallback;
  PPO_FX_DEVICE_POWER_REQUIRED_CALLBACK      DevicePowerRequiredCallback;
  PPO_FX_DEVICE_POWER_NOT_REQUIRED_CALLBACK  DevicePowerNotRequiredCallback;
  PPO_FX_POWER_CONTROL_CALLBACK              PowerControlCallback;
  PPO_FX_DIRECTED_POWER_UP_CALLBACK          DirectedPowerUpCallback;
  PPO_FX_DIRECTED_POWER_DOWN_CALLBACK        DirectedPowerDownCallback;
  ULONG                                      DirectedFxTimeoutInSeconds;
  PVOID                                      DeviceContext;
  ULONG                                      ComponentCount;
  PO_FX_COMPONENT_V2                         Components[ANYSIZE_ARRAY];
} PO_FX_DEVICE_V3, *PPO_FX_DEVICE_V3;

メンバー

Version

この構造体のバージョン番号。ドライバーが DFx でダイレクト電源サポートに登録する場合は、このメンバーを PO_FX_VERSION_V3 に設定します。

Flags

ダイレクト子デバイスと電源子デバイスが Directed PoFx をオプトアウトできるかどうかを制御します。

使用可能なフラグ値は次のとおりです。

フラグ	説明
PO_FX_DEVICE_FLAG_DIRECT_CHILDREN_OPTIONAL	このデバイスのダイレクト子デバイスが、必要に応じて Directed PoFx をサポートできるようにします。設定されていない場合、すべての直接の子は、このデバイスが Directed PoFx を完全にサポートするために Directed PoFx をサポートする必要があります。
PO_FX_DEVICE_FLAG_POWER_CHILDREN_OPTIONAL	このデバイスの電源子デバイスが必要に応じて Directed PoFx をサポートできるようにします。指定しない場合、すべての電源子は、このデバイスが Directed PoFx を完全にサポートするために Directed PoFx をサポートする必要があります。
PO_FX_DEVICE_FLAG_DFX_CHILDREN_OPTIONAL	PO_FX_DEVICE_FLAG_DIRECT_CHILDREN_OPTIONALとPO_FX_DEVICE_FLAG_POWER_CHILDREN_OPTIONALの両方を設定します
PO_FX_DEVICE_FLAG_DISABLE_FAST_RESUME	休止状態やスリープなどのシステム状態からの再開時に D0-IRP が完了する前に、S0-IRP が完了しないように PoFx を強制します。 PO_FX_DEVICE_FLAG_ENABLE_FAST_RESUMEと相互に排他的です。
PO_FX_DEVICE_FLAG_ENABLE_FAST_RESUME	Hibernate や Sleep などのシステム状態から再開する D0-IRP の前に、S0-IRP を完了できるように PoFx を強制します。 PO_FX_DEVICE_FLAG_ENABLE_FAST_RESUMEと相互に排他的です。

ComponentActiveConditionCallback

デバイスドライバーによって実装される ComponentActiveConditionCallback コールバックルーチンへのポインター。

ComponentIdleConditionCallback

デバイスドライバーによって実装される ComponentIdleConditionCallback コールバックルーチンへのポインター。

ComponentIdleStateCallback

デバイスドライバーによって実装される ComponentIdleStateCallback コールバックルーチンへのポインター。

DevicePowerRequiredCallback

デバイスドライバーによって実装される DevicePowerRequiredCallback コールバックルーチンへのポインター。

DevicePowerNotRequiredCallback

デバイスドライバーによって実装される DevicePowerNotRequiredCallback コールバックルーチンへのポインター。

PowerControlCallback

デバイスドライバーによって実装される PowerControlCallback コールバックルーチンへのポインター。

DirectedPowerUpCallback

デバイスドライバーによって実装される PO_FX_DIRECTED_POWER_UP_CALLBACK コールバックルーチンへのポインター。デバイスは、PoFx に DirectedPower* 登録するときにコールバックのみを提供できます。残りの PoFx コールバックを実装する必要はありません。

DirectedPowerDownCallback

デバイスドライバーによって実装される PO_FX_DIRECTED_POWER_DOWN_CALLBACK コールバックルーチンへのポインター。

DirectedFxTimeoutInSeconds

ソフトウェアアクティビティが存在しなくなった後にデバイスがアイドル状態になった推奨タイムアウトを秒単位で指定するヒントをフレームワークに提供します。既定値は 2 分です。

DeviceContext

呼び出し元によって割り当てられたデバイスコンテキストへのポインター。このポインターは、この構造体によって指されるドライバーによって実装された各コールバック関数にパラメーターとして渡されます。デバイスドライバーは、このコンテキストを使用して、デバイスの現在の電源状態に関する情報を格納します。このコンテキストは PoFx に対して不透明です。

ComponentCount

Components 配列内の要素の数。さらに、このメンバーは、デバイス内のコンポーネントの数を指定します。

Components[ANYSIZE_ARRAY]

このメンバーは、1 つ以上のPO_FX_COMPONENT_V2要素の配列の最初の要素です。配列に複数の要素が含まれている場合、追加の要素は PO_FX_DEVICE_V2 構造体の直後に配置されます。配列には、デバイス内のコンポーネントごとに 1 つの要素が含まれています。各コンポーネントの Fx 電源状態は、デバイス内の他のコンポーネントの Fx 電源状態とは無関係に制御できます。 ANYSIZE_ARRAY定数は、Ntdef.h ヘッダーファイルで 1 に定義されています。

注釈

デバイスを PoFx に登録するために、ドライバーは PoFxRegisterDevice ルーチンを呼び出し、パラメーターとして、デバイスを記述する PO_FX_DEVICE 構造体へのポインターを提供します。 DFx ではなく PoFx を使用するには、 PO_FX_DEVICE_V2 構造体または PO_FX_DEVICE_V3 構造体を使用して PoFx に登録します。

Components 配列の各要素は、デバイス内の 1 つのコンポーネントの電源状態属性を記述します。デバイス内の各コンポーネントは、 Components 配列インデックスによって識別されます。 PoFxActivateComponent や PoFxCompleteIdleCondition などのルーチンでは、コンポーネントの配列インデックスを使用してコンポーネントを識別します。

デバイスドライバーは、8 つのコールバックルーチンをすべて実装する必要はありません。ドライバーが対応するコールバックルーチンを実装していない場合、 ドライバーは、PO_FX_DEVICE 構造体の関数ポインターを NULL に設定できます。ただし、特定のコールバックルーチンを実装する必要があります。具体的には、デバイス内の 1 つ以上のコンポーネントに複数の Fx 状態がある場合、ドライバーは ComponentIdleStateCallback、 ComponentActiveConditionCallback、および ComponentIdleConditionCallback ルーチンを実装する必要があります。それ以外の場合、デバイスの登録は失敗し、PoFxRegisterDevice はSTATUS_INVALID_PARAMETERを返します。

ドライバーが PO_FX_DEVICE_FLAG_DISABLE_FAST_RESUME または PO_FX_DEVICE_FLAG_ENABLE_FAST_RESUME のいずれかを提供しない場合、システムはプラットフォームの既定の構成にフォールバックします。既定の構成は、x86/x64 プラットフォームでは PO_FX_DEVICE_FLAG_ENABLE_FAST_RESUME 、ARM32/ARM64 プラットフォーム の場合はPO_FX_DEVICE_FLAG_DISABLE_FAST_RESUME です。これらのフラグは Win11 22000 以降でのみ受け入れられ、以前のリリースでは無視されます。 WDF ドライバーの場合、これらのフラグは、WDF_POWER_FRAMEWORK_SETTINGSの PoFxDeviceFlags フィールドを使用して指定できます。