DXGKDDI_NOTIFY_SURPRISE_REMOVAL Rückruffunktion (dispmprt.h)

  • Artikel

DXGKDDI_NOTIFY_SURPRISE_REMOVAL wird vom Betriebssystem aufgerufen, wenn ein Benutzer ein externes Anzeigegerät trennt, ohne das System zu benachrichtigen.

Syntax

DXGKDDI_NOTIFY_SURPRISE_REMOVAL DxgkddiNotifySurpriseRemoval;

NTSTATUS DxgkddiNotifySurpriseRemoval(
  [in] PVOID MiniportDeviceContext,
  [in] DXGK_SURPRISE_REMOVAL_TYPE RemovalType
)
{...}

Parameter

[in] MiniportDeviceContext

Ein Handle für einen Kontextblock, der einem Grafikkarte zugeordnet ist. Die DxgkDdiAddDevice-Funktion des Anzeigeminiporttreibers hat dieses Handle zuvor für das DirectX-Grafikkernsubsystem bereitgestellt.

[in] RemovalType

Ein Wert vom Typ DXGK_SURPRISE_REMOVAL_TYPE , der den Typ des Überraschungsentfernungsereignisses identifiziert.

Rückgabewert

Gibt STATUS_SUCCESS zurück, wenn Softwareressourcen für RemovalType = DxgkRemovalHibernation bereinigt wurden. Wenn der Treiber stattdessen einen Fehlercode zurückgibt, versucht das Betriebssystem, das System neu zu starten, wie im folgenden Abschnitt Mitbemerkungen beschrieben.

Hinweise

Dieser Rückruf kann optional von Windows Display Driver Model (WDDM) 1.2 und höher implementiert werden.

Hinweis

Das Betriebssystem ruft DxgkDdiNotifySurpriseRemoval nur auf, wenn der Anzeigeminiporttreiber Unterstützung angibt, indem das SupportSurpriseRemovalInHibernation-Element der DXGK_DRIVERCAPS Struktur auf 1 festgelegt wird.

Wenn das Betriebssystem eine überraschende Entfernung erkennt, benachrichtigt es den Treiber so schnell wie möglich. DxgkDdiNotifySurpriseRemoval ist eine DDI-Funktion der Ebene null , was bedeutet, dass sie aufgerufen werden kann, wenn ein Treiber eine ausstehende GPU-Workload hat und/oder in anderen DDI-Funktionen ausgeführt wird. Da ein Aufruf dieser Funktion darauf hindeutet, dass die Grafikhardware physisch entfernt wurde oder aus dem System verschwunden ist, kann jeder weitere Versuch, auf Hardware zuzugreifen, Zu Problemen führen, z. B. zu einem harten Hängen.

Das Betriebssystem kategorisiert das Entfernen von Überraschungen wie folgt:

  • Die überraschende Entfernung tritt auf, wenn sich das System und das Grafikgerät in einem Energiesparmodus oder Ruhezustand befinden. Wenn das Betriebssystem aus dem Zustand mit niedriger Leistung fortgesetzt wird, erkennt es diese überraschende Entfernung und ruft sofort den DxgkDdiNotifySurpriseRemoval-Rückruf des Treibers mit RemovalType = DxgkRemovalHibernation auf. Es wird in diesem Fall wahrscheinlich keine ausstehenden GPU-Arbeiten oder DDI-Aufrufe geben, daher sollte es für den Treiber relativ sicher und einfach zu handhaben sein. Status Details werden wie folgt zurückgegeben:

    • Das Betriebssystem erwartet, dass der Treiber den DxgkDdiNotifySurpriseRemoval-Aufruf ordnungsgemäß verarbeitet und STATUS_SUCCESS zurückgibt.
    • Wenn es sich bei dem entfernten Grafikgerät um das POST-Gerät (Power-On Self-Test) handelt, versucht das Betriebssystem, das System ordnungsgemäß neu zu starten, unabhängig von der zurückgegebenen status.
    • Wenn der Treiber bei einem Nicht-POST-Gerät den Aufruf ausschlägt und nur SupportSurpriseRemovalInHibernation in seinem DXGK_DRIVERCAPS unterstützt, startet das Betriebssystem das System ordnungsgemäß neu. Wenn supportSurpriseRemoval in DXGK_DRIVERCAPS unterstützt wird, ignoriert das Betriebssystem die Rückgabe status und beendet das Grafikgerät weiterhin. Weitere Rückgabehinweise finden Sie unten.

  • Das Grafikgerät wird überraschend entfernt/nicht angeschlossen, wenn es noch ausgeführt wird. Wenn das Betriebssystem diese Art der überraschenden Entfernung erkennt, ruft es sofort den DxgkDdiNotifySurpriseRemoval-Rückruf des Treibers mit RemovalType = DxgkRemovalPnPNotify auf. In diesem Fall sind möglicherweise noch einige GPU-Arbeiten oder DDI-Aufrufe ausstehend. Wenn der Treiber diese Benachrichtigung empfängt und diese überraschende Entfernung verarbeiten kann, sollte der Treiber dieses Gerät sofort als überraschende Entfernung in seinem eigenen Gerätekontext markieren, um jeglichen Hardwarezugriff zu vermeiden und dann STATUS_SUCCESS zurück an das Betriebssystem zurückzugeben. Das Betriebssystem ruft weiterhin andere DDI-Funktionen auf, um die Ressourcen zu sauber und das Grafikgerät zu beenden. Wie unten erwähnt, sollte der Treiber nur die Softwareressourcen freigeben oder sauber und darf keine Hardware in diesen DDI-Aufrufen berühren oder darauf zugreifen. Wenn der Treiber diese überraschende Entfernung nicht verarbeiten kann, sollte ein ordnungsgemäßer Fehler an das Betriebssystem zurückgegeben werden. Bei einem Ausfall überprüft das Betriebssystem das System sofort, um weitere Hardware- oder Datenschäden zu vermeiden.

Wenn der Display-Miniporttreiber STATUS_SUCCESS zurückgibt, entfernt das DirectX-Grafikkernsubsystem weiterhin den externen Grafikkarte aus dem Grafikstapel und ruft andere vom Treiber implementierte DxgkDdiXxx-Kernelmodusfunktionen auf, um alle Ressourcen freizugeben. In diesem Fall muss der Treiber die Bereinigung der Softwareressourcen als Reaktion auf Aufrufe des Betriebssystems abschließen, darf jedoch keine Hardwareeinstellungen berühren oder sauber. Wenn keine andere Hardware den Treiber verwendet, wird der Treiber vom Betriebssystem entladen.

Wenn der Treiber einen Fehlercode zurückgibt, wird nicht DXGK_DRIVERCAPS festgelegt. SupportSurpriseRemovalInHibernation oder implementiert diese Funktion nicht, das DirectX-Grafikkernsubsystem ruft keine treiberimplementierten DxgkDdiXxx-Funktionen mehr auf und versucht, das System neu zu starten. In diesem Fall wird die Ressource, die zugewiesen wurde, bevor das externe Anzeigegerät getrennt wurde, nicht freigegeben.

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Windows 8
Unterstützte Mindestversion (Server) Windows Server 2012
Zielplattform Desktop
Kopfzeile dispmprt.h
IRQL PASSIVE_LEVEL

Weitere Informationen

D3DKMT_WDDM_1_2_CAPS

DXGK_DRIVERCAPS

DXGK_SURPRISE_REMOVAL_TYPE

DxgkDdiAddDevice