API GUIDE / MIPI DSI / OVERVIEW

G32S10 MIPI DSI API 概述

模块概述：本文档说明仓库中已实现的 G32S10 MIPI DSI host 与芯片内置 D-PHY TX 接口：

1. 文档范围

本文档说明仓库中已实现的 G32S10 MIPI DSI host 与芯片内置 D-PHY TX 接口：

HAL：code/include/drivers/g32s10/dsi/hal_dsi.h
DSI host LL：code/include/drivers/g32s10/dsi/ll_dsi.h
D-PHY TX LL：code/include/drivers/g32s10/dsi/ll_dphy_tx.h
寄存器定义：dsi_regs.h、dphy_tx_regs.h
面板描述：code/include/drivers/g32s10/dpu/lcd_panel.h
实现：code/drivers/g32s10/dsi/hal_dsi.c

本文档只描述当前已落地的 API，不包含尚未实现的抽象初始化结构体、回调注册、HAL 中断屏蔽或视频测试图案接口。

2. 分层关系

Framebuffer / Panel driver
           |
           v
        HAL DSI
           |
           v
  LL DSI host + LL D-PHY TX
           |
           v
DSI host registers + on-chip D-PHY TX registers

HAL DSI：维护单个运行期状态，计算时钟与视频时序，配置 host 和芯片内置 D-PHY，等待 packet FIFO 与 PHY 状态，并提供统一错误码。
LL DSI host：按具名字段访问 DSI host 寄存器；不维护软件状态，不做参数校验、等待、时钟管理或面板命令解释。
LL D-PHY TX：按具名字段访问芯片内置 D-PHY TX 寄存器；不适合面板代码直接调用。
寄存器定义：定义实例地址、寄存器布局和位域 mask，不定义初始化策略。

3. 资源模型与公开类型

3.1 硬件实例与单例状态

名称	类型	基地址	说明
`MIPI_DSI`	`dsi_regs_t *`	`0x10005000`	G32S10 唯一的 MIPI DSI host 寄存器实例。
`MIPI_DPHY_TX`	`dphy_tx_regs_t *`	`0x10006000`	与该 host 配套的芯片内置 D-PHY TX 寄存器实例。

hal_dsi_init() 只接受上述两个实例。HAL 在成功初始化后保存 DSI host、D-PHY、lane 数、byte clock、TX escape divider 和命令间延时；重复初始化返回 IM_ERR_BUSY。hal_dsi_deinit() 清除该状态并关闭 HAL_CPM_ID_GATE_MIPI_DSI 时钟。

调用方负责在初始化前完成 BSP pinmux、面板供电和复位。HAL 不接管 GPIO，也不发送面板电源或复位命令。

3.2 DSI 面板描述符

DSI 面板必须设置 lcd_panel_t.interface = LCD_PANEL_IF_DSI。DPU 侧仍使用 TFT/DPI 输出，DSI host 将该 DPI 流编码为 DSI 视频流。

lcd_panel_dsi_config_t 是 HAL 的主要输入：

字段	说明
`lane_count`	data lane 数量，仅支持 `1` 或 `2`。
`virtual_channel`	DSI virtual channel，范围 `0` 到 `3`。
`byte_clock_hz`	每 data lane byte clock；为 0 时 HAL 依据像素时钟、颜色编码和 lane 数估算。
`command_delay_us`	每个成功发送的命令包后的软件延时，0 表示不延时。
`max_hs_to_lp_cycles`、`max_lp_to_hs_cycles`、`max_bta_cycles`	DSI host D-PHY 时序寄存器值。
`color_coding`、`color_type_18bit`	DPI 颜色编码和 18-bit packed/loosely packed 选择。
`data_enable_polarity`、`hsync_active`、`vsync_active`、`color_mode_polarity`、`shutdown_polarity`	DSI host DPI 输入极性。
`video_mode`	non-burst sync pulse、non-burst sync event 或 burst sync pulse。
`clk_mode`	连续或非连续 HS clock lane。
`exit_lp_mode`	指定 video blanking 区保持 HS 的 `LCD_PANEL_DSI_EXIT_LP_MODE_*` 位集合；未置位的窗口允许进入 LP。
`slcd_te_mode`、`slcd_te_edge`	供 DPU 配置 MIPI-DBI/TE 兼容路径使用，DSI HAL 不使用。

timing 提供像素时钟、活动区和 porch/sync 参数。pixclock_hz 为 0 时，HAL 使用完整水平、垂直总像素数和 refresh_hz 计算像素时钟；两者都无法提供有效时钟时初始化失败。

3.3 DSI 配置枚举

类型	可用值	作用
`lcd_panel_dsi_video_mode_t`	non-burst sync pulses、non-burst sync events、burst sync pulses	选择 `VID_MODE_CFG.VID_MODE_TYPE`。
`lcd_panel_dsi_clk_mode_t`	continuous、non-continuous	控制 HS clock lane 是否由 host 自动停止。
`lcd_panel_dsi_color_coding_t`	16-bit config1/2/3、18-bit config1/2、24-bit	选择 DSI DPI color coding，并决定 byte clock 的估算位宽。
`lcd_panel_dsi_18bit_type_t`	packed、loosely	只对 18-bit color coding 有效；packed 模式下 HAL 将 video packet size 向上对齐到 4 像素。
`lcd_panel_dsi_exit_lp_mode_t`	VSA、VBP、VFP、VACT、HBP、HFP 位组合	对应 blanking 区保持 HS；未设置的区域允许 host 进入 LP。

4. DPU 协作与时序

DSI video mode 的数据源是 DPU TFT/DPI：

BSP 配置所需时钟和 pinmux，面板驱动完成供电、复位。
调用 hal_dsi_init(MIPI_DSI, MIPI_DPHY_TX, panel)，此时 host 在 command mode。
调用 hal_dsi_send_init_packets() 发送 panel 初始化表。
初始化 DPU，选择 HAL_DPU_OUTPUT_TFT，并用同一个 DSI panel 调用 hal_dpu_config_tft()。
调用 hal_dsi_enter_video_mode()，再配置并提交 DPU frame descriptor。

byte_clock_hz 表示单条 data lane 的 byte clock。若 panel 未显式提供，HAL 先依据像素时钟、每像素字节数和 lane 数估算，并加入传输裕量；对于时钟敏感的面板应在 panel 描述符明确设置该值。

5. 参数校验与使用限制

当前 D-PHY 硬件和 HAL 仅支持 1 或 2 条 data lane。
HAL 使用芯片内置的 MIPI_DPHY_TX 实例，完整配置 D-PHY 模拟、数字、lane timing 和 TTL/阻抗寄存器。
timeout_us 是 packet FIFO 等待时间，单位为微秒；它不等同于面板命令间的 command_delay_us。
hal_dsi_get_*_status() 返回原始寄存器位。应结合 dsi_regs.h 的 DSI_*_MASK 宏解释。
HAL 不提供线程同步；同一时刻的模式切换、包发送和 DPU 帧启动由上层串行化。