WdfDeviceStopIdle-Makro (wdfdevice.h)

Artikel
02/27/2024

[Gilt für KMDF und UMDF]

Die WdfDeviceStopIdle-Methode informiert das Framework darüber, dass das angegebene Gerät in den Betriebszustand (D0) versetzt werden muss.

Syntax

NTSTATUS WdfDeviceStopIdle(
   _In_ WDFDEVICE Device,
   _In_ BOOLEAN WaitForD0
);

Parameter

[in] Device

Ein Handle für ein Framework-Geräteobjekt.

[in] WaitForD0

Ein boolescher Wert, der angibt, wann WdfDeviceStopIdle zurückgegeben wird. Wenn true, wird es erst zurückgegeben, nachdem das angegebene Gerät in den D0-Gerätestromzustand eingetreten ist. Wenn FALSE, gibt die Methode sofort zurück.

Rückgabewert

Keine

Bemerkungen

Dieses Makro kann die folgenden Werte zurückgeben:

Rückgabewert	Bedeutung
STATUS_PENDING	Das Gerät wird asynchron eingeschaltet.
STATUS_INVALID_DEVICE_STATE	Der Treiber ist nicht der Besitzer der Energierichtlinie für das Gerät.
STATUS_POWER_STATE_INVALID	Es ist ein Gerätefehler aufgetreten, und das Gerät kann nicht in den D0-Netzzustand gelangen.

Die -Methode gibt möglicherweise andere NTSTATUS-Werte zurück.

Hinweis

Für Geräte, die SystemManagedIdleTimeout oder SystemManagedIdleTimeoutWithHint in der WDF_POWER_POLICY_IDLE_TIMEOUT_TYPE-Enumeration angeben, wenn WdfDeviceStopIdle aufgerufen wird und WaitForD0 auf FALSE festgelegt ist, wenn sich das Gerät noch in D0 befindet und der Leerlaufzeitpunkt noch nicht abgelaufen ist, gibt WdfDeviceStopIdle ab WDF-Versionen 1.33/2.33 STATUS_SUCCESS zurück (in früheren Versionen hat dies zu einem Rückgabewert von STATUS_PENDING geführt).

Eine Fehlerüberprüfung tritt auf, wenn der Treiber ein ungültiges Objekthandle bereitstellt.

Wenn Ihr Gerät im Leerlauf in einen Zustand mit geringer Leistung gelangen kann, muss Ihr Treiber möglicherweise gelegentlich WdfDeviceStopIdle aufrufen, um das Gerät wieder in den Betriebszustand (D0) zu versetzen oder zu verhindern, dass es in einen Zustand mit niedriger Leistung wechselt.

WdfDeviceStopIdle verhindert nicht, dass das Framework das Gerät in einen Ruhezustand überführt, wenn das System in einen Sx-Ruhezustand wechselt. Die einzige Auswirkung besteht darin, Übergänge zu Dx-Ruhezuständen zu verhindern, während sich das System im Arbeitszustand S0 befindet. Wenn das Gerät die gesteuerte Energieverwaltung unterstützt, verhindert WdfDeviceStopIdle nicht, dass das Gerät direkt heruntergefahren wird.

Warnung

Rufen Sie WdfDeviceStopIdle während des Herunterschaltens nicht direkt oder indirekt mit WaitForD0 = TRUE auf. Wenn beispielsweise der EvtDeviceArmWakeFromS0-Rückruf auf einen anderen Thread wartet, der aufruft WdfDeviceStopIdle(TRUE), wird der Energieübergang blockiert, und das System stürzt ab.

Ihr Treiber muss WdfDeviceStopIdlenicht aufrufen, wenn sich ein Gerät im Leerlauf befindet und das Framework eine E/A-Anforderung in der energieverwalteten E/A-Warteschlange des Geräts platziert. Darüber hinaus muss Ihr Treiber WdfDeviceStopIdlenicht aufrufen, wenn sich ein Gerät im Leerlauf befindet und ein Aktivierungssignal erkennt. In beiden Fällen fordert das Framework den Bustreiber auf, den Energiezustand des Geräts auf D0 wiederherzustellen.

Obwohl Treiber WdfDeviceStopIdle normalerweise nicht aufrufen müssen, wenn sie E/A-Anforderungen verarbeiten, die sie aus einer energieverwalteten E/A-Warteschlange abrufen, ist der Aufruf zulässig. Treiber dürfen den WaitForD0-Parameter jedoch nicht auf TRUE festlegen, wenn E/A-Anforderungen aus einer energieverwalteten E/A-Warteschlange verarbeitet werden.

Ihr Treiber mussWdfDeviceStopIdle aufrufen, wenn er aufgrund einer Anforderung, die der Treiber außerhalb einer energieverwalteten E/A-Warteschlange erhalten hat, auf das Gerät zugreifen muss. Ihr Treiber kann beispielsweise eine vom Treiber definierte Schnittstelle oder eine WMI-Anforderung unterstützen, die den Zugriff auf das Gerät erfordert. In diesem Fall müssen Sie sicherstellen, dass sich das Gerät im Betriebszustand befindet, bevor der Treiber auf das Gerät zugreift, und dass das Gerät in seinem Betriebszustand bleibt, bis der Treiber den Zugriff auf das Gerät abgeschlossen hat.

Das Aufrufen von WdfDeviceStopIdle zwingt das Gerät in den Betriebszustand (D0), wenn sich das System im Arbeitszustand (S0) befindet. Das Gerät bleibt in seinem Arbeitszustand, bis der Treiber WdfDeviceResumeIdle aufruft. An diesem Punkt kann das Framework das Gerät in einen Energiesparzustand versetzen, wenn es im Leerlauf verbleibt.

Rufen Sie WdfDeviceStopIdle nicht auf, bevor das Framework die EvtDeviceD0Entry-Rückruffunktion des Treibers zum ersten Mal aufgerufen hat.

Ein Aufruf von WdfDeviceStopIdle kann ein Gerät im Leerlauf nur dann in seinen Betriebszustand wiederherstellen, wenn sich das System im Betriebszustand (S0) befindet. Wenn das System in einen Zustand mit geringer Leistung wechselt oder das Gerät als Reaktion auf Sx (wobei x > 0) bereits heruntergefahren wurde, wenn ein Treiber WdfDeviceStopIdle aufruft und der WaitForD0-Parameter auf TRUE festgelegt ist, wird die Funktion erst zurückgegeben, wenn das System in den S0-Zustand zurückkehrt.

Jedem erfolgreichen Aufruf von WdfDeviceStopIdle muss schließlich ein Aufruf von WdfDeviceResumeIdle folgen, andernfalls kehrt das Gerät nie wieder in einen Energiesparzustand zurück, wenn es wieder im Leerlauf ist. Aufrufe von WdfDeviceStopIdle können geschachtelt werden, sodass die Anzahl der Aufrufe von WdfDeviceResumeIdle der Anzahl von Aufrufen von WdfDeviceStopIdle entsprechen muss. Rufen Sie WdfDeviceResumeIdle nicht auf, wenn ein Aufruf von WdfDeviceStopIdle fehlschlägt.

Wenn das System nach der Rückgabe von WdfDeviceStopIdle in einen Energiesparzustand wechselt, wechselt das Gerät auch in einen Energiesparzustand. Wenn das System in seinen Arbeitszustand (S0) zurückkehrt, kehrt das Gerät auch in den Arbeitszustand (D0) zurück. Der Energieverweis aus dem Aufruf von WdfDeviceStopIdle bleibt aktiv und verhindert, dass das Gerät in einen Zustand mit niedriger Leistung wechselt, bis ein übereinstimmender Aufruf von WdfDeviceResumeIdle vorliegt.

Weitere Informationen finden Sie unter Unterstützung des Powerdowns im Leerlauf.

Wenn WaitForD0TRUE ist, muss WdfDeviceStopIdle unter IRQL = PASSIVE_LEVEL aufgerufen werden. Wenn WaitForD0FALSE ist, muss diese Methode unter IRQL <= DISPATCH_LEVEL aufgerufen werden.

Das Aufrufen von WdfDeviceStopIdleWithTag anstelle von WdfDeviceStopIdle stellt zusätzliche Informationen (Tagwert, Zeilennummer und Dateiname) bereit, die Sie in Microsoft-Debuggern anzeigen können.

Beispiele

Im folgenden Codebeispiel wird WdfDeviceStopIdle zurückgegeben, nachdem das angegebene Gerät in den D0-Gerätestromzustand eingetreten ist.

NTSTATUS  status;

status = WdfDeviceStopIdle(Device, TRUE);

Anforderungen

Anforderung	Wert
Zielplattform	Universell
KMDF-Mindestversion	1.0
UMDF-Mindestversion	2.0
Kopfzeile	wdfdevice.h (einschließen von Wdf.h)
Bibliothek	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	Weitere Informationen finden Sie im Abschnitt mit den Hinweisen.
DDI-Complianceregeln	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Freigeben über