📚 课程目录第4章 Atomic API引入背景

4. Atomic API 引入背景：为什么需要 Atomic？传统接口的竞态条件与闪烁问题

在 DRM/KMS 显示驱动的发展历程中，传统的逐属性更新接口（如 drmModeSetCrtc、drmModeSetPlane、drmModeSetConnector 等）长期占据主导地位。然而，随着显示分辨率提升、多平面合成复杂化以及用户空间对无撕裂（tear-free）体验的要求日益严苛，传统接口的固有缺陷逐渐暴露。Atomic API 的引入正是为了解决这些深层次的设计问题。

4.1 传统接口的设计缺陷

传统 DRM 接口采用“逐个属性提交”的模式，每个系统调用仅更新一个或少数几个显示状态。这种设计在单显示器、低刷新率场景下尚可工作，但在现代复杂显示管线中引发了严重的竞态条件（race condition）和视觉伪影。

缺陷类别	具体表现	典型后果
非原子性提交	多个属性更新需要多次 ioctl，中间状态暴露给硬件	屏幕闪烁（flicker）、部分更新生效
缺乏状态校验	每个 ioctl 独立校验，无法保证全局一致性	提交失败后状态回滚不完整，驱动进入不一致状态
无事务回滚	失败后无法整体回退到提交前状态	用户空间需要手动恢复，极易出错
隐式依赖顺序	用户空间必须按特定顺序调用接口	跨驱动版本兼容性差，应用层逻辑复杂
缺少测试能力	无法在不生效的情况下验证配置是否合法	调试困难，生产环境出现意外黑屏

关键认知： 传统接口的“逐个提交”模式本质上是一种非事务性的更新机制。在并发场景下，多个用户空间线程或进程同时操作显示状态时，竞态条件几乎不可避免。

4.2 竞态条件：多线程下的状态撕裂

竞态条件在传统 DRM 接口中表现为：两个或多个用户空间线程同时调用不同的属性更新接口，导致硬件最终看到的状态是多个提交的“混合体”。

典型场景： 线程 A 调用 drmModeSetCrtc 切换主显示输出，线程 B 同时调用 drmModeSetPlane 调整覆盖层位置。由于内核没有全局锁保护整个更新序列，硬件可能在 A 的 CRTC 配置已生效但 B 的 Plane 配置尚未写入时触发 VBlank 中断，导致一帧画面中 CRTC 和 Plane 的状态不匹配。

下图展示了传统接口下竞态条件导致的状态撕裂过程：

上图中，VBlank 中断在 CRTC 更新已生效但 Plane 更新尚未写入的时刻采样了显示状态，导致硬件输出一帧“CRTC 新 + Plane 旧”的混合画面。这种状态撕裂在用户空间表现为屏幕局部闪烁或内容错位。

4.3 闪烁问题：中间状态的视觉暴露

闪烁（flicker）是传统接口最直观的用户可见问题。当多个显示属性需要同时变更时，传统接口的逐个提交方式会暴露中间状态给显示器。

典型的闪烁场景包括：

分辨率切换： 先调用 drmModeSetCrtc 改变时序，再调用 drmModeSetConnector 更新连接器状态，中间出现短暂的黑屏或信号丢失。
多平面合成： 先更新主平面（Primary Plane）的 framebuffer，再更新覆盖平面（Overlay Plane）的 alpha 值，中间出现主平面新内容与旧 alpha 混合的错误画面。
色彩管理： 先设置 CTM（Color Transformation Matrix），再设置 Gamma LUT，中间出现颜色跳变。

性能代价： 传统接口为了减少闪烁，用户空间往往需要插入额外的 VBlank 等待或使用双缓冲技巧，这不仅增加了应用层的复杂度，还引入了额外的延迟。在 4K@120Hz 等高刷新率场景下，这种延迟会显著影响用户体验。

4.4 状态校验缺失：不一致状态的传播

传统接口的另一个严重缺陷是缺乏全局状态校验。每个 ioctl 只校验自身涉及的属性，而不检查与其他属性之间的约束关系。

例如，某些硬件平台要求：

Overlay Plane 的尺寸必须小于 Primary Plane 的尺寸。
缩放因子必须在特定范围内。
多个 Plane 之间不能有像素重叠（取决于硬件合成能力）。

在传统接口下，用户空间可能先设置了一个过大的 Overlay Plane（通过 drmModeSetPlane），然后尝试设置一个较小的 Primary Plane（通过 drmModeSetCrtc）。第一个 ioctl 通过校验，第二个 ioctl 也通过校验，但两者组合后的状态却是非法的。硬件在尝试合成时可能产生未定义行为，甚至导致驱动崩溃。

4.5 Atomic API 的解决方案

Atomic API 通过引入“全有或全无”的事务语义，从根本上解决了上述问题。其核心设计原则包括：

设计原则	实现方式	解决的问题
原子性提交	单个 `DRM_IOCTL_MODE_ATOMIC` 提交所有属性变更	竞态条件、状态撕裂
全局校验	提交前对整个显示管线状态进行一致性检查	非法状态组合、驱动崩溃
事务回滚	校验失败时自动回滚到提交前状态	部分更新生效、状态不一致
测试模式	支持 `DRM_MODE_ATOMIC_TEST_ONLY` 标志位	无副作用验证配置合法性
异步提交	支持 `DRM_MODE_ATOMIC_NONBLOCK` 非阻塞模式	减少用户空间等待延迟

下图展示了 Atomic API 的事务性提交流程与传统接口的对比：

4.6 从传统到 Atomic：迁移路径

对于正在使用传统接口的驱动和应用，迁移到 Atomic API 需要理解以下关键变化：

接口统一： 所有属性更新合并到单个 drmModeAtomicCommit 调用，不再使用分散的 drmModeSetCrtc 等接口。
属性对象化： 每个显示对象（CRTC、Plane、Connector）的属性通过 drmModeObjectSetProperty 添加到 Atomic 请求中。
提交标志位： 使用 DRM_MODE_ATOMIC_TEST_ONLY 进行无副作用测试，使用 DRM_MODE_ATOMIC_NONBLOCK 实现异步提交。
事件处理： Atomic 提交通过 drmEventContext 中的 page_flip_handler 或 sequence_handler 通知完成状态。

迁移建议： 对于新开发的 DRM 驱动，应直接实现 Atomic 接口并声明 DRIVER_ATOMIC 标志。对于已有传统驱动的维护，建议逐步将核心状态更新逻辑迁移到 Atomic 路径，同时保留传统接口作为兼容层。

4.7 本章小结

传统 DRM 接口的逐个提交模式在并发场景下必然产生竞态条件和闪烁问题，其根源在于缺乏事务性语义和全局状态校验。Atomic API 通过“全有或全无”的原子提交、全局校验、事务回滚和测试模式，为显示驱动提供了现代、可靠的状态更新机制。理解这些背景是掌握后续 Atomic API 优化实战的基础。