DXGKDDI_SET_POWER_STATE Rückruffunktion (dispmprt.h)

Artikel
02/06/2025

Die DxgkDdiSetPowerState--Funktion legt den Leistungszustand eines Displayadapters oder eines untergeordneten Geräts eines Anzeigeadapters fest.

Syntax

DXGKDDI_SET_POWER_STATE DxgkddiSetPowerState;

NTSTATUS DxgkddiSetPowerState(
  [in] IN_CONST_PVOID MiniportDeviceContext,
  [in] IN_ULONG DeviceUid,
  [in] IN_DEVICE_POWER_STATE DevicePowerState,
  [in] IN_POWER_ACTION ActionType
)
{...}

Parameter

[in] MiniportDeviceContext

Ein Handle zu einem Kontextblock, der einem Anzeigeadapter zugeordnet ist. Die DxgkDdiAddDevice-Funktion des Display-Miniporttreibers stellt dieses Handle zuvor für das DirectX-Grafik-Kernel-Subsystem bereit.

[in] DeviceUid

Eine positive ganze Zahl, die das Gerät identifiziert, für das der Energiezustand festgelegt werden soll. Wenn DeviceUid-DISPLAY_ADAPTER_HW_ID (definiert in Video.h) entspricht, ist das Gerät der Anzeigeadapter selbst. Andernfalls ist DeviceUid der Bezeichner eines untergeordneten Geräts des Anzeigeadapters. Untergeordnete Gerätebezeichner wurden zuvor von der DxgkDdiQueryChildRelations--Funktion zugewiesen.

[in] DevicePowerState

Ein DEVICE_POWER_STATE Enumerationswert, der den Energiezustand bereitstellt (PowerDeviceD0, PowerDeviceD1, PowerDeviceD2, PowerDeviceD3), auf das das Gerät festgelegt werden soll.

[in] ActionType

Ein POWER_ACTION Enumerationswert, der den Grund (PowerActionSleep, PowerActionHibernate, PowerActionShutdown) für die Änderung des Energiezustands bereitstellt.

Rückgabewert

DxgkDdiSetPowerState gibt STATUS_SUCCESS zurück, wenn dies erfolgreich ist. DxgkDdiSetPowerState- sollte nie fehlschlagen; Sie kann jedoch jeden NTSTATUS-typierten Wert zurückgeben, der in Ntstatus.h definiert ist und das NT_SUCCESS(Status) Makro übergibt.

Bemerkungen

Wenn der angeforderte Zustand PowerDeviceD1, PowerDeviceD2-oder PowerDeviceD3-ist, speichert DxgkDdiSetPowerState alle Kontexte, die später erforderlich sind, um das Gerät wieder in PowerDeviceD0 zu bringen und das Gerät dann in den angeforderten Zustand zu setzen. Wenn der angeforderte Zustand PowerDeviceD0 (vollständig aktiviert) ist, stellt DxgkDdiSetPowerState den Gerätekontext wieder her und platziert das Gerät in PowerDeviceD0.

Wenn DxgkDdiSetPowerState- mit einer Anforderung aufgerufen wird, den VGA-fähigen Displayadapter in den Ruhezustand zu versetzen, sollte der Bildschirmadapter nicht heruntergeschaltet werden. Stattdessen sollte der Kontext gespeichert und der Bustreiber die Stromversorgung des Grafikkartentreibers zulassen. Auf diese Weise kann der Power Manager den Ruhezustandsfortschritt anzeigen, nachdem der Miniporttreiber über die Änderung des Energiezustands benachrichtigt wurde.

Das Betriebssystem ruft möglicherweise DxgkDdiSetPowerState auf einem untergeordneten Gerät des Displayadapters auf, der nicht mehr angeschlossen ist (z. B. ein Monitor, der kürzlich nicht angeschlossen wurde). Diese Anomalie tritt auf, da zwischen dem Zeitpunkt, zu dem das Betriebssystem die DxgkDdiSetPowerState- des Treibers aufruft, eine inhärente Latenz besteht und die Zeit, zu der das Betriebssystem die Trennung verarbeitet. Der Treiber muss solche Situationen ohne Fehlschlagen behandeln.

Wenn DevicePowerState- gleich PowerDeviceD0ist, verlassen Sie sich nicht auf den Wert ActionType.

Ab Windows Display Driver Model (WDDM) 1.2 sollte der DevicePowerState Parameter auf PowerDeviceD0festgelegt ist, der Miniporttreiber DxgkCbAcquirePostDisplayOwnership aufrufen, um die Informationen zum Anzeigemodus abzufragen. Dieser Anzeigemodus wurde möglicherweise zuvor vom Firmware- und Systemladeprogramm festgelegt. Wenn DxgkCbAcquirePostDisplayOwnership- mit STATUS_SUCCESSzurückgibt, sollte der Treiber bestimmen, ob die Anzeige basierend auf den Anzeigemodusinformationen neu initialisiert werden muss, die über den DisplayInfo Parameter zurückgegeben wurden. Andernfalls sollte der Treiber nicht davon ausgehen, dass derzeit ein bestimmter Anzeigemodus auf dem Gerät aktiviert ist, und er sollte die Anzeige initialisieren.

Die funktion DxgkDdiSetPowerState sollte seitenfähig gemacht werden.