4. 渲染故障排查工具：dmesg日志分析、drm_info、modetest、igt-gpu-tools使用

当GPU渲染出现异常（如画面撕裂、黑屏、花屏、分辨率错误或HDR无法启用）时，系统日志与专用诊断工具是定位问题的第一道防线。本章将系统讲解四个核心排查工具的使用方法、输出解读与典型故障特征。

4.1 dmesg 日志分析：驱动加载与硬件状态

dmesg 是内核环形缓冲区的输出接口，记录从引导到当前时刻的驱动加载、设备枚举、错误与警告信息。在DRM故障排查中，它是第一手证据来源。

4.1.1 关键过滤命令

# 查看 DRM 相关日志（推荐）
dmesg | grep -i drm

# 查看 GPU 驱动相关日志（以 i915/amdgpu/nouveau 为例）
dmesg | grep -iE "i915|amdgpu|nouveau"

# 查看 HDR/色彩空间相关日志
dmesg | grep -iE "hdr|color|bt2020|pq|eotf"

# 查看错误与警告级别日志
dmesg --level=err,warn | grep -iE "drm|gpu|display"

4.1.2 典型故障日志特征

4.2 drm_info：DRM子系统拓扑与属性查看

drm_info 是DRM子系统的诊断工具，以树状结构展示所有DRM设备、CRTC、Encoder、Connector、Plane及其属性。它比 sysfs 更直观，比 modetest 更侧重静态信息。

4.2.1 基本用法

# 查看所有DRM设备信息
drm_info

# 查看指定设备（如 card0）
drm_info --device=/dev/dri/card0

# 输出为 JSON 格式（便于脚本解析）
drm_info --json

4.2.2 输出解读要点

• CRTC：扫描控制器，负责将framebuffer合成并输出。关注其 mode 属性是否与期望分辨率一致。
• Connector：物理接口（HDMI/DP/eDP）。关注 connection 状态（connected/disconnected）、edid 是否存在、hdr_output_metadata 是否支持。
• Plane：硬件图层。关注 type（Primary/Overlay/Cursor）、format 是否包含所需像素格式（如 NV12、P010、ARGB2101010）。
• Encoder：编码器。关注其与CRTC的绑定关系。

4.3 modetest：模式设置与显示测试

modetest 是 libdrm 提供的测试工具，用于枚举显示设备、测试模式设置、绘制测试图案。它可以直接操作DRM接口，绕过用户态合成器（如Wayland/Weston），是验证硬件显示能力的“裸金属”工具。

4.3.1 常用命令

# 列出所有DRM设备及其资源
modetest -M amdgpu

# 在指定连接器上测试模式（如 connector 35，分辨率 1920x1080）
modetest -M amdgpu -s 35:1920x1080-60

# 测试 overlay plane（如 plane 19，使用 NV12 格式）
modetest -M amdgpu -s 35:1920x1080-60 -P 19:1920x1080@NV12

# 测试 HDR 模式（需驱动支持）
modetest -M amdgpu -s 35:3840x2160-60 -C 35:BT2020

4.3.2 输出解读

4.4 igt-gpu-tools：压力测试与合规性检查

igt-gpu-tools（Intel GPU Tools）是DRM子系统最全面的测试套件，包含数百个测试用例，覆盖渲染、显示、电源管理、HDR、VRR等。虽然最初为Intel开发，但已被AMD和NVIDIA（开源驱动）广泛采用。

4.4.1 安装与基本使用

# 安装（以 Ubuntu/Debian 为例）
sudo apt install igt-gpu-tools

# 列出所有测试用例
sudo igt_list_tests

# 运行指定测试（如 kms_hdr）
sudo igt_runner kms_hdr

# 运行所有显示相关测试
sudo igt_runner kms_*

4.4.2 常用测试子集

4.4.3 测试结果解读

# 测试通过示例
IGT-Version: 1.28-git (x86_64) (Linux: 6.5.0-14-generic)
Subtest: test_hdr_metadata
(kms_hdr:1234) CRTC_INFO: HDR metadata set successfully
(kms_hdr:1234) CRTC_INFO: PQ EOTF enabled
Subtest: test_hdr_metadata: SUCCESS (0.001s)

# 测试失败示例
IGT-Version: 1.28-git (x86_64) (Linux: 6.5.0-14-generic)
Subtest: test_hdr_metadata
(kms_hdr:1234) CRTC_DEBUG: Failed to set HDR metadata: Invalid argument
(kms_hdr:1234) CRTC_ERROR: HDR metadata not supported by connector
Subtest: test_hdr_metadata: FAIL (0.002s)

4.5 工具协同使用案例：HDR无法启用排查

以下是一个完整的排查流程，展示四个工具如何协同工作：

1. dmesg：检查驱动加载与HDR相关日志。
   dmesg | grep -iE "hdr|bt2020|pq" → 确认驱动是否支持HDR元数据。
2. drm_info：查看Connector的 hdr_output_metadata 属性。
   drm_info | grep -A 10 "Connector.*HDMI" → 确认连接器是否报告HDR支持。
3. modetest：测试HDR模式设置。
   modetest -M amdgpu -s 35:3840x2160-60 -C 35:BT2020 → 验证硬件能否接受HDR模式。
4. igt-gpu-tools：运行HDR专项测试。
   sudo igt_runner kms_hdr → 获取详细的HDR功能测试报告。