G32S10 DPU HAL 接口

1. 资源模型与公开类型

1.1 输出接口类型

lcd_panel_interface_t 描述面板传输接口：

/* Defined in drivers/g32s10/dpu/lcd_panel.h */
typedef enum {
    LCD_PANEL_IF_TFT  = 1,
    LCD_PANEL_IF_SLCD = 2,
    LCD_PANEL_IF_DSI  = 3,
} lcd_panel_interface_t;

hal_dpu_config_t.output 使用 DPU 硬件输出枚举，而非 panel 接口枚举：

typedef enum {
    HAL_DPU_OUTPUT_TFT  = 1,
    HAL_DPU_OUTPUT_SLCD = 2,
} hal_dpu_output_t;

DSI panel 必须使用 HAL_DPU_OUTPUT_TFT，因为 DISP_COM.DP_IF_SEL 没有 DSI 编码。

1.2 RGB 色彩顺序

色彩顺序由 lcd_panel_order_t 统一定义 (参见 drivers/g32s10/dpu/lcd_panel.h), 枚举值与 DPU 寄存器 LAYER_CONFIG.COLOR_ORDER 3-bit 字段编码一致。

/* Defined in drivers/g32s10/dpu/lcd_panel.h -- listed here for reference only */
typedef enum {
    LCD_PANEL_ORDER_RGB = 0,
    LCD_PANEL_ORDER_RBG,
    LCD_PANEL_ORDER_BGR,
    LCD_PANEL_ORDER_BRG,
    LCD_PANEL_ORDER_GBR,
    LCD_PANEL_ORDER_GRB,
} lcd_panel_order_t;

色彩顺序由 TFT/SLCD/DSI 面板描述符中的对应字段决定, HAL 在 hal_dpu_config_tft() / hal_dpu_config_slcd() 中自动读取并写入 DPU 寄存器。图层 fb_layer_config_t 本身不携带 color_order, 确保单一数据源原则。

1.3 DMA burst 长度

typedef enum {
    HAL_DPU_BURST_LEN_4  = 0,
    HAL_DPU_BURST_LEN_8  = 1,
    HAL_DPU_BURST_LEN_16 = 2,
    HAL_DPU_BURST_LEN_32 = 3,
} hal_dpu_burst_len_t;

约束：NV12 和 NV21 最大只支持 HAL_DPU_BURST_LEN_16。

1.3.1 hal_dpu_packed_bytes_per_pixel

uint8_t hal_dpu_packed_bytes_per_pixel(fb_pixel_format_t format);

功能说明：返回单平面 packed 格式的字节数。RGB555、ARGB1555、RGB565和 YUV422 返回 2，RGB888 和 ARGB8888 返回 4；NV12、NV21 及非法 格式返回 0。该辅助函数不访问硬件，也不返回 error_code_t。

参数表：

返回值表：

1.4 中断类型

typedef enum {
    HAL_DPU_IRQ_STOP_ACK      = DPU_STATUS_STOP_ACK_MASK,
    HAL_DPU_IRQ_TFT_UNDERRUN  = DPU_STATUS_TFT_UNDERRUN_MASK,
    HAL_DPU_IRQ_LAYER0_END    = DPU_STATUS_LAYER0_END_MASK,
    HAL_DPU_IRQ_COMPOSE_START = DPU_STATUS_COMPOSE_START_MASK,
    HAL_DPU_IRQ_DISPLAY_END   = DPU_STATUS_DISPLAY_END_MASK,
} hal_dpu_irq_t;

枚举值与 dpu_regs.h 中的 DPU_STATUS_*_MASK 宏一一对应。

补充说明：

• 非直通模式下，描述符中的 EOD_MSK 必须与 INTC.EOD_MSK 同时使能，才产生 DISPLAY_END 中断

• 直通模式下，中断只由 INTC 对应 mask 位控制

1.5 公开结构体

DPU HAL 层不定义像素格式、图层配置、面板时序和接口配置的结构体。这些类型分别由middleware/fb.h 和 drivers/g32s10/dpu/lcd_panel.h 统一定义, HAL 的配置接口直接 消费这些上游类型。

上游类型 (HAL 直接使用, 此处列出作参考):

所有转换逻辑 (porch->start/end 坐标, stride_bytes->stride_pixels, 信号极性->delay/invert 位) 全部在 HAL 实现内部完成, 不暴露中间转换结构体。

DPU 特有类型 (仅 HAL 定义):

1.5.1 hal_dpu_size_t

typedef struct {
    uint16_t width;
    uint16_t height;
} hal_dpu_size_t;

1.5.2 hal_dpu_position_t

typedef struct {
    uint16_t x;
    uint16_t y;
} hal_dpu_position_t;

1.5.3 hal_dpu_csc_config_t

typedef struct {
    uint16_t mult_y;   /**< CSC_MULT_YRV (0x3200) Y  (26:16) */
    uint16_t mult_rv;  /**< CSC_MULT_YRV (0x3200) RV (10:0)  */
    uint16_t mult_gu;  /**< CSC_MULT_GUGV (0x3204) GU (8:0)  */
    uint16_t mult_gv;  /**< CSC_MULT_GUGV (0x3204) GV (25:16) */
    uint16_t mult_bu;  /**< CSC_MULT_BU (0x3208) BU (11:0)    */
    uint8_t  sub_y;    /**< CSC_SUB_YUV (0x320C) Y  (4:0)     */
    uint8_t  sub_uv;   /**< CSC_SUB_YUV (0x320C) UV (23:16)   */
} hal_dpu_csc_config_t;

1.5.4 hal_dpu_config_t

typedef struct {
    hal_dpu_output_t output;
    hal_dpu_burst_len_t burst_len;
    bool direct_mode_enable;
    hal_dpu_irq_callback_t callback;
    void *callback_user_ctx;
    hal_plic_priority_t irq_priority;
} hal_dpu_config_t;

调用方在初始化时传入该配置。HAL 会拷贝配置并在内部维护运行期状态；调用方不持有 HAL 状态结构。

1.5.5 hal_dpu_irq_callback_t

typedef void (*hal_dpu_irq_callback_t)(dpu_regs_t *dpux,
                                       uint32_t irq_status,
                                       void *user_ctx);

回调在 DPU IRQ 上下文执行，只应做轻量处理，例如记录状态、唤醒等待线程或设置标志位。

1.6 单实例模型与双描述符机制

当前 HAL 采用单 DPU 实例模型：

• 所有公共 API 的第一个参数均为 dpu_regs_t *dpux

• dpux 必须是有效 DPU 实例，目前只接受 DPU

• HAL 运行期状态保存在 hal_dpu.c 的内部静态状态中

• hal_dpu_init() 绑定 dpux 和 hal_dpu_config_t，后续 API 必须传入同一个 dpux

• HAL 不依赖 OS 锁；线程安全由上层 framebuffer/middleware 负责

HAL 内部维护一对 front/back 描述符用于帧更新：

• hal_dpu_config_frame() 只打包 back descriptor，不写 FRM_CFG_ADDR

• hal_dpu_commit_frame() 将 back descriptor 地址写入 FRM_CFG_ADDR，必要时写 FRM_CFG_START，然后交换 front/back 指针

• hal_dpu_is_busy() 读取 DC_ST.WORKING 位，供上层帧同步使用

描述符数据结构和打包逻辑均为 HAL 私有实现，不暴露外部。

2. HAL 接口规范

2.1 HAL 接口

2.1.1 hal_dpu_init

error_code_t hal_dpu_init(dpu_regs_t *dpux, const hal_dpu_config_t *config);

功能说明：初始化唯一的 DPU HAL 实例并绑定寄存器基地址。

参数表：

返回值表：

2.1.2 hal_dpu_deinit

error_code_t hal_dpu_deinit(dpu_regs_t *dpux);

功能说明：停止 DPU、屏蔽中断并释放 HAL 内部状态。

参数表：

返回值表：

2.1.3 hal_dpu_config_frame

error_code_t hal_dpu_config_frame(dpu_regs_t *dpux,
                                  const fb_layer_config_t *layer,
                                  uint16_t frame_width,
                                  uint16_t frame_height,
                                  bool end_of_chain,
                                  bool disp_end_irq);

功能说明：根据图层配置构建待提交的帧描述符。

参数表：

返回值表：

2.1.4 hal_dpu_commit_frame

error_code_t hal_dpu_commit_frame(dpu_regs_t *dpux);

功能说明：将待提交的帧描述符写入硬件并交换前后描述符。

参数表：

返回值表：

2.1.5 hal_dpu_is_busy

bool hal_dpu_is_busy(dpu_regs_t *dpux);

功能说明：查询 DPU 是否正在扫描一帧图像。

参数表：

返回值表：

2.1.6 hal_dpu_config_tft

error_code_t hal_dpu_config_tft(dpu_regs_t *dpux, const lcd_panel_t *panel);

功能说明：根据 TFT 或 DSI 面板描述符配置 DPU TFT/DPI 输出。

参数表：

返回值表：

2.1.7 hal_dpu_config_slcd

error_code_t hal_dpu_config_slcd(dpu_regs_t *dpux, const lcd_panel_t *panel);

功能说明：根据 SLCD 面板描述符配置 DPU SLCD 输出。

参数表：

返回值表：

2.1.8 hal_dpu_slcd_write_command

error_code_t hal_dpu_slcd_write_command(dpu_regs_t *dpux,
                                        uint32_t command,
                                        uint32_t timeout_us);

功能说明：通过 SLCD 寄存器接口发送一条命令并等待接口空闲。

参数表：

返回值表：

2.1.9 hal_dpu_slcd_write_param

error_code_t hal_dpu_slcd_write_param(dpu_regs_t *dpux,
                                      uint32_t param,
                                      bool is_last,
                                      uint32_t timeout_us);

功能说明：通过 SLCD 寄存器接口发送参数或数据。

参数表：

返回值表：

2.1.10 hal_dpu_slcd_send_init_table

error_code_t hal_dpu_slcd_send_init_table(dpu_regs_t *dpux,
                                          const lcd_panel_t *panel,
                                          uint32_t timeout_us);

功能说明：按面板初始化表发送 SLCD 命令、参数和延时项。

参数表：

返回值表：

2.1.11 hal_dpu_start

error_code_t hal_dpu_start(dpu_regs_t *dpux);

功能说明：启动 DPU 显示输出。

参数表：

返回值表：

2.1.12 hal_dpu_stop

error_code_t hal_dpu_stop(dpu_regs_t *dpux, bool general_stop, uint32_t max_retries);

功能说明：停止 DPU 显示输出。

参数表：

返回值表：

2.1.13 hal_dpu_soft_reset

error_code_t hal_dpu_soft_reset(dpu_regs_t *dpux, uint32_t max_retries);

功能说明：触发 DPU 软复位并等待完成。

参数表：

返回值表：

2.1.14 hal_dpu_get_status

error_code_t hal_dpu_get_status(dpu_regs_t *dpux, uint32_t *status_out);

功能说明：读取 DPU 状态寄存器。

参数表：

返回值表：

2.1.15 hal_dpu_enable_irq

error_code_t hal_dpu_enable_irq(dpu_regs_t *dpux, uint32_t irq_mask);

功能说明：使能指定的 DPU 中断。

参数表：

返回值表：

2.1.16 hal_dpu_disable_irq

error_code_t hal_dpu_disable_irq(dpu_regs_t *dpux, uint32_t irq_mask);

功能说明：屏蔽指定的 DPU 中断。

参数表：

返回值表：

2.1.17 hal_dpu_get_irq_status

error_code_t hal_dpu_get_irq_status(dpu_regs_t *dpux, uint32_t *irq_status_out);

功能说明：读取待处理的 DPU 中断状态。

参数表：

返回值表：

2.1.18 hal_dpu_clear_irq_status

error_code_t hal_dpu_clear_irq_status(dpu_regs_t *dpux, uint32_t irq_mask);

功能说明：清除待处理的 DPU 中断状态。

参数表：

返回值表：

2.1.19 hal_dpu_enable_direct_mode

error_code_t hal_dpu_enable_direct_mode(dpu_regs_t *dpux, bool enable);

功能说明：启用或关闭 IPU 直通模式。

参数表：

返回值表：

2.1.20 hal_dpu_config_direct_layer

error_code_t hal_dpu_config_direct_layer(dpu_regs_t *dpux,
                                         const hal_dpu_size_t *frame_size,
                                         const hal_dpu_size_t *layer_size,
                                         const hal_dpu_position_t *layer_pos);

功能说明：配置直通模式下的帧尺寸、图层尺寸和位置。

参数表：

返回值表：

2.1.21 hal_dpu_config_csc

error_code_t hal_dpu_config_csc(dpu_regs_t *dpux, const hal_dpu_csc_config_t *config);

功能说明：配置 YUV 转 RGB 所需的 CSC 系数。

参数表：

返回值表：

2.1.22 hal_dpu_pinmux_init

error_code_t hal_dpu_pinmux_init(const struct lcd_panel *panel);

功能说明：为 TFT/SLCD 面板配置 DPU pinmux（GPIOA 引脚属主与复用功能）。TFT 数据 D[23:6] 位于 PA[17:0]，PCLK=PA18、VSYNC=PA19、HSYNC=PA20、DE=PA21；SLCD 数据 PA[9:0]（位数由 panel 配置决定，SPI DBI 类型无 GPIO 数据脚），DC=PA19、WR=PA20、 TE=PA21（TE 使用 FUNC_2，其余为 FUNC_0）。DSI 面板的引脚由 BSP 配置，本函数直接 返回 IM_OK，不修改 GPIO。

参数表：

返回值表：

2.1.23 hal_dpu_set_cfg_end

error_code_t hal_dpu_set_cfg_end(dpu_regs_t *dpux, bool commit);

功能说明：提交或暂存直通模式（direct mode）的批量寄存器写入，对应 REG_CFG_END (0x2224)。

参数表：

返回值表：

注意：与 hal_dpu_commit_frame() 无关 —— 后者把帧描述符交给 DMA，本接口只控制直通模式寄存器写的提交时机。直通模式要先把整批几何参数写进去再提交，只提交半批会让直通通路按寄存器里残留的旧参数起跑。

3. 推荐操作流程

3.1 描述符模式

1. 打开 DPU 时钟并释放模块复位

2. 调用 hal_dpu_pinmux_init(panel) 完成板级 pinmux 配置（DSI 面板除外， 其引脚由 BSP 配置）

3. 填充 hal_dpu_config_t

4. 调用 hal_dpu_init(DPU, &config) 初始化 HAL 并注册 IRQ

5. 配置输出接口：hal_dpu_config_tft() 或 hal_dpu_config_slcd()

6. SLCD 面板调用 hal_dpu_slcd_send_init_table() 发送初始化表

7. 调用 hal_dpu_enable_irq() 使能需要的中断，例如 HAL_DPU_IRQ_DISPLAY_END

8. 调用 hal_dpu_config_frame() 打包 back descriptor

9. 调用 hal_dpu_commit_frame() 提交 back descriptor 到硬件

10. 后续帧更新重复步骤 8 和 9，上层通过 IRQ 或状态查询做帧同步

3.2 SLCD TE 帧同步

SLCD TE 的硬件等待由 hal_dpu_config_slcd() 根据 panel 描述符配置：

• panel->slcd.te_mode = LCD_PANEL_TE_LCDC 时使能 LCDC-managed TE

• panel->slcd.te_active_edge 决定 SLCD_CFG.TE_MD

• panel->slcd.te_inactive_level 决定 SLCD_CFG.TE_DP

• 面板初始化表需要显式发送 TE enable 命令，例如常见的 0x35

对于具体屏幕，TE edge 必须与面板 TE 输出相位匹配。KWH035 当前使用 LCD_PANEL_TE_EDGE_BACK，避免在固定扫描位置产生撕裂。

3.3 TFT 输出流程

1. 调用 hal_dpu_config_tft() 配置 TFT_HSYNC / TFT_VSYNC / TFT_HDE / TFT_VDE / TFT_CFG

2. 按描述符模式提交帧

3.4 SLCD 输出流程

1. 调用 hal_dpu_config_slcd() 配置 SLCD 基本寄存器

2. 调用 hal_dpu_slcd_send_init_table() 发送 panel 初始化表，并在末尾发送 start-frame command、打开 FMT_EN

3. 按描述符模式提交帧

3.5 IPU 直通模式

1. 初始化时设置 hal_dpu_config_t.direct_mode_enable = true，或调用 hal_dpu_enable_direct_mode(DPU, true)

2. 按需配置 CSC

3. 调用 hal_dpu_config_direct_layer() 配置直通图层尺寸和位置

4. 配置 TFT 或 SLCD 输出接口

5. 调用 hal_dpu_start() 写 REG_CFG_END