DXGK_DEBUG_REPORT_INTERFACE 结构 (dispmprt.h)

项目
08/07/2023

DXGK_DEBUG_REPORT_INTERFACE 结构包含指向调试报表接口中的函数的指针，该接口由显示端口驱动程序实现。

语法

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;

成员

Size

此结构的大小（以字节为单位）。

Version

调试报表接口的版本号。版本号常量在 Dispmprt.h (中定义，例如，DXGK_DEBUG_REPORT_INTERFACE_VERSION_1) 。

Context

指向显示端口驱动程序提供的上下文的指针。

InterfaceReference

指向由显示端口驱动程序实现的接口引用函数的指针。

InterfaceDereference

指向由显示端口驱动程序实现的接口取消引用函数的指针。

DbgReportCreate

创建初始错误报告。

如果显示微型端口驱动程序检测到故障，然后从中恢复，则可以创建一个错误报告，稍后可用于调试。首先，调用 DbgReportCreate 来创建初始报表。然后，通过对 DbgReportSecondaryData 进行一次或多项调用，将数据添加到报表。将数据添加到报表后，请调用 DbgReportComplete。

DbgReportComplete 的语法如下。

// 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 是与显示适配器关联的上下文块的句柄。显示微型端口驱动程序在其 DxgkDdiAddDevice 函数中创建此句柄*。此参数可以为 NULL。
ulCode 是错误报告的代码。支持以下代码：
- THREAD_STUCK_IN_DEVICE_DRIVER
- VIDEO_DRIVER_DEBUG_REPORT_REQUEST
- VIDEO_TDR_FATAL_ERROR
- VIDEO_TDR_SUCCESS
ulpArg1 是要添加到报表中的第一个参数。显示微型端口驱动程序的开发人员确定 ulpArg1 的值和含义。
ulpArg2 是要添加到报表中的第二个参数。显示微型端口驱动程序的开发人员确定 ulpArg2 的值和含义。
ulpArg3 是要添加到报表的第三个参数。显示微型端口驱动程序的开发人员确定 ulpArg3 的值和含义。
ulpArg4 保留。

DbgReportSecondaryData

将数据追加到先前由 DbgReportCreate 创建的初始错误报告。

调用 DbgReportSecondaryData ，将数据添加到先前调用 DbgReportCreate 创建的初始报表。可以多次调用 DbgReportSecondaryData ，但每次调用时，写入报表的数据都会覆盖上一次调用写入的数据。以下步骤提供了以增量方式向报表添加数据的良好策略。

获取最安全收集的数据。
调用 DbgReportSecondaryData 以将数据写入报表。
获取收集风险更大的数据。
调用 DbgReportSecondaryData 将原始安全数据以及新收集的风险数据写入报表。必须在此调用中包含安全和有风险的数据，因为此调用写入的数据会覆盖第一次调用 DbgReportSecondaryData 所写入的数据。
继续调用 DbgReportSecondaryData，每次增强数据，直到没有更多要添加的数据。
将数据添加到报表后，通过调用 DbgReportComplete 关闭报表。报告存储在文件中，并在计算机重新启动时发送给 Microsoft。
如果计算机在调用 DbgReportComplete 之前停止响应，则会保存最近成功调用 DbgReportSecondaryData 添加到报表的数据，然后在计算机重新启动时发送到 Microsoft。

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

hReport 是错误报告的句柄，数据将追加到其中。显示微型端口驱动程序以前通过调用 DbgReportCreate 获取此句柄。
pvData 是指向缓冲区的指针，用于保存要添加到报表的数据。
ulDataSize 是要添加到报表的数据的大小（以字节为单位）。此参数的值必须小于或等于 DXGK_DEBUG_REPORT_MAX_SIZE。

DbgReportComplete

关闭错误报告并释放与报表关联的所有资源。

DbgReportCreate 在系统事件日志中创建一个条目，并显示一个对话框，该对话框通知用户失败并提供将错误报告上传到 Microsoft 的机会。

错误报告保存在文件中，并计划在计算机重新启动时发送给 Microsoft。错误报告包含一个错误代码和四个参数。错误代码和前三个参数由 DbgReportCreate 的调用方提供。报表中的第四个参数由操作系统提供，指示自计算机启动以来生成的报表数。例如，如果第四个参数的值为 5，则表示自上次启动计算机以来，显示微型端口驱动程序生成了四个以前的错误报告。仅保存第五个报表，因为每个报表都覆盖了上一个报表。

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

hReport 是要关闭的错误报告的句柄。显示微型端口驱动程序以前通过调用 DbgReportCreate 获取此句柄。

IRQL： PASSIVE_LEVEL

注解

显示微型端口驱动程序提供此结构的 Size 和 Version 成员，然后调用 DxgkCbQueryServices*，这将填充此结构的其余成员。

要求

要求	值
最低受支持的客户端	Windows Vista
标头	dispmprt.h (包括 Dispmprt.h)

通过

DXGK_DEBUG_REPORT_INTERFACE 结构 (dispmprt.h)

语法

成员

注解

要求

反馈

其他资源