VIDEO_PORT_DEBUG_REPORT_INTERFACE structure (video.h)

Article
08/19/2022

The VIDEO_PORT_DEBUG_REPORT_INTERFACE structure holds pointers to the Debug Report functions, which are implemented by the video port driver.

Syntax

typedef struct _VIDEO_PORT_DEBUG_REPORT_INTERFACE
{
    IN USHORT                  Size;
    IN USHORT                  Version;
    OUT PVOID                  Context;
    OUT PINTERFACE_REFERENCE   InterfaceReference;
    OUT PINTERFACE_DEREFERENCE InterfaceDereference;

    OUT
    PVIDEO_DEBUG_REPORT
    (*DbgReportCreate)(
        IN PVOID HwDeviceExtension,
        IN ULONG ulCode,
        IN ULONG_PTR ulpArg1,
        IN ULONG_PTR ulpArg2,
        IN ULONG_PTR ulpArg3,
        IN ULONG_PTR ulpArg4
        );

    OUT
    BOOLEAN
    (*DbgReportSecondaryData)(
        IN OUT PVIDEO_DEBUG_REPORT pReport,
        IN PVOID pvData,
        IN ULONG ulDataSize
        );

    OUT
    VOID
    (*DbgReportComplete)(
        IN OUT PVIDEO_DEBUG_REPORT pReport
        );
} VIDEO_PORT_DEBUG_REPORT_INTERFACE, *PVIDEO_PORT_DEBUG_REPORT_INTERFACE;

Members

Size

Specifies the size, in bytes, of this structure.

Version

Specifies the version of the interface returned by the video port driver. Currently, the only supported version is VIDEO_PORT_DEBUG_REPORT_INTERFACE_VERSION_1.

Context

Pointer to a context that is provided by the video port driver.

InterfaceReference

Pointer to an interface reference function that is implemented by the video port driver.

InterfaceDereference

Pointer to an interface dereference function that is implemented by the video port driver.

OUT (IN PVOID HwDeviceExtension,IN ULONG ulCode,IN ULONG_PTR ulpArg1,IN ULONG_PTR ulpArg2,IN ULONG_PTR ulpArg3,IN ULONG_PTR ulpArg4) PVIDEO_DEBUG_REPORT( *DbgReportCreate unnamedParam1)

OUT (IN OUT PVIDEO_DEBUG_REPORT pReport,IN PVOID pvData,IN ULONG ulDataSize) BOOLEAN( *DbgReportSecondaryData unnamedParam1)

OUT (IN OUT PVIDEO_DEBUG_REPORT pReport) VOID( *DbgReportComplete unnamedParam1)

Remarks

The video miniport driver supplies the Size and Version members of this structure, and then calls VideoPortQueryServices, which initializes its remaining members.

If your video miniport driver detects a failure and then recovers from it, you can create an error report that can later be used for debugging by calling the callback function members of VIDEO_PORT_DEBUG_REPORT_INTERFACE as follows:

First, call DbgReportCreate to create an initial report.
Then add data to the report by making one or more calls to DbgReportSecondaryData.
When you have finished adding data to the report, call DbgReportComplete.

The error report is saved in a file and scheduled to be sent to Microsoft when the computer is rebooted. The error report contains an error code and four arguments. The error code and the first three arguments are provided by the caller of DbgReportCreate. The fourth argument in the report is provided by the operating system and indicates the number of reports generated since the computer was started. For example, if the value of ulpArg4 is 5, this means that four previous error reports were generated by the display miniport driver since the computer was last started. Only the fifth report is saved because each report overwrites the previous one.

The VIDEO_DEBUG_REPORT structure returned by DbgReportCreate and subsequently passed to DbgReportSecondaryData and DbgReportComplete is opaque. Do not attempt to access its members directly.

The following sections describe these callback functions in detail. These callbacks must be called at IRQL = PASSIVE_LEVEL.

DbgReportCreate

DbgReportCreate creates an initial error report. It creates an entry in the system event log and displays a dialog box that informs the user of the failure and presents the opportunity to upload an error report to Microsoft. DbgReportCreate returns a pointer to an opaque VIDEO_DEBUG_REPORT structure that represents a handle to the newly created debug report.

DbgReportCreate Parameters

HwDeviceHandle [in] A handle to a context block associated with a display adapter. The display miniport driver created this handle in its DxgkDdiAddDevice function. This parameter can be NULL.
ulCode [in] A code for the error report. The following codes are supported: THREAD_STUCK_IN_DEVICE_DRIVER VIDEO_DRIVER_DEBUG_REPORT_REQUEST, VIDEO_TDR_FATAL_ERROR, and VIDEO_TDR_SUCCESS.
ulpArg1 [in] The first argument to be added to the report. The developer of the display miniport driver determines the value and meaning of ulpArg1.
ulpArg2 [in] The second argument to be added to the report. The developer of the display miniport driver determines the value and meaning of ulpArg2.
ulpArg3 [in] The third argument to be added to the report. The developer of the display miniport driver determines the value and meaning of ulpArg3.
ulpArg4 [in] Reserved for system use.

DbgReportSecondaryData

The DbgReportSecondaryData function appends data to an initial error report that was previously created by DbgReportCreate. If DbgReportSecondaryData succeeds, it returns TRUE. Otherwise, it returns FALSE.

Call DbgReportSecondaryData to add data to an initial report that was created by a previous call to DbgReportCreate. You can call DbgReportSecondaryData several times, but with each call, the data written to the report overwrites the data written by the previous call. The following steps give a good strategy for incrementally adding data to the report.

Obtain the data that is safest to collect.
Call DbgReportSecondaryData to write that data to the report.
Obtain data that is more risky to collect.
Call DbgReportSecondaryData to write the original safe data along with the newly collected risky data to the report. You must include both the safe and the risky data in this call because the data written by this call overwrites the data written by the first call to DbgReportSecondaryData.
Continue calling DbgReportSecondaryData, enhancing the data each time, until you have no more data to add.

When you have finished adding data to the report, close the report by calling DbgReportComplete. If the computer stops responding before you call DbgReportComplete, the data added to the report by the most recent successful call to DbgReportSecondaryData is saved and then sent to Microsoft when the computer is rebooted.

DbgReportSecondaryData Parameters

hReport [in, out] A handle to the error report to which data will be appended. The display miniport driver previously obtained this handle by calling DbgReportCreate.
pvData [in] A pointer to a buffer that holds the data to be added to the report.
ulDataSize [in] The size, in bytes, of the data to be added to the report. The value of this parameter must be less than or equal to DXGK_DEBUG_REPORT_MAX_SIZE.

DbgReportComplete

The DbgReportComplete function closes an error report and frees any resources associated with the report.

DbgReportComplete creates an entry in the system event log and displays a dialog box that informs the user of the failure and the opportunity to upload an error report to Microsoft.

DbgReportComplete Parameters

hReport A pointer to a VIDEO_DEBUG_REPORT structure that contains a handle to the error report that is to be closed. The display miniport driver previously obtained this handle by calling DbgReportCreate.

Requirements

Requirement	Value
Minimum supported client	Windows XP SP2
Minimum supported server	Windows Server 2003 SP1
Header	video.h (include Video.h)

Share via