DXGKDDI_GETDISPLAYSTATENONINTRUSIVE回调函数 (dispmprt.h)

项目
02/26/2024

操作系统调用显示微型端口驱动程序的 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	设备已关闭电源。

注解

OS 调用 DxgkDdiGetDisplayStateNonIntrusive 以从驱动程序收集显示状态信息。与 DxgkDdiGetDisplayStateIntrusive 不同，驱动程序的 DxgkDdiGetDisplayStateNonIntrusive 例程不应执行任何对用户造成明显副作用的操作，并且收集过程应相对较快， (理想情况下，) 几毫秒内。此例程的调用频率相对较高。除了需要诊断错误的用户状态外，OS 还可以使用此例程从驱动程序记录历史状态信息，以便进行调试。

在极少数情况下，特定于平台的实现要求驱动程序在调用 DxgkDdiGetDisplayStateNonIntrusive 时执行侵入性操作，驱动程序应执行这些操作，但必须将 pArgs-ReturnSubStatus> 设置为相应的DXGK_DIAG_GETDISPLAYSTATE_CAUSED_GLITCH或DXGK_DIAG_GETDISPLAYSTATE_CHANGED_DISPLAY_STATE。根据 ReturnSubStatus 值，操作系统 (OS) 可能仅针对给定系统上的错误情况调用此例程。

OS 将定期调用 DxgkDdiGetDisplayStateNonIntrusive，或者定期调用其他经常发生的事件 (，) 收集驱动程序状态数据以进行调试，并查看历史时间线。在通过调用 DxgkDdiGetDisplayStateIntrusive 收集更多详细信息之前 (，OS 还会在特定错误情况下调用此例程，例如黑屏) 。鉴于此调用的可能频率，驱动程序应尽快完成。操作系统将调用此 DDI，其中 NumOfTargets 设置为给定图形适配器支持的最大目标数，并填充 了 VidPnTargetId 。微型端口驱动程序应仅填充实际连接了监视器的目标的显示状态信息。对于未连接监视器的 vidpntarget，微型端口应只填写DXGK_DIAG_DISPLAY_CONNECTIVITY操作系统将忽略该目标的所有其他字段。

注意

驱动程序应仅使用 ReturnSubStatus 报告错误条件，而不应使用DXGK_DIAG_GETDISPLAYSTATE_MONITOR_NOT_CONNECTED报告监视器连接状态。 DXGK_DIAG_GETDISPLAYSTATE_MONITOR_NOT_CONNECTED main用途是用于操作系统不询问监视器连接性的侵入性调用。

如果驱动程序在收集信息时在给定 vidpntarget 上遇到故障，则它应使用 ReturnSubStatus 设置错误状态并继续下一个 vidpntarget，并且不会使总体调用失败，除非所有路径都失败。理想情况下，驱动程序应在某些内部错误日志中记录此调用期间遇到的错误，以便当 OS 调用 DxgkDdiCollectDiagnosticInfo 来收集黑盒信息时，这些错误会捕获为内部日志收集的一部分，以帮助 IHV 在调试期间帮助 IHV。

此 DDI 的同步级别为零级同步。