2. DRM基础概念

在进入硬件光标与 VBlank 同步的实战之前，必须先建立一张清晰的 DRM 术语地图。很多初学者在阅读内核代码时会被 drm_crtc、drm_plane、drm_encoder、drm_connector 这些结构体绕晕，根本原因是没有理解它们各自在显示流水线中的位置与职责。本节将 DRM 的架构拆解为“用户空间—内核 DRM 核心—KMS 对象—硬件驱动”四层，并逐一说明每个核心术语的作用与相互关系。

一、DRM 的整体架构分层

DRM（Direct Rendering Manager）是 Linux 内核中负责管理 GPU 与显示控制器的子系统。它并不是一个单一模块，而是由多个层次协作构成的框架：

• 用户空间层：包括 libdrm、Mesa、Wayland 合成器、X Server 等，通过 ioctl 与内核 DRM 设备节点（如 /dev/dri/card0）交互。
• DRM 核心层：提供通用对象管理、内存管理（GEM/TTM）、模式设置（KMS）、原子提交（Atomic Commit）等基础设施。
• KMS 对象层：由 CRTC、Plane、Encoder、Connector、Framebuffer 等对象组成，描述“显示什么、显示到哪里、怎么显示”。
• 硬件驱动层：如 i915、amdgpu、msm、rockchip 等，负责把 KMS 对象的配置翻译成寄存器操作。

理解这四层的关键在于：用户空间只操作抽象对象，内核核心负责校验与调度，硬件驱动负责落地。硬件光标与 VBlank 同步正是发生在 KMS 对象层与硬件驱动层之间的交互。

二、KMS 核心对象及其职责

KMS（Kernel Mode Setting）是 DRM 中负责显示模式设置与画面合成的子系统。它的核心对象可以类比为一条“显示流水线”：

这五个对象的关系可以用一句话概括：Framebuffer 提供像素，Plane 负责合成，CRTC 负责扫描与时序，Encoder 负责信号转换，Connector 负责物理输出。 硬件光标本质上是一个特殊的 Plane，它拥有独立的 Framebuffer 和位置属性，由 CRTC 在扫描时叠加到主画面上。

三、对象之间的连接关系与数据流

为了更直观地理解这些对象如何串联，下面用一张结构关系图展示 KMS 对象在显示流水线中的位置与连接方向。图中同时标注了硬件光标 Plane 与 VBlank 信号的位置，便于后续章节对照。

从图中可以看到，主画面与光标画面分别从各自的 Framebuffer 出发，经过 Plane 合成后进入 CRTC。CRTC 在扫描输出时，会在每个 VBlank 周期产生中断，驱动可以借此机会安全地更新光标位置或切换光标图像，避免撕裂。

四、典型场景：一次光标移动的完整路径

假设用户移动鼠标，Wayland 合成器需要把光标从 (100, 200) 移动到 (120, 220)。这条路径大致如下：

1. 合成器通过 libdrm 构造一个原子提交请求，设置 Cursor Plane 的 CRTC_X、CRTC_Y 属性。
2. DRM 核心校验该 Plane 是否属于目标 CRTC，格式是否支持，坐标是否越界。
3. 驱动在原子提交的 atomic_flush 阶段把新坐标写入 CRTC 的光标位置寄存器。
4. CRTC 在下一个 VBlank 到来时，用新坐标扫描光标，画面无撕裂。
5. 若驱动支持 DRM_CAP_CURSOR_WIDTH/HEIGHT，用户空间可查询硬件光标的最大尺寸。

下面是一段查询光标能力的典型代码片段：

uint64_t cap;
drmGetCap(fd, DRM_CAP_CURSOR_WIDTH, &cap);
printf("cursor max width: %llu\n", (unsigned long long)cap);

drmGetCap(fd, DRM_CAP_CURSOR_HEIGHT, &cap);
printf("cursor max height: %llu\n", (unsigned long long)cap);

/* 查询 CRTC 是否支持光标 Plane */
drmModePlaneRes *planes = drmModeGetPlaneResources(fd);
for (uint32_t i = 0; i < planes->count_planes; i++) {
    drmModePlane *p = drmModeGetPlane(fd, planes->planes[i]);
    if (p->possible_crtcs & (1 << crtc_index)) {
        printf("plane %u can drive crtc %u\n", p->plane_id, crtc_index);
    }
    drmModeFreePlane(p);
}

五、常见误区与复盘