DXGKDDI_GETDISPLAYSTATEINTRUSIVE Rückruffunktion (dispmprt.h)

Artikel
02/23/2024

Das Betriebssystem ruft die DxgkDdiGetDisplayStateNonIntrusive-Routine eines Anzeigeminiporttreibers auf, um Anzeigezustandsinformationen vom Treiber zu sammeln.

Syntax

DXGKDDI_GETDISPLAYSTATEINTRUSIVE DxgkddiGetdisplaystateintrusive;

NTSTATUS DxgkddiGetdisplaystateintrusive(
  [in]     HANDLE Context,
  [in/out] PDXGKARG_GETDISPLAYSTATEINTRUSIVE pArgs
)
{...}

Parameter

[in] Context

Zeiger auf einen privaten Kontext, der von DxgkDdiQueryInterface zurückgegeben wird.

[in/out] pArgs

Zeiger auf eine DXGKARG_GETDISPLAYSTATEINTRUSIVE-Struktur .

Rückgabewert

DxgkDdiGetDisplayStateIntrusive gibt bei Erfolg STATUS_SUCCESS zurück. Andernfalls wird ein Fehlercode wie einer der folgenden zurückgegeben.

Fehlercode	Bedeutung
STATUS_DRIVER_INTERNAL_ERROR	Im Treiber ist ein generischer Softwarefehler aufgetreten.
STATUS_ACCESS_DENIED	Die Hardware wird derzeit von anderen Threads verwendet, und dieser DDI kann keinen Zugriff darauf erhalten.
STATUS_DEVICE_HARDWARE_ERROR	Ein generischer HW-Fehler ist aufgetreten.
STATUS_DEVICE_POWERED_OFF	Das Gerät ist ausgeschaltet.

Hinweise

Das Betriebssystem ruft DxgkDdiGetDisplayStateIntrusive auf, um Anzeigezustandsinformationen vom Treiber zu sammeln, wenn sich der Benutzer bereits in einem fehlerhaften Zustand befindet. Im Gegensatz zu DxgkDdiGetDisplayStateNonIntrusive kann die DxgkDdiGetDisplayStateIntrusive-Routine des Treibers aufdringlichere Vorgänge ausführen, die sichtbare Nebenwirkungen für den Benutzer haben. Ein aufdringlicher Vorgang wird wie folgt definiert (nicht intrusive Vorgänge weisen keine dieser Eigenschaften auf):

Dies verursacht Nebenwirkungen (Störungen), die für den Benutzer sichtbar sind (z. B. vorübergehendes Beenden des Scanvorgangs und destruktive Überwachung der Konnektivitätsprüfung).
Es ist langsam und wirkt sich auf die System- oder Anzeigeleistung aus, wenn es häufig aufgerufen wird (mehrmals in einer Sekunde).
Der Zustand des Anzeigesubsystems (oder eines anderen Subsystems) wird direkt oder indirekt geändert.

Der Treiber sollte den Zustand des Systems beim Sammeln von Daten nicht absichtlich ändern.

Das Betriebssystem ruft diese Routine viel seltener im Vergleich zu Aufrufen von DxgkDdiGetDisplayStateNonIntrusive auf. In den meisten Fehlerszenarien ruft das Betriebssystem zuerst DxgkDdiGetDisplayStateNonIntrusive und dann DxgkDdiGetDisplayStateIntrusive auf, um sicherzustellen, dass unbeabsichtigte Auswirkungen des aufdringlichen Aufrufs nicht auf die nicht intrusive Datensammlung wirken.

DXGKRNL ruft diese Routine auf, wobei NumOfTargets auf die Anzahl der Ziele festgelegt ist, für die das Betriebssystem meldet, dass ein Monitor mit der entsprechenden ausgefüllten VidPnTargetId verbunden ist. Wenn der Treiber der Ansicht ist, dass kein Monitor an ein bestimmtes Ziel angeschlossen ist, sollte er den ReturnSubStatus festlegen, damit dieses Ziel DXGK_DIAG_GETDISPLAYSTATE_MONITOR_NOT_CONNECTED wird.

Hinweis

Wenn der Treiber bei einem bestimmten vidpntarget beim Sammeln von Informationen einen Fehler auftritt, sollte er ReturnSubStatus verwenden, um den Fehlerzustand festzulegen und mit dem nächsten vidpntarget fortzufahren und den Gesamtaufruf nicht zu schlagen, es sei denn, alle Pfade haben Fehler. Treiber sollten im Idealfall Fehler aufzeichnen, die während dieses Aufrufs in einem internen Fehlerprotokoll aufgetreten sind. Wenn das Betriebssystem DxgkDdiCollectDiagnosticInfo zum Sammeln von Blackbox-Informationen aufruft, werden diese Fehler als Teil einer internen Protokollsammlung erfasst, um IHVs beim Debuggen zu unterstützen.

Das Betriebssystem verfügt über ein ausreichendes Timeout (ca. 5 Sekunden), damit DxgkDdiGetDisplayStateIntrusive abgeschlossen werden kann, sodass der Treiber mehr Zeit hat, um den gesamten relevanten Zustand zu erfassen. Nach einem Timeout kann das Betriebssystem den Computer überprüfen und ein Speicherabbild sammeln, wenn der Treiber in diesem Aufruf hängen bleibt. Daher sollte der Miniport versuchen, diesen Aufruf immer innerhalb des Zeitrahmens abzuschließen.

Die Synchronisierungsebene für diesen DDI ist die Synchronisierung auf Nullebene.