DXGKDDI_NOTIFY_SURPRISE_REMOVAL Rückruffunktion (dispmprt.h)
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 zu einem Kontextblock, der einem Anzeigeadapter zugeordnet ist. Die DxgkDdiAddDevice-Funktion des Display-Miniporttreibers dieses Handle für das DirectX-Grafik-Kernel-Subsystem 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 = DxgkRemovalHibernationbereinigt wurden. Wenn der Treiber stattdessen einen Fehlercode zurückgibt, versucht das Betriebssystem, das System neu zu starten, wie im folgenden Abschnitt "Hinweise" beschrieben.
Bemerkungen
Dieser Rückruf kann optional von Windows Display Driver Model (WDDM) 1.2 und höher angezeigten Miniporttreibern implementiert werden.
Anmerkung
Das Betriebssystem ruft DxgkDdiNotifySurpriseRemoval nur dann auf, wenn der Anzeigeminiporttreiber die Unterstützung angibt, indem der SupportSurpriseRemovalInHibernation Member der DXGK_DRIVERCAPS-Struktur auf 1 festgelegt wird.
Wenn das Betriebssystem eine Überraschungsentfernung erkennt, benachrichtigt es den Treiber so schnell wie möglich. DxgkDdiNotifySurpriseRemoval ist eine Ebene Null DDI-Funktion, was bedeutet, dass sie aufgerufen werden kann, wenn ein Treiber über ausstehende GPU-Workload verfügt und/oder innerhalb anderer DDI-Funktionen ausgeführt wird. Da ein Aufruf dieser Funktion angibt, dass die Grafikhardware physisch entfernt wurde oder vom System verschwunden ist, kann jeder weitere Versuch, auf Hardware zuzugreifen, Probleme verursachen, wie z. B. eine harte Blockade.
Das Betriebssystem kategorisiert das Entfernen von Überraschungen wie folgt:
Die Überraschungsentfernung tritt auf, wenn sich das System und das Grafikgerät in einem Energiesparzustand befinden, z. B. Ruhezustand oder Ruhezustand. Wenn das Betriebssystem aus dem Energiesparzustand fortgesetzt wird, erkennt es diese Überraschungsentfernung und ruft sofort die DxgkDdiNotifySurpriseRemoval Rückruf mit RemovalType = DxgkRemovalHibernationauf. In diesem Fall werden wahrscheinlich keine ausstehenden GPU-Aufrufe oder DDI-Aufrufe ausgeführt, daher sollte es relativ sicher und einfach sein, damit der Treiber verarbeitet werden kann. Rückgabestatusdetails sind wie folgt:
- Das Betriebssystem erwartet, dass der Treiber die DxgkDdiNotifySurpriseRemoval ordnungsgemäß aufruft und STATUS_SUCCESSzurückgibt.
- Wenn das entfernte Grafikgerät das Post-Gerät (Power-On Self-Test) ist, versucht das Betriebssystem, das System ordnungsgemäß neu zu starten, unabhängig vom zurückgegebenen Status.
- Bei einem Nicht-POST-Gerät schlägt der Treiber den Anruf fehl und unterstützt nur SupportSurpriseRemovalInHibernation- in seinem DXGK_DRIVERCAPS, startet das Betriebssystem das System ordnungsgemäß neu. Wenn es SupportSurpriseRemoval- in DXGK_DRIVERCAPSunterstützt, ignoriert das Betriebssystem den Rückgabestatus und setzt das Beenden des Grafikgeräts fort. Weitere Hinweise zur Rückgabe finden Sie weiter unten.
Das Grafikgerät ist überraschend entfernt/nicht angeschlossen, wenn es noch ausgeführt wird. Wenn das Betriebssystem diese Art von Überraschungsentfernung erkennt, ruft es sofort die DxgkDdiNotifySurpriseRemoval Rückruf mit RemovalType = DxgkRemovalPnPNotifyauf. Möglicherweise gibt es noch einige ausstehende GPU-Vorgänge oder DDI-Aufrufe, die in diesem Fall abgeschlossen werden sollen. Wenn der Treiber diese Benachrichtigung erhält und diese Überraschungsentfernung verarbeiten kann, sollte der Treiber dieses Gerät sofort als Überraschungsentfernung in seinem eigenen Gerätekontext markieren, um den 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 bereinigen und das Grafikgerät zu beenden. Wie unten erwähnt, sollte der Treiber nur die Softwareressourcen freigeben oder bereinigen und darf keine Hardware in diesen DDI-Aufrufen berühren oder darauf zugreifen. Wenn der Treiber diese Überraschungsentfernung 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_SUCCESSzurückgibt, entfernt das DirectX-Grafik-Kernelsubsystem weiterhin den externen Displayadapter aus dem Grafikstapel und ruft andere Treiber implementierte DxgkDdiXxx Kernelmodusfunktionen auf, um alle Ressourcen freizugeben. In diesem Fall muss der Treiber die Bereinigung von Softwareressourcen als Reaktion auf Aufrufe des Betriebssystems abschließen, jedoch keine Hardwareeinstellungen berühren oder bereinigen. Wenn kein anderer Hardwaretreiber verwendet wird, wird der Treiber vom Betriebssystem entladen.
Wenn der Treiber einen Fehlercode zurückgibt, wird DXGK_DRIVERCAPSnicht festgelegt.SupportSurpriseRemovalInHibernationoder implementiert diese Funktion nicht, ruft das DirectX-Grafik-Kernelsubsystem keine treiberimplementierten DxgkDdiXxx--Funktionen 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 |
|---|---|
| mindestens unterstützte Client- | Windows 8 |
| mindestens unterstützte Server- | Windows Server 2012 |
| Zielplattform- | Desktop |
| Header- | dispmprt.h |
| IRQL- | PASSIVE_LEVEL |