3. 原子提交核心机制

在 KMS（Kernel Mode Setting）中，一次显示更新往往涉及多个 Plane、CRTC、Connector 以及底层 Framebuffer 的联动修改。如果这些修改被拆成多次独立生效，用户就会看到撕裂、闪烁或中间态错位。原子提交（Atomic Commit）正是为了解决这一问题：它把一组属性变更打包成一个不可分割的事务，要么全部生效，要么全部不生效。理解原子提交，核心要抓住四个关键词：Atomic Commit、Atomic State、Commit Flags、非阻塞提交。

一、核心原理：从“逐项设置”到“状态快照”

传统模式设置接口（如 drmModeSetCrtc）是命令式的：调用一次，立即改变一个对象。原子提交则改为“状态驱动”：用户态先构造一个 drmModeAtomicReq，把要修改的对象属性逐条加入请求，然后一次性提交。内核在提交时不会直接改硬件，而是先构建一份新的 Atomic State（原子状态），对整份状态做校验，校验通过后才在合适的时机刷入硬件。

Atomic State 可以理解为“本次提交后系统期望达到的完整显示配置快照”。它包含每个 CRTC 的 mode、active 状态、每个 Plane 的 framebuffer、src/dst 坐标、zpos、alpha，以及 Connector 的 link 状态等。内核中对应的结构是 drm_atomic_state，其中又按对象类型分为 drm_crtc_state、drm_plane_state、drm_connector_state。校验阶段会检查带宽、缩放能力、格式支持、Plane 与 CRTC 的兼容性等，任何一项失败都会让整次提交返回错误，硬件保持原状。

二、Commit Flags：控制提交行为的关键参数

提交时通过 flags 参数控制行为，最常用的几个标志如下：

其中 ALLOW_MODESET 需要特别谨慎：一旦带上它，提交可能触发链路重训练、时钟重算，耗时明显增加，且可能造成短暂黑屏。日常页面翻转若只改 Plane 的 framebuffer 和坐标，不应携带该标志。

三、同步提交与异步提交流程

同步提交（默认，不带 NONBLOCK）会一直等到提交完成或失败才返回。它的优点是逻辑简单、错误立即可见；缺点是会阻塞调用线程，尤其在等待 vsync 时可能浪费大量 CPU 时间。异步提交（带 DRM_MODE_ATOMIC_NONBLOCK）在完成校验和排队后立即返回，真正的生效在后续的 commit worker 或 page flip 中断中完成。此时错误不再通过返回值直接暴露，而是通过 DRM_EVENT_FLIP_COMPLETE 或 DRM_EVENT_FLIP_FAILED 事件通知。

drmModeAtomicReq *req = drmModeAtomicAlloc();
drmModeAtomicAddProperty(req, plane_id, prop_fb_id, fb_id);
drmModeAtomicAddProperty(req, plane_id, prop_crtc_id, crtc_id);
drmModeAtomicAddProperty(req, plane_id, prop_src_x, 0);
drmModeAtomicAddProperty(req, plane_id, prop_src_y, 0);

uint32_t flags = DRM_MODE_ATOMIC_NONBLOCK |
                 DRM_MODE_PAGE_FLIP_EVENT;

int ret = drmModeAtomicCommit(fd, req, flags, user_data);
if (ret) {
    /* 非阻塞下这里通常只代表参数或校验早期失败 */
    fprintf(stderr, "atomic commit failed: %s\n", strerror(errno));
}
drmModeAtomicFree(req);

下面这张图展示了从用户态构造请求，到内核构建 Atomic State、校验、同步/异步生效，再到事件回传的完整信号链。

四、典型场景：多 Plane 视频播放的原子更新

假设一个播放器同时使用视频 Plane 和 UI Plane。每帧需要更新视频 Plane 的 framebuffer，同时保持 UI Plane 不变。若采用逐项设置，视频层先切换、UI 层后切换，中间可能出现一帧 UI 与视频不同步。原子提交把两个 Plane 的变更放进同一个请求：视频 Plane 换 fb，UI Plane 的 fb 保持不变但仍在同一 Atomic State 中参与校验。提交成功后，两个 Plane 在同一 vsync 边界一起切换，画面保持一致。

如果播放器还要动态调整视频 Plane 的 zpos 或 alpha，也应一并放入同一请求。否则 zpos 单独提交可能造成一帧遮挡关系错误。对于高帧率场景，建议使用 NONBLOCK | PAGE_FLIP_EVENT，让渲染线程不必等待上一次 flip 完成，从而形成流水线。

五、常见误区与复盘要点

• 误区一：非阻塞提交没有错误。非阻塞提交的返回值只代表请求是否被接受，真正的失败通过 FLIP_FAILED 事件返回。必须注册事件处理，否则会丢失错误。
• 误区二：TEST_ONLY 可以替代真实提交。TEST_ONLY 只做校验，不改变硬件，适合探测，但不能用来“预演”后再直接生效，仍需一次真实提交。
• 误区三：所有提交都带 ALLOW_MODESET。只有分辨率、刷新率、Connector 状态变化时才需要。日常翻转带上它会显著增加延迟。
• 误区四：忘记释放 AtomicReq。每次 drmModeAtomicAlloc 后必须 drmModeAtomicFree，否则内存泄漏。
• 复盘要点：排查原子提交问题时，先确认 flags 组合，再确认事件是否被正确读取，最后检查 Atomic State 中每个对象的属性是否完整、是否互相冲突。

掌握原子提交的关键，在于把“改硬件”思维切换为“提交状态”思维：用户态负责描述目标状态，内核负责校验与整体生效，Commit Flags 决定这次提交是探测、同步还是异步，事件机制则负责把最终结果回传给用户态。理解这条链路，后续排查多 Plane 状态不一致、提交失败或画面撕裂时，就能快速定位到是状态构建、校验还是事件处理环节出了问题。