функция обратного вызова DXGKDDI_GETDISPLAYSTATENONINTRUSIVE (dispmprt.h)

Статья
08/07/2023

Операционная система вызывает подпрограмму DxgkDdiGetDisplayStateNonIntrusive драйвера минипорта дисплея для неинструктивного сбора сведений о состоянии отображения от драйвера.

Синтаксис

DXGKDDI_GETDISPLAYSTATENONINTRUSIVE DxgkddiGetdisplaystatenonintrusive;

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

Параметры

[in] Context

Указатель на закрытый контекст, возвращенный DxgkDdiQueryInterface.

[in/out] pArgs

Указатель на структуру DXGKARG_GETDISPLAYSTATENONINTRUSIVE .

Возвращаемое значение

DxgkDdiGetDisplayStateNonIntrusive возвращает STATUS_SUCCESS в случае успешного выполнения. В противном случае возвращается код ошибки, например один из следующих.

Код ошибки	Значение
STATUS_DRIVER_INTERNAL_ERROR	В драйвере произошла общая ошибка программного обеспечения.
STATUS_ACCESS_DENIED	Оборудование в настоящее время используется другими потоками, и этот DDI не может получить доступ к нему.
STATUS_DEVICE_HARDWARE_ERROR	Произошла общая ошибка HW.
STATUS_DEVICE_POWERED_OFF	Устройство отключено.

ОС вызывает DxgkDdiGetDisplayStateNonIntrusive для сбора сведений о состоянии отображения из драйвера. В отличие от DxgkDdiGetDisplayStateIntrusive, подпрограмма DxgkDdiGetDisplayStateNonIntrusive драйвера не должна выполнять никаких операций, вызывающих видимые побочные эффекты для пользователя, и процесс сбора данных должен быть относительно быстрым (в идеале в течение нескольких миллисекунд). Частота вызовов этой подпрограммы будет относительно высокой. Помимо вызова для диагностики плохого состояния пользователя, ОПЕРАЦИОННая система также может использовать эту процедуру для записи сведений о состоянии журнала из драйвера в целях отладки.

В редких случаях, когда для конкретной платформы требуется, чтобы драйвер выполнял интрузивные операции в рамках вызова DxgkDdiGetDisplayStateNonIntrusive, драйвер должен выполнять операции, но должен задать для pArgs-ReturnSubStatus> значение DXGK_DIAG_GETDISPLAYSTATE_CAUSED_GLITCH или DXGK_DIAG_GETDISPLAYSTATE_CHANGED_DISPLAY_STATE соответствующим образом. В зависимости от значения ReturnSubStatus операционная система (ОС) может вызывать эту подпрограмму только для сценариев ошибок в данной системе.

ОС будет часто вызывать DxgkDdiGetDisplayStateNonIntrusive (периодически или при других распространенных событиях) для сбора данных о состоянии драйвера в целях отладки и просмотра исторических временная шкала. Операционная система также будет вызывать эту подпрограмму в определенных сценариях ошибок (таких как черные экраны) перед сбором более подробных сведений путем вызова DxgkDdiGetDisplayStateIntrusive. Учитывая возможную частоту этого вызова, драйверы должны выполнять его как можно быстрее. ОС вызовет этот DDI с параметром NumOfTargets , для которых задано максимальное число целевых объектов, поддерживаемых заданным графическим адаптером, и заполнено значение VidPnTargetId . Драйвер мини-порта должен заполнять сведения о состоянии отображения только для целевых объектов, к которым фактически подключен монитор. Для vidpntarget, на котором нет подключенного монитора, мини-порт должен просто заполнить DXGK_DIAG_DISPLAY_CONNECTIVITY и ОС проигнорирует все остальные поля для этого целевого объекта.

Примечание

Драйверы должны использовать только ReturnSubStatus для отчета об ошибках и не использовать DXGK_DIAG_GETDISPLAYSTATE_MONITOR_NOT_CONNECTED для создания отчетов о состоянии подключения монитора. Цель main DXGK_DIAG_GETDISPLAYSTATE_MONITOR_NOT_CONNECTED — для интрузивных вызовов, когда ОС не спрашивает о подключении монитора.

Если драйвер достигает сбоя в заданном объекте vidpntarget при сборе сведений, он должен использовать ReturnSubStatus , чтобы задать состояние ошибки и перейти к следующему vidpntarget и не завершать общий вызов, если все пути не попадут в сбои. В идеале драйверы должны записывать ошибки во время этого вызова в некоторых внутренних журналах ошибок, чтобы при вызове ОС DxgkDdiCollectDiagnosticInfo для сбора сведений о "черном ящике" эти ошибки регистрировались как часть внутреннего сбора журналов, чтобы помочь IHV во время отладки.

Уровень синхронизации для этого DDI — синхронизация нулевого уровня.