WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS-Struktur (wdfdevice.h)

  • Artikel

[Gilt für KMDF und UMDF]

Die WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS-Struktur enthält vom Treiber bereitgestellte Informationen, die das Framework verwendet, wenn sich ein Gerät im Leerlauf befindet und sich das System im Systembetriebszustand (S0) befindet.

Syntax

typedef struct _WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS {
  ULONG                                 Size;
  WDF_POWER_POLICY_S0_IDLE_CAPABILITIES IdleCaps;
  DEVICE_POWER_STATE                    DxState;
  ULONG                                 IdleTimeout;
  WDF_POWER_POLICY_S0_IDLE_USER_CONTROL UserControlOfIdleSettings;
  WDF_TRI_STATE                         Enabled;
  WDF_TRI_STATE                         PowerUpIdleDeviceOnSystemWake;
  WDF_POWER_POLICY_IDLE_TIMEOUT_TYPE    IdleTimeoutType;
  WDF_TRI_STATE                         ExcludeD3Cold;
} WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS, *PWDF_DEVICE_POWER_POLICY_IDLE_SETTINGS;

Member

Size

Die Größe (in Bytes) dieser Struktur.

IdleCaps

Ein WDF_POWER_POLICY_S0_IDLE_CAPABILITIES typisierter Enumerator, der die Fähigkeit des Geräts angibt, sich selbst zu reaktivieren, nachdem er auf einen Zustand mit geringer Leistung eingestellt wurde, während das System in seinem Betriebszustand (S0) verbleibt.

DxState

Ein DEVICE_POWER_STATE typisiertes Enumerator, der den Zustand der niedrigen Geräteleistung identifiziert, den das Gerät nach Ablauf des Leerlauftimeouts erhält. DEVICE_POWER_STATE Werte werden in wdm.h definiert.

IdleTimeout

Die Zeitspanne in Millisekunden, die das Gerät im Leerlauf verbleibt, bevor es vom Framework in den von DxState bereitgestellten Zustand mit geringer Leistung versetzt wird. Geben Sie IdleTimeoutDefaultValue an, um den Standardwert für Leerlauftimeout des Frameworks zu verwenden. Weitere Informationen dazu, wann das Framework das Gerät als im Leerlauf betrachtet, finden Sie unter Unterstützung des Leerlaufbetriebs.

UserControlOfIdleSettings

Ein WDF_POWER_POLICY_S0_IDLE_USER_CONTROL typisiertes Enumerator, der angibt, ob Benutzer die Möglichkeit haben, die Einstellungen im Leerlauf des Geräts zu ändern.

Enabled

Ein WDF_TRI_STATE typisierter Enumerator, der angibt, ob das Gerät ausgeschaltet wird, wenn es im Leerlauf bleibt und die Systemleistung bei S0 liegt. Dieses Element kann über einen der folgenden Werte verfügen:

WdfTrue : Das Herunterschalten ist aktiviert.

WdfFalse : Das Herunterschalten ist deaktiviert.

WdfUseDefault : Das Herunterschalten ist zunächst standardmäßig aktiviert. Wenn der UserControlOfIdleSettings-Member jedoch auf IdleAllowUserControl festgelegt ist, überschreibt die Einstellung oder die INF-Datei des Treibers den Anfangswert.

Wenn das Herunterfahren aktiviert ist, das Gerät über eine Aktivierungsfunktion verfügt und der Wert für das Leerlauftimeout abläuft, ruft das Framework die Rückruffunktion EvtDeviceArmWakeFromS0 des Treibers auf, bevor das Gerät in einen Energiesparzustand wechselt.

PowerUpIdleDeviceOnSystemWake

Ein WDF_TRI_STATE typisierter Enumerator, der angibt, ob das Gerät in seinen Arbeitszustand (D0) zurückkehrt, wenn das System in seinen Arbeitszustand (S0) zurückkehrt. Dieser Member ist nur gültig, wenn der Treiber das IdleCaps-Element auf IdleCannotWakeFromS0 festlegt. Das PowerUpIdleDeviceOnSystemWake-Element kann einen der folgenden Werte aufweisen:

WdfTrue : Wenn sich sowohl das Gerät als auch das System in einem Energiesparzustand befinden, kehrt das Gerät in seinen Betriebszustand zurück, wenn das System in seinen Betriebszustand zurückkehrt.

WdfFalse : Wenn sich sowohl das Gerät als auch das System in einem Energiesparzustand befinden, verbleibt das Gerät im Zustand mit geringer Leistung, wenn das System in den Betriebszustand zurückkehrt.

WdfUseDefault : Der Standardwert, den das Framework verwendet, wenn der Treiber keinen anderen Wert legt. Dieser Wert hat die gleiche Bedeutung wie WdfFalse.

Wenn der PowerUpIdleDeviceOnSystemWake-Member auf WdfFalse oder WdfUseDefault festgelegt ist, kehrt das Gerät nur dann in seinen Arbeitszustand zurück, wenn software auf das Gerät zugreift, z. B. wenn eine Anwendung eine E/A-Anforderung an das Gerät sendet. Weitere Informationen finden Sie unter Gerät kehrt in den Betriebszustand zurück.

Der PowerUpIdleDeviceOnSystemWake-Member ist in Version 1.9 und höher von KMDF und ab Version 2.0 von UMDF verfügbar.

IdleTimeoutType

Ein WDF_POWER_POLICY_IDLE_TIMEOUT_TYPE typisierter Enumerator, der angibt, wie das IdleTimeout-Element verwendet wird.

Das IdleTimeoutType-Element ist in Version 1.11 und höher von KMDF und ab Version 2.0 von UMDF verfügbar. Weitere Informationen finden Sie unter Hinweise.

ExcludeD3Cold

Ein WDF_TRI_STATE typisierter Enumerator, der angibt, ob der D3cold-Energiezustand eine zulässige Wahl für den Energiesparzustand sein soll, den das Gerät beim Ablauf des Leerlauftimeouts erhält. Das ExcludeD3Cold-Element kann einen der folgenden Werte aufweisen:

WdfTrue : Das Framework versetzt ein Gerät in einen D-Zustand mit geringer Leistung, wenn der Leerlaufzeitlimit abläuft. Wenn dieser D-Zustand D3 ist, wird das Gerät zu D3hot verschoben. Wenn ExcludeD3Cold auf WdfTrue festgelegt ist, ist kein weiterer Übergang von D3hot zu D3cold zulässig.

WdfFalse : Das Gerät kann in den D3cold-Energiezustand versetzt werden, wenn der Leerlaufzeitlimit abläuft, wenn alle folgenden Kriterien erfüllt sind:

  • Das DxState-Element dieser Struktur gibt PowerDeviceD3 oder PowerDeviceMaximum an.
  • Die ACPI-Firmware gibt an, dass das Gerät den D3cold-Energiezustand unterstützt.
  • Wenn der Treiber idleCanWakeFromS0 oder IdleUsbSelectiveSuspend im IdleCaps-Member dieser Struktur angegeben hat, kann das Gerät im D3cold-Energiezustand auf ein externes Aktivierungsereignis reagieren. Andernfalls gilt diese Anforderung nicht.
WdfUseDefault : Das Framework untersucht den DDInstall. HW-Abschnitt der INF-Datei des Treibers. Wenn die folgenden Zeilen vorhanden sind, hat dieser Wert die gleiche Bedeutung wie WdfFalse:
Include = machine.inf
Needs = PciD3ColdSupported
Andernfalls hat dieser Wert die gleiche Bedeutung wie WdfTrue.

Der ExcludeD3Cold-Member ist ab KMDF-Version 1.11 sowie ab Version 2.0 von UMDF verfügbar und wird in Betriebssystemen vor Windows 8 ignoriert. Weitere Informationen finden Sie unter Hinweise.

Hinweise

Die WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS-Struktur wird als Eingabe für WdfDeviceAssignS0IdleSettings verwendet.

Wenn ein Treiber WdfDeviceAssignS0IdleSettings zum ersten Mal aufruft, werden die folgenden Aktionen ausgeführt:

  • Das Framework speichert die Werte aller WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS Strukturmember.
  • Wenn der UserControlOfIdleSettings-Member auf IdleAllowUserControl festgelegt ist und der Enabled-Member auf WdfUseDefault festgelegt ist, liest das Framework die Registrierung, um herauszufinden, ob der Benutzer das Herunterschalten des Geräts im Leerlauf aktiviert hat.
Bei nachfolgenden Aufrufen von WdfDeviceAssignS0IdleSettings speichert das Framework nur die Werte der Elemente DxState, IdleTimeout und Enabled . Außerdem speichert das Framework in KMDF 1.9 und früher den Wert des IdleCaps-Members , es sei denn , der Wert ist IdleUsbSelectiveSuspend. Daher muss der Treiber die folgenden Regeln verwenden:
  • Wenn der Treiber IdleUsbSelectiveSuspend für den Wert des IdleCaps-Members angibt, muss er dies beim ersten Aufrufen von WdfDeviceAssignS0IdleSettings tun, und er kann diesen Wert anschließend nicht ändern.
  • Wenn der Treiber IdleCanWakeFromS0 oder IdleCannotWakeFromS0 beim ersten Aufruf von WdfDeviceAssignS0IdleSettings angibt, kann er anschließend WdfDeviceAssignS0IdleSettings erneut aufrufen, um diesen Wert zu ändern (der Wert kann jedoch nicht in IdleUsbSelectiveSuspend geändert werden).

Ab KMDF 1.11 und UMDF 2.0 kann ein KMDF-Treiber jederzeit zwischen IdleUsbSelectiveSuspend und IdleCannotWakeFromS0 wechseln.

Ab Windows 8 führt das Festlegen des IdleTimeoutType-Members auf SystemManagedIdleTimeoutout oder SystemManagedIdleTimeoutWithHint dazu, dass sich das Framework beim Power Management Framework (PoFx) registriert.

Wenn der Treiber die Unterstützung des funktionalen Energiezustands für ein Gerät mit mehreren Komponenten implementiert, muss der Treiber entweder IdleTimeoutType auf DriverManagedIdleTimeoutout festlegen oder WdfDeviceAssignS0IdleSettings überhaupt nicht aufrufen.

Weitere Informationen finden Sie unter Unterstützen von Funktionsenergiezuständen und Übersicht über das Power Management Framework.

Die folgenden Regeln gelten für den Wert, den Sie für den DxState-Member angeben:

  • Der Wert darf nicht PowerDeviceD0 sein.
  • Bei USB-Geräten darf der Wert nicht PowerDeviceD0 oder PowerDeviceD3 sein.
  • Wenn Sie PowerDeviceMaximum angeben, verwendet das Framework den Wert, den der Treiber für den Bus des Geräts im DeviceWake-Member seiner WDF_DEVICE_POWER_CAPABILITIES-Struktur bereitgestellt hat.
  • Wenn der Wert des IdleCaps-MembersIdleCanWakeFromS0 ist, können Sie keinen Geräteleistungszustand angeben, der niedriger als der Geräteleistungszustand im DeviceWake-Member der WDF_DEVICE_POWER_CAPABILITIES Struktur des Bustreibers ist. (Anders ausgedrückt: Wenn der DeviceWake-Wert des Bustreibers PowerDeviceD2 ist, darf der DxState-Wert Ihres Funktionstreibers nicht PowerDeviceD3 sein.)
In Betriebssystemen, die früher als Windows 8, bedeutet der D3-Netzzustand, dass sich das Gerät in einem Zustand mit geringer Leistung befindet, dass jedoch weiterhin eine gewisse Stromversorgung für den Bus beibehalten wird. Ab Windows 8 heißt der frühere D3-Energiezustand D3hot, und ein neuer Energiezustand (D3cold) ist verfügbar. Ein Gerät kann den D3cold-Zustand entweder während sich das System im Betriebszustand (S0) oder in einem Zustand mit geringer Leistung befindet. Wenn sich ein Gerät im D3cold-Netzzustand befindet, ist der Bus inaktiv, und das Gerät muss ein eigenes Wake-Signal auslösen, wenn eine externe Aktion (z. B. das Einstecken eines Netzwerkkabels) ein Hardwareereignis verursacht.

Ab KMDF 1.11 und UMDF 2.0 kann ein Gerät, das das Herunterfahren im Leerlauf unterstützt , den ExcludeD3Cold-Member dieser Struktur verwenden, um anzugeben, ob der D3cold-Energiezustand eine zulässige Wahl für den Zustand mit niedriger Geräteleistung sein soll, den das Gerät nach Ablauf des Leerlauftimeoutzeitraums eingibt.

Informationen zu Registrierungseinträgen, die die Leerlauffunktionen eines Geräts steuern, finden Sie unter Benutzersteuerung des Geräteleidle- und Aktivierungsverhaltens.

Um die WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS-Struktur zu initialisieren, sollte Ihr Treiber WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS_INIT aufrufen.

Anforderungen

Anforderung Wert
KMDF-Mindestversion 1.0
UMDF-Mindestversion 2.0
Kopfzeile wdfdevice.h (einschließen von Wdf.h)