DXGK_DEBUG_REPORT_INTERFACE-Struktur (dispmprt.h)

Artikel
08/07/2023

Die DXGK_DEBUG_REPORT_INTERFACE-Struktur enthält Zeiger auf Funktionen in der Debugbericht-Schnittstelle, die vom Anzeigeporttreiber implementiert wird.

Syntax

typedef struct _DXGK_DEBUG_REPORT_INTERFACE {
  USHORT                    Size;
  USHORT                    Version;
  PVOID                     Context;
  PINTERFACE_REFERENCE      InterfaceReference;
  PINTERFACE_DEREFERENCE    InterfaceDereference;
  DXGK_DEBUG_REPORT_HANDLE( )(HANDLE DeviceHandle,ULONG ulCode,ULONG_PTR ulpArg1,ULONG_PTR ulpArg2,ULONG_PTR ulpArg3,ULONG_PTR ulpArg4) *DbgReportCreate;
  BOOLEAN( )(DXGK_DEBUG_REPORT_HANDLE hReport,PVOID pvData,ULONG ulDataSize)                  *DbgReportSecondaryData;
  VOID( )(DXGK_DEBUG_REPORT_HANDLE hReport)                     *DbgReportComplete;
} DXGK_DEBUG_REPORT_INTERFACE, *PDXGK_DEBUG_REPORT_INTERFACE;

Member

Size

Die Größe (in Bytes) dieser Struktur.

Version

Die Versionsnummer der Debugberichtsschnittstelle. Versionsnummernkonstanten werden in Dispmprt.h definiert (z. B. DXGK_DEBUG_REPORT_INTERFACE_VERSION_1).

Context

Ein Zeiger auf einen Kontext, der vom Anzeigeporttreiber bereitgestellt wird.

InterfaceReference

Ein Zeiger auf eine Schnittstellenverweisfunktion, die vom Anzeigeporttreiber implementiert wird.

InterfaceDereference

Ein Zeiger auf eine Schnittstellendereferenzierungsfunktion, die vom Anzeigeporttreiber implementiert wird.

DbgReportCreate

Erstellt einen anfänglichen Fehlerbericht.

Wenn ihr Anzeige-Miniporttreiber einen Fehler erkennt und anschließend wiederhergestellt wird, können Sie einen Fehlerbericht erstellen, der später zum Debuggen verwendet werden kann. Rufen Sie zunächst DbgReportCreate auf , um einen ersten Bericht zu erstellen. Fügen Sie dann dem Bericht Daten hinzu, indem Sie einen oder mehrere Aufrufe von DbgReportSecondaryData ausführen. Wenn Sie das Hinzufügen von Daten zum Bericht abgeschlossen haben, rufen Sie DbgReportComplete auf.

Die Syntax für DbgReportComplete folgt.

// IRQL: PASSIVE_LEVEL
DXGK_DEBUG_REPORT_HANDLE (*DbgReportCreate)(
  _In_ HANDLE    DeviceHandle,
  _In_ ULONG     ulCode,
  _In_ ULONG_PTR ulpArg1,
  _In_ ULONG_PTR ulpArg2,
  _In_ ULONG_PTR ulpArg3,
  _In_ ULONG_PTR ulpArg4
);

DeviceHandle ist ein Handle für einen Kontextblock, der einer Grafikkarte zugeordnet ist. Der Display-Miniporttreiber hat dieses Handle in seiner DxgkDdiAddDevice-Funktion* erstellt. Dieser Parameter kann NULL sein.
ulCode ist ein Code für den Fehlerbericht. Die folgenden Codes werden unterstützt:
- THREAD_STUCK_IN_DEVICE_DRIVER
- VIDEO_DRIVER_DEBUG_REPORT_REQUEST
- VIDEO_TDR_FATAL_ERROR
- VIDEO_TDR_SUCCESS
ulpArg1 ist das erste Argument, das dem Bericht hinzugefügt wird. Der Entwickler des Anzeigeminiporttreibers bestimmt den Wert und die Bedeutung von ulpArg1.
ulpArg2 ist das zweite Argument, das dem Bericht hinzugefügt wird. Der Entwickler des Anzeigeminiporttreibers bestimmt den Wert und die Bedeutung von ulpArg2.
ulpArg3 ist das dritte Argument, das dem Bericht hinzugefügt wird. Der Entwickler des Anzeigeminiporttreibers bestimmt den Wert und die Bedeutung von ulpArg3.
ulpArg4 ist reserviert.

DbgReportSecondaryData

Fügt Daten an einen anfänglichen Fehlerbericht an, der zuvor von DbgReportCreate erstellt wurde.

Rufen Sie DbgReportSecondaryData auf, um einem anfänglichen Bericht Daten hinzuzufügen, der durch einen vorherigen Aufruf von DbgReportCreate erstellt wurde. Sie können DbgReportSecondaryData mehrmals aufrufen, aber bei jedem Aufruf überschreiben die in den Bericht geschriebenen Daten die vom vorherigen Aufruf geschriebenen Daten. Die folgenden Schritte bieten eine gute Strategie für das inkrementelle Hinzufügen von Daten zum Bericht.

Rufen Sie die Daten ab, die am sichersten zu sammeln sind.
Rufen Sie DbgReportSecondaryData auf, um diese Daten in den Bericht zu schreiben.
Abrufen von Daten, die riskanter zu sammeln sind.
Rufen Sie DbgReportSecondaryData auf, um die ursprünglichen sicheren Daten zusammen mit den neu gesammelten riskanten Daten in den Bericht zu schreiben. Sie müssen sowohl die sicheren als auch die riskanten Daten in diesen Aufruf einbeziehen, da die von diesem Aufruf geschriebenen Daten die Daten überschreiben, die vom ersten Aufruf von DbgReportSecondaryData geschrieben wurden.
Fahren Sie mit dem Aufrufen von DbgReportSecondaryData fort, und verbessern Sie die Daten jedes Mal, bis Sie keine weiteren Daten mehr hinzufügen können.
Wenn Sie das Hinzufügen von Daten zum Bericht abgeschlossen haben, schließen Sie den Bericht, indem Sie DbgReportComplete aufrufen. Der Bericht wird in einer Datei gespeichert und beim Neustart des Computers an Microsoft gesendet.
Wenn der Computer nicht mehr reagiert, bevor Sie DbgReportComplete aufrufen, werden die Dem Bericht durch den letzten erfolgreichen Aufruf von DbgReportSecondaryData hinzugefügten Daten gespeichert und dann an Microsoft gesendet, wenn der Computer neu gestartet wird.

BOOLEAN (*DbgReportSecondaryData)(
  _Inout_ DXGK_DEBUG_REPORT_HANDLE hReport,
  _In_    PVOID                    pvData,
  _In_    ULONG                    ulDataSize
);

hReport ist ein Handle für den Fehlerbericht, an den Daten angefügt werden. Der Anzeige-Miniporttreiber hat dieses Handle zuvor durch Aufrufen von DbgReportCreate abgerufen.
pvData ist ein Zeiger auf einen Puffer, der die Daten enthält, die dem Bericht hinzugefügt werden sollen.
ulDataSize ist die Größe der Daten, die dem Bericht hinzugefügt werden sollen, in Bytes. Der Wert dieses Parameters muss kleiner oder gleich DXGK_DEBUG_REPORT_MAX_SIZE sein.

DbgReportComplete

Schließt einen Fehlerbericht und gibt alle ressourcen frei, die dem Bericht zugeordnet sind.

DbgReportCreate erstellt einen Eintrag im Systemereignisprotokoll und zeigt ein Dialogfeld an, das den Benutzer über den Fehler informiert und die Möglichkeit bietet, einen Fehlerbericht an Microsoft hochzuladen.

Der Fehlerbericht wird in einer Datei gespeichert und soll beim Neustart des Computers an Microsoft gesendet werden. Der Fehlerbericht enthält einen Fehlercode und vier Argumente. Der Fehlercode und die ersten drei Argumente werden vom Aufrufer von DbgReportCreate bereitgestellt. Das vierte Argument im Bericht wird vom Betriebssystem bereitgestellt und gibt die Anzahl der Berichte an, die seit dem Starten des Computers generiert wurden. Wenn der Wert des vierten Arguments beispielsweise 5 ist, bedeutet dies, dass vier vorherige Fehlerberichte vom Anzeige-Miniporttreiber seit dem letzten Start des Computers generiert wurden. Nur der fünfte Bericht wird gespeichert, da jeder Bericht den vorherigen bericht überschreibt.

// IRQL: PASSIVE_LEVEL
VOID DbgReportComplete(
   IN OUT DXGK_DEBUG_REPORT_HANDLE hReport
);

hReport ist ein Handle für den Fehlerbericht, der geschlossen werden soll. Der Anzeige-Miniporttreiber hat dieses Handle zuvor durch Aufrufen von DbgReportCreate abgerufen.

IRQL: PASSIVE_LEVEL

Hinweise

Der Anzeige-Miniporttreiber stellt die Member Size und Version dieser Struktur bereit und ruft dann DxgkCbQueryServices* auf, das die verbleibenden Member dieser Struktur ausfüllt.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows Vista
Kopfzeile	dispmprt.h (include Dispmprt.h)

Freigeben über