4. drm_plane_state 结构体：平面状态、坐标、格式、Fence

drm_plane_state 是 DRM 原子提交中描述单个平面（Plane）瞬时状态的核⼼结构体。它记录了该平面在某一帧的所有配置参数，包括绑定的 Framebuffer、显示坐标、像素格式、裁剪区域以及同步 Fence。原子提交的核心工作就是构造、校验并提交这些状态对象。

4.1 结构体核心字段解析

以下表格列出了 drm_plane_state 中最关键的字段及其语义：

4.2 坐标与裁剪模型

平面状态定义了从 Framebuffer 到 CRTC 显示区域的完整映射链路。下图展示了源裁剪、缩放和显示定位的关系：

4.3 像素格式与颜色属性

Framebuffer 的像素格式由 drm_framebuffer 的 format 字段描述，而 drm_plane_state 通过 fb 指针间接引用。平面支持的格式列表在 drm_plane 的 format_types 数组中声明。

常见像素格式分类：

4.4 Fence 同步机制

drm_plane_state 中的 fence 字段用于实现 GPU 与 Display 之间的流水线同步。它本质上是一个 dma_fence，表示该平面的 Framebuffer 内容何时可以被 Display 硬件安全读取。

Fence 的工作流程如下：

1. 出站 Fence（Out-fence）： 用户空间在提交原子 commit 时，可以为每个平面关联一个 out-fence。当 Display 硬件完成对该平面的扫描输出后，该 fence 被 signal。
2. 入站 Fence（In-fence）： 用户空间可以传入一个 in-fence，表示 GPU 渲染尚未完成。Display 驱动必须等待该 fence signal 后才能开始扫描该平面。
3. 驱动处理： 在 atomic_commit 的 commit_tail 阶段，驱动调用 drm_atomic_set_fence_for_plane() 将 in-fence 安装到 plane_state，并在硬件编程前等待。

4.5 状态校验流程示例

以下代码片段展示了驱动在 atomic_check 中如何校验 drm_plane_state 的坐标和格式：

static int my_plane_atomic_check(struct drm_plane *plane,
                                 struct drm_atomic_state *state)
{
    struct drm_plane_state *new_state = drm_atomic_get_new_plane_state(state, plane);
    struct drm_crtc_state *crtc_state;
    struct drm_framebuffer *fb = new_state->fb;
    int ret;

    if (!fb || !new_state->crtc)
        return 0;  /* 平面关闭，跳过校验 */

    crtc_state = drm_atomic_get_new_crtc_state(state, new_state->crtc);

    /* 1. 校验像素格式是否在平面支持列表中 */
    ret = drm_plane_check_pixel_format(plane, fb->format->format);
    if (ret)
        return ret;

    /* 2. 校验源裁剪坐标不越界（16.16 定点数） */
    if (new_state->src_x + new_state->src_w > fb->width << 16 ||
        new_state->src_y + new_state->src_h > fb->height << 16)
        return -EINVAL;

    /* 3. 校验显示坐标不超出 CRTC 尺寸 */
    if (new_state->crtc_x + new_state->crtc_w > crtc_state->mode.hdisplay ||
        new_state->crtc_y + new_state->crtc_h > crtc_state->mode.vdisplay)
        return -EINVAL;

    /* 4. 校验缩放比例在硬件限制内 */
    if (new_state->crtc_w > (new_state->src_w >> 16) * 8 ||
        new_state->crtc_h > (new_state->src_h >> 16) * 8)
        return -EINVAL;

    return 0;
}

4.6 状态所有权与引用计数

drm_plane_state 的生命周期由 DRM 核心管理，但驱动需要理解以下所有权规则：

• 分配： 驱动通过 drm_atomic_helper_plane_duplicate_state() 或自定义 atomic_duplicate_state 回调创建新状态。
• 销毁： 原子提交完成后，旧状态通过 drm_atomic_helper_plane_destroy_state() 释放。
• Framebuffer 引用： fb 字段在状态复制时自动增加引用计数，销毁时减少。驱动不应手动干预。
• Fence 引用： fence 字段在设置时通过 dma_fence_get() 获取引用，在状态清理时通过 dma_fence_put() 释放。