PO_FX_COMPONENT_IDLE_STATE_CALLBACK コールバック関数 (wdm.h)

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

ComponentIdleStateCallback コールバックルーチンは、指定されたコンポーネントの Fx 電源状態に対する保留中の変更をドライバーに通知します。

構文

PO_FX_COMPONENT_IDLE_STATE_CALLBACK PoFxComponentIdleStateCallback;

void PoFxComponentIdleStateCallback(
  [in] PVOID Context,
  [in] ULONG Component,
  [in] ULONG State
)
{...}

パラメーター

[in] Context

デバイスコンテキストへのポインター。デバイスドライバーは、このコンテキストを使用して、デバイスの現在の電源状態に関する情報を格納します。デバイスドライバーは、デバイスを電源管理フレームワーク (PoFx) に登録するためにドライバーが使用したPO_FX_DEVICE構造体の DeviceContext メンバーにこのポインターを指定しました。このコンテキストは PoFx に対して不透明です。

[in] Component

コンポーネント番号を指定します。このパラメーターは、デバイスドライバーが PoFx にデバイスを登録するために使用したPO_FX_DEVICE構造体の Components 配列へのインデックスです。 Components 配列に N 個の要素が含まれている場合、コンポーネントインデックスの範囲は 0 から N-1 です。

[in] State

コンポーネントが変更される新しい Fx 電源状態を指定します。このパラメーターが 0 の場合、新しい状態は F0 になります。このパラメーターが 1 の場合、新しい状態は F1 になります。などなど。

戻り値

なし

解説

PoFx がドライバーの ComponentIdleStateCallback ルーチンを呼び出すとき、ドライバーは保留中の Fx 状態の変更に備える必要がある場合があります。必要な準備が完了したら、ドライバーは PoFxCompleteIdleState ルーチンを呼び出して、 ドライバーが ComponentIdleStateCallback コールバックへの応答を完了したことを PoFx に通知する必要があります。 PoFxCompleteIdleState 呼び出しは、ComponentIdleStateCallback ルーチンが戻る前または後に行うことができます。

コンポーネントが F0 から、デバイスがコンポーネントのハードウェア状態を失う低電力 Fx 状態に切り替える場合、ドライバーは、新しい Fx 状態への移行が発生する前に、コンポーネントのハードウェア状態を保存する必要があります。コンポーネントが低電力 Fx 状態から F0 に切り替え、ハードウェアの状態が以前に保存されている場合、ドライバーは、電源がコンポーネントに復元された後、ハードウェアの状態を復元する必要があります。

一部のデバイスでは、デバイスハードウェアでコンポーネントの電源状態が制御される場合があります。これらのデバイスの場合、ドライバーは通常、コンポーネントの電源状態を変更する役割を担います。他のデバイスの場合、コンポーネントの電源状態は、デバイスの外部にあるハードウェアによって制御される場合があり、ドライバーは通常、コンポーネントの電源状態を構成するために PoFx に依存する必要があります。

ドライバーがコンポーネントの電源状態の構成を担当する場合、ドライバーは ComponentIdleStateCallback コールバックに応答して電源状態を変更する必要があります。 F0 から低電力 Fx 状態への移行の場合、コンポーネントは ComponentIdleStateCallback ルーチンへのエントリ時に F0 になり、ドライバーは PoFxCompleteIdleState を呼び出す前にコンポーネントを新しい Fx 状態に切り替える必要があります。低電力 Fx 状態から F0 に移行する場合、コンポーネントは ComponentIdleStateCallback ルーチンへのエントリ時に低電力 Fx 状態になり、ドライバーは PoFxCompleteIdleState を呼び出す前にコンポーネントを F0 に切り替える必要があります。

ドライバーがコンポーネントの電源状態を構成する責任がない場合、ドライバーはコンポーネントが ComponentIdleStateCallback ルーチンへのエントリ時に常に F0 状態であると想定する必要があります。 F0 から低電力 Fx 状態への保留中の遷移の場合、ドライバーが PoFxCompleteIdleState を呼び出すまで、新しい Fx 状態への遷移は発生しません。低電力 Fx 状態から F0 への移行では、 ComponentIdleStateCallback ルーチンが呼び出される前に F0 への遷移が発生します。

PoFx は ComponentIdleStateCallback ルーチンを呼び出して、1 つの低電力 Fx 状態から別の低電力 Fx 状態に直接切り替えることはありません。たとえば、PoFxSetComponentLatency、PoFxSetComponentResidency、または PoFxSetComponentWake ルーチンの呼び出しに応じて、PoFx で 1 つの低電力 Fx 状態から別の状態にコンポーネントを切り替える必要がある場合があります。この場合、PoFx は最初に ComponentIdleStateCallback ルーチンを呼び出して古い Fx 状態から F0 に切り替え、次に ComponentIdleStateCallback ルーチンを 2 回目に呼び出して F0 から新しい Fx 状態に切り替えます。

例

ComponentIdleStateCallback コールバックルーチンを定義するには、まず、定義するコールバックルーチンの種類を識別する関数宣言を指定する必要があります。 Windows には、ドライバーのコールバック関数型のセットが用意されています。コールバック関数の種類を使用して関数を宣言すると、ドライバーのコード分析、静的ドライバー検証ツール (SDV)、およびその他の検証ツールでエラーが検出され、Windows オペレーティングシステムのドライバーを記述するための要件になります。

たとえば、という名前MyComponentIdleStateCallbackの ComponentIdleStateCallback コールバックルーチンを定義するには、次のコード例に示すように、PO_FX_COMPONENT_IDLE_STATE_CALLBACK型を使用します。

PO_FX_COMPONENT_IDLE_STATE_CALLBACK MyComponentIdleStateCallback;

次に、コールバックルーチンを次のように実装します。

_Use_decl_annotations_
VOID
  MyComponentIdleStateCallback(
    PVOID Context,
    ULONG Component,
    ULONG State
    )
  {
      // Function body
  }

PO_FX_COMPONENT_IDLE_STATE_CALLBACK関数の種類は、Wdm.h ヘッダーファイルで定義されています。コード分析ツールの実行時にエラーをより正確に識別するには、必ず注釈を _Use_decl_annotations_ 関数定義に追加してください。注釈を _Use_decl_annotations_ 使用すると、ヘッダーファイル内のPO_FX_COMPONENT_IDLE_STATE_CALLBACK関数型に適用される注釈が確実に使用されます。関数宣言の要件の詳細については、「 WDM ドライバーの関数ロール型を使用して関数を宣言する」を参照してください。の詳細 _Use_decl_annotations_については、「関数の動作に注釈を付ける」を参照してください。

要件

要件	値
サポートされている最小のクライアント	Windows 8 以降のバージョンの Windows でサポートされています。
対象プラットフォーム	デスクトップ
Header	wdm.h (Wudfwdm.h を含む)
IRQL	IRQL <= DISPATCH_LEVELで呼び出されます。