1. 显示驱动调试的战场为什么工具选不对排查效率差十倍做显示驱动这行的朋友都有体会屏幕点不亮、花屏、闪屏、分辨率不对、旋转方向反了、多屏输出错乱——这些问题一旦出现如果没有趁手的调试工具基本就是盲人摸象。你只能靠加打印、反复编译内核、重启设备来试一轮下来十几分钟没了一天也验证不了几个猜想。而显示驱动又偏偏是嵌入式、移动端、车载座舱里最容易出问题、也最难定位的模块之一因为它横跨了硬件时序、总线协议、内核框架、用户态合成器好几个层次。这篇内容就是围绕显示驱动调试工具展开的。我会把 DRM 子系统的核心调试手段、modetest 这类用户态工具的用法、Android 平台上显示相关的排查路径以及实际工作中踩过的坑尽量讲透。关键词覆盖显示驱动、调试工具、DRM、modetest、Android 这几个方向。不管你是刚接手显示模块的新人还是已经调过几块屏的老手这里应该都能找到能直接抄作业的东西。先说一个反直觉的结论显示驱动调试里大部分问题根本不需要改代码就能定位。真正高效的排查是先用手头的工具把问题出在哪一层确定下来再决定要不要动驱动。很多人一上来就翻驱动源码结果查了半天发现是设备树里一个时序参数写错了或者用户态合成器配置不对。工具的价值就在于帮你快速分层。2. DRM 框架下的调试入口从内核态到用户态的完整链路2.1 为什么 DRM 的调试信息都藏在 debugfs 里现代 Linux 显示驱动基本都跑在 DRMDirect Rendering Manager框架下。DRM 把显示管线抽象成了一套对象模型CRTC 负责扫描输出时序Encoder 负责把像素编码成具体接口信号Connector 代表物理接口HDMI、DP、MIPI DSI 等Plane 是图层Framebuffer 是帧缓冲。这套抽象很优雅但问题是它把大量状态藏在内核里用户态默认看不到。所以 DRM 把关键调试信息都暴露在了 debugfs 下典型路径是/sys/kernel/debug/dri/。这个目录下通常会有若干个以数字编号的子目录每个对应一个 DRM 设备节点。进去之后你会看到一堆文件我挑几个最常用的说modes当前 Connector 支持的所有显示模式列表排查为什么这个分辨率点不亮第一站。state当前显示管线的完整状态快照包括每个 CRTC 绑定的 Connector、当前 mode、Plane 配置等。这个文件是排查多屏、图层问题的核心。framebuffer当前注册的 framebuffer 信息看格式、尺寸、pitch。gem_names或类似文件查看 GEM 对象分配情况排查内存泄漏时有用。clients哪些用户态进程打开了这个 DRM 设备排查谁占着屏幕不放很有用。注意debugfs 默认可能没挂载。如果/sys/kernel/debug是空的先执行mount -t debugfs none /sys/kernel/debug。另外部分内核出于安全考虑会限制 debugfs 访问权限需要 root。我个人的习惯是接手一块新屏或者遇到显示异常第一件事就是cat /sys/kernel/debug/dri/0/state把当前状态完整看一遍。很多时候问题一眼就能看出来比如某个 CRTC 的 mode 是空的或者 Connector 的 status 显示 disconnected 但硬件明明插着。2.2 内核日志里的显示线索怎么抓debugfs 是静态快照内核日志则是动态过程。显示驱动在初始化、模式设置、热插拔时都会打日志关键是你要知道过滤什么。最直接的是按 DRM 相关模块名过滤。不同平台模块名不一样常见的有drm、msm、i915、rockchip-drm、mediatek-drm等。用dmesg | grep -i drm能捞出一大批。但日志量大时我建议按关键字分层过滤排查时序问题grepmode、timing、pclk、hdisplay、vdisplay。排查连接问题grephotplug、connect、edid、hpd。排查内存问题grepgem、alloc、fail、oom。排查电源问题greppower、regulator、clk、enable。这里有个经验显示驱动的日志往往在系统启动早期就打完了如果你用dmesg看不到可能是环形缓冲区被冲掉了。可以调大 log buffer或者用dmesg -s 1048576指定更大的读取缓冲区。另外printk.devkmsgon这类参数有时会影响日志输出排查时留意一下。2.3 从内核态到用户态谁在真正控制屏幕很多人搞不清一件事内核 DRM 驱动只是提供了能力真正决定屏幕上显示什么的往往是用户态。在 Android 上是 SurfaceFlinger在桌面 Linux 上是合成器如 Weston、Mutter在嵌入式里可能是直接调 DRM API 的应用。所以当你看到屏幕异常时要先判断是内核态问题还是用户态问题。一个简单的判断方法用 modetest 直接绕过用户态合成器去设置模式。如果 modetest 能正常显示测试图案说明内核 DRM 驱动和硬件链路是好的问题在用户态如果 modetest 也不行那问题大概率在内核或硬件。这个分层判断能帮你省下大量时间。我见过不少案例驱动工程师吭哧吭哧查了半天内核最后发现是合成器配置里把某个图层设成了透明。3. modetest 实战一个工具打通显示管线验证3.1 modetest 到底能干什么modetest 是 libdrm 自带的一个用户态测试工具源码在 libdrm 的 tests/modetest 目录下。它的核心能力是枚举 DRM 设备上的所有资源CRTC、Encoder、Connector、Plane、Framebuffer并允许你手动组合这些资源来设置显示模式。它的典型用途有这么几个验证某块屏能不能点亮、支持哪些分辨率。测试多屏同时输出的组合。验证图层Plane叠加、缩放、格式转换是否正常。在用户态合成器出问题时作为对照手段确认内核链路是否正常。编译上如果你用的是发行版直接apt install libdrm-tests或类似包就能装上。嵌入式环境一般需要自己交叉编译 libdrm把 modetest 一起编出来。交叉编译时注意链接的 libdrm 版本要和设备上的驱动匹配版本差太多可能出现 ioctl 不兼容。3.2 枚举资源先看清楚手里有什么牌不带参数直接跑modetest -M driver它会打印出设备上所有资源。输出分几大块Encoders、Connectors、CRTCs、Planes、Frame buffers。我一般重点看 Connectors 和 CRTCs。Connectors 那块会列出每个接口的 ID、状态connected/disconnected、支持的 modes 列表、支持的 encoder。比如你看到某个 HDMI connector 状态是 connectedmodes 里有一堆分辨率那说明 EDID 读取正常硬件检测也没问题。CRTCs 那块列出每个 CRTC 的 ID 和它当前绑定的 framebuffer。如果某个 CRTC 的 fb 是 0说明它当前没在输出。这里有个细节modetest 输出的 mode 名字后面会带一些标记比如(15)这种是 refresh rate表示 preferred mode。preferred mode 是显示器 EDID 里推荐的模式通常优先用它。3.3 点亮一块屏的完整命令拆解假设你已经从枚举结果里拿到了connector ID 是 40CRTC ID 是 35想用 1920x1080 模式。最基础的命令是modetest -M rockchip -s 4035:1920x1080这里的-s是 set mode格式是connectorcrtc:mode。执行后屏幕上应该会出现 modetest 默认的测试图案彩条加一些几何图形。如果你想指定刷新率可以写成1920x1080-60。如果想用 connector 的 preferred mode可以省略 mode 部分直接-s 4035。再进一步如果你想测试某个特定格式的 framebuffer可以用-P参数指定 plane 和格式modetest -M rockchip -s 4035:1920x1080 -P 4535:1920x1080AR24这里45是 plane IDAR24是像素格式ARGB8888。这个命令会把指定 plane 绑定到 CRTC 上用 AR24 格式显示测试图案。测试不同格式支持情况时特别有用。3.4 多屏与图层组合的验证套路多屏场景下modetest 可以同时设置多个 connector。比如双屏输出modetest -M rockchip -s 4035:1920x1080 -s 4136:1280x720注意两个 connector 要绑到不同的 CRTC 上如果硬件 CRTC 数量不够第二个会失败。这时候枚举结果里的 CRTC 数量就是你的上限。图层叠加测试是另一个高频场景。比如你想验证一个视频层叠加在 UI 层上面可以用多个-P参数modetest -M rockchip -s 4035:1920x1080 -P 4535:1920x1080AR24 -P 4635:1280x720NV12这里第二个 plane 用了 NV12 格式模拟视频层。如果显示正常说明硬件的图层叠加和格式转换都没问题。如果花屏或者颜色不对那就要查格式配置或者硬件能力了。提示plane 的 ID 和它支持的格式、能力能否缩放、能否旋转都在枚举结果里。绑定前先确认这个 plane 支不支持你要的格式否则会报错。3.5 modetest 报错信息怎么读modetest 的报错通常比较直接但有几个高频错误值得单独说failed to set mode: Permission denied权限问题检查是不是 root或者有没有被 SELinux/AppArmor 拦。failed to set mode: Invalid argument参数不合法最常见的是 mode 和 connector 不匹配或者 CRTC 已经被占用。no CRTC foundCRTC 数量不够或者都被占了。failed to create framebuffer内存分配失败或者格式不支持。遇到报错别急着改代码先把枚举结果和报错对照着看八成能定位到是参数问题还是能力问题。4. Android 平台显示调试的特殊性4.1 Android 显示栈和标准 Linux 的差异Android 虽然底层也是 Linux 内核加 DRM但显示栈上面叠了厚厚一层。从下往上大致是内核 DRM 驱动 → HWCHardware Composer→ SurfaceFlinger → 应用。HWC 是 Android 特有的硬件合成抽象层它决定了哪些图层交给硬件合成、哪些交给 GPU。这个结构带来的调试复杂性在于同一个显示异常可能是内核 DRM 的问题可能是 HWC 的问题也可能是 SurfaceFlinger 的合成策略问题。而且 Android 的权限管理更严很多 debugfs 节点默认访问不了。所以在 Android 上排查显示问题第一步往往是确认问题在哪一层。我常用的手段是用dumpsys SurfaceFlinger看合成器状态、图层列表、显示设备信息。用dumpsys display看显示设备管理器的状态。如果设备有 root还是可以用 modetest 直接测内核链路。看logcat里 HWC 和 SurfaceFlinger 的日志。4.2 dumpsys 里那些关键字段dumpsys SurfaceFlinger的输出很长但有几个字段是必看的Display Devices列出所有显示设备包括内置屏、外接屏以及它们的活跃模式、分辨率、刷新率。Layers当前所有图层的列表包括每个图层的可见性、位置、格式、合成方式Device 还是 Client。Composition合成策略能看到哪些图层走了硬件合成。如果屏幕花屏我会先看 Layers 里有没有异常图层比如某个图层格式不对或者位置越界。如果某个图层本该走硬件合成却走了 GPU可能是 HWC 的能力判断出了问题。dumpsys display则更偏向显示设备管理能看到每个 display 的状态、支持的 mode、当前 mode、亮度等。排查外接屏识别问题时特别有用。4.3 Android 上跑 modetest 的注意事项Android 上跑 modetest 有几个坑第一权限。Android 的/dev/dri/card0默认只有特定用户组能访问普通 shell 进不去。需要 root 后chmod或者用su切换。第二SELinux。即使 root 了SELinux 也可能拦住对 DRM 设备的访问。临时可以用setenforce 0关掉 enforcing 模式验证但生产环境不能这么干得配 policy。第三SurfaceFlinger 占用。如果 SurfaceFlinger 正在用这个 DRM 设备modetest 去设置模式可能冲突。稳妥的做法是先停掉 SurfaceFlingerstop surfaceflinger测完再启回来。第四Android 的 DRM 驱动可能做了定制某些标准 ioctl 行为不一致。遇到 modetest 报奇怪的错先确认驱动版本和 libdrm 版本是否匹配。4.4 从 logcat 里捞显示相关日志Android 的日志系统比 dmesg 复杂但过滤好了效率很高。显示相关的 tag 常见的有SurfaceFlinger、HWComposer、gralloc、display。logcat -s SurfaceFlinger HWComposer gralloc如果日志太多可以按关键字再过滤比如logcat | grep -i mode\|resolution\|hotplug。有个经验Android 启动早期的显示初始化日志很关键但默认 logcat 可能抓不到。可以用logcat -b all抓所有缓冲区或者看dmesg里的内核日志。另外persist.vendor.log之类的属性有时会影响日志级别排查时留意。5. 那些年踩过的显示调试坑5.1 时序参数差一点屏幕就是点不亮这是最经典的坑。MIPI DSI 屏的时序参数hactive、hfront-porch、hback-porch、hsync-len、vactive、vfront-porch、vback-porch、vsync-len、pixel clock必须和屏厂规格书完全一致差一点就可能点不亮或者显示偏移。我遇到过一次屏幕能亮但图像整体右移了几十个像素。查了半天驱动代码最后发现是 hback-porch 少写了 20。这种问题用 modetest 反而不好查因为它用的是标准模式不走你的自定义时序。得靠内核日志里的 timing 打印或者直接对照规格书逐项核对。经验是拿到新屏先把规格书里的时序参数抄成一张表和驱动里的值逐项对比。别嫌麻烦这一步能省下后面几小时的排查。5.2 EDID 读取失败导致分辨率不对HDMI/DP 外接屏的分辨率是靠 EDID 协商的。如果 EDID 读取失败系统会 fallback 到一个默认模式通常是最低分辨率。表现就是外接屏能亮但分辨率很低。排查方法看内核日志里有没有EDID相关的错误比如 checksum 失败、读取超时。用 modetest 枚举 connector如果 modes 列表是空的或者只有一两个默认模式基本就是 EDID 没读到。原因可能是 I2C 总线问题、HPD 检测问题、或者屏本身 EDID 数据有问题。可以尝试强制指定 mode 绕过 EDID验证是不是 EDID 的锅。5.3 多屏场景下 CRTC 分配错乱多屏输出时CRTC 和 Connector 的绑定关系很关键。如果绑定错了可能出现两个屏显示同样的内容或者一个屏黑屏。modetest 枚举时能清楚看到每个 CRTC 当前绑定的 encoder 和 connector。如果发现绑定关系不对可以手动用-s重新绑定。但要注意有些硬件对 CRTC 和 Connector 的对应关系有限制不是任意组合都行。这个限制通常在驱动里枚举结果的 encoder possible_crtcs 字段能看到。5.4 Android 上图层格式不匹配导致花屏Android 的 gralloc 分配的 buffer 格式和 HWC 期望的格式如果不匹配就会花屏或者颜色错乱。这种问题在 logcat 里通常有unsupported format之类的报错。排查时先看dumpsys SurfaceFlinger里图层的格式再对照 HWC 支持的格式列表。如果确实不支持要么改 gralloc 分配格式要么让 HWC 走 GPU 合成兜底。5.5 debugfs 节点消失的诡异情况有时候你会发现/sys/kernel/debug/dri/下空空如也或者某些节点不见了。这通常是因为驱动初始化失败或者 debugfs 没挂载。先确认挂载再看内核日志里 DRM 驱动有没有报错。还有一种情况是驱动被编译成了模块但没加载lsmod | grep drm确认一下。6. 把工具用成条件反射我的显示调试工作流调了这么多显示问题我慢慢形成了一套固定的工作流分享出来供参考。第一步确认现象。屏幕是完全不亮、花屏、闪屏、分辨率不对、还是颜色异常现象不同排查方向完全不同。第二步分层定位。用 modetest 绕过用户态测内核链路。能亮说明内核 OK问题在上层不能亮说明问题在内核或硬件。第三步看状态。cat /sys/kernel/debug/dri/0/state看当前管线状态对照预期找差异。第四步查日志。dmesg 和 logcat 按关键字过滤找报错和异常。第五步对照规格。时序参数、格式、能力逐项对照硬件规格书。第六步最小化验证。用最简单的配置单屏、单图层、标准模式先跑通再逐步加复杂度。这套流程看起来简单但能覆盖八成以上的显示问题。剩下的两成往往是硬件本身的问题或者驱动里的深层 bug那就需要更深入的调试手段了比如用逻辑分析仪抓 MIPI 信号、用示波器看时钟。最后分享一个小技巧把常用的 modetest 命令和 debugfs 路径做成脚本或者 alias排查时直接调用能省下不少敲命令的时间。显示调试本身就是个体力活能自动化的部分尽量自动化。另外不同平台的 DRM 驱动实现差异挺大遇到问题别只盯着通用文档多看具体平台的驱动源码和厂商文档。很多坑是平台特有的通用资料里根本不会提。