WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS-Struktur (wdfdevice.h)

Artikel
08/08/2023

[Gilt für KMDF und UMDF]

Die WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS-Struktur enthält vom Treiber bereitgestellte Informationen über die Fähigkeit eines Geräts, sich selbst und das System zu reaktivieren, wenn sich beide in einem Energiesparzustand 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;

Member

Size

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

DxState

Ein DEVICE_POWER_STATE typisierter Enumerator, der den Niedrigen Geräteleistungszustand identifiziert, den das Gerät erhält, wenn der Systemleistungszustand in einen reaktivierbaren Energiesparzustand fällt. Der Wert von DxState darf nicht PowerDeviceD0 sein. DEVICE_POWER_STATE Werte werden in wdm.h definiert.

UserControlOfWakeSettings

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

Enabled

Ein WDF_TRI_STATE typisierter 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. Dieser Member kann einen der folgenden Werte aufweisen:

WdfTrue : Das Aktivieren des Systems ist aktiviert.

WdfFalse : Das Aktivieren des Systems ist deaktiviert.

WdfUseDefault : Das Aktivieren des Systems ist zunächst standardmäßig aktiviert. Wenn das UserControlOfWakeSettings-Element jedoch auf WakeAllowUserControl festgelegt ist, überschreibt die Einstellung des Benutzers oder die INF-Datei des Treibers den Anfangswert.

Wenn die Aktivierung des Systems aktiviert ist und das System in einen Low-Power-Zustand wechselt, ruft das Framework die Rückruffunktion EvtDeviceArmWakeFromSx oder EvtDeviceArmWakeFromSxWithReason des Treibers auf, bevor das Gerät in einen Energiesparzustand wechselt.

ArmForWakeIfChildrenAreArmedForWake

Ein boolescher Wert, der bei Festlegung auf TRUE angibt, dass die Fähigkeit eines übergeordneten Geräts, sich selbst zu reaktivieren, und das System aktiviert werden soll, wenn diese Funktion für die untergeordneten Geräte des Geräts aktiviert ist. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise". Dieses Element ist in Version 1.7 und höher von KMDF verfügbar.

IndicateChildWakeOnParentWake

Ein boolescher Wert, der bei Festlegung auf TRUE angibt, dass das Framework die aktivierungsbasierte status für untergeordnete Geräte bereitstellt, wenn ein übergeordnetes Gerät ein Aktivierungssignal erkennt. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise". Dieses Element ist in Version 1.7 und höher von KMDF verfügbar.

Hinweise

Die WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS-Struktur wird als Eingabe für WdfDeviceAssignSxWakeSettings verwendet.

Um die WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS-Struktur zu initialisieren, sollte der Treiber WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS_INIT aufrufen.

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

Das Framework speichert die Werte aller WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS Strukturmember.
Wenn das UserControlOfWakeSettings-Element auf WakeAllowUserControl festgelegt ist und das Enabled-Element auf WdfUseDefault festgelegt ist, liest das Framework die Registrierung, um festzustellen, ob der Benutzer die Aktivierung des Systems aktiviert hat.

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

Speichert den Wert des UserControlOfWakeSettings-Elements .
Sucht in der Registrierung nach einer Benutzereinstellung, wenn der Wert des Enabled-ElementsWdfUseDefault ist.

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

Der Wert darf nicht PowerDeviceD0 sein.
Wenn Sie PowerDeviceMaximum angeben, verwendet das Framework den Wert, den der Treiber für den Gerätebus im DeviceWake-Member seiner WDF_DEVICE_POWER_CAPABILITIES-Struktur bereitgestellt hat.
Sie können 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, kann der DxState-Wert ihres Funktionstreibers nicht PowerDeviceD3 sein.)

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

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

Wenn der Treiber das ArmForWakeIfChildrenAreArmedForWake-Element auf TRUE festlegt, ruft das Framework die Rückruffunktion EvtDeviceArmWakeFromSx oder EvtDeviceArmWakeFromSxWithReason auf, wenn die Aktivierungsfunktion eines untergeordneten Geräts aktiviert ist, auch wenn die Aktivierungsfunktion des übergeordneten Geräts nicht aktiviert ist.
Um den Stromverbrauch zu reduzieren, sollten Sie die Aktivierungsmöglichkeit Ihres Geräts möglicherweise nicht aktivieren, es sei denn, ein untergeordnetes Gerät, das auch eine Aktivierungsmöglichkeit unterstützt, ist angeschlossen. Wenn Ihr Treiber das ArmForWakeIfChildrenAreArmedForWake-Element auf TRUE festlegt, haben die Werte des Enabled-Elements die folgende Bedeutung:
- Wenn Enabledauf WdfFalse festgelegt ist, aktiviert das Framework die Aktivierungsmöglichkeit ihres Treibers nur, wenn die Aktivierungsmöglichkeit eines untergeordneten Geräts aktiviert ist.
- Wenn Aktiviertauf WdfTrue festgelegt ist, aktiviert das Framework immer die Aktivierungsmöglichkeit Ihres Treibers, unabhängig davon, ob Ihr Gerät über aktivierte untergeordnete Geräte verfügt oder nicht.
- Wenn Enabledden Wert WdfUseDefault und UserControlOfWakeSettingswakeAllowUserControl aufweist, 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 das Element IndicateChildWakeOnParentWake auf TRUE festlegt, ruft das Framework die Rückruffunktion EvtDeviceWakeFromSxTriggered im Treiber des übergeordneten Geräts und im Treiber für jedes aktivierungsfähige untergeordnete Gerät auf. Wenn der Treiber diesen Member auf FALSE festlegt, ruft das Framework die Rückruffunktion EvtDeviceWakeFromSxTriggered nur im Treiber des übergeordneten Geräts auf. Ihr Treiber sollte IndicateChildWakeOnParentWake auf TRUE festlegen, wenn die Treiber für die untergeordneten Geräte Hardware untersuchen müssen, um zu ermitteln, warum das System aktiviert wurde.