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 的裝置， 當呼叫 WdfDeviceStopIdle 並將 WaitForD0 設定為 FALSE 時，如果裝置仍在 D0 且閒置逾時期間尚未經過，則從 WDF 1.33/2.33 版開始，WdfDeviceStopIdle 會傳回先前版本中的 STATUS_SUCCESS (，這會導致傳回值STATUS_PENDING) 。

如果驅動程式提供無效的物件句柄，就會發生錯誤檢查。

如果您的裝置在閑置時可以進入低電源狀態，您的驅動程式可能必須偶爾呼叫 WdfDeviceStopIdle ，讓裝置回到其運作 (D0) 狀態，或防止其進入低電源狀態。

WdfDeviceStopIdle 不會在系統變更為 Sx 睡眠狀態時，防止架構將裝置轉換為睡眠狀態。 其唯一的效果是防止在系統處於 S0 運作狀態時轉換為 Dx 睡眠狀態。 同樣地，如果裝置支援 導向電源管理， WdfDeviceStopIdle 不會防止裝置進入向下電源。

警告

請勿在關閉電源期間直接或間接呼叫具有 WaitForD0 = TRUE 的 WdfDeviceStopIdle。 例如，如果 EvtDeviceArmWakeFromS0 回呼等候另一個呼叫 WdfDeviceStopIdle(TRUE)的線程，則會封鎖電源轉換，且系統當機。

當裝置閑置時，驅動程式 不需要 呼叫 WdfDeviceStopIdle ，而且架構會將 I/O 要求放在裝置的電源受控 I/O 佇列中。 此外，您的驅動程式 不需要 在裝置閑置且偵測到喚醒訊號時呼叫 WdfDeviceStopIdle 。 在這兩種情況下，架構會要求總線驅動程式將裝置的電源狀態還原至 D0。

雖然驅動程式通常不需要在處理從電源管理的 I/O 佇列取得的 I/O 要求時呼叫 WdfDeviceStopIdle ，但允許呼叫。 不過，從電源管理的 I/O 佇列處理 I/O 要求時，驅動程式不得將 WaitForD0 參數設定為 TRUE 。

如果驅動程式必須存取裝置，則 驅動程式必須呼叫WdfDeviceStopIdle ，因為驅動程式已在電源管理的 I/O 佇列外部收到要求。 例如，您的驅動程式可能支援驅動程式定義的介面或需要存取裝置的 WMI 要求。 在此情況下，您必須確定裝置在驅動程式存取裝置之前處於其工作狀態，而且裝置會維持在其工作狀態，直到驅動程式完成存取裝置為止。

呼叫 WdfDeviceStopIdle 會強制裝置進入其運作 (D0) 狀態，如果系統處於其運作 (S0) 狀態。 裝置會維持在其運作狀態，直到驅動程式呼叫 WdfDeviceResumeIdle 為止，當架構保持閑置狀態時，該架構可以將裝置置於低電源狀態。

在架構第一次呼叫驅動程式的 EvtDeviceD0Entry 回呼函式之前，請勿呼叫 WdfDeviceStopIdle。

呼叫 WdfDeviceStopIdle 時，只有當系統處於其工作 (S0) 狀態時，才會將閒置裝置還原到其工作狀態。 如果系統轉換為低電源狀態，或裝置已關閉電源，以回應 Sx () 當 > 驅動程式呼叫 WdfDeviceStopIdle 且 WaitForD0 參數設定為 TRUE 的 WdfDeviceStopIdle 時，函式不會傳回，直到系統回到其 S0 狀態為止。

每次成功呼叫 WdfDeviceStopIdle 時，最後都必須接聽 WdfDeviceResumeIdle 的呼叫，否則如果裝置再次變成閑置狀態，則永遠不會回到低電量狀態。 WdfDeviceStopIdle 的呼叫可以巢狀化，因此 WdfDeviceResumeIdle 的呼叫數目必須等於 WdfDeviceStopIdle 的呼叫數目。 如果呼叫 WdfDeviceStopIdle 失敗，請勿呼叫 WdfDeviceResumeIdle。

如果系統在 WdfDeviceStopIdle 傳回後進入低電源狀態，裝置也會進入低電源狀態。 當系統回到其運作 (S0) 狀態時，裝置也會回到其運作 (D0) 狀態。 從呼叫 WdfDeviceStopIdle 的電源參考會維持作用中狀態，並防止裝置進入低電源狀態，直到 WdfDeviceResumeIdle 有相符的呼叫為止。

如需詳細資訊，請參閱 支援閑置電源關閉。

如果 WaitForD0 為 TRUE，則必須在 IRQL = PASSIVE_LEVEL呼叫 WdfDeviceStopIdle 。 如果 WaitForD0 為 FALSE，則必須在 IRQL <= DISPATCH_LEVEL呼叫此方法。

呼叫 WdfDeviceStopIdleWithTag 而不是 WdfDeviceStopIdle 提供您可以在 Microsoft 調試程序中檢視的其他資訊 (標記值、行號和) 檔名。

範例

在下列程式代碼範例中， WdfDeviceStopIdle 會在指定的裝置進入 D0 裝置電源狀態之後傳回。

NTSTATUS  status;

status = WdfDeviceStopIdle(Device, TRUE);

規格需求

需求 值
目標平台 Universal
最低 KMDF 版本 1.0
最低UMDF版本 2.0
標頭 wdfdevice.h (包含 Wdf.h)
程式庫 Wdf01000.sys (KMDF) ;WUDFx02000.dll (UMDF)
IRQL 請參閱一節。
DDI 合規性規則 DriverCreate (kmdf) 、 KmdfIrql (kmdf) 、 KmdfIrql2 (kmdf) 、 KmdfIrqlExplicit (kmdf)

另請參閱