Einführung in das Framework zur gesteuerten Energieverwaltung

  • Artikel

Ab Windows 10, Version 1903, bietet Version 3 des Frameworks zur Laufzeit-Energieverwaltung (Power Management Framework, PoFx) ein optionales gesteuertes Energiemodell, das Directed PoFx (DFx).

Mit DFx leitet das Betriebssystem Gerätestapel an, in die entsprechenden Leerlaufzustände mit niedriger Leistung zu wechseln, wenn das System in den Leerlauf wechselt und keine Aktivierungsbroker-Softwareaktivität vorhanden ist, und ermöglicht es dem System, zuverlässiger in den Energiesparmodus überzugehen.

Ziel ist es, Systeme energieeffizienter zu machen und den Energieverbrauch für Windows-Geräte über Formfaktoren hinweg zu reduzieren.

DFx wird derzeit nur für Geräte mit D-Statuseinschränkungen unterstützt. DFx überspringt jede Geräteunterstruktur mit einer F-Statuseinschränkung.

DFx fährt Paging- oder Debug-Geräte nicht herunter.

Anforderungen für WDF-Treiber (Nicht-Miniport)

Ein WDF-Treiber, der ein Energierichtlinienbesitzer ist, muss eine entsprechende S0-Idle-Richtlinie implementieren indem er SystemManagedIdleTimeout oder SystemManagedIdleTimeoutWithHint für die WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS-Struktur angibt. Dadurch kann das sich im Leerlauf befindende Gerät herunterschalten. Als zusätzliche Resilienzmaßnahme kann der Treiber DFx aktivieren, indem er dem AddReg-Direktivenabschnitt des INF im Abschnitt DDInstall.HW den folgenden Registrierungsschlüssel hinzufügt:

HKR,"WDF","WdfDirectedPowerTransitionEnable",0x00010001,1

Ein WDF-Treiber für Version 31 und höher aktiviert DFx standardmäßig. Wenn dies nicht erwünscht ist, kann der Treiber DFx deaktivieren, indem er den Registrierungsschlüssel auf 0 festlegt:

HKR,"WDF","WdfDirectedPowerTransitionEnable",0x00010001,0

Ein WDF-Treiber für Version 33 und höher kann DFx alternativ deaktivieren, indem das DirectedPoFxEnabled-Element derWDF_POWER_FRAMEWORK_SETTINGS-Struktur auf WdfFalse festgelegt wird.

Tipp

Um die WDF_POWER_FRAMEWORK_SETTINGS-Struktur zu initialisieren, sollte der Treiber WDF_POWER_FRAMEWORK_SETTINGS_INIT aufrufen.

Da das Anfordern eines vom System verwalteten Leerlauftimeouts dazu führt, dass WDF im Namen des Treibers bei PoFx registriert wird, muss sich der Treiber in diesem Szenario nicht bei PoFx registrieren.

Wenn der Treiber DriverManagedIdleTimeout angibt, sollten Sie zum vom System verwalteten Leerlauftimeout wechseln. Wenn dies nicht möglich ist, verwenden Sie die im nachfolgenden Abschnitt WDM bereitgestellten Richtlinien, um DFx zu aktivieren.

Wenn der WDF-Treiber keine Laufzeitenergieverwaltung verwendet, fügen Sie Unterstützung dafür hinzu und verwenden Sie das vom System verwaltete Leerlauftimeout. Geben Sie hierzu eine WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS-Struktur als Eingabe für WdfDeviceAssignS0IdleSettings an.

Anforderungen für WDM-Treiber (Nicht-Miniport)

Wenn Ihr Treiber die von WDF bereitgestellte systemverwaltete Leerlaufunterstützung nicht verwendet (der Treiber ist entweder ein WDF-Treiber mit treiberseitig verwaltetem Leerlauf oder ein WDM-Treiber), kann er weiterhin DFx-Unterstützung erhalten, indem er sich bei PoFx registriert. In diesem Szenario registriert sich der Treiber bei PoFx, indem er Folgendes implementiert:

Stellen Sie Zeiger auf diese Rückrufe in einer PO_FX_DEVICE_V3-Struktur bereit, die für die PoFxRegisterDevice-Funktion eingegeben wird.

Um DFx-Unterstützung zu erhalten, muss ein Treiber:

  • Bei der Registrierung für PoFx die PO_FX_DIRECTED_POWER* Rückrufe angeben
  • Bei der Rückkehr aus dem Leerlauf PoFxReportDevicePoweredOn über die PO_FX_DIRECTED_POWER_UP_CALLBACK-Rückruffunktion aufrufen Wenn es sich um einen WDF-Treiber handelt, kann er ein Flag festlegen und dann in EvtDeviceD0Entry das Flag überprüfen und PoFxReportDevicePoweredOn aufrufen.
  • Beim Fortsetzen des Sx-Übergangs PoFxReportDevicePoweredOn aufrufen. Wenn es sich um einen WDF-Treiber handelt, muss er IRP_MN_SET_POWER vorverarbeiten. Der Vorverarbeitungsrückruf sollte nur dann fortgesetzt werden, wenn Parameters.Power.Type == SystemPowerState. Da das Gerät während des gesamten Standby-/Fortsetzungszyklus möglicherweise im Dx-Zustand verbleibt, funktioniert der obige Ansatz zum Überprüfen eines Flags in EvtDeviceD0Entry nicht. Stattdessen sollte die Ereignisrückruffunktion EvtDeviceWdmIrpPreprocessIoSetCompletionRoutine aufrufen, um eine IoCompletion-Routine festzulegen und aus der Abschlussroutine PoFxReportDevicePoweredOn aufrufen.

Beispiel

Im folgenden Beispiel sind die oben beschriebene Selbstregistrierungsoption aufgeführt:

PO_FX_DEVICE_V3 MyPoFxDevice;
POHANDLE MyPoFxHandle;

RtlZeroMemory(&MyPoFxDevice, sizeof(PO_FX_DEVICE_V3));
MyPoFxDevice.Version = PO_FX_VERSION_V3;

// Initialize other PoFx callbacks and other fields like
// components and their idle states.

MyPoFxDevice.DirectedPowerUpCallback = <Driver's DFx power up callback>
MyPoFxDevice.DirectedPowerDownCallback = <Driver's DFx power down callback>

Status = PoFxRegisterDevice(
  <Driver's device object>,
  (PPO_FX_DEVICE)&MyPoFxDevice,
  &MyPoFxHandle);
  if (!NT_SUCCESS(Status)) {
  return Status;
}

Wenn Ihr Treiber zuvor PO_FX_VERSION_V1 angegeben hat, sollten Sie beachten, dass PO_FX_DEVICE_V3-Strukturen für die Komponentenarraystruktur PO_FX_COMPONENT_V2 verwenden.

Anforderungen für Miniport-Treiber

Für Geräteklassen, die einem Port-/Miniporttreibermodell folgen, übernehmen vom System bereitgestellte Porttreiber in der Regel den Besitz von Energierichtlinien. Für die meisten Miniports müssen keine Codeänderungen vorgenommen werden, um DFx zu aktivieren, da die DFx-Unterstützung von den entsprechenden Porttreibern übernommen wird.

Leitfaden für Drittanbieter-Miniports von KS.sys

Ab Windows 10, Version 2004 (auch bekannt als 20H1 oder Build 19041) deaktiviert KS.sys standardmäßig DFx und die zugehörigen HLK-Anforderungen. Drittanbieter-Minports von KS.sys können DFx und zugehörige HLK aktivieren, indem sie sich bei PoFx anmelden und den KsDFxSupportEnable-Registrierungsschlüssel zum INF hinzufügen.

Ein Treiber kann sich mithilfe der in diesem Abschnitt erwähnten Implementierung bei PoFx anmelden. Außerdem muss im Abschnitt AddReg-Direktiven die folgende Zeile hinzugefügt werden.

HKR, , KSDFxSupportEnable, 0x00010001, 1

Der AddReg-Abschnitt kann entweder über den [DDInstall.HW]-Abschnitt des Geräts oder den [service-install-section] des Treibers aufgerufen werden. Durch das Hinzufügen im Abschnitt [DDInstall.HW] wird nur das entsprechende Gerät geändert. Dies ist nützlich, wenn derselbe Treiber für verschiedene VID/PID-Kombinationen verwendet wird, DFx jedoch nur für ein bestimmtes Gerät aktiviert werden muss.

Durch Hinzufügen des AddReg-Abschnitts im [service-install-section] wird DFx für alle Geräte aktiviert, die diesen Treiber verwenden.

Testen

Microsoft bietet drei Tests für DFx: einen Einzelgerätetest im Windows Driver Kit zum Testen von benutzerdefinierten Geräten, einen HLK-Test auf Geräteebene und einen HLK-Test auf Systemebene, der zum Testen aller Geräte in einem System bestimmt ist.

Der Einzelgerätetest ist als Teil des PwrTest-Tools verfügbar, das im Lieferumfang des WDK enthalten ist. Um darauf zuzugreifen, führen Sie das Tool mit dem /directedfx-Schalter aus. Weitere Informationen finden Sie unter PwrTest DirectedFx Scenario.

Informationen zu HLK-Tests finden Sie auf den folgenden Seiten:

Es wird empfohlen, DFx nach einem S4-Übergang zu testen, um alle Fälle abzufangen, in denen ein Treiber nach dem Fortsetzen von S4 PoFxReportDevicePoweredOn möglicherweise nicht ordnungsgemäß aufruft.

DFx- und S-Statusübergänge

  • Der D-Zielstatus für DFx-Übergänge sollte mit dem für Runtime D3 (RTD3) übereinstimmen, der sich möglicherweise vom D-Zielstatus für S3/S4-Übergänge unterscheidet. Berücksichtigen Sie ein Szenario, in dem ein Gerät D2 für RTD3 eingibt, aber D3 für S3/S4 eingibt. In diesem Fall sollte der D-Zielstatus für DFx D2 sein.
  • Ebenso sollte das Arm-for-Wake-Verhalten für DFx mit dem Arm-for-Wake-Verhalten für RTD3 übereinstimmen, das sich von dem für S3/S4-Übergänge verwendeten Arm-for-Wake-Verhalten unterscheiden kann. So kann ein Gerät beispielsweise für RTD3 D2/wake-armed und für S3/S4 D3/no-wake-armed eingeben. In diesem Szenario sollten DFx-Übergänge auch D2/wake-armed eingeben.

DFx und Runtime D3 (RTD3)

  • Bei RTD3 wechselt ein Gerät in der Regel in einen D-Zustand mit niedrigerer Leistung, wenn es in den Leerlauf wechselt. Wenn neue Arbeit eintrifft, wird das Gerät sofort in D0 reaktiviert. Mit DFx sollte das Gerät weiterhin im D-Zielzustand bleiben (und neue Arbeit in seine Warteschlangen schreiben), bis PoFx es zum Einschalten angibt.

Weitere Informationen