📚 课程目录第2章 KMS核心数据结构

2. KMS核心数据结构：drm_device、drm_crtc、drm_encoder、drm_connector、drm_plane

KMS（Kernel Mode Setting）是Linux内核显示子系统的基石，其核心逻辑围绕五个关键数据结构展开。理解这些结构及其相互关系，是进行故障排查与调试的前提。本章将逐一剖析每个结构的作用、关键成员及调试入口。

调试要点： 在KMS调试中，90%的显示异常（黑屏、花屏、分辨率错误）都可以追溯到这五个结构的状态或连接关系异常。掌握它们的生命周期和依赖链，是定位问题的第一步。

2.1 整体架构关系

五个核心数据结构构成了KMS的“显示管线”（Display Pipeline）。数据从内存（Framebuffer）经过平面（Plane）合成，由CRTC扫描输出，通过编码器（Encoder）转换为特定信号，最终由连接器（Connector）输出到显示设备。下图展示了这一完整链路：

  关键理解： 显示管线是单向数据流。调试时，应从连接器（Connector）端反向追溯：检查连接器是否检测到设备 → 编码器是否匹配 → CRTC是否激活 → 平面是否提交了有效帧缓冲。

2.2 drm_device：全局设备容器

drm_device 是KMS驱动中最高层级的抽象结构，代表一个完整的显示控制器设备。它作为全局容器，管理所有子对象（CRTC、Encoder、Connector、Plane）的生命周期。

关键成员	类型	说明	调试入口
`dev`	`struct device *`	内核通用设备指针，关联硬件平台设备	`/sys/class/drm/`
`mode_config`	`struct drm_mode_config`	模式配置管理结构，包含所有CRTC/Encoder/Connector/Plane列表	`cat /sys/kernel/debug/dri/0/state`
`driver`	`struct drm_driver *`	驱动回调函数集，包含`irq_handler`、`atomic_commit`等	`lsmod \| grep drm`
`filelist`	`struct list_head`	已打开DRM文件描述符列表，用于跟踪用户态客户端	`lsof /dev/dri/*`

常见故障： 当 drm_device 初始化失败时，通常表现为 /dev/dri/card0 不存在或 dmesg 中出现 [drm] *ERROR* failed to initialize。此时应优先检查硬件探测、IO资源分配和中断注册。

2.3 drm_crtc：显示控制器核心

CRTC（Cathode Ray Tube Controller，沿用历史名称）是显示管线的核心调度单元。它负责从内存中读取像素数据，生成时序信号（行同步、场同步、像素时钟），并驱动编码器输出。

CRTC的关键调试属性包括：

active/enable： 表示CRTC是否正在扫描输出。如果 active = false，即使其他组件正常，屏幕也不会显示内容。
mode： 当前显示模式（分辨率、刷新率、时序参数）。模式不匹配会导致黑屏或画面偏移。
vblank： 垂直消隐期状态。vblank中断丢失会导致画面撕裂或原子提交超时。

// 调试示例：通过 debugfs 查看 CRTC 状态
# cat /sys/kernel/debug/dri/0/crtc-0/state
crtc[0]: enable=1 active=1
mode: 1920x1080@60 148500 1920 2008 2052 2200 1080 1084 1089 1125 flags: 0x5
vblank: enabled, last=12345, count=123456

2.4 drm_encoder：信号编码与转换

Encoder负责将CRTC输出的并行像素数据转换为特定显示接口所需的串行信号格式。常见的Encoder类型包括：

Encoder类型	对应接口	典型故障	调试方法
TMDS	HDMI / DVI	信号质量差、无显示	检查TMDS时钟、差分电压
LVDS	内置笔记本屏幕	屏幕闪烁、花屏	检查链路映射、通道数
eDP	嵌入式DisplayPort	训练失败、黑屏	查看DPCD寄存器、链路训练状态
DAC	VGA	颜色偏移、重影	检查DAC负载、同步信号

  调试技巧： 使用 modetest 工具可以列出所有Encoder及其支持的CRTC掩码。如果Encoder的 possible_crtcs 位掩码与当前CRTC不匹配，则无法建立连接。

# modetest -M imx-drm -c
Connectors:
id      encoder status          name            size (mm)       modes   encoders
1       1       connected       HDMI-A-1        520x290          1       1
2       2       connected       LVDS-1          310x170          1       2

Encoders:
id      crtc    type    possible crtcs  possible clones
1       1       TMDS    0x00000001      0x00000000
2       2       LVDS    0x00000002      0x00000000

2.5 drm_connector：物理连接检测

Connector代表物理显示接口（HDMI、DP、VGA等），负责检测显示设备的连接状态、获取EDID信息、管理热插拔事件。

Connector调试的核心是状态检测：

status： 物理连接状态。如果始终为 disconnected，检查HPD（热插拔检测）引脚或GPIO配置。
EDID： 显示器的扩展显示标识数据。EDID读取失败会导致无法获取支持的分辨率列表。
dpms： 电源管理状态。DPMS关闭时，即使连接状态正常，屏幕也会黑屏。

// 通过 sysfs 查看连接器状态
# cat /sys/class/drm/card0-HDMI-A-1/status
connected

# cat /sys/class/drm/card0-HDMI-A-1/edid | hexdump -C
00000000  00 ff ff ff ff ff ff 00  10 ac 05 30 4c 4d 30 32  |.........0LM02|
00000010  2c 1e 01 04 a5 3c 22 78  fb 02 35 a5 55 4e a0 28  |,....<"x..5.UN.(|

2.6 drm_plane：图像层合成

Plane代表一个独立的图像层，可以叠加在CRTC的输出之上。现代KMS驱动支持多个Plane，用于实现硬件光标、视频叠加、UI合成等场景。

Plane类型	用途	数量	调试关注点
Primary Plane	主显示层，必须绑定到CRTC	至少1个	framebuffer是否有效、格式是否支持
Cursor Plane	硬件鼠标光标	0或1个	光标位置、大小限制、热点偏移
Overlay Plane	视频叠加、UI覆盖层	0~N个	Z-order、alpha混合、缩放能力

常见故障： 如果Primary Plane未正确绑定framebuffer，CRTC将无法获取像素数据，导致黑屏。使用 drm_info 或 cat /sys/kernel/debug/dri/0/state 检查plane的 fb_id 是否为有效值。

// 查看 plane 状态
# cat /sys/kernel/debug/dri/0/plane-0/state
plane[0]: crtc=0 fb=1
crtc-pos: 0x0 size: 1920x1080
src: 0.000000x0.000000+1920.000000+1080.000000
format: XR24 little-endian (0x34325258)

2.7 数据结构关系总结

下表总结了五个核心数据结构在显示管线中的角色、依赖关系和调试优先级：

数据结构	角色	依赖	调试优先级	关键检查项
drm_device	全局容器	硬件探测成功	1（最先检查）	设备文件是否存在、驱动加载
drm_crtc	扫描输出核心	绑定Primary Plane	2	active/enable、mode时序
drm_encoder	信号编码	绑定CRTC	3	possible_crtcs、类型匹配
drm_connector	物理连接	绑定Encoder	4	status、EDID、dpms
drm_plane	图像层合成	绑定Framebuffer	5	fb_id、格式、位置

  调试口诀： “先看设备有没有，再看CRTC活不活；编码连接要匹配，平面帧缓冲别空。” 按照这个顺序排查，可以快速定位90%的KMS显示问题。