DXGKDDI_GETDISPLAYSTATENONINTRUSIVE Rückruffunktion (dispmprt.h)

Artikel
02/23/2024

Das Betriebssystem ruft die DxgkDdiGetDisplayStateNonIntrusive-Routine eines Anzeige-Miniporttreibers auf, um nicht inintrusiv Anzeigezustandsinformationen vom Treiber zu sammeln.

Syntax

DXGKDDI_GETDISPLAYSTATENONINTRUSIVE DxgkddiGetdisplaystatenonintrusive;

NTSTATUS DxgkddiGetdisplaystatenonintrusive(
  [in]     HANDLE Context,
  [in/out] PDXGKARG_GETDISPLAYSTATENONINTRUSIVE pArgs
)
{...}

Parameter

[in] Context

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

[in/out] pArgs

Zeiger auf eine DXGKARG_GETDISPLAYSTATENONINTRUSIVE-Struktur .

Rückgabewert

DxgkDdiGetDisplayStateNonIntrusive 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 DxgkDdiGetDisplayStateNonIntrusive auf, um Anzeigezustandsinformationen vom Treiber zu sammeln. Im Gegensatz zu DxgkDdiGetDisplayStateIntrusive sollte die DxgkDdiGetDisplayStateNonIntrusive-Routine des Treibers keine Vorgänge ausführen, die sichtbare Nebenwirkungen für den Benutzer verursachen, und der Sammlungsprozess sollte relativ schnell sein (idealerweise innerhalb weniger Millisekunden). Die Anruffrequenz dieser Routine wird relativ hoch sein. Abgesehen davon, dass zur Diagnose eines fehlerhaften Benutzerzustands aufgerufen wird, kann das Betriebssystem diese Routine auch verwenden, um verlaufsbezogene Zustandsinformationen vom Treiber zu Debugzwecken aufzuzeichnen.

In seltenen Fällen, in denen eine plattformspezifische Implementierung erfordert, dass der Treiber störende Vorgänge im Rahmen eines Aufrufs von DxgkDdiGetDisplayStateNonIntrusive durchführt, muss der Treiber die Vorgänge ausführen, aber pArgs-ReturnSubStatus> auf DXGK_DIAG_GETDISPLAYSTATE_CAUSED_GLITCH oder DXGK_DIAG_GETDISPLAYSTATE_CHANGED_DISPLAY_STATE entsprechend festlegen. Basierend auf dem ReturnSubStatus-Wert ruft das Betriebssystem diese Routine möglicherweise nur für Fehlerszenarien auf einem bestimmten System auf.

Das Betriebssystem ruft DxgkDdiGetDisplayStateNonIntrusive häufig (entweder in regelmäßigen Abständen oder bei anderen häufig auftretenden Ereignissen) auf, um Treiberzustandsdaten zu Debugzwecken zu sammeln und die historischen Zeitleiste zu untersuchen. Das Betriebssystem ruft diese Routine auch in bestimmten Fehlerszenarien (z. B. schwarzen Bildschirmen) auf, bevor ausführlichere Informationen durch Aufrufen von DxgkDdiGetDisplayStateIntrusive gesammelt werden. Angesichts der möglichen Häufigkeit dieses Anrufs sollten Die Fahrer ihn so schnell wie möglich abschließen. Das Betriebssystem ruft diesen DDI auf, wobei NumOfTargets auf die maximale Anzahl von Zielen festgelegt ist, die von der angegebenen Grafikkarte unterstützt werden und VidPnTargetId ausgefüllt ist. Der Miniporttreiber sollte nur die Anzeigezustandsinformationen für Ziele ausfüllen, an denen tatsächlich ein Monitor angeschlossen ist. Für ein vidpntarget, an das kein Monitor angeschlossen ist, sollte der Miniport einfach DXGK_DIAG_DISPLAY_CONNECTIVITY ausfüllen, und das Betriebssystem ignoriert alle anderen Felder für dieses Ziel.

Hinweis

Treiber sollten nur ReturnSubStatus verwenden, um Fehlerbedingungen zu melden, und nicht DXGK_DIAG_GETDISPLAYSTATE_MONITOR_NOT_CONNECTED zum Melden des Überwachungskonnektivitätsstatus. Der Standard Zweck von DXGK_DIAG_GETDISPLAYSTATE_MONITOR_NOT_CONNECTED ist für aufdringliche Aufrufe, bei denen das Betriebssystem nicht nach der Überwachungskonnektivität fragt.

Wenn der Treiber bei einem bestimmten vidpntarget beim Sammeln von Informationen auf einen Fehler stößt, sollte er ReturnSubStatus verwenden, um den Fehlerzustand festzulegen und mit dem nächsten vidpntarget fortzufahren und den Gesamtaufruf nicht erfolgreich zu führen, es sei denn, alle Pfade treffen 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.

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