fb_stage 与 fb_stage_wip DPU 差异及升级说明

1. 文档目的

本文用于介绍kernel5.10在从2025.04更新到2026.01之后，即dpu使用的目录由fb_stage变为fb_stage_wip之后，DPU 显示主链路获得的能力、稳定性和使用收益，供客户评估后续软件升级。

对比目录：

2. 总体结论

fb_stage_wip 对 DPU Composer/RDMA 的提交和完成链路进行了系统性增强。

相对 fb_stage，fb_stage_wip 的核心提升是：将原先偏“当前配置后立即启动”的控制方式，扩展为“图层更新请求 -> frame descriptor 队列 -> DPU 中断完成回收 -> 下一帧安全提交”的调度模型；同时补足 DMMU/TLB 映射、DMA descriptor 生命周期、刷新等待、旋转联动和用户态控制接口。

因此，fb_stage_wip 更适合持续刷帧、多图层、Composer 叠加、RDMA/Writeback、动态旋转及复杂 buffer 切换场景。fb_stage 后续不再维护；客户如需持续获得 DPU 主链路的功能完善与问题修正，应以升级至 fb_stage_wip 为主。

3. 框架差异

3.1 fb_stage：基础直接控制模型

fb_stage 已具备基础 framebuffer、RDMA、Composer、DMMU/TLB 和 rotator 控制能力，但主流程更接近：

该模型适合单 framebuffer、固定图层配置、较简单的显示切换。多图层独立更新、硬件仍在读取旧 descriptor 时的软件更新保护、以及不同输出通路之间的切换控制相对有限。

3.2 fb_stage_wip：队列化的 Composer/RDMA 调度模型

fb_stage_wip 将 Composer 提交链路拆分为请求、描述符、硬件完成三个阶段：

主要新增的内部管理对象包括：

• 每图层请求队列：独立缓存各 layer 的待提交更新；

• comp_desc_queued_list 与 comp_desc_done_list：区分“硬件正在使用”和“软件可复用”的 frame descriptor；

• 新旧 comp_setup_info 比较：避免每次提交均无差别重建全部配置；

• rdma_next_frame、rdma_changed、display_end 等状态：把 RDMA 切帧与 DPU 完成时序关联起来；

• wait queue、completion 和 refresh/vblank 状态：为提交、写回完成、图层安全更新提供同步点。

该变化的直接收益是：软件不会轻易改写硬件仍在读取的 descriptor 或 buffer 对应配置，DPU 在多帧连续更新时的时序更可控。

4. 面向 DPU 的主要优化

以下列出对 DPU 使用价值较大的改动。

5. 关键能力说明

5.1 描述符队列和完成回收

fb_stage_wip 为 Composer descriptor 增加“空闲、已排队、已完成”的管理方式。软件提交新的图层组合时，优先从可用 descriptor 中构建新帧；DPU 硬件执行期间，该 descriptor 保持在 queued 状态；收到对应完成事件后才进入 done/可复用状态。

适用价值：

• 连续刷新时，避免软件覆盖硬件正在读取的 frame/layer descriptor；

• 多 layer 在不同时间更新时，能够聚合成完整帧后再提交；

• DPU 忙时可通过队列和等待机制协调提交，而不是依赖上层自行猜测硬件状态。

5.2 DPU 中断状态细化

WIP 对 DPU 的 EOD、EOW、EOC、SOC 等事件增加了单独处理逻辑，并用这些事件推进 descriptor、RDMA 和图层更新状态。

可将其理解为：

这对“上一帧尚未结束、下一帧已经到来”的高频刷新场景尤其重要。

5.3 DMMU/TLB、cache 与 DMA 一致性处理

WIP 在 Composer 调用链中增加 DMMU 映射入口；提交前根据图层 tlb_en 与 framebuffer 的缓存属性执行相应同步。其目标不是单纯增加一次 cache flush，而是保证：

该能力对下列 buffer 更有意义：

• 启用 TLB/DMMU 的用户 buffer；

• RGB 与 NV12/NV21 等不同格式混合的图层；

• CPU、视频模块或其他 DMA 设备生产、DPU 消费的图像 buffer；

• cacheable framebuffer 配置。

5.4 Composer、RDMA、Rotator 的组合输出

WIP 按使用场景选择 Composer 输出模式：

这使 DPU 可以按需求搭建“多图层合成 -> 写回 -> 旋转/上屏”的通路，而不局限于单一直接显示。

5.5 动态旋转与 framebuffer 对齐

WIP 将 rot_angle_set（请求的目标角度）与实际 DPU/rotator 工作状态结合，并增加 layer 角度及完成等待处理。对于 90 度和 270 度场景，还在 framebuffer 分配、line_length 和旋转对齐尺寸上做了适配。

实际含义：动态横竖屏切换不应只修改一个角度寄存器；framebuffer 的行长度、有效宽高和硬件输出路径也必须与旋转要求匹配。WIP 已在驱动主链路中补充相关处理，降低应用仅切角度造成内存布局不匹配的风险。

5.6 对外控制接口完善

WIP 扩展了与 framebuffer/Composer 相关的控制能力，包括旋转角度设置/获取、指定 layer 等待 vsync、等待合成完成、强制更新、render lock/unlock 等。

这些接口的目的不是增加普通显示功能，而是让上层在以下时刻有明确同步手段：

• 图层内容写完后再交给 DPU；

• 切换 buffer 前等待当前 layer 到达安全位置；

• Writeback 场景等待硬件合成完成后再使用输出 buffer；

• 动态旋转或图层参数改变时，减少与正在执行的帧发生竞争。

6. 建议升级到 fb_stage_wip 的具体使用场景

场景 1：双缓冲/多缓冲 UI 连续刷新

典型流程：应用持续绘制下一帧 framebuffer，并在 yoffset 或图层地址切换后上屏。

升级收益：WIP 的 RDMA 切帧状态、vblank 等待和 descriptor 队列更适合连续提交，可减少“软件快速切换、硬件尚未消费完成”的时序风险。

场景 2：多图层叠加显示

典型组合：背景 UI + 图标/OSD + 视频/YUV 图层；不同图层的更新频率不同。

升级收益：WIP 支持按 layer 缓存更新请求并聚合提交，配合 layer 的 format、stride、alpha、z-order 等配置，更适合让 DPU 硬件完成叠加，减少每次仅更新一个 layer 时影响其他 layer 的可能性。

场景 3：NV12/NV21 视频或相机 buffer 与 UI 合成

典型流程：视频模块提供 YUV buffer，UI 模块提供 RGB/ARGB buffer，DPU Composer 做硬件合成。

升级收益：WIP 对 layer stride、UV 地址、DMMU/TLB 映射和提交同步的处理更完整，适合多格式 buffer 进入同一 DPU 合成通路。

场景 3：Composer 写回后再上屏

典型流程：多个图层先合成为一张中间图，再通过 RDMA 读取该结果送屏。

升级收益：WIP 明确支持 COMP_WRITE_BACK_2_RDMA，并用写回结束/descriptor 队列协调 buffer 生命周期，适合需要中间合成结果的显示链路。

场景 5：开机后动态横竖屏切换

典型流程：设备运行中在 0、90、180、270 度之间切换，且界面/图层持续刷新。

升级收益：WIP 的 rotator、Composer 输出模式、framebuffer 对齐和 layer angle 联动更完整。对于 90/270 度，还能避免只修改角度而未同步处理 line length 与 frame 空间的典型问题。

场景 6：需要稳定定位 DPU 刷新问题

典型问题：偶现花屏、闪烁、切帧不同步、图层显示旧内容、合成结果未完成即被使用。

升级收益：WIP 的中断状态、descriptor 队列、等待接口和更细的 DPU 控制状态，能够提供更清晰的问题定位基础；fb_stage 后续不维护时，新问题也更难获得主线修正。

7. 不升级的风险

保留 fb_stage 不代表基础显示一定不可用；对于单 framebuffer、固定分辨率、低频更新的简单产品，现有版本可能仍可满足使用。但需要接受以下边界和风险：

8. 升级建议

8.1 推荐策略

建议后续 DPU 功能开发和客户项目统一以 fb_stage_wip 为基础，不建议在 fb_stage 上继续叠加新的复杂显示功能。特别是涉及 Composer、RDMA、动态旋转、多图层或 TLB/DMMU 的项目，应优先升级。

8.2 升级验证重点

升级并不是只替换目录；应结合实际产品完成以下验证：

1. 基础显示：冷启动、热重启、待机恢复、背光开关后是否正常上屏。

2. RDMA：双/多缓冲连续切换，验证无明显错帧、闪烁和停帧。

3. Composer：RGB/ARGB/YUV 图层叠加、alpha、z-order、crop、stride 是否符合预期。

4. TLB/DMMU：使用外部/用户图像 buffer 时验证地址映射及 cache 同步正确性。

5. Writeback：确认写回完成后才读取或复用输出 buffer。

6. 旋转：分别验证 0/90/180/270 度，尤其检查 90/270 度的源图宽高、stride、framebuffer 行长度和显示方向。

7. 压力测试：高频提交、频繁切图层、长时间运行和异常恢复场景。

9. 最终建议

fb_stage_wip 的价值在于增强整个 DPU 的可控性，而不仅是解决单一显示问题：它将图层更新、descriptor 生命周期、DPU 中断、RDMA 切帧、Writeback、Rotator、TLB/DMMU 和用户态同步接口串成更完整的控制链路。

对于只需维持当前简单显示功能的产品，fb_stage 可以作为存量方案；对于后续需要维护、扩展或交付复杂显示能力的客户，应明确选择 fb_stage_wip 作为后续升级基线。由于 fb_stage 已停止维护，继续基于旧目录开发会逐步增加功能补丁分散、问题回归和维护成本。