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

  • [アーティクル]

GetIdleWakeInfo ルーチンを使用すると、デバイスのドライバーは、デバイスがウェイク イベントを通知できるデバイスの電源状態を検出できます。

構文

GET_IDLE_WAKE_INFO GetIdleWakeInfo;

NTSTATUS GetIdleWakeInfo(
  [in, optional] PVOID Context,
  [in]           SYSTEM_POWER_STATE SystemPowerState,
  [out]          PDEVICE_WAKE_DEPTH DeepestWakeableDstate
)
{...}

パラメーター

[in, optional] Context

インターフェイス固有のコンテキスト情報へのポインター。 呼び出し元は、インターフェイスのD3COLD_SUPPORT_INTERFACE構造体の Context メンバーの値にこのパラメーターを設定します。

[in] SystemPowerState

システムの電源状態。 このパラメーターを、次のいずれかのSYSTEM_POWER_STATE列挙値 に 設定します。

  • PowerSystemWorking
  • PowerSystemSleeping1
  • PowerSystemSleeping2
  • PowerSystemSleeping3
  • PowerSystemHibernate
これらの値は、システム電源状態 S0 (システム動作状態) から S4 を表します。 呼び出し元によって提供される SystemPowerState 値の場合、ルーチンは、デバイスがスリープ解除信号を発行できる最も深いデバイスの電源状態を決定します。

[out] DeepestWakeableDstate

最も深いウェイク可能な Dx 状態。 このパラメーターは、 DEVICE_WAKE_DEPTH 変数へのポインターです。 呼び出しが成功した場合、ルーチンは次のいずれかの列挙値をこの変数に書き込みます。

  • DeviceWakeDepthNotWakeable
  • DeviceWakeDepthD0
  • DeviceWakeDepthD1
  • DeviceWakeDepthD2
  • DeviceWakeDepthD3hot
  • DeviceWakeDepthD3cold
DeviceWakeDepthD0 から DeviceWakeDepthD3cold の範囲の値は、コンピューターが SystemPowerState パラメーターで指定されたシステム電源状態のときに、デバイスがウェイク信号を送信できる最も低い電源の Dx 状態を示します。 DeviceWakeDepthNotWakeable は、コンピューターが SystemPowerState で指定されたシステム電源状態にあるときに、デバイスがウェイク信号を送信できるデバイスの電源状態がないことを示します。

ルーチンが最も深いスリープ解除可能なデバイスの状態を特定できない場合 (プラットフォーム ファームウェアにこの情報が含まれていない可能性があります)、呼び出しは失敗し、ルーチンはエラー状態コードを返します。 PowerSystemWorking から PowerSystemHibernate までの範囲の SystemPowerState パラメーター値に対して GetIdleWakeInfo 呼び出しが失敗した場合、そのような値はすべて失敗します。

戻り値

GetIdleWakeInfo ルーチンは、最も深いスリープ解除可能なデバイスの状態を正常に取得した場合、STATUS_SUCCESSを返します。 それ以外の場合は、適切なエラー状態コードが返されます。

注釈

呼び出し元によって指定されたシステム電源状態の場合、このルーチンは、デバイスがウェイク イベントをプロセッサに通知できる最も低い電源デバイスの電源状態を決定しようとします。 成功した場合、ルーチンはデバイスの電源状態を DeepestWakeableDstate パラメーターが指す場所に書き込み、STATUS_SUCCESSを返します。 または、デバイスがデバイスの電源状態からウェイク イベントを通知できないとルーチンが判断した場合、ルーチンは値 DeviceWakeDepthNotWakeable をこの場所に書き込み、STATUS_SUCCESSを返します。

デバイスのドライバーは、 GetIdleWakeInfo ルーチンによって提供される情報を使用して、デバイスがウェイク イベントを通知できる条件を決定します。 特定のウェイク イベントを通知できる必要があるデバイスは、これらのイベントを通知できないデバイスの電源状態に入るべきではありません。 一部の種類のデバイスでは、コンピューターが S0 (動作中) のシステム電源状態のときにデバイスが送信する必要があるウェイク信号は、コンピューターがオフになっているように見える場合にデバイスが送信する必要がある電源とは異なります。

たとえば、カードが PCI Express カード スロットに挿入され、スロットの PCI Express ホット プラグ コントローラー デバイスが D0 デバイスの電源状態にある場合、このデバイスはプロセッサに割り込みを通知します。 ただし、カードが挿入されたときにコントローラー デバイスが低電力 Dx 状態の場合、コンピューターのシステム電源状態によって、このデバイスがウェイク イベントをプロセッサに通知する必要があるかどうかを判断する場合があります。 理想的には、コントローラー デバイスは次のように動作する必要があります。

  • コンピューターが S0 (動作中) システムの電源状態にある場合、デバイスはウェイク イベントをプロセッサに通知する必要があります。
  • コンピューターがスリープ状態 (低電力 Sx 状態) の場合、デバイスはスリープ解除イベントを通知しないようにする必要があります。
一部の古いデバイスでは、この理想的な動作がサポートされていない場合があります。 この例の PCI Express ホット プラグ コントローラー デバイスがスリープ解除イベントを通知できるのは、コンピューターが S3 状態の場合のみである場合、コントローラーのドライバー (この場合は受信トレイ Pci.sys ドライバー) は、コンピューターが S0 にあるときにコントローラーを D0 に保持する必要があります (スリープ状態に入る準備が整っていない)。

この例のドライバーは 、GetIdleWakeInfo ルーチンを呼び出して、コンピューターが S0 の間にホット プラグ コントローラー デバイスを D0 状態のままにするかどうかを判断できます。 この呼び出しでは、ドライバーは SystemPowerState = PowerSystemWorking を設定します。 このデバイスは、次のいずれかの場合に D0 状態 (コンピューターが S0 の場合) のままにしないでください。

  • GetIdleWakeInfo 呼び出しは、出力パラメーターを DeviceWakeDepthNotWakeable または DeviceWakeDepthD0 に設定し、STATUS_SUCCESSを返します。
  • GetIdleWakeInfo 呼び出しが失敗し、エラー状態コードが返されます。
ドライバーは、コンピューターが S0 の場合、デバイスがウェイク イベントを通知できないことを意味するこれらの結果のいずれかを解釈する必要があります。 この情報に基づいて、コンピューターが S0 の終了を準備するまで、ドライバーはデバイスを D0 に保持する必要があります。

ほとんどのデバイスのドライバーは、 DeviceWakeDepthD0 の出力値を DeviceWakeDepthNotWakeable と同じように扱うことができます。 デバイスが D0 にあるときにウェイク 信号をアームする理由があるのは、少数のドライバーだけです。 これらは、デバイスが D0 状態か低電力 Dx 状態かに関係なく、スリープ解除信号をトリガーする外部イベントを監視する単純なデバイスのドライバーです。 このようなデバイスの例として、コンピューターの電源ボタンまたはスリープ ボタンがあります。

GetIdleWakeInfo ルーチンは、基になるバス ドライバーと ACPI システム ファームウェアに対してクエリを実行して、デバイスがウェイク イベントを通知できる最も低いデバイス電源状態を判断します。 バス ドライバーとファームウェアがこの情報を指定できない場合、ルーチンは失敗し、エラー状態コードを返します。

DEVICE_CAPABILITIES構造体には、GetIdleWakeInfo ルーチンから入手できるのと同様の情報を提供する DeviceWake メンバーが含まれています。 ただし、 DeviceWake メンバーの情報は、システムの低電力状態 S1 から S4 にのみ適用されます。 デバイスによっては、 DeviceWake メンバーの情報が S0 システムの電源状態にも適用される場合がありますが、ドライバーはこのような動作に依存しないようにする必要があります。 GetIdleWakeInfo ルーチンのみが、コンピューターが S0 にある場合にスリープ解除イベントを通知するデバイスの機能を確実に報告します。

インライン ヘルパー関数 MapWakeDepthToDstate は、GetIdleWakeInfo ルーチンのDEVICE_WAKE_DEPTH出力値を、PoRequestPowerIrp ルーチンによって入力パラメーターとして使用できるDEVICE_POWER_STATE値に変換するために提供されます。

要件

要件 値
サポートされている最小のクライアント Windows 8以降で使用できます。
対象プラットフォーム デスクトップ
Header wdm.h (Wdm.h を含む)
IRQL PASSIVE_LEVEL

こちらもご覧ください

D3COLD_SUPPORT_INTERFACE

DEVICE_CAPABILITIES

DEVICE_POWER_STATE

DEVICE_WAKE_DEPTH

PoRequestPowerIrp

SYSTEM_POWER_STATE