WdfDeviceStopIdle マクロ (wdfdevice.h)
[KMDF と UMDF に適用]
WdfDeviceStopIdle メソッドは、指定されたデバイスを動作 (D0) 電源状態にする必要があることをフレームワークに通知します。
構文
NTSTATUS WdfDeviceStopIdle(
_In_ WDFDEVICE Device,
_In_ BOOLEAN WaitForD0
);
パラメーター
[in] Device
フレームワーク デバイス オブジェクトへのハンドル。
[in] WaitForD0
WdfDeviceStopIdle がいつ返されるのか示すブール値。 TRUE の場合、指定したデバイスが D0 デバイスの電源状態に入った後にのみ が返されます。 FALSE の場合、メソッドは直ちにを返します。
戻り値
なし
解説
このマクロは、次の値を返すことができます。
| 戻り値 | 説明 |
|---|---|
| STATUS_PENDING | デバイスの電源が非同期的に稼働しています。 |
| STATUS_INVALID_DEVICE_STATE | ドライバーは、デバイスの電源ポリシー所有者ではありません。 |
| STATUS_POWER_STATE_INVALID | デバイスの障害が発生し、デバイスが D0 電源状態に入ることができません。 |
メソッドは、他の NTSTATUS 値を返す場合があります。
注意
WDF_POWER_POLICY_IDLE_TIMEOUT_TYPE列挙で SystemManagedIdleTimeout または SystemManagedIdleTimeoutWithHint を指定するデバイスの場合は、 WaitForD0 をFALSE に設定して WdfDeviceStopIdle を呼び出すときに、デバイスがまだ D0 にあり、アイドル タイムアウト期間がまだ経過していない場合、WDF バージョン 1.33/2.33 以降では、WdfDeviceStopIdle は STATUS_SUCCESSを返します (以前のバージョンでは、戻り値は STATUS_PENDING になりました)。
ドライバーが無効なオブジェクト ハンドルを提供すると、バグ チェックが発生します。
デバイスがアイドル状態になったときに低電力状態になる可能性がある場合は、ドライバーが WdfDeviceStopIdle を呼び出して、デバイスを動作状態 (D0) に戻すか、低電力状態に入らないようにする必要がある場合があります。
WdfDeviceStopIdle では、システムが Sx スリープ状態に変わると、フレームワークによってデバイスがスリープ状態に移行されるのを防ぐことはありません。 その唯一の効果は、システムが S0 の動作状態にある間に Dx スリープ状態への遷移を防ぐことです。 同様に、デバイスが ダイレクト電源管理をサポートしている場合、 WdfDeviceStopIdle は、デバイスがダイレクト電源を停止するのを防ぐものではありません。
警告
WdfDeviceStopIdle を WaitForD0 = TRUE で直接または間接的に呼び出さないでください。 たとえば、 EvtDeviceArmWakeFromS0 コールバックが を呼び出 WdfDeviceStopIdle(TRUE)す別のスレッドで待機すると、電源切り替えがブロックされ、システムがクラッシュします。
デバイスがアイドル状態で、フレームワークがデバイスの電源マネージド I/O キューに I/O 要求を配置するときに、ドライバーは WdfDeviceStopIdle を呼び出す必要はありません。 さらに、デバイスがアイドル状態でウェイク シグナルが検出された場合、ドライバーは WdfDeviceStopIdle を呼び出す必要はありません。 どちらの場合も、フレームワークは、デバイスの電源状態を D0 に復元するようにバス ドライバーに要求します。
ドライバーは通常、電源マネージド I/O キューから取得した I/O 要求を処理するときに WdfDeviceStopIdle を呼び出す必要はありませんが、呼び出しは許可されます。 ただし、電源マネージド I/O キューからの I/O 要求を処理する場合、ドライバーは WaitForD0 パラメーターを TRUE に設定しないでください。
ドライバー が 電源マネージド I/O キューの外部で受信した要求のためにデバイスにアクセスする必要がある場合、ドライバーは WdfDeviceStopIdle を呼び出す必要があります。 たとえば、ドライバーは、ドライバー定義のインターフェイスまたはデバイスへのアクセスを必要とする WMI 要求をサポートする場合があります。 この場合は、ドライバーがデバイスにアクセスする前にデバイスが動作状態であること、およびドライバーがデバイスへのアクセスを完了するまでデバイスが動作状態のままであることを確認する必要があります。
システムが動作 (S0) 状態の場合、 WdfDeviceStopIdle を呼び出すと、デバイスは強制的に動作 (D0) 状態になります。 ドライバーが WdfDeviceResumeIdle を呼び出すまで、デバイスは動作状態のままです。その時点で、フレームワークはデバイスがアイドル状態のままである場合に低電力状態にすることができます。
フレームワークがドライバーの EvtDeviceD0Entry コールバック関数を初めて呼び出す前に、WdfDeviceStopIdle を呼び出さないでください。
WdfDeviceStopIdle を呼び出すと、システムが動作 (S0) 状態の場合にのみ、アイドル状態のデバイスを動作状態に復元できます。 ドライバーが WdfDeviceStopIdle を呼び出し、WaitForD0 パラメーターを TRUE に設定したときに、システムが低電力状態に移行している場合、または Sx (x > 0) に応答してデバイスの電源が既に切れている場合、この関数はシステムが S0 状態に戻るまで戻りません。
WdfDeviceStopIdle を正常に呼び出すたびに、最終的に WdfDeviceResumeIdle の呼び出しが行われる必要があります。そうしないと、デバイスが再びアイドル状態になると低電力状態に戻ることはありません。 WdfDeviceStopIdle の呼び出しは入れ子にできるため、WdfDeviceResumeIdle への呼び出しの数は、WdfDeviceStopIdle への呼び出しの数と同じである必要があります。 WdfDeviceStopIdle の呼び出しが失敗した場合は、WdfDeviceResumeIdle を呼び出さないでください。
WdfDeviceStopIdle が戻った後にシステムが低電力状態に入ると、デバイスも低電力状態になります。 システムが動作 (S0) 状態に戻ると、デバイスも動作 (D0) 状態に戻ります。 WdfDeviceStopIdle への呼び出しからの電源参照はアクティブなままであり、WdfDeviceResumeIdle の呼び出しが一致するまでデバイスが低電力状態になるのを防ぎます。
詳細については、「 アイドル状態の電源ダウンのサポート」を参照してください。
WaitForD0 が TRUE の場合、IRQL = PASSIVE_LEVELで WdfDeviceStopIdle を呼び出す必要があります。 WaitForD0 が FALSE の場合は、IRQL <= DISPATCH_LEVELでこのメソッドを呼び出す必要があります。
WdfDeviceStopIdle の代わりに WdfDeviceStopIdleWithTagを呼び出すと、Microsoft デバッガーで表示できる追加情報 (タグ値、行番号、ファイル名) が提供されます。
例
次のコード例では、指定したデバイスが D0 デバイスの電源状態に入った後に WdfDeviceStopIdle が返されます。
NTSTATUS status;
status = WdfDeviceStopIdle(Device, TRUE);
要件
| 要件 | 値 |
|---|---|
| 対象プラットフォーム | ユニバーサル |
| 最小 KMDF バージョン | 1.0 |
| 最小 UMDF バージョン | 2.0 |
| Header | wdfdevice.h (Wdf.h を含む) |
| Library | Wdf01000.sys (KMDF);WUDFx02000.dll (UMDF) |
| IRQL | 「解説」を参照してください。 |
| DDI コンプライアンス規則 | DriverCreate(kmdf)、 KmdfIrql(kmdf)、 KmdfIrql2(kmdf)、KmdfIrqlExplicit(kmdf) |