DXGKDDI_SET_POWER_STATE Rückruffunktion (dispmprt.h)

Artikel
02/23/2024

Die DxgkDdiSetPowerState-Funktion legt den Energiezustand einer Grafikkarte oder eines untergeordneten Geräts einer Grafikkarte 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 für einen Kontextblock, der einer Grafikkarte zugeordnet ist. Die DxgkDdiAddDevice-Funktion des Display-Miniporttreibers hat dieses Handle zuvor für das DirectX-Grafikkernsubsystem bereitgestellt.

[in] DeviceUid

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

[in] DevicePowerState

Ein DEVICE_POWER_STATE Enumerationswert, der den Energiezustand (PowerDeviceD0, PowerDeviceD1, PowerDeviceD2, PowerDeviceD3) bereitstellt, auf den 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 bei Erfolg STATUS_SUCCESS zurück. DxgkDdiSetPowerState sollte nie fehlschlagen; Es kann jedoch jeden NTSTATUS-typisierten Wert zurückgeben, der in Ntstatus.h definiert ist und das makro NT_SUCCESS(Status) übergibt.

Hinweise

Wenn der angeforderte Zustand gleich PowerDeviceD1, PowerDeviceD2 oder PowerDeviceD3 ist, speichert DxgkDdiSetPowerState alle Kontexte, die später erforderlich sind, um das Gerät wieder auf PowerDeviceD0 zu bringen, und versetzt das Gerät dann in den angeforderten Zustand. Wenn der angeforderte Status PowerDeviceD0 (vollständig aktiviert) lautet, 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 Grafikkarte in den Ruhezustand zu versetzen, sollte die Grafikkarte nicht heruntergefahren werden. Stattdessen sollte der Kontext gespeichert und der Bustreiber die Grafikkarte herunterfahren lassen. Auf diese Weise kann der Power Manager den Status des Ruhezustands anzeigen, nachdem der Anzeige-Miniporttreiber über die Änderung des Energiezustands benachrichtigt wurde.

Das Betriebssystem kann DxgkDdiSetPowerState auf einem untergeordneten Gerät der Grafikkarte aufrufen, das nicht mehr verbunden ist (z. B. ein Monitor, der kürzlich nicht angeschlossen wurde). Diese Anomalie tritt auf, weil zwischen dem Zeitpunkt, zu dem das Betriebssystem die DxgkDdiSetPowerState des Treibers aufruft, und der Zeit, zu der das Betriebssystem die Trennung verarbeitet, eine inhärente Latenz besteht. Der Treiber muss solche Situationen ohne Fehler behandeln.

Wenn DevicePowerState gleich PowerDeviceD0 ist, verlassen Sie sich nicht auf den Wert von ActionType.

Wenn der DevicePowerState-Parameter ab Windows Display Driver Model (WDDM) 1.2 auf PowerDeviceD0 festgelegt ist, sollte der Anzeige-Miniporttreiber DxgkCbAcquirePostDisplayOwnership aufrufen, um die Informationen zum Anzeigemodus abzufragen. Dieser Anzeigemodus wurde möglicherweise zuvor von der Firmware und dem Systemladeprogramm festgelegt. Wenn DxgkCbAcquirePostDisplayOwnership mit STATUS_SUCCESS zurückgibt, sollte der Treiber bestimmen, ob die Anzeige anhand der Über den DisplayInfo-Parameter zurückgegebenen Anzeigemodusinformationen neu initialisiert werden muss. 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 DxgkDdiSetPowerState-Funktion sollte ausgelagert werden.