G32S10 IPU API 概述

1. 文档范围

本文档定义 G32S10 SDK IPU 模块的正式接口，覆盖以下两层：

• HAL IPU：面向 BSP 和显示集成方（display integration）的功能级接口

• LL IPU：面向寄存器与位操作的低层接口（static inline）

对应文件：

设计原则：

• HAL 是薄寄存器语义层：封装时钟门控、IRQ 注册、RUN/STOP/RESET、连续帧 ready 位和运行期换帧；不维护用户句柄，不执行 cache 操作，不做阻塞等待或 业务状态机。

• 配置结构体携带图像语义（格式、字节序、几何、坐标、alpha），由 HAL 编码进 寄存器；寄存器位布局不向调用方暴露。

• HAL 维护的唯一软件状态：单实例绑定、时钟门控、IRQ 注册，以及 ISR 缓存的pending_irq 锁存位。

1.1 职责划分

2. 分层关系

分层职责如下：

• HAL IPU

• 封装 init/deinit（时钟门控 HAL_CPM_ID_GATE_IPU、IRQ 注册）、配置、启动、停止、复位、连续帧 buffer ready 与运行期换帧。

• 负责参数合法性检查：实例、掩码范围、枚举值、idle 前置条件。

• 维护 ISR 锁存的 pending_irq（HAL_IPU_IRQ_OUT_END / HAL_IPU_STATUS_SIZE_ERR）。

• 不执行 cache 操作，不提供阻塞等待接口。

• LL IPU

• 提供寄存器访问入口：状态读取、格式配置、地址/stride 配置、触发/停止/复位、OSD 参数、CSC 系数、读仲裁、ready 位和诊断。

• 不做业务语义判断，不分配资源，不维护状态。

• 公开接口首参数为 ipu_regs_t *ipux 或 const ipu_regs_t *ipux。

• ipu_regs.h

• 定义 IPU 基地址实例、寄存器结构体布局、位域 mask/shift、枚举编码、对齐和图像尺寸范围。

3. 当前实现约束与行为说明

3.1 单实例与时钟门控

• HAL 是单实例绑定：hal_ipu_init() 二次调用返回 IM_ERR_BUSY；全局状态由 ISR 与调用者共享。

• init 使能 HAL_CPM_ID_GATE_IPU 时钟门控，deinit 释放；失败路径回滚状态。

3.2 格式编码约束

• 背景（输入）格式仅可编码 ARGB8888、NV12、YUV422。

• OSD 通道 0 启用时，输出格式必须等于输入（背景）格式——OSD 不改变格式。 YUV422 背景同样支持：OSD 模式下 D_FMT.OUT_FMT 无效，硬件自动取CH_BK_PIC_TYPE（spec 10.1.4.8、旧 SDK 注释确认），无需 YUV422 输出编码。

• OSD 通道 0（小图）格式：ARGB8888、ARGB1555、RGB888、NV12、NV21、2-bit； RGB888 每像素占 4 字节存储。

• OSD 通道 0 禁用时（CSC 路径），输出格式仅可编码 ARGB8888、RGB888、NV12、 NV21、HSV；CSC 输入仅可编码 NV12、YUV422；输出方向为 DPU 时输出格式 只能是 RGB888（SPEC 10.1.5.2）。

• OSD 通道 0 禁用时 output==input 的直通仅支持 ARGB8888、NV12；YUV422 无 D_FMT 编码，不能直通，需改用 CSC 转换（YUV422→ARGB/RGB/NV12/NV21/HSV）。

• 12 种 ARGB 字节序均支持；IPU 的 ARGB8888 字节序与 DPU 理解相反（IPU 中 alpha 在低字节）。

• NV12/NV21 宽高必须为偶数；2-bit 格式仅作为 OSD 通道 0 小图格式暴露， 不作为背景/输出格式。

3.3 RUN/STOP/RESET 前置条件

• hal_ipu_config() 与 hal_ipu_start() 要求硬件 idle，非 idle 返回IM_ERR_BUSY。

• hal_ipu_config() 校验输入/输出/通道 0 地址 8 字节对齐且非零、stride 不低于格式下限、OSD 通道 0 完整位于背景帧内、NV12 偶数宽高；不满足返回IM_ERR_INVALID_PARAM，格式无法编码返回 IM_ERR_UNSUPPORTED。

• 连续帧模式运行中不得调用 hal_ipu_config()；换帧使用hal_ipu_update_frame()。

• 按 spec，RUN 前 BUFF_STATE.BK_BUFF0_STATE 必须为 1。

3.4 调试辅助与 Kconfig

• hal_ipu_dump_regs() 仅在 CONFIG_SDK_ENABLE_DEBUG_HELPERS=y 与CONFIG_IPU_ENABLE_DEBUG_HELPERS=y 时编译，否则返回 IM_ERR_UNSUPPORTED。

• 诊断信息应优先读取 hal_ipu_get_status()、hal_ipu_get_cycle_count() 与hal_ipu_get_debug_info() 的原始值保存。

3.5 LL 接口不做参数保护

• LL 接口默认调用方已保证 ipux、掩码、枚举和地址范围合法。

• HAL 接口负责参数检查并返回 IM_ERR_INVALID_PARAM、IM_ERR_UNSUPPORTED 或IM_ERR_BUSY。

• 同一 IPU 实例的 LL 访问必须由调用方保证互斥。

4. 推荐关注的错误码