读龙芯集成显示控制器的驱动源码之前我一直觉得做国产平台的显示驱动无非就是映射寄存器、填几个sync参数、把帧缓冲地址交给屏幕三件事。真正把LS系列DCU对应到 Linux 内核的 DRM 驱动、完整梳理一遍 LSDC 的实现之后才明白复杂度和风险点完全不在写寄存器而在内核框架的约束和硬件特性的边界这两者之间找平衡。哪怕只是让一块板子在接上HDMI之后自动切成正确分辨率也会牵扯到DRM子系统的状态对象、atomic事务、GEM buffer管理、vblank事件回调等一系列机制。这篇文章就把我读LSDC驱动源码时的整体架构理解、关键路径和排查记录整理一遍适合正在折腾龙芯嵌入式主板显示输出、或者想用DRM框架做国产显示控制器驱动的朋友。DRM 这个词在 Linux 图形栈里经常被误解成游戏加速其实现在的 DRM 早就分化成两种角色一是 KMSKernel Mode Setting负责显示模式、扫描输出和画面合成二是渲染管理负责GPU上下文、command buffer提交等。LSDC 作为集成在桥片或SoC里的显示控制器主要承担的是 KMS 职责渲染部分不依赖独立GPU的execbuf。所以这篇分析的重点会落在 KMS 路径驱动怎么初始化、怎么建立一个可用的mode configuration、怎么把用户空间的framebuffer变成屏幕上的像素以及出问题时从哪里下手。1. 为什么LSDC值得单独写一篇源码分析1.1 DRM驱动与fbdev的根本差异先理解一下为什么不能继续用旧的fbdev 手工set mode方案。传统fbdev适合单一帧缓冲、单调显示的设备它没有对象化的显示器-编码器-CRTC状态管理也不支持多个独立显示输出上的复杂配置。龙芯的DCU在LS2K1000、LS7A等平台上往往支持两路显示输出有些还支持HDMI、VGA、LVDS这几个不同的物理接口如果用fbdev所有输出都会挤在同一个framebuffer模型里双屏配置、分辨率切换、vsync同步都会变成痛苦。DRM 把显示链路拆成了 Plane、CRTC、Encoder、Connector 四个层次。Plane 是内存里的图像层CRTC 负责按时序把一组 plane 扫描到某个输出上Encoder 做信号编码比如把并行RGB变成HDMI TMDS信号Connector 描述物理接口状态。LSDC 驱动要做的就是在初始化时把这套对象都挂到 drm_device 上然后让用户空间的合成器通过 DRM ioctl 来查询和配置。我调试时最直观的体会是只要这个层次对象挂得对用户态工具就会自动按标准流程找到显示器只要对象挂得不对哪怕硬件操作完全正确modetest 就是列不出 mode。所以源码分析第一个重点不是寄存器而是这些框架对象怎么被组装。可以说理解 DRM 的状态机语义比记住 DCU 的寄存器偏移更加重要。1.2 LSDC的适用平台与功能边界根据公开资料和实际板卡情况LSDC 驱动覆盖的硬件通常是龙芯 LS2K1000、LS2K2000 相关处理器内置或桥片集成的 DCU 显示控制器具体路径常见为 drivers/gpu/drm/lsdc。在功能上它和 x86 平台核显驱动有本质区别龙芯 DCU 本身不具备完整的 3D 渲染管线不存在传统的 execbuf 渲染调度路径它主要提供 scanout、plane 叠加、gamma 校正、硬件光标和显示时序生成器。在我实际接触的内核源码中LSDC 会显式声明 DRIVER_MODESET 和 DRIVER_ATOMIC而 DRIVER_RENDER 是不使能的。这样做的好处是即使有用户态图形库配合内核驱动也不会去注册渲染节点用户态的 3D 加速只能通过其他用户态栈完成或者干脆走软件渲染。这一点对系统集成工程师很重要因为如果在系统里看不到 /dev/dri/renderD128你第一反应不该是驱动坏了而是这个显示控制器的定位就是 KMS-only。2. 架构总览LSDC驱动由哪些部分组成2.1 从设备树到平台驱动LSDC 驱动源码首先是一个普通的 platform_driver 或者 PCI 驱动具体取决于内核把 DCU 枚举为平台设备还是 PCI 设备。LS2K1000 这类处理器的 DCU 通常挂在系统总线上通过设备树描述所以源码里会出现 compatible 字符串例如 loongson,ls2k1000-dcu 这类定义。MODULE_DEVICE_TABLE(of, lsdc_of_match) 让内核能在启动时自动匹配这个驱动。这个阶段的重点是拿到硬件资源device_node、MMIO 地址范围、中断号、时钟频率。我在调试中遇到过多次资源没配对的情况某个板子的引导程序给 DCU 预留的寄存器地址和源码里预期基址偏移不一致导致驱动 probe 成功但一访问寄存器就总线错误。如果你改完设备树后内核日志停在 lsdc: failed to request irq优先检查 interrupts 属性是否指向了正确的中断控制器。static const struct of_device_id lsdc_of_match[] { { .compatible loongson,ls2k1000-dcu }, { .compatible loongson,ls2k2000-dcu }, { /* sentinel */ } }; MODULE_DEVICE_TABLE(of, lsdc_of_match); static struct platform_driver lsdc_platform_driver { .probe lsdc_platform_probe, .remove lsdc_platform_remove, .driver { .name lsdc, .of_match_table lsdc_of_match, }, }; module_platform_driver(lsdc_platform_driver);平台的差异在源码里会通过 different compatible 字符串来区分同一套驱动代码兼顾多个 DCU 版本时往往在 probe 阶段用 of_device_get_match_data 或者 device_get_match_data 拿到一个代表硬件特性的私有数据指针里面保存了 regmap 配置、格式掩码、lane 数量等信息。这样后续代码就不必到处写 if 判断具体芯片型号可维护性会好很多。2.2 drm_driver与设备的生命周期源码里一定有类似这样的定义static const struct drm_driver lsdc_drm_driver { .driver_features DRIVER_GEM | DRIVER_MODESET | DRIVER_ATOMIC, .fops lsdc_drm_fops, .name lsdc, .desc Loongson Display Controller DRM Driver, .date 20230401, .major 1, .minor 0, };这里有几个值得注意的点。DRIVER_GEM 表示它用 GEM 接口管理内存对象DRIVER_MODESET 表示它参与 KMSDRIVER_ATOMIC 表示它支持原子模式设置。不加 DRIVER_RENDER 则是明确不提供渲染调度。这一切组合起来最终会在用户空间看到 card0 和 card1 节点但不会有 renderD128 节点。驱动的 probe 函数一般先分配一个私有结构体 lsdc_device里面包含 MMIO 映射、中断屏蔽、互斥锁、以及 DRM 子设备指针然后调用 drm_dev_alloc、drm_dev_register。如果这里顺序错了比如在 MMIO 还没映射时就调用 drm_mode_config_init后面任何通过 drm_device 访问 io 的操作都会崩。生命周期方面源码析构时会用 drm_dev_unregister 和 drm_dev_put。在没有用户打开 fd 的时候drm_device 可以临时释放这是 DRM 的 device refcount 机制。LSDC 驱动还做了 runtime_pm 支持屏幕完全关闭时 DCU 时钟可以被关掉这对嵌入式板的整机功耗很重要。2.3 模式配置对象的组装顺序模式配置对象是自底向上建的先建 CRTC再建 Encoder再建 Connector最后把 Plane 绑定到 CRTC 上。很多人不理解为什么会是这个顺序实际上是因为 Connector 需要拿到 Encoder 列表去决定能否连接Encoder 需要拿到可能的 CRTC mask 去决定可以接到哪些 CRTC 上。这个 mask 如果设置错会出现合成器报告 could not set crtc for output。LSDC 驱动里通常会把两个 CRTC 映射到两路显示输出每个 CRTC 允许接任意一个 Encoder。为了简单很多国产驱动会每个 Connector 直连一个 Encoder 再连接一个 CRTC这样掩码永远只有一位。在某一版源码我见过一个偷懒实现所有 Connector 都直接挂到 CRTC0 上结果连接第二个屏幕时无论如何都只能克隆无法独立输出。要做到独立双屏必须给两个 CRTC 设不同的 possible_crtcs然后让每个 Connector 对应不同的 CRTC 位。static int lsdc_modeset_init(struct drm_device *ddev) { struct lsdc_device *ldev to_lsdc(ddev); struct drm_crtc *crtc; struct drm_plane *plane; unsigned int i; for (i 0; i ldev-dcu_count; i) { plane lsdc_plane_create(ddev, i, 0); if (IS_ERR(plane)) return PTR_ERR(plane); crtc lsdc_crtc_create(ddev, plane, i); if (IS_ERR(crtc)) return PTR_ERR(crtc); if (!lsdc_encoder_create(ddev, crtc, i)) return -ENOMEM; if (!lsdc_connector_create(ddev, i)) return -ENOMEM; } return 0; }对象树建立得对不对早期看 dmesg 里 drm 驱动的注册打印后期可以直接 cat /sys/kernel/debug/dri/0/state。debugfs 里会展示每个 object 的 id、type、possible_crtcs、state。这个是我调试时最依赖的信息源。3. 显示流水线寄存器层面的硬件抽象3.1 DCU的寄存器视图龙芯 DCU 的寄存器在源码里通常用一个私有结构描述基址偏移常见的功能块包括寄存器区域作用备注DC_CTRL总开关、像素格式、gamma使能控制扫描输出全局状态DC_TIMING水平/垂直同步参数与前后肩决定分辨率与刷新率DC_FB0/FB1两个plane的帧缓冲地址需要按硬件对齐要求设置DC_INT中断状态与使能vblank、fifo overflowDC_PAL调色板/gamma LUT硬件gamma我强调一下具体命名在不同芯片版本里会有差异但逻辑一致。读源码时不要死记偏移要去看芯片手册里对应模块的位域定义。很多 DMA 传输的问题都出在缓存一致性上DCU 扫描内存时 CPU 侧可能还有 dirty cache所以驱动要在提交帧缓冲前后做 cache flush。LSDC 驱动如果没有对 buffer 做 dma_map_single 或者采用 DRM 的 DMA helper很容易出现画面有上半屏雪花下半屏正常的典型缓存问题。这种问题跟像素格式无关跟寄存器配置也无关本质是 CPU 和 DMA 看到的内存视图不同步。解决方法一般有两个思路一是使用 DMA API 分配一致内存二是在切换帧缓冲时显式调用 arch 相关的 cache 维护函数。对龙芯平台来说cache synco 指令序列和 LoongArch 的 dma_map 行为都要仔细验证。如果驱动替换 buffer 后不主动 flush合成器不会报错但屏幕上就会随机出现纹理残缺。3.2 CRTC驱动时序生成与像素时钟CRTC 是显示控制器最核心的部件源码里对应 struct drm_crtc_helper_funcs 里面的 mode_set_nofb 和 atomic_flush。DCU 生成逐行扫描信号时会根据一个像素时钟频率数出每行的周期、行总数、同步脉冲位置。用户空间配置一个 mode比如 1920x108060驱动要计算出最终的参数并写入时序寄存器。如果 DCU 的 PLL 不能精确生成目标像素时钟就需要接受一个接近值。我遇到过某平台在 2560x144060 下找不到 clock其实是 PLL 的参考时钟不支持那么高的倍频不是代码 bug。解决办法不是改驱动而是换一个刷新率比如降到50Hz或者调整 PLL 约束参数。注意实现 atomic_check 的时机。DRM 框架会在 mode_set 之前调用 atomic_check如果驱动在这里返回 -EINVAL整个模式配置会被拒绝用户空间会看到配置失败的错误。国产驱动常见的问题是没有在 atomic_check 里检查 plane 与 crtc 是否匹配导致随意把 plane 挂到不支持的 crtc 上硬件就会花屏。更细的检查还包括帧缓冲格式是否硬件支持、地址对齐是否满足要求。以典型的 CRTC 提交为例atomic_flush 里要做的就是把算好的 timing 参数写入寄存器并打开 vblank 中断。如果 atomic_flush 里漏写 hdisplay/vdisplay 相关的寄存器即使分辨率改了屏幕实际输出宽度也可能不对。很多时候 debug 半天发现是某位域没写一个 iowrite32 就能解决。3.3 Plane与硬件图层LSDC 如果拿到的是有多个硬件图层的 DCU驱动就要为每个硬件 layer 注册一个 drm_plane。Primary plane 是最底层的全屏层Cursor plane 通常是一个小尺寸、带硬件游标的层Overlay plane 可以有缩放、颜色键等特性。难点在于把硬件 plane index 和 drm_plane 一一对应同时确保 format 列表和硬件完全一致。源码实现里常见模式是static const uint32_t lsdc_plane_formats[] { DRM_FORMAT_XRGB8888, DRM_FORMAT_ARGB8888, DRM_FORMAT_RGB888, DRM_FORMAT_XRGB2101010, }; static const uint64_t lsdc_plane_modifiers[] { DRM_FORMAT_MOD_LINEAR, DRM_FORMAT_MOD_INVALID, };注意 DRM_FORMAT_MOD_INVALID 最后一个元素告诉内核没有更多 modifier。如果不提供 modifiers 接口有些用户态会选择 linear但一旦有压缩格式需求比如 AFBC没有 modifier 实现就会失败。龙芯 DCU 不支持压缩贴图所以 LINEAR 就够了但这个接口不能缺失否则某些合成器会 fallback 失败。另一个容易踩的坑是硬件对 10bit 格式的支持如果硬件实际不支持 XRGB2101010但驱动把它列在 formats 里那么用户态一旦选择该格式画面上就会出现颜色异常而且这种异常很难和信号问题区分因为整体还是能显示的。4. 核心路径源码拆解模式设置与buffer提交4.1 atomic事务与state对象DRM 的 atomic 机制可以理解成数据库事务把多个显示参数打包成一个 drm_atomic_state通过一次 ioctl 提交内核会先原子地检查所有对象是否兼容再一次性 commit。阅读 LSDC 驱动时重点抓住几个回调atomic_check检查新的 state 是否可以被硬件接受。atomic_begin提交前可能把 vblank 中断禁掉以避免撕裂。atomic_flush真正把新地址、新时序写到硬件寄存器。atomic_end重新使能 vblank。我在分析提交路径时常看的一个函数是 lsdc_crtc_atomic_flush它会遍历新 state 中的 plane把每个 plane 的帧缓冲地址写到 DC_FBx 寄存器。因为只有写完所有 plane 后硬件才会在下一个 vblank 统一切换所以要在同一个临界区完成。如果发现自己写了一半比如 primary plane 切了而 cursor plane 没切就会出现短暂撕裂或残影。除了 atomic 路径老的页面翻转 page_flip 接口其实也映射到 atomic commit。LSDC 支持 DRIVER_ATOMIC 后旧 drv-page_flip 通过 drm_atomic_helper_page_flip 实现驱动自身一般不需要再单独实现。这一点对源码阅读很重要你看到的 page_flip 相关代码可能根本不在 lsdc 驱动目录里而在 DRM helper 头文件里。4.2 GEM对象与DMA寻址龙芯 DCU 访问内存时走 DMA所以帧缓冲必须通过 GEM 分配并能映射成总线地址。常见实现是用 drm_gem_dma_create 或者 shmem 版本再用辅助接口创建 scanout buffer。这里有个嵌入式平台的经典问题如果 DCU 的 DMA 地址宽度只有 32 位而系统内存超过 4GB就必须保证显存落在低 32 位地址空间。驱动初始化时可以用 dma_set_mask_and_coherent 限制寻址范围也可以在分配时使用 GFP_DMA32。遇到系统进桌面后一旦切换 buffers 就黑屏的情况大多数是地址超过 4GB 导致 DCU 读到了错误总线的数据。还有一个细节是缓冲区的 stride。DRM 对象里一个 linear framebuffer 的 pitch 必须是硬件要求的对齐粒度。源码里 lsdc 可能对 32bpp 要求每行 64 字节对齐如果用户空间传了一个 stride 未对齐的 fbatomic_check 要主动拒绝否则会出现斜条纹或者画面每一行错半个像素的症状。我见过有的合成器默认使用 256 字节对齐这当然没问题但如果你为省内存强行把宽度设成奇数驱动必须拦下来。4.3 fbdev兼容层与内核启动画面很多龙芯板子虽然跑合成器但启动阶段用的还是内核自带的 fbcon。LSDC 驱动一般通过 drm_fbdev_generic_setup 或者 drm_fbdev_dma_setup 挂一个兼容层。这个层的好处是不用手写 fb_ops内核会根据 drm_device 的配置自动创建 /dev/fb0。如果启动时内核参数里加了 vga 之类的旧参数fbcon 可能拿不到正确 mode。建议启动参数直接设 drm.debug0x1f 并用 modetest 确认当前 mode不要靠 fbcon 的 log 猜。还有一个经验当 drm_fbdev_generic_setup 设置 preferred_depth 为 32 时控制台可能比 16bpp 占更多内存。对于只有 256MB 内存的板子可以考虑把 32 改成 16 来节省空间。但要注意改成 16 之后如果没有一个合成器主动接管屏幕启动画面颜色会偏少。实际项目里我通常固定 32bpp因为只做 KMS 的板子内存预算也不差这点。5. 调试工具与问题排查实录5.1 drm.debug与modetest联合使用先给一个最小可用的诊断套餐内核参数 drm.debug0x1f安装 libdrm 工具集。启动后用 modetest 查看当前连接器状态modetest -M lsdc -c modetest -M lsdc -p cat /sys/kernel/debug/dri/0/state当 modetest 能列出连接器、mode 和 plane说明 KMS 对象组织没问题如果输出全是空问题几乎都在初始化或 probe 阶段。dmesg 里用 drm:lsdc 开头过滤会有很详细的对象注册信息。想要更深入可以用 tracepoint 观察 vblank 事件/sys/kernel/tracing/events/drm/drm_vblank_event 之类。我建议排查时不要直接改源码先确认对象是否注册成功。很多时候黑屏不是驱动代码逻辑错而是某个对象没有被初始化。比如 connector detection 一直返回 falsemodetest 就看不到 mode合成器自然无法启动。5.2 花屏、偏移与vblank超时按老经验出现花屏按六个方向查fb 地址是否有效、stride 是否正确、格式是否被硬件支持、缓冲区是否被其他 DMA 踩踏、fifo overflow 中断是否触发、CRTC 时序是否在屏幕消隐期内。区分前两种用 dmesg 里的 FIFO overflow 信息如果有溢出多半是总线带宽不足非驱动问题如果没有溢出优先怀疑 stride 和地址对齐。vblank timeout 报错很常见。如果驱动没有正确注册 vblank irq handler但某个合成器调用 drm_vblank_get内核会等 1 秒然后打印vblank wait timed out。此时去查中断使能寄存器有没有被清掉以及 platform_get_irq 拿到的中断号是否和中断控制器一致。另一个藏得比较深的坑是设备树把同一个中断号分配给了两个设备导致 vblank 中断被另一个设备的中断处理函数吞掉。这种问题用 perf 或 tracing 看中断事件很容易发现。5.3 源码阅读顺序建议如果你准备完整看一遍 LSDC 源码我建议按这个顺序先看驱动入口和 probe了解硬件资源再看 mode_config_init了解对象树再看 crtc helper 函数核心时序再看 plane 与 format内存扫描最后看 connector 和 EDID物理输出。不要一上来追 atomic 的 state 所有分支因为 DRM framework 的样板代码很多容易迷失。可配合其他同为嵌入式显示控制器的驱动对照着看我读 LSDC 时发现很多回调模式和标准 helper 有相似之处毕竟大家都走同一套框架。在我接触的版本里LSDC 的源码规模并不大整个驱动可能只有几千行比起庞大复杂的商业显卡驱动要简单太多特别适合作为 DRM 驱动入门的学习对象。但简单不意味着没有深坑DCU 的每个版本都对格式支持、layer 数量和 PLL 范围有细微差别源码里的 ifdef 和版本分支也值得注意。从内核 5.10 到 6.1DRM 的 helper 接口变化很大比如在新内核里很多驱动把 fbdev 辅助换成了 drm_client API如果你在一个新内核上编译旧的 LSDC 补丁失败优先检查 fbdev 相关函数是否改名。6. 实际操作中的经验总结与个人体会6.1 一个让我查了半天的双屏坑真要说踩坑我印象最深的一次是双屏独立输出。当时工具列出了两个 monitor但是把第二个输出用扩展模式连到左边后右屏一直黑左屏克隆了右屏的画面。查了半天寄存器后来发现是 encoder 的 possible_crtcs 掩码没有给第二个 crtc 留位导致第二个 connector 只能复用第一个 crtc。改完掩码、重新加载驱动后一切正常。这类问题在寄存器层面完全看不出异常因为硬件根本没接收到第二路 DCU 使能的命令。这也印证了我前面说的DRM 驱动开发的难点相当比例在框架语义而不在硬件细节。6.2 启动阶段的开机logo与fbcon处理另一个常遇到的问题是在启动阶段想显示开机 logo。DRM 驱动的 fbcon 虽然能显示但要让它和你的合成器共存需要保证 fbdev client 不会抢占 DRM master。你可以用 drm_client 的 callback 屏蔽自己的 fbdev client或者在用户态等合成器拿到 DRM master 后再关闭 fbcon。实际操作中我直接关掉 fbcon 的 VT 切换用系统服务从 /dev/dri/card0 启动合成器简单省事。6.3 从旧驱动迁移到LSDC的最后建议如果你手上的板子还在用旧的内核里单独的 fb 驱动我建议尽快迁移到 LSDC DRM 驱动。迁移初期多花的时间主要在设备树、内核配置和启动参数的调整上但稳定下来之后你会拿到标准的 DRM/KMS 接口、atomic 状态管理、以及和图形栈原生配合的缓冲机制。可以说在龙芯平台上做显示输出读一遍 LSDC 的源码比自己在旧 fbdev 上修修补补要划算得多。最后再分享一个体感这类国产显示控制器驱动的核心价值并不在于某个寄存器写得多漂亮而在于把有限硬件能力封装成标准接口让上层生态不需要为特定芯片写专用代码。你在调试中遇到的很多问题最终答案往往藏在内核 DRM 框架的设计逻辑里而不是藏在芯片手册里。所以遇到黑屏别急着翻寄存器先看对象挂没挂对再看格式匹配不匹配最后才动手改时序——按这个顺序排查大概率能少走一半弯路。