API GUIDE / DPU / OVERVIEW

G32S10 DPU API 概述

模块概述：本文档定义 G32S10 SDK DPU（Display Processing Unit / Display Controller）模块对外暴露的正式接口，覆盖以下两层：

1. 文档范围

本文档定义 G32S10 SDK DPU（Display Processing Unit / Display Controller）模块对外暴露的正式接口，覆盖以下两层：

HAL DPU：面向 BSP、显示面板驱动、图形栈和业务模块的功能级接口
LL DPU：面向 DPU 寄存器与描述符字段的低层接口

本文档基于以下实现和头文件编写：

code/include/drivers/g32s10/dpu/hal_dpu.h
code/include/drivers/g32s10/dpu/ll_dpu.h
code/include/drivers/g32s10/dpu/dpu_regs.h
code/drivers/g32s10/dpu/hal_dpu.c
code/include/drivers/g32s10/dpu/hal_dpu_pinmux.h
code/drivers/g32s10/dpu/hal_dpu_pinmux.c

2. 分层关系

Application / GUI / Panel Driver
           |
           v
        HAL DPU
           |
           v
         LL DPU
           |
           v
      DPU Registers / Descriptors

分层职责如下：

HAL DPU

封装显示控制器初始化、输出接口配置、图层/帧描述符配置和启动/停止流程
提供 TFT/SLCD 板级 pinmux 配置（hal_dpu_pinmux_init()）
维护软件态设备状态、回调函数、中断掩码和显示模式
统一验证实例、参数范围与初始化状态，并返回 error_code_t
内部管理 front/back 双描述符；通过 hal_dpu_commit_frame() 提交并交换 staging 描述符

LL DPU

提供寄存器级访问入口和 bit field 配置函数
不维护软件状态，不注册业务回调
不主动等待硬件状态，除非函数名明确表示 poll/wait

dpu_regs.h

定义 DPU 基地址、寄存器布局、寄存器偏移、状态位与中断位

3. 资源模型与公开类型

3.1 DPU 实例与能力

DPU 寄存器基地址：

实例	基地址	说明
`DPU`	`0x13340000`	Display Controller 寄存器内存映射基地址

当前 HAL 覆盖以下已实现能力：

输入格式：RGB888、ARGB8888、RGB565、RGB555、ARGB1555、NV12、NV21、YUV422
DPU 输出：TFT/DPI、SLCD(MIPI-DBI Type A/B/C)；MIPI DSI 由独立 DSI host 接收 TFT/DPI 输出
CSC、IPU 直通模式和描述符 DMA 模式

3.2 像素格式

像素格式由 fb_pixel_format_t 统一定义 (参见 middleware/fb.h), HAL 层直接引用该类型, 不自行定义枚举。HAL 将其映射到 DPU 寄存器 LAYER_CONFIG.FORMAT 编码；两者的数值不要求相同。

`fb_pixel_format_t`	DPU FORMAT	内存布局
`RGB555`	0	单 `rgb` 平面，2 bytes/pixel
`ARGB1555`	1	单 `rgb` 平面，2 bytes/pixel；A bit 被硬件忽略
`RGB565`	2	单 `rgb` 平面，2 bytes/pixel
`RGB888`	4	单 `rgb` 平面，4-byte lane；bits 31:24 被硬件忽略
`ARGB8888`	5	单 `rgb` 平面，4 bytes/pixel；A byte 被硬件忽略
`NV12`	8	Y + UV 两平面 4:2:0
`NV21`	9	Y + VU 两平面 4:2:0
`YUV422`	10	Y + UV 两平面 4:2:2

NV12、NV21 要求宽和高均为偶数；YUV422 要求宽为偶数。YUV 的y.stride_bytes 和 uv.stride_bytes 均以字节为单位写入 descriptor。外部图层的平面由调用者持有；其存储必须保持有效，直到成功提交另一帧或 framebuffer 被 disable。

4. 参数校验与错误码

错误码	触发场景
`IM_OK`	操作成功
`IM_ERR_INVALID_PARAM`	空指针、非法实例、尺寸越界、地址未对齐、非法枚举值
`IM_ERR_NOT_READY`	DPU 未初始化、输出接口未配置或 IRQ 子系统未就绪
`IM_ERR_BUSY`	DPU HAL 已初始化，不能重复 init
`IM_ERR_TIMEOUT`	等待停止、复位、SLCD busy 或中断状态超时

5. 注意事项

所有 HAL 公共 API 的 dpux 必须为 DPU
HAL 不提供多实例 handle，运行期状态由 hal_dpu.c 内部静态对象维护
HAL 不做 OS 级互斥，线程安全由上层 framebuffer/middleware 负责
帧描述符地址由 HAL 内部管理并保证 8 字节对齐
NV12/NV21 的 Y 地址必须 8 字节对齐，UV 地址无额外对齐要求，且 burst 长度最大为 16
hal_dpu_config_frame() 不启动硬件，提交统一由 hal_dpu_commit_frame() 完成
LL DPU 接口只保证寄存器字段写入，不保证显示时序、面板协议和内存布局语义正确