做显示驱动调试的人大概都经历过这种时刻屏幕不亮驱动代码来回看了好几遍寄存器也按手册配了硬件同事说信号已近送到屏端可问题就是不知道卡在哪一层。前面几篇我们把显示驱动的框架、设备树、开机点亮的流程都过了一遍这篇专门聊调试工具——准确说是我自己在实际项目中反复用、确实能救命的那几个工具以及我习惯的排查路子。显示驱动调试工具和使用思路这几年还算比较热门的话题。很多人一上来就问“用什么工具”但实际上工具只是后半段前面更关键的是你要能判断问题到底发生在数据层还是时序层还是链路物理层。工具选错了越调越乱。这篇我按实际排查顺序来讲先把链条拆开再一个层次一个层次地说该用什么工具、怎么用、实际会遇到什么幺蛾子。1. 显示驱动调试为什么麻烦先认清链路和“症状对应层”显示驱动和串口、网卡这类驱动最大的不同是它的数据路径特别长。上层提交的画面要经过用户态DRM接口、内核的Plane/CRTC/Encoder、物理传输链路最后到屏端的驱动芯片任何一个环节出问题现象都是“屏幕显示不正常”。我见过不少同事拿到一个花屏问题上来就翻寄存器翻了半天没结果。原因很简单花屏可能是内存里的数据被踩了可能是framebuffer的stride配错可能是MIPI DSI的同步包丢了甚至可能是背光闪烁被误判成花屏。这四个原因对应的排查工具完全不同如果不对症下药纯靠肉眼看现象猜效率非常低。我一般会先把“症状”映射到“嫌疑层”。这不需要什么高科技一张简单的对照表就够了症状优先怀疑的层首轮排查方向完全不亮电源、时序、使能信号示波器量CLK/DE查寄存器花屏/错位数据层、时序参数导出framebuffer、查HBP/HSW颜色异常像素格式、颜色深度检查XRGB/RGB格式配置闪屏/白条时序、背光控制抓GPIO翻转跟踪vblank/flip撕裂(tearing)帧同步、page flip查vblank中断频率、fence回片分辨率不对EDID解析、mode配置edid-decode、modetest有了这张表再决定用哪些工具。我自己还有一个习惯排查显示问题之前先把“分辨率刷新率接口类型”这三个要素固定下来。很多问题不是必然出现的比如某个时序参数在1080p60下刚好合规切到720p50就出界了。你不固定复现条件后面会用大量时间在无关参数上打转。这套思路定了下面每个章节就按链条的层次来展开先查画面对不对再查时序参数再追踪运行行为最后落到物理链路。2. 画面数据对不对用户态工具与帧缓冲导出显示问题一出现我第一步永远是确认“内核拿到的画面内容到底是啥”。屏幕显示的是最终结果但驱动内部真正处理的是framebuffer里的裸像素数据。数据对了再往时序查数据本身就错了那就是数据层的配置问题。2.1 modetest三秒钟看清当前显示链路状态modetest是libdrm自带的一个测试工具也是我优先级最高的工具。它能在不写业务代码的情况下把当前DRM设备的所有connector、crtc、encoder、plane以及它们之间的绑定关系全部打出来。常用命令组合是这样的# 查看当前设备的全局链路拓扑 modetest -M card0 -c # 查看plane属性 modetest -M card0 -p # 强制把某个connector设为指定分辨率 modetest -M card0 -s 32:1920x108060第一次用的时候重点看-c输出的内容。一个正常的connector条目会告诉你当前连接状态、连接的是哪个crtc、支持哪些mode、EDID里读到的物理尺寸、当前生效的mode是什么。我习惯先确认“内核认为当前分辨率是多少”而不是“上层设置的多少”。这两个经常不一样。之前就遇到过应用层以为自己设置的是1080p其实内核已经悄悄回退到1024x768现象就是画面被等比缩放加上两侧黑边很多人会去查合成器配置其实modetest扫一眼就明白了。modetest还可以用来快速验证“某个分辨率能不能设上去”。直接modetest -s 32:1920x1080如果设不了通常会有error信息这就能把“应用层设置失败”和“内核拒绝该mode”两种问题快速分开。2.2 导出framebuffer把驱动看到的画面拉到电脑上看modetest只看链路状态要想看实际画面内容最直接的办法是把/dev/fb0里的裸数据导出然后转成图片。# 把当前framebuffer导出成裸数据 dd if/dev/fb0 of/tmp/fb.raw bs1920 count1080这里bs其实是每行字节数不一定等于宽乘以像素字节数要看stride。如果stride和宽度不对应直接按宽高去转图片出来的画面会斜切。这是排查时最容易忽略的点。导出来后用Python转成PNGimport sys import numpy as np from PIL import Image # 用法: python fb2png.py fb.raw 1920 1080 xrgb8888 path, w, h, fmt sys.argv[1], int(sys.argv[2]), int(sys.argv[3]), sys.argv[4] raw np.fromfile(path, dtypenp.uint8) if fmt xrgb8888: img_data raw[: w * h * 4].reshape(h, w, 4)[:, :, [0, 1, 2]] elif fmt rgb565: rgb565 raw[: w * h * 2].reshape(h, w, 2).astype(np.uint16) r ((rgb565[:, :, 1] 3) 0x1F) 3 g ((rgb565[:, :, 0] 5) | ((rgb565[:, :, 1] 0x07) 3)) 2 b ((rgb565[:, :, 0] 2) 0x1F) 3 img_data np.stack([r, g, b], axis-1) Image.fromarray(img_data.astype(np.uint8)).save(fb.png)转出来的图片如果能对上预期画面说明数据层没问题问题在时序或物理链路如果转出来是斜的、花条纹或者颜色错乱那就是framebuffer的地址映射、stride、颜色格式这边出了问题。我遇到过最典型的情况驱动配置了RGB565输出但用户态按XRGB8888去提交显示出来所有颜色都偏紫偏蓝大部分人会去调gamma其实只是格式不匹配。用这个脚本一看一眼就能定位。建议把脚本存下来几乎每个显示项目都会用到。2.3 无硬件联调用虚拟显示驱动先跑通流程很多时候屏端硬件还没回来或者出问题的时候不方便接屏这时候我建议用内核自带的虚拟显示驱动先把KMS流程跑通。它不需要真实显示器在内核里模拟一个connector能完整走一遍DRM/KMS的modeset链路。这种虚拟环境下modetest依然能用看拓扑、切分辨率、绑定plane都没问题。这样做的好处是能把“驱动逻辑的问题”和“屏端物理的问题”快速隔离。比如用户态提交一个4K模式失败虚拟环境下也失败那就是内核KMS配置逻辑有问题虚拟环境下成功而真实屏失败那才需要往EDID、时序参数、物理链路方向查。这个思路也被很多团队应用在CI回归里每次改完驱动代码先在虚拟显示环境下跑一遍modetest和协议测试基本能挡掉大部分低级错误。3. 时序和物理信号从寄存器到示波器的分层确认画面数据没问题问题还在的话十有八九出在时序参数上。时序这东西软件能看到的是寄存器的值硬件能看到的是波形两边对不上就是bug所在。3.1 用devmem直接读寄存器验证驱动“以为”的配置驱动代码里配置的时序参数不一定等于实际写入寄存器的值。有些芯片在写入时会做钳制例如水平后沿最小值限制、像素时钟范围限制等有些驱动还会在commit流程里被后面的模块二次修改。所以我习惯把寄存器直接读出来看。# 读取芯片寄存器32位宽度 devmem 0x32a10020 32地址从哪里来芯片手册的显示控制器章节。比如你想确认当前HBP的值查找LCDC时序配置寄存器的位定义把读回的值按位解析。这里特别提醒一点选寄存器之前先确认模块时钟是否使能。曾经在排查时读了一下午全都是0后来发现时钟门控没打开读回的是总线上的默认值根本不是控制器里的值。有了寄存器值再和驱动代码里计算出的时序参数对照问题往往立刻现形。比如代码里HFP配了88寄存器里只有16那就要查是谁在中间做了钳制还是寄存器地址搞错了。3.2 EDID解码你配的时序屏可能根本不认显示器端的能力是通过EDID上报的。驱动解析EDID出错或者显示器的EDID本身写得有问题都会导致时序参数算出来是“能在屏幕上亮但实际不对”的状态。读取并解码EDID其实很简单# 从sysfs直接导出EDID dd if/sys/class/drm/card0-DP-1/edid of/tmp/edid.bin bs128 count1 # 用edid-decode解析 edid-decode /tmp/edid.binedid-decode的输出里我最关注的是Detailed Timing Descriptor和Display Range Limits这两段。前者告诉你在某个分辨率下厂商建议的HFP/HBP/HSW/VFP/VBP/VSV值是多少后者告诉你像素时钟的上下限。某个项目就出过这种问题显示器的EDID里写的最佳时序是1080p60像素时钟148.5MHz但驱动自动计算时没参考厂商时序而是按CVT公式自己算了一套导致HBP偏大、有效像素被压缩到屏幕外右边出现一条约20像素的黑边。后来直接按EDID里的厂商时序去做问题就没了。所以EDID在时序排查里不是可有可无的工具而是第一手依据。3.3 逻辑分析仪和示波器物理链路上的“照妖镜”前面所有软件工具都验证完之后如果问题还在就只能上硬件测量工具了。对显示驱动来说最重要的两个是逻辑分析仪和示波器。逻辑分析仪适合抓协议包。比如MIPI DSI信号用逻辑分析仪配合协议解析插件能直接看到命令包的类型、数据负载、LP/HS状态切换。判断驱动发出去的初始化序列是否正确、同步包有没有丢失靠这个最直观。用的时候有个坑别把采样率拉到最高同时开所有通道逻辑分析仪的内存是有限的采样率越高能采的时间越短。正确做法是先预估信号频率选一个刚好满足采样定理余量的采样率再设定合适的触发条件。比如抓DSI的同步包就配置触发条件为“检测到HS-LP切换沿”这样能精准定位到链路切换的瞬间。示波器则用于看模拟特性。像素时钟的频率是否准确、信号的上升沿是否够陡、DE信号的极性是否正确、有没有异常的毛刺这些都得用示波器量。选示波器时带宽至少要探头信号频率的3到5倍测的时候探头接地线要尽量短否则容易测出假的振铃。这套组合拳里最关键的经验是不要一开始就拿示波器四处点。一定要先用软件工具缩小范围到只剩下“某个信号的某个边沿不对”这种具体怀疑时再上硬件测量。否则显示屏可能就几条信号线盲扫逻辑分析仪采回来的数据足够你分析一整周。3.4 HFP/HBP/HSW到底怎么查边界花屏的常见凶器要说显示时序参数里最容易出幺蛾子的HFP/HBP/HSW这三个水平方向的参数排第一。它们决定了每一行有效像素之前和之后“等待”多少个像素时钟。配置不当最典型的现象就是画面整体左右偏移、边缘出现竖条、或者特定分辨率下花屏。排查时不要只看驱动代码里的初始值一定要配合前面说的devmem读寄存器以及示波器量H/V同步信号相对于DE的位置。三者一致才说明配置真正生效了。我见过一个案例驱动代码里HBP在1920x1080下是220看起来没问题但切到1280x720时由于代码里用了同一个修正系数HBP被算成了负数驱动钳制后变成了16结果画面下半部分整体错位。这种问题光看代码很难发现必须靠寄存器读回加上实际画面共同确认。4. 运行中的行为追踪日志、ftrace和状态文件时序问题排查完还有一类不好碰的问题属于“动态行为”范畴。现象是偶发闪一下、偶尔撕裂、运行几个小时才出现一次。这类问题靠静态配置检查没用必须在运行过程中把驱动“做过什么”全部记录下来。4.1 DRM日志开关怎么开才有效很多驱动都有调试日志但默认是关的。DRM框架层可以通过参数直接打开# 打开DRM核心调试日志0x1f是常用的一组组合 echo 0x1f /sys/module/drm/parameters/debug打开后dmesg里会出现大量和KMS提交、vblank事件、fence信号相关的信息。不过我建议按需开不要图省事直接设成0xff因为日志量大会严重拖慢系统本来偶现的问题可能就复现不出来了。如果是自己维护的驱动我会更推荐在关键函数入口加分级打印模式切换、plane更新、中断处理这几处用动态调试。内核的动态调试机制允许运行时按函数名开关日志配合trace_printk能拿到比普通printk更精准的时间戳和上下文。4.2 ftrace给函数调用过程“录像”偶现问题最难的是你不知道它发生在什么路径上。ftrace可以把函数调用关系录下来我通常用函数图模式抓DRM相关的调用链# 挂载tracefs mount -t tracefs tracefs /sys/kernel/tracing # 切换到函数图模式只跟踪drm相关函数 echo function_graph /sys/kernel/tracing/current_tracer echo drm_* /sys/kernel/tracing/set_ftrace_filter echo 1 /sys/kernel/tracing/tracing_on # 复现问题之后把trace导出来 cat /sys/kernel/tracing/trace /tmp/drm_trace.txt拿到trace后先看模式切换期间有没有函数被调用到一半就返回或者某个atomic check函数返回错误导致整个commit回滚。之前遇到一个偶发黑屏就是通过ftrace看到某个平台的vblank使能函数在关闭后再打开时漏了一个状态恢复导致下一次flip不产生vblank事件应用层就一直等画面就卡在黑屏上。ftrace对低版本内核还有个兼容性问题有时候/sys/kernel/debug/tracing路径不存在需要先确认debugfs有没有挂载。现在的内核里tracefs和debugfs是分开的两个文件系统别挂错了。4.3 读KMS状态文件看驱动“自己以为”的状态动态调试和ftrace看的是过程但很多时候我也需要看结果。DRM框架提供了一个状态导出路径把当前所有对象的状态打出来cat /sys/kernel/debug/dri/0/state这个文件会列出所有crtc、encoder、connector、plane的当前状态、绑定的对象ID、属性值。出现“显示状态和预期不符”的问题时这个文件特别有用。它能告诉你内核认为哪个plane正在扫描、扫描的framebuffer ID是多少、crtc有没有被enable。如果内核状态和实际屏幕显示不一致那问题就可能出在硬件寄存器没同步上如果内核状态本身已经错了那就是驱动状态机逻辑有bug。类似地还可以用drm_info工具查看更细的属性信息比如当前像素格式、颜色编码、色彩深度。调试颜色异常时这个比反复猜要快得多。4.4 帧率、撕裂和vblank事件性能类问题的观测点涉及帧率不稳、画面撕裂这类性能问题时我一般看两件事一是vblank中断是不是按预期频率触发二是page flip有没有按时完成。vblank事件可以从dmesg里打开相关日志观察也可以用ftrace跟踪drm_handle_vblank这类关键函数。如果vblank中断频率只有预期的一半那多半是panel刷新率配置错了或者中断被其他高优先级任务挤占。如果vblank正常但画面还是撕裂那问题就在应用层的提交策略比如没有等vblank就直接提交了下一帧或者双缓冲交换时机不对。page flip队列满的问题也很常见。用modetest反复切帧能测出来如果连续切换几十次后出现busy错误那就是驱动里fence回片太慢前一个buffer还在被扫描就收到新的flip请求。这种情况需要在驱动里查fence的信号时机也可以临时在用户态做“提交前等待上一帧完成”的规避但根因多半是驱动在vblank中断里处理的事太多。5. 一个闪屏叠加错位问题的完整排查链路工具都过了一遍我拿一个实际遇到的完整排查过程来串一下这样更有参考价值。现象是这样的某嵌入式设备1080p下一切正常切到720p后屏幕下半部分明显错位而且每隔几秒闪一下白条。现象很随机复现率又高业务方最开始怀疑是应用层合成问题。我一上来没用示波器先做了两件事。第一把framebuffer导出来转成PNG发现画面内容本身完全正确说明数据层没问题。第二用modetest确认720p模式确实设置成功而且crtc也切过去了说明链路状态基本正常。那问题就往时序配置上引。接下来读dmesg看到一条关于像素时钟超出范围的告警。再拿edid-decode看显示器的EDID发现这个屏在720p下厂商建议的HBP值应该比较大但驱动在改分辨率时复用了1080p的一组系数算出来的HBP超出了硬件的钳制范围最终被控制器压到了最小值。用devmem读寄存器确认实际上生效的HBP确实和驱动代码里计算的值不一致。到这里下半屏错位的根因就锁定了水平后沿太小导致每行的有效数据被提前推进显示位置整体错位。剩下那个“闪白条”还没有解释。我用ftrace盯着背光控制的GPIO操作函数发现它每次都跟着一通背光enable/disable被周期触发。问题在板级配置用来控制背光的GPIO和显示接口的热插拔检测脚在初始化时发生复用冲突运行过程中只要检测线程误读到电平变化就会误触发一次背光关闭再开启视觉上就是白条闪一下。修复方式分两处修改模式切换代码里的时序参数计算逻辑按厂商建议值重新计算HBP/HFP同时修正GPIO的mux配置把背光控制脚独占出来。修完之后连续10个小时在两种分辨率之间每30秒切换一次做压力测试没有再复现。整个过程用到的工具就是modetest、dd加Python转图、edid-decode、devmem、dmesg、ftrace一个示波器都没用。这个案例想说明的是显示驱动的问题往往不是单点的可能是“配置错误外部资源冲突”的组合。按链路一层层排查每一层都用对工具看起来复杂的现象是可以被拆解掉的。6. 常用调试工具清单和几个使用习惯文章最后把上面提到的工具整理成一张速查表方便平时排查照着用。工具作用推荐使用场景关键注意点modetest查看/设置DRM链路状态排查分辨率、链路绑定问题和内核DRM版本保持匹配fbset/dd读取framebuffer原始数据判断画面数据是否正确注意stride和格式PythonPIL裸数据转图片可视化framebuffer内容格式参数要按实际配置edid-decode解析显示器EDID确认厂商推荐时序和范围注意le16/be16字节序devmem直接读寄存器验证配置是否真正生效先确认模块时钟门控dmesg内核日志看驱动报错和告警只开需要的日志级别动态调试运行时函数级日志定位驱动内部流程不要全开会拖慢系统ftrace记录函数调用链排查偶发流程问题注意tracefs挂载路径debugfs dri state导出完整KMS状态判断内核状态是否异常需要root权限逻辑分析仪抓总线协议包排查DSI/LVDS链路问题采样率和触发条件先想清楚示波器测量信号波形和时序排查物理信号问题带宽要够接地线要短vkms虚拟显示无屏模拟KMS流程前期联调、CI回归不能验证物理信号质量几个我已经固化的使用习惯第一永远先定复现条件再动工具。分辨率、刷新率、接口类型、温度环境这些没固定之前任何工具测出来的结果都可能误导你。第二软件工具能解决的问题绝不用硬件工具去猜。导出帧缓冲、读寄存器、看日志这三板斧能覆盖超过七成的显示驱动问题剩下真正需要示波器的通常已经是硬件设计层面的硬骨头。第三显示驱动问题有时候病根在显示链路之外。这次背光GPIO就是典型所以我排查时除了DRM自家工具还会顺手看看GPIO、电源、时钟相关节点的状态能少走很多弯路。第四虚拟显示驱动跑回归是个性价比很高的做法。每次改动合入之前先在上面跑一遍modetest的切分辨率测试能挡住不少低级错误。回到标题说的“必备调试工具”我的核心观点其实就是一句话别迷信某个特别厉害的工具真正重要的是养成“按链路层次选择工具”的排查习惯。把数据层、时序层、运行行为、物理信号这四个层次的工具都准备好显示驱动的大多数问题都能在一个合理的时间内定位到根因。这篇是系列第5篇后面如果大家对某个工具的实际使用细节感兴趣比如modetest的原子提交用法或者ftrace在显示问题里的更多案例我可以再单独展开写。希望这篇能帮正在被显示问题折磨的同行们省下几个通宵。