DXGKDDI_COLLECTDIAGNOSTICINFO callback function (dispmprt.h)

Article
10/21/2021

The DxgkDdiCollectDiagnosticInfo callback routine collects the private driver information for reasons that are specified by DXGK_DIAGNOSTICINFO_TYPE.

In Windows 10, version 1903, the driver will be called to collect private information if the function calls to DxgkDdiAddDevice or DxgkDdiStartDevice failed.

Syntax

DXGKDDI_COLLECTDIAGNOSTICINFO DxgkddiCollectdiagnosticinfo;

NTSTATUS DxgkddiCollectdiagnosticinfo(
  [in]      IN_CONST_PDEVICE_OBJECT PhysicalDeviceObject,
  [in, out] INOUT_PDXGKARG_COLLECTDIAGNOSTICINFO pCollectDiagnosticInfo
)
{...}

Parameters

[in] PhysicalDeviceObject

A pointer to a physical device object (PDO) that identifies a display adapter.

[in, out] pCollectDiagnosticInfo

A pointer to a DXGKARG_COLLECTDIAGNOSTICINFO structure which describes information collected by the driver.

Return value

Returns STATUS_SUCCESS if the private data information was successfully collected. Otherwise, it returns an error code such as one of the following.

Error Code	Meaning
STATUS_DRIVER_INTERNAL_ERROR	A generic SW error happened inside the driver.
STATUS_ACCESS_DENIED	The hardware is currently being used by other threads and this DDI can't get access to it.
STATUS_DEVICE_HARDWARE_ERROR	A generic HW error happened.
STATUS_DEVICE_POWERED_OFF	The device is powered off.

Remarks

This function is called at PASSIVE level, at any time in between the calls to DxgkDdiAddDevice and DxgkDdiStartDevice, and should support synchronization zero level. The collected data shouldn't contain any private user information.

WDDM 2.7 and later drivers are required to support the DXGK_DI_BLACKSCREEN DXGK_DIAGNOSTICINFO_TYPE enum type for black screen black box data collection.

For black screen scenarios, the OS will first collect the white box data from the driver by calling DxgkDdiGetDisplayStateNonIntrusive and DxgkDdiGetDisplayStateIntrusive before calling this DDI to collect black box information.

It is recommended to use pCollectDiagnosticInfo->BucketingString to bucketize the black box data where possible. If the size of the BufferSizeIn input buffer is not sufficient for all the black box data then drivers should make their own tradeoffs in leaving out the data that is least important in most black screen root cause analysis.

Requirements

Requirement	Value
Minimum supported client	Windows 10, version 1903
Header	dispmprt.h
IRQL	PASSIVE_LEVEL