WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS Struktur (wdfdevice.h)

Artikel
03/22/2025

[Gilt für KMDF und UMDF]

Die WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS-Struktur enthält vom Treiber bereitgestellte Informationen zur Fähigkeit eines Geräts, sich selbst und das System zu reaktivieren, wenn sich beide in einem Zustand mit geringem Stromverbrauch befinden.

Syntax

typedef struct _WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS {
  ULONG                                 Size;
  DEVICE_POWER_STATE                    DxState;
  WDF_POWER_POLICY_SX_WAKE_USER_CONTROL UserControlOfWakeSettings;
  WDF_TRI_STATE                         Enabled;
  BOOLEAN                               ArmForWakeIfChildrenAreArmedForWake;
  BOOLEAN                               IndicateChildWakeOnParentWake;
} WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS, *PWDF_DEVICE_POWER_POLICY_WAKE_SETTINGS;

Elemente

Size

Die Größe dieser Struktur in Byte.

DxState

Ein DEVICE_POWER_STATE-typed-Enumerator, der den niedrigen Geräteleistungszustand identifiziert,, in den das Gerät wechselt, wenn der Systemstromzustand in einen weckbaren Energiesparzustand fällt. Der Wert von DxState kann nicht PowerDeviceD0werden. DEVICE_POWER_STATE Werte werden in wdm.hdefiniert.

UserControlOfWakeSettings

Ein WDF_POWER_POLICY_SX_WAKE_USER_CONTROL-typed-Enumerator, der angibt, ob Benutzer die Aktivierungseinstellungen des Geräts ändern können.

Enabled

Ein WDF_TRI_STATE-typed-Enumerator, der angibt, ob das Gerät das System reaktivieren kann (d. h. das System auf S0 wiederherstellen), wenn sich das System in einem Energiesparzustand befindet. Dieses Element kann einen der folgenden Werte aufweisen:

WdfTrue – Das Aufwachen des Systems ist aktiviert.

WdfFalse – Das Aufwachen des Systems ist deaktiviert.

WdfUseDefault- – Das Aufwachen des Systems ist standardmäßig aktiviert; wenn der UserControlOfWakeSettings Member jedoch auf WakeAllowUserControlfestgelegt ist, überschreibt die EINSTELLUNG oder die INF-Datei des Benutzers den Anfangswert.

Wenn das System aktiviert ist und das System in einen Energiesparzustand wechselt, ruft das Framework die EvtDeviceArmWakeFromSx oder EvtDeviceArmWakeFromSxWithReason Rückruffunktion auf, bevor das Gerät in einen Energiesparzustand wechselt.

ArmForWakeIfChildrenAreArmedForWake

Ein boolescher Wert, der bei Festlegung auf TRUEangibt, dass die Fähigkeit eines übergeordneten Geräts, sich selbst zu reaktivieren, und das System aktiviert werden sollte, wenn diese Möglichkeit für die untergeordneten Geräte des Geräts aktiviert ist. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise". Dieser Member ist in Version 1.7 und höheren Versionen von KMDF verfügbar.

IndicateChildWakeOnParentWake

Ein boolescher Wert, der bei Festlegung auf TRUEangibt, dass das Framework den Status "Aufwachen" für untergeordnete Geräte bereitstellt, wenn ein übergeordnetes Gerät ein Reaktivierungssignal erkennt. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise". Dieser Member ist in Version 1.7 und höheren Versionen von KMDF verfügbar.

Bemerkungen

Die WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS Struktur wird als Eingabe für WdfDeviceAssignSxWakeSettingsverwendet.

Um die WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS Struktur zu initialisieren, sollte ihr Treiber WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS_INITaufrufen.

Wenn ein Treiber zum ersten Mal WdfDeviceAssignSxWakeSettingsaufruft, treten die folgenden Aktionen auf:

Das Framework speichert die Werte aller WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS Strukturmmber.
Wenn der UserControlOfWakeSettings Member auf WakeAllowUserControl festgelegt ist und das Enabled Member auf WdfUseDefaultfestgelegt ist, liest das Framework die Registrierung vor, um herauszufinden, ob der Benutzer das Aktivieren des Systems aktiviert hat.

Bei nachfolgenden Aufrufen von WdfDeviceAssignSxWakeSettingsspeichert das Framework nicht den Wert des UserControlOfWakeSettings Member. Das Framework führt also die folgenden Schritte aus, wenn der Treiber zum ersten Mal WdfDeviceAssignSxWakeSettings aufruft, aber nicht während späterer Aufrufe:

Speichert den Wert des UserControlOfWakeSettings Member.
Sucht nach einer Benutzereinstellung in der Registrierung, wenn der Wert des Enabled Member WdfUseDefaultist.

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

Der Wert kann nicht PowerDeviceD0werden.
Wenn Sie PowerDeviceMaximumangeben, 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.
Sie können keinen Gerätestromzustand angeben, der niedriger als der Gerätestromzustand im DeviceWake Mitglied der WDF_DEVICE_POWER_CAPABILITIES Struktur des Bustreibers ist. (Wenn der DeviceWake-Wert des Bustreibers Wert PowerDeviceD2ist, kann der DxState-Wert des Funktionstreibers nicht PowerDeviceD3.)

Informationen zu Registrierungseinträgen, die die Wake-Funktionen eines Geräts steuern, finden Sie unter Benutzersteuerung des Geräte-Idle- und Wake-Verhaltens.

Wenn das Von der WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS-Struktur beschriebene Gerät ein übergeordnetes Gerät ist, kann der Treiber für das übergeordnete Gerät die ArmForWakeIfChildrenAreArmedForWake und IndicateChildWakeOnParentWarentWake Member wie folgt verwenden:

Wenn der Treiber den ArmForWakeIfChildrenAreArmedForWake Member auf TRUEfestlegt, ruft das Framework die EvtDeviceArmWakeFromSx oder EvtDeviceArmWakeFromSxWithReason Rückruffunktion auf, wenn die Wake-Fähigkeit eines untergeordneten Geräts aktiviert ist, auch wenn die Aktivierungsfunktion des übergeordneten Geräts nicht aktiviert ist.
Um den Stromverbrauch zu verringern, möchten Sie die Aktivierungsfunktion Ihres Geräts möglicherweise nicht aktivieren, es sei denn, ein untergeordnetes Gerät, das auch eine Aktivierungsmöglichkeit unterstützt, ist eingesteckt. Wenn Ihr Treiber den ArmForWakeIfChildrenAreArmedForWake Member auf TRUEfestlegt, haben die Werte des Enabled Member die folgenden Bedeutungen:
- Wenn EnabledWdfFalse-ist, aktiviert das Framework die Aktivierungsfunktion Ihres Treibers nur, wenn die Aktivierungsfunktion eines untergeordneten Geräts aktiviert ist.
- Wenn EnabledWdfTrue-ist, aktiviert das Framework immer die Aktivierungsmöglichkeit Ihres Treibers, unabhängig davon, ob Ihr Gerät untergeordnete Geräte aktiviert hat oder nicht.
- Wenn EnabledWdfUseDefault und UserControlOfWakeSettingsWakeAllowUserControlist, können Benutzer steuern, ob Ihr Gerät immer aktiviert ist oder ob es nur aktiviert ist, wenn Ihr Gerät über untergeordnete Geräte verfügt, die aktiviert sind.
Wenn der Treiber die IndicateChildWakeOnParentWake Member auf TRUEfestlegt, ruft das Framework die EvtDeviceWakeFromSxTriggered Rückruffunktion im Treiber des übergeordneten Geräts und im Treiber für jedes aktivierte untergeordnete Gerät auf. Wenn der Treiber dieses Element auf FALSE-festlegt, ruft das Framework nur die EvtDeviceWakeFromSxTriggered Rückruffunktion im Treiber des übergeordneten Geräts auf. Ihr Treiber sollte IndicateChildWakeOnParentWake auf TRUE- festlegen, wenn die Treiber für die Kinder Ihres Geräts Hardware untersuchen müssen, um zu ermitteln, warum das System wach wurde.