去年拿到一块龙芯 3A5000 的开发板系统起来不算难麻烦的是图形界面。Xorg 日志翻来覆去看了好几遍libdrm 也重编过最后折腾了一圈才发现问题根本不在用户态而是内核里那块显示控制器驱动没有按预期工作。这一步步把问题挖到底之后LSDC 这个名字才真正进入了我的视野。LSDC 是龙芯 SoC 里显示控制器的缩写也是 Linux 内核 DRM 子系统下对应驱动的名字。这篇文章就把我对 LSDC DRM 驱动的理解、源码层面的分析思路、以及实际调试时踩过的坑完整记录下来给同样在做龙芯平台显示适配、或者想搞清楚一个 DRM 显示驱动是怎么从头搭起来的读者做个参考。1. 为什么我建议入手龙芯显示适配时先读懂 LSDC1.1 一块开发板的黑屏把我引到了 DRM 驱动层先说个具体的场景。板子启动后系统日志一切正常串口能登录但接上 HDMI 显示器就是没有信号。按常规思路先怀疑 Xorg 配置换过 xf86-video-modesetting也试过不加载任何 xf86-video 驱动再怀疑用户态渲染直接跑modetest看内核输出能力结果 modetest 根本枚举不出任何连接器。这时候排查范围已经缩到内核了。lsmod里能看到驱动模块在但dmesg | grep -i lsdc一看驱动 probe 阶段就报错了。这个经历让我意识到一件事在龙芯这种 SoC 平台上显示链路从上到下的分层比普通 x86 平台更要靠底层驱动兜底而 LSDC 就是这条链路里最接近硬件的那一环。1.2 LSDC 这个名字背后的实际含义龙芯 SoC 的图形方案分两块一部分型号内部有独立的 GPU 核心另一部分只带一个纯粹的显示控制器。LSDC 要管的就是后者——它本身不参与 3D 渲染只管把内存里的帧数据按一定时序送到显示接口上。换句话说LSDC 驱动要做的事非常聚焦驱动初始化、显存对象管理、模式设置、输出管线的连接与探测。它不需要实现复杂的 GPU 调度也不需要 command buffer 提交这让它的代码量比常见 GPU 驱动小很多反而适合做 DRM 驱动入门和移植参考。但量小不等于简单。显示控制器直接操作寄存器所有的初始化顺序、时序计算、中断处理都要精确匹配硬件规格任何一个疏忽都会直接表现为黑屏或者花屏而且这种问题很难通过用户态手段定位。1.3 读这份驱动的正确姿势如果你之前只写过 userspace 程序第一次打开内核 DRM 驱动源码可能会觉得绕IOCTL 入口、文件操作、回调函数、原子提交……一层包一层。我的建议是不要按源码文件的顺序从头读到尾而是按运营链路来读先搞清设备是怎么被发现的再追一个 framebuffer 从用户态提交到屏幕上显示要经过哪些代码路径最后再回来看初始化细节。接下来我会按照这个思路来拆解。2. DRM 框架下的 LSDC四个核心对象与两条分界线2.1 Plane、CRTC、Encoder、Connector 在 LSDC 里的映射DRM 框架把显示硬件抽象成四类对象Plane、CRTC、Encoder、Connector。用大白话解释Plane 是画面图层比如主图层、光标图层它把一块显存区域和屏幕上的显示区域关联起来。CRTC 是显示时序发生器负责产生像素时钟、行场同步信号决定当前屏幕显示的是哪个 Plane。Encoder 是信号编码转换单元把 CRTC 输出的并行 RGB/时序信号转成 HDMI、VGA 或其他接口需要的信号。Connector 对应物理输出接口负责探测有没有显示器连接、读取 EDID、返回显示器支持的显示模式。LSDC 驱动的输出链路基本也是这套模型。你在代码里会看到struct lsdc_crtc、struct lsdc_encoder、struct lsdc_connector这一层封装它们内部嵌着 DRM 框架定义的公共结构体再通过 container_of 互相访问。理解这个映射关系有什么用Debug 的时候你能迅速判断问题出在哪个环节同样是黑屏CRTC 没使能、Encoder 没通电、Connector 没探测到显示器表象可能完全一样但排查路径完全不同。我后来定位黑屏问题时第一件事就是问自己modetest 里到底有没有列出 connector没有——那就别急着查时序参数先查管线枚举。2.2 用户态与内核态的 ioctl 边界LSDC 驱动负责接收用户态通过/dev/dri/card0发来的系统调用。libdrm 把drmModeGetResources、drmModeSetCrtc、drmModePageFlip这类操作封装成 ioctl内核侧的drm_ioctl再根据命令字分发给驱动设置的回调。这里有一条重要分界线**DRM 核心框架处理通用的对象管理和资源分配LSDC 驱动只需要实现硬件相关的回调。**比如 framebuffer 的创建、对象的引用计数、atomic 状态管理这些活儿框架都帮你干了LSDC 要做的只是实现struct drm_driver里的gem_create_object、prime_fd_to_handle以及在 CRTC/Plane 回调里把具体的寄存器参数算好、写进去。所以读 LSDC 源码不需要从头一个函数一个函数啃先找到struct drm_driver定义看它注册了哪些回调哪些是驱动自己实现的哪些是空操作整个驱动的边界就清楚了。2.3 寄存器资源的获取方式驱动能干活的前提是能访问到硬件寄存器。LSDC 通常以 platform device 的形式挂在设备树里设备树节点会描述寄存器起始地址、中断号等信息。驱动 probe 时通过平台资源接口拿到这些信息再映射到内核虚拟地址空间。典型的代码风格大致如下static int lsdc_platform_probe(struct platform_device *pdev) { struct resource *res; void __iomem *reg_base; res platform_get_resource(pdev, IORESOURCE_MEM, 0); reg_base devm_ioremap_resource(pdev-dev, res); if (IS_ERR(reg_base)) return PTR_ERR(reg_base); /* 后续通过 reg_base offset 访问各控制器寄存器 */ }这里有个经验值得提内核里看到的寄存器地址已经经过了 CPU 地址映射千万不要直接拿设备树里的物理地址当作驱动里 I/O 读写地址用。另外显示控制器通常有多个功能块比如主显示控制、HDMI 接口控制、I2C 控制器它们在寄存器空间里各占一段偏移。驱动头文件里会维护对应的偏移定义读源码时建议对照数据手册一起看否则很难理解那些魔法数字的含义。3. 从 probe 到上屏初始化调用的关键链路3.1 probe 阶段的标准舞步一个 DRM 驱动的初始化流程在框架层面其实有固定套路。LSDC 的 probe 函数大致遵循以下顺序先做硬件资源准备映射寄存器、获取中断、初始化时钟相关配置。分配并初始化struct drm_device把驱动私有数据挂进去。注册 DRM 驱动回调比如文件操作、GEM 相关的钩子。创建各个输出组件Plane/CRTC/Encoder/Connector并建立连接关系。调用drm_dev_register让设备对用户态可见。如果启用了 fbdev 模拟层再初始化一下兼容 framebuffer。这个顺序看起来平淡但每一步的顺序都是有讲究的。比如第 4 步必须在第 5 步之前完成因为drm_dev_register之后用户态就能打开设备了如果组件还没注册好用户态 ioctl 问框架要资源列表时只能拿到一个残缺的管线。3.2 输出管线的搭建顺序输出组件的创建顺序同样值得琢磨。我读驱动时注意到一个特征Plane 和 CRTC 的初始化通常会放在 Encoder 前面。这背后的逻辑是——CRTC 要绑定到它支持的 Plane 上在 DRM 的 atomic 框架里Plane 和 CRTC 的关联关系需要提前建立起来。用表格简化一下各组件在初始化阶段最常见的职责组件初始化阶段主要任务后续运行时的关键回调Plane声明支持的像素格式、创建属性atomic_update把 framebuffer 地址写入寄存器CRTC保存硬件上下文、初始化时序链mode_set计算并写入时序、enable/disable开关输出Encoder关联 CRTC 与 Connectorenable启动信号链路、atomic_check校验连接关系Connector注册物理接口、获取 EDID 相关方法detect探测显示设备、get_modes返回可用模式列表在 LS2K2000 这类型号上驱动甚至可能支持不止一个显示输出比如 HDMI 和 VGA 各有一个 Connector。多个输出同时存在时初始化流程会更复杂要保证每个 Connector 都能通过 Encoder 找到对应的 CRTC同时不能被框架错误地串线。这一步稍有疏漏就会出现独显启动后 HDMI 有信号但 VGA 无信号这类缺一路的怪问题。3.3 fbdev 兼容层让字符终端也能显示很多人不理解为什么 DRM 驱动里还带着fbdev emulation这种东西。原因很现实系统启动阶段引导程序要显示 logo内核崩溃时要打 oops 到屏幕上这些场景依赖一个简单直接的显示接口而不是完整 DRM 框架。LSDC 驱动通常会注册一个drm_fbdev_emulation或类似机制在 DRM 设备之上模拟一个 /dev/fb0。这样一来开机 logo、字符终端、甚至一些老的显示工具都能正常工作而真正的图形栈例如 Xorg 或 Wayland 合成器仍然通过 DRM 主设备工作。调试时这个兼容层特别有用。如果/dev/fb0上 printf 的内容能正常显示说明底层显示管线已经通了问题很可能出在用户态图形栈如果 fb0 都黑屏直接去查驱动初始化也不迟。4. 一帧画面的旅程从 DRM Framebuffer 到像素时钟4.1 GEM 对象、显存与 framebuffer 的关系用户态要显示一张画面首先要创建一块放置像素数据的缓存。在 DRM 框架里这块缓存被封装成 GEM 对象再给 GEM 对象套上格式、分辨率等描述信息就变成了 DRM Framebuffer。LSDC 驱动平时用的是主平面它把 Framebuffer 对应的内存地址取出来通过 Plane 的更新回调写到显示控制器的起始地址寄存器里。这里要注意的是显示控制器在扫描输出时访问的是物理地址所以驱动必须保证这块内存在 DMA 访问期间是有效的并且地址对齐满足硬件要求——这也是下一章要讲的显存分配问题的由来。4.2 模式设置与时序计算模式设置是 CRTC 回调里最重要的一块逻辑。当用户在 Xorg 或者通过drmModeSetCrtc切换分辨率时内核会走一遍 atomic 模式设置流程。LSDC 得到struct drm_display_mode之后要把它换算成自己控制器能认的时序参数。换算的核心是把显示模式里的水平/垂直时序参数active、blank 起始、sync 偏移等转换成寄存器值。举个直观的例子一个 1920x108060 的模式实际行周期不是只有 1920 个像素还要算上前后肩、同步脉冲最终大概落在 2200 个像素时钟周期左右。像素时钟频率、Htotal、Vtotal 这三个参数决定了最终的刷新率。这一部分出错最常见的结果不是死机而是画面偏移屏幕左右滚动这类看起来很奇怪的现象。说实话我第一次遇到屏幕右移出一大块黑边时完全没往时序寄存器想后来对照数据手册逐个字段排查才发现是同步脉冲宽度配置不对。4.3 Plane 更新与帧切换LSDC 扫描显示时默认读取的是主平面指到的那块显存地址。如果显示内容要更新用户态只需要把新的 Framebuffer 提交上来触发 Plane 的 atomic_update 回调驱动在这里把新的 Framebuffer 地址写入控制器。这里有一个关键细节**写显存地址的时机要跟硬件扫描同步。**如果在控制器刚好扫到屏幕中间时改了显存地址用户就会看到撕裂tearing。常见做法是等垂直消隐期再更新寄存器或者启用控制器的双缓冲机制。LSDC 驱动设计中帧切换路径上通常会把这种同步逻辑考虑进去用户态配合 PageFlip 也能实现无撕裂的流畅切换。4.4 连接器探测与 EDID 读取显示器插入、拔出、开机时内核需要对 Connector 做一次探测。探测的核心动作是通过连接器对应的 I2C 通道读显示器 EDID解析出它支持的分辨率和刷新率列表再交给用户态去选择。LSDC 驱动里往往也包含一个 I2C 适配器实现——可能挂在显示控制器的 I2C 控制器之上也可能操作 GPIO 模拟 I2C。这部分代码虽然不起眼但经常是HDMI 为什么识别不到显示器的根源。一开始我不理解为什么显示驱动还要管 I2C后来调试一台电视不识别的问题查到最后就是 EDID 读取时序没有按显示器的要求来。5. 显存管理设计LSDC 如何选择 TTM/GEM5.1 龙芯 SoC 的显示内存格局LSDC 驱动的显存管理之所以值得单独讲是因为龙芯低端 SoC 的显示控制器大多没有独立显存。它扫描输出的数据要从系统内存里来这就带来两个要求内存物理连续、DMA 可访问。这跟带独显 GPU 的平台完全不同。独显驱动管的是板载 VRAM显存分配逻辑相对独立LSDC 要管的则是把系统内存里某一段划给显示控制器用。如果这段内存不连续或者分配时没有考虑 DMA 地址宽度限制显示就会出现花屏甚至完全无法输出。5.2 GEM 与 TTM 的取舍DRM 框架下有两套显存管理思路GEM 和 TTM。GEM 是通用图形内存管理主打简洁TTM 则能管理显存/系统内存之间的换入换出多用于独立显卡。LSDC 这种没有独立显存的显示控制器通常更适合 GEM 路线分配本质上就是dma_alloc_attrs或者drm_gem_cma_*拿到一块物理连续的内存然后按 GEM 对象包装起来交给用户态做 mmap 或者显存导入导出。如果驱动选择 TTM一般是像样的独立 GPU 或者模拟 GPU 才会用到。LSDC 类驱动如果用 TTM 但又不做换出那纯粹是给自己增加复杂度。读代码时看到驱动用的是哪个管理模型基本就能判断出作者的侧重点。5.3 大块连续内存的分配实践LSDC 需要的是一大块连续物理内存这块内存要能被显示控制器直接按地址访问。实际驱动代码里常见的路径是在 GEM 对象创建时走 DMA 分配器得到总线地址和分配大小然后把它映射成用户态可写的虚拟地址。这里有一个容易踩的坑**调试时要留意 32 位与 64 位地址空间的问题。**显示控制器的 DMA 地址宽度未必跟 CPU 一致如果 SoC 的显示控制器只能寻址低 32 位物理地址而系统内存分配出来的 DMA 地址落在 4G 以上那即使驱动看起来分配成功了显示画面依然是不确定的。好在现代龙芯平台大多已经放宽了地址宽度但在做老旧板卡适配时还是要主动确认这个细节。6. 调试 LSDC 驱动的四个关键位置与踩坑记录6.1 先看 dmesg 中的 lsdc 加载记录调 LSDC 的第一步永远是dmesg | grep -i lsdc。驱动 probe 阶段如果失败一般会留下比较明确的错误日志比如资源获取失败、某个寄存器读写结果不符合预期、设备树 compatible 没匹配上。如果 kernel log 里完全没有 lsdc 字样的记录就要往前查是不是设备树节点没使能驱动是否编进了内核模块是否被加载我有一次遇到的驱动不工作到最后竟然是内核 config 里把模块编成了 built-in但设备树 compatible 字符串没对上整个 probe 回调直接被跳过了。6.2 用 modetest 验证输出管线用户态最趁手的探查工具是modetest它是 libdrm 自带的测试程序。运行modetest -c能列出 Connectormodetest -p能看 Plane 信息modetest -M可以指定驱动名称。一个典型的验证流程是先确认 Connector 存在再确认它能在插上显示器之后枚举出正确的 mode 列表然后用modetest -s指定 connector 和分辨率做一次测试显示。如果这步能点亮屏幕说明从 GEM 到 CRTC 再到 Connector 的整条链路是通的如果这步不行再逐层拆。我还习惯配合/sys/kernel/debug/dri/0/下面的调试节点来看寄存器或状态。很多 DRM 驱动在 debugfs 里导出了每个组件的状态字符串对快速判断驱动认为当前处于什么状态非常有用。6.3 黑屏、花屏定位顺序遇到黑屏我通常按这个顺序排查串口/日志层面确认驱动加载成功无 probe 错误。dmesg里看 Connector 是否检测到显示器EDID 是否读到。用 modetest 手动触发一次模式设置确认 CRTC 是否使能、时钟是否输出。检查显存地址与 framebuffer 内容可以在调试节点里 dump 一小块内存确认写入的像素数据正确。最后才是怀疑硬件链路比如 HDMI 线缆、转接器、显示器输入源。花屏则通常指向显存参数要么内存地址不对要么 stride 行距没对上。常见错误是把 1920x1080 的 stride 按 1920 算忘了每个像素占 4 字节结果画面整体切斜。6.4 移植到新板卡时最容易忽略的环节如果你想把 LSDC 驱动从参考板移植到新板卡最值得注意的不是驱动源码本身而是设备树描述。寄存器基地址、中断号、时钟来源、复位信号的描述都要跟着新板子重新核对。尤其是显示涉及到的时钟树很多 SoC 的显示控制器需要外部源配置好正确的像素时钟才能工作这种配置往往放在 bootloader 或者设备树 clk 节点里驱动本身只管寄存器而不管 PLL 初始化的具体策略。另外提醒一点不同型号龙芯 SoC 的显示控制器寄存器偏移可能并不完全一致。移植时不要想当然地认为参考板上的偏移定义在新芯片上也一样最好逐个功能块对照新芯片的数据手册确认否则会因为一个看似不起眼的寄存器位被写错换来一个莫名其妙的黑屏。最后分享一个我自己养成的调试习惯拿到一块新板子我会只做最小化的验证——先把内核默认 framebuffer 的 logo 成功显示出来再把 modetest 的测试画面点亮这之后再考虑跑完整的图形栈。这两步通过基本能判定 LSDC 驱动层的初始化、模式设置、显存分配都正常剩下的问题就往用户态丢。别一上来就并行排查否则黑屏问题很容易变成五六个变量搅在一起的泥潭。
去年拿到一块龙芯 3A5000 的开发板系统起来不算难麻烦的是图形界面。Xorg 日志翻来覆去看了好几遍libdrm 也重编过最后折腾了一圈才发现问题根本不在用户态而是内核里那块显示控制器驱动没有按预期工作。这一步步把问题挖到底之后LSDC 这个名字才真正进入了我的视野。LSDC 是龙芯 SoC 里显示控制器的缩写也是 Linux 内核 DRM 子系统下对应驱动的名字。这篇文章就把我对 LSDC DRM 驱动的理解、源码层面的分析思路、以及实际调试时踩过的坑完整记录下来给同样在做龙芯平台显示适配、或者想搞清楚一个 DRM 显示驱动是怎么从头搭起来的读者做个参考。1. 为什么我建议入手龙芯显示适配时先读懂 LSDC1.1 一块开发板的黑屏把我引到了 DRM 驱动层先说个具体的场景。板子启动后系统日志一切正常串口能登录但接上 HDMI 显示器就是没有信号。按常规思路先怀疑 Xorg 配置换过 xf86-video-modesetting也试过不加载任何 xf86-video 驱动再怀疑用户态渲染直接跑modetest看内核输出能力结果 modetest 根本枚举不出任何连接器。这时候排查范围已经缩到内核了。lsmod里能看到驱动模块在但dmesg | grep -i lsdc一看驱动 probe 阶段就报错了。这个经历让我意识到一件事在龙芯这种 SoC 平台上显示链路从上到下的分层比普通 x86 平台更要靠底层驱动兜底而 LSDC 就是这条链路里最接近硬件的那一环。1.2 LSDC 这个名字背后的实际含义龙芯 SoC 的图形方案分两块一部分型号内部有独立的 GPU 核心另一部分只带一个纯粹的显示控制器。LSDC 要管的就是后者——它本身不参与 3D 渲染只管把内存里的帧数据按一定时序送到显示接口上。换句话说LSDC 驱动要做的事非常聚焦驱动初始化、显存对象管理、模式设置、输出管线的连接与探测。它不需要实现复杂的 GPU 调度也不需要 command buffer 提交这让它的代码量比常见 GPU 驱动小很多反而适合做 DRM 驱动入门和移植参考。但量小不等于简单。显示控制器直接操作寄存器所有的初始化顺序、时序计算、中断处理都要精确匹配硬件规格任何一个疏忽都会直接表现为黑屏或者花屏而且这种问题很难通过用户态手段定位。1.3 读这份驱动的正确姿势如果你之前只写过 userspace 程序第一次打开内核 DRM 驱动源码可能会觉得绕IOCTL 入口、文件操作、回调函数、原子提交……一层包一层。我的建议是不要按源码文件的顺序从头读到尾而是按运营链路来读先搞清设备是怎么被发现的再追一个 framebuffer 从用户态提交到屏幕上显示要经过哪些代码路径最后再回来看初始化细节。接下来我会按照这个思路来拆解。2. DRM 框架下的 LSDC四个核心对象与两条分界线2.1 Plane、CRTC、Encoder、Connector 在 LSDC 里的映射DRM 框架把显示硬件抽象成四类对象Plane、CRTC、Encoder、Connector。用大白话解释Plane 是画面图层比如主图层、光标图层它把一块显存区域和屏幕上的显示区域关联起来。CRTC 是显示时序发生器负责产生像素时钟、行场同步信号决定当前屏幕显示的是哪个 Plane。Encoder 是信号编码转换单元把 CRTC 输出的并行 RGB/时序信号转成 HDMI、VGA 或其他接口需要的信号。Connector 对应物理输出接口负责探测有没有显示器连接、读取 EDID、返回显示器支持的显示模式。LSDC 驱动的输出链路基本也是这套模型。你在代码里会看到struct lsdc_crtc、struct lsdc_encoder、struct lsdc_connector这一层封装它们内部嵌着 DRM 框架定义的公共结构体再通过 container_of 互相访问。理解这个映射关系有什么用Debug 的时候你能迅速判断问题出在哪个环节同样是黑屏CRTC 没使能、Encoder 没通电、Connector 没探测到显示器表象可能完全一样但排查路径完全不同。我后来定位黑屏问题时第一件事就是问自己modetest 里到底有没有列出 connector没有——那就别急着查时序参数先查管线枚举。2.2 用户态与内核态的 ioctl 边界LSDC 驱动负责接收用户态通过/dev/dri/card0发来的系统调用。libdrm 把drmModeGetResources、drmModeSetCrtc、drmModePageFlip这类操作封装成 ioctl内核侧的drm_ioctl再根据命令字分发给驱动设置的回调。这里有一条重要分界线**DRM 核心框架处理通用的对象管理和资源分配LSDC 驱动只需要实现硬件相关的回调。**比如 framebuffer 的创建、对象的引用计数、atomic 状态管理这些活儿框架都帮你干了LSDC 要做的只是实现struct drm_driver里的gem_create_object、prime_fd_to_handle以及在 CRTC/Plane 回调里把具体的寄存器参数算好、写进去。所以读 LSDC 源码不需要从头一个函数一个函数啃先找到struct drm_driver定义看它注册了哪些回调哪些是驱动自己实现的哪些是空操作整个驱动的边界就清楚了。2.3 寄存器资源的获取方式驱动能干活的前提是能访问到硬件寄存器。LSDC 通常以 platform device 的形式挂在设备树里设备树节点会描述寄存器起始地址、中断号等信息。驱动 probe 时通过平台资源接口拿到这些信息再映射到内核虚拟地址空间。典型的代码风格大致如下static int lsdc_platform_probe(struct platform_device *pdev) { struct resource *res; void __iomem *reg_base; res platform_get_resource(pdev, IORESOURCE_MEM, 0); reg_base devm_ioremap_resource(pdev-dev, res); if (IS_ERR(reg_base)) return PTR_ERR(reg_base); /* 后续通过 reg_base offset 访问各控制器寄存器 */ }这里有个经验值得提内核里看到的寄存器地址已经经过了 CPU 地址映射千万不要直接拿设备树里的物理地址当作驱动里 I/O 读写地址用。另外显示控制器通常有多个功能块比如主显示控制、HDMI 接口控制、I2C 控制器它们在寄存器空间里各占一段偏移。驱动头文件里会维护对应的偏移定义读源码时建议对照数据手册一起看否则很难理解那些魔法数字的含义。3. 从 probe 到上屏初始化调用的关键链路3.1 probe 阶段的标准舞步一个 DRM 驱动的初始化流程在框架层面其实有固定套路。LSDC 的 probe 函数大致遵循以下顺序先做硬件资源准备映射寄存器、获取中断、初始化时钟相关配置。分配并初始化struct drm_device把驱动私有数据挂进去。注册 DRM 驱动回调比如文件操作、GEM 相关的钩子。创建各个输出组件Plane/CRTC/Encoder/Connector并建立连接关系。调用drm_dev_register让设备对用户态可见。如果启用了 fbdev 模拟层再初始化一下兼容 framebuffer。这个顺序看起来平淡但每一步的顺序都是有讲究的。比如第 4 步必须在第 5 步之前完成因为drm_dev_register之后用户态就能打开设备了如果组件还没注册好用户态 ioctl 问框架要资源列表时只能拿到一个残缺的管线。3.2 输出管线的搭建顺序输出组件的创建顺序同样值得琢磨。我读驱动时注意到一个特征Plane 和 CRTC 的初始化通常会放在 Encoder 前面。这背后的逻辑是——CRTC 要绑定到它支持的 Plane 上在 DRM 的 atomic 框架里Plane 和 CRTC 的关联关系需要提前建立起来。用表格简化一下各组件在初始化阶段最常见的职责组件初始化阶段主要任务后续运行时的关键回调Plane声明支持的像素格式、创建属性atomic_update把 framebuffer 地址写入寄存器CRTC保存硬件上下文、初始化时序链mode_set计算并写入时序、enable/disable开关输出Encoder关联 CRTC 与 Connectorenable启动信号链路、atomic_check校验连接关系Connector注册物理接口、获取 EDID 相关方法detect探测显示设备、get_modes返回可用模式列表在 LS2K2000 这类型号上驱动甚至可能支持不止一个显示输出比如 HDMI 和 VGA 各有一个 Connector。多个输出同时存在时初始化流程会更复杂要保证每个 Connector 都能通过 Encoder 找到对应的 CRTC同时不能被框架错误地串线。这一步稍有疏漏就会出现独显启动后 HDMI 有信号但 VGA 无信号这类缺一路的怪问题。3.3 fbdev 兼容层让字符终端也能显示很多人不理解为什么 DRM 驱动里还带着fbdev emulation这种东西。原因很现实系统启动阶段引导程序要显示 logo内核崩溃时要打 oops 到屏幕上这些场景依赖一个简单直接的显示接口而不是完整 DRM 框架。LSDC 驱动通常会注册一个drm_fbdev_emulation或类似机制在 DRM 设备之上模拟一个 /dev/fb0。这样一来开机 logo、字符终端、甚至一些老的显示工具都能正常工作而真正的图形栈例如 Xorg 或 Wayland 合成器仍然通过 DRM 主设备工作。调试时这个兼容层特别有用。如果/dev/fb0上 printf 的内容能正常显示说明底层显示管线已经通了问题很可能出在用户态图形栈如果 fb0 都黑屏直接去查驱动初始化也不迟。4. 一帧画面的旅程从 DRM Framebuffer 到像素时钟4.1 GEM 对象、显存与 framebuffer 的关系用户态要显示一张画面首先要创建一块放置像素数据的缓存。在 DRM 框架里这块缓存被封装成 GEM 对象再给 GEM 对象套上格式、分辨率等描述信息就变成了 DRM Framebuffer。LSDC 驱动平时用的是主平面它把 Framebuffer 对应的内存地址取出来通过 Plane 的更新回调写到显示控制器的起始地址寄存器里。这里要注意的是显示控制器在扫描输出时访问的是物理地址所以驱动必须保证这块内存在 DMA 访问期间是有效的并且地址对齐满足硬件要求——这也是下一章要讲的显存分配问题的由来。4.2 模式设置与时序计算模式设置是 CRTC 回调里最重要的一块逻辑。当用户在 Xorg 或者通过drmModeSetCrtc切换分辨率时内核会走一遍 atomic 模式设置流程。LSDC 得到struct drm_display_mode之后要把它换算成自己控制器能认的时序参数。换算的核心是把显示模式里的水平/垂直时序参数active、blank 起始、sync 偏移等转换成寄存器值。举个直观的例子一个 1920x108060 的模式实际行周期不是只有 1920 个像素还要算上前后肩、同步脉冲最终大概落在 2200 个像素时钟周期左右。像素时钟频率、Htotal、Vtotal 这三个参数决定了最终的刷新率。这一部分出错最常见的结果不是死机而是画面偏移屏幕左右滚动这类看起来很奇怪的现象。说实话我第一次遇到屏幕右移出一大块黑边时完全没往时序寄存器想后来对照数据手册逐个字段排查才发现是同步脉冲宽度配置不对。4.3 Plane 更新与帧切换LSDC 扫描显示时默认读取的是主平面指到的那块显存地址。如果显示内容要更新用户态只需要把新的 Framebuffer 提交上来触发 Plane 的 atomic_update 回调驱动在这里把新的 Framebuffer 地址写入控制器。这里有一个关键细节**写显存地址的时机要跟硬件扫描同步。**如果在控制器刚好扫到屏幕中间时改了显存地址用户就会看到撕裂tearing。常见做法是等垂直消隐期再更新寄存器或者启用控制器的双缓冲机制。LSDC 驱动设计中帧切换路径上通常会把这种同步逻辑考虑进去用户态配合 PageFlip 也能实现无撕裂的流畅切换。4.4 连接器探测与 EDID 读取显示器插入、拔出、开机时内核需要对 Connector 做一次探测。探测的核心动作是通过连接器对应的 I2C 通道读显示器 EDID解析出它支持的分辨率和刷新率列表再交给用户态去选择。LSDC 驱动里往往也包含一个 I2C 适配器实现——可能挂在显示控制器的 I2C 控制器之上也可能操作 GPIO 模拟 I2C。这部分代码虽然不起眼但经常是HDMI 为什么识别不到显示器的根源。一开始我不理解为什么显示驱动还要管 I2C后来调试一台电视不识别的问题查到最后就是 EDID 读取时序没有按显示器的要求来。5. 显存管理设计LSDC 如何选择 TTM/GEM5.1 龙芯 SoC 的显示内存格局LSDC 驱动的显存管理之所以值得单独讲是因为龙芯低端 SoC 的显示控制器大多没有独立显存。它扫描输出的数据要从系统内存里来这就带来两个要求内存物理连续、DMA 可访问。这跟带独显 GPU 的平台完全不同。独显驱动管的是板载 VRAM显存分配逻辑相对独立LSDC 要管的则是把系统内存里某一段划给显示控制器用。如果这段内存不连续或者分配时没有考虑 DMA 地址宽度限制显示就会出现花屏甚至完全无法输出。5.2 GEM 与 TTM 的取舍DRM 框架下有两套显存管理思路GEM 和 TTM。GEM 是通用图形内存管理主打简洁TTM 则能管理显存/系统内存之间的换入换出多用于独立显卡。LSDC 这种没有独立显存的显示控制器通常更适合 GEM 路线分配本质上就是dma_alloc_attrs或者drm_gem_cma_*拿到一块物理连续的内存然后按 GEM 对象包装起来交给用户态做 mmap 或者显存导入导出。如果驱动选择 TTM一般是像样的独立 GPU 或者模拟 GPU 才会用到。LSDC 类驱动如果用 TTM 但又不做换出那纯粹是给自己增加复杂度。读代码时看到驱动用的是哪个管理模型基本就能判断出作者的侧重点。5.3 大块连续内存的分配实践LSDC 需要的是一大块连续物理内存这块内存要能被显示控制器直接按地址访问。实际驱动代码里常见的路径是在 GEM 对象创建时走 DMA 分配器得到总线地址和分配大小然后把它映射成用户态可写的虚拟地址。这里有一个容易踩的坑**调试时要留意 32 位与 64 位地址空间的问题。**显示控制器的 DMA 地址宽度未必跟 CPU 一致如果 SoC 的显示控制器只能寻址低 32 位物理地址而系统内存分配出来的 DMA 地址落在 4G 以上那即使驱动看起来分配成功了显示画面依然是不确定的。好在现代龙芯平台大多已经放宽了地址宽度但在做老旧板卡适配时还是要主动确认这个细节。6. 调试 LSDC 驱动的四个关键位置与踩坑记录6.1 先看 dmesg 中的 lsdc 加载记录调 LSDC 的第一步永远是dmesg | grep -i lsdc。驱动 probe 阶段如果失败一般会留下比较明确的错误日志比如资源获取失败、某个寄存器读写结果不符合预期、设备树 compatible 没匹配上。如果 kernel log 里完全没有 lsdc 字样的记录就要往前查是不是设备树节点没使能驱动是否编进了内核模块是否被加载我有一次遇到的驱动不工作到最后竟然是内核 config 里把模块编成了 built-in但设备树 compatible 字符串没对上整个 probe 回调直接被跳过了。6.2 用 modetest 验证输出管线用户态最趁手的探查工具是modetest它是 libdrm 自带的测试程序。运行modetest -c能列出 Connectormodetest -p能看 Plane 信息modetest -M可以指定驱动名称。一个典型的验证流程是先确认 Connector 存在再确认它能在插上显示器之后枚举出正确的 mode 列表然后用modetest -s指定 connector 和分辨率做一次测试显示。如果这步能点亮屏幕说明从 GEM 到 CRTC 再到 Connector 的整条链路是通的如果这步不行再逐层拆。我还习惯配合/sys/kernel/debug/dri/0/下面的调试节点来看寄存器或状态。很多 DRM 驱动在 debugfs 里导出了每个组件的状态字符串对快速判断驱动认为当前处于什么状态非常有用。6.3 黑屏、花屏定位顺序遇到黑屏我通常按这个顺序排查串口/日志层面确认驱动加载成功无 probe 错误。dmesg里看 Connector 是否检测到显示器EDID 是否读到。用 modetest 手动触发一次模式设置确认 CRTC 是否使能、时钟是否输出。检查显存地址与 framebuffer 内容可以在调试节点里 dump 一小块内存确认写入的像素数据正确。最后才是怀疑硬件链路比如 HDMI 线缆、转接器、显示器输入源。花屏则通常指向显存参数要么内存地址不对要么 stride 行距没对上。常见错误是把 1920x1080 的 stride 按 1920 算忘了每个像素占 4 字节结果画面整体切斜。6.4 移植到新板卡时最容易忽略的环节如果你想把 LSDC 驱动从参考板移植到新板卡最值得注意的不是驱动源码本身而是设备树描述。寄存器基地址、中断号、时钟来源、复位信号的描述都要跟着新板子重新核对。尤其是显示涉及到的时钟树很多 SoC 的显示控制器需要外部源配置好正确的像素时钟才能工作这种配置往往放在 bootloader 或者设备树 clk 节点里驱动本身只管寄存器而不管 PLL 初始化的具体策略。另外提醒一点不同型号龙芯 SoC 的显示控制器寄存器偏移可能并不完全一致。移植时不要想当然地认为参考板上的偏移定义在新芯片上也一样最好逐个功能块对照新芯片的数据手册确认否则会因为一个看似不起眼的寄存器位被写错换来一个莫名其妙的黑屏。最后分享一个我自己养成的调试习惯拿到一块新板子我会只做最小化的验证——先把内核默认 framebuffer 的 logo 成功显示出来再把 modetest 的测试画面点亮这之后再考虑跑完整的图形栈。这两步通过基本能判定 LSDC 驱动层的初始化、模式设置、显存分配都正常剩下的问题就往用户态丢。别一上来就并行排查否则黑屏问题很容易变成五六个变量搅在一起的泥潭。
