API GUIDE / JPEGD / LL

G32S10 JPEGD LL 接口

LL 层接口：当前 HAL 固定使用以下 selector，不在 HAL public API 中暴露选择器配置：

1. `jpegd_regs.h` 寄存器层

1.1 基地址

名称	地址	说明
`JPEGD_IOBASE`	`0x13210000`	G32S10 JPEGD 寄存器基地址
`JPEGD`	`(jpegd_regs_t *)(uintptr_t)JPEGD_IOBASE`	JPEGD 寄存器实例指针

1.2 主要寄存器

寄存器	RW	偏移	说明
`trig`	RW	`0x000`	启动、软件 reset 和 reset 状态
`ctrl`	RW	`0x004`	timeout、QT/HA/HD table selector、cross 4K 控制
`nmcu`	RW	`0x008`	当前帧 MCU 数量减一
`frm_info`	RW	`0x00C`	对齐后的输出帧宽高
`line_strd`	RW	`0x010`	输出行 stride
`rawy_addr`	RW	`0x014`	输出 Y 平面起始地址
`rawc_addr`	RW	`0x018`	NV12/YUV420 输出 UV 平面起始地址
`bs_addr`	RW	`0x01C`	entropy bitstream 起始地址
`timeout_thrd`	RW	`0x020`	硬件 timeout 阈值
`format_ctrl`	RW	`0x024`	输出像素格式
`code_pix_total`	RW	`0x028`	解码输出的对齐后 RAW 字节总数
`markers`	RW	`0x02C`	Restart marker 使能和 interval
`post_ready_key0` / `post_ready_key1`	RW	`0x030` / `0x034`	Post-ready debug key
`version_num`	R	`0x038`	RTL 版本号
`intr_enable`	RW	`0x03C`	中断使能
`intr_stat`	R	`0x040`	中断状态
`intr_clr`	W	`0x044`	中断清除
`glb_stat`	R	`0x100`	帧结束状态和 RAW 输出长度
`glb_fsm`	R	`0x104`	全局 FSM 和 reset FSM 状态
`debug_*`	R/RW	`0x108-0x16C`	bitstream/raw/debug FSM/EXI/ETC 运行期信息
`qt_tab_y[16]`	RW	`0x300-0x33C`	Y 分量量化表，16 个 32-bit word
`qt_tab_u[16]`	RW	`0x340-0x37C`	U 分量量化表，16 个 32-bit word
`qt_tab_v[16]`	RW	`0x380-0x3BC`	V 分量量化表，16 个 32-bit word
`huffmin[16]`	RW	`0x400-0x43C`	Huffman minimum table
`huffbase[64]`	RW	`0x500-0x5FC`	Huffman base table
`huffsymb[336]`	RW	`0x600-0xB3C`	Huffman symbol table

1.3 关键位域

1.3.1 TRIG

位	宏	说明
31	`JPEGD_RESET_END_MASK`	软件 reset 完成状态
8	`JPEGD_SW_SEQ_RST_REGS_MASK`	Sequence reset 是否覆盖 sequence-level registers
4:7	`JPEGD_SW_RESET_CYCLE_MASK`	软件 reset pulse 宽度
3	`JPEGD_SW_FSM_RESET_MASK`	软件触发 FSM reset
2	`JPEGD_SW_SEQ_RESET_MASK`	软件触发 sequence reset
1	`JPEGD_SW_FRM_RESET_MASK`	软件触发 frame reset
0	`JPEGD_START_MASK`	软件启动一帧解码

1.3.2 CTRL

位	宏	说明
13	`JPEGD_CROSS_4K_DIS_MASK`	cross-4K-boundary 控制
12	`JPEGD_TIME_OUT_EN_MASK`	硬件 timeout 检测使能
10:11	`JPEGD_QT_V_MASK`	V 分量量化表 selector
9	`JPEGD_HA_V_MASK`	V 分量 AC Huffman table selector
8	`JPEGD_HD_V_MASK`	V 分量 DC Huffman table selector
6:7	`JPEGD_QT_U_MASK`	U 分量量化表 selector
5	`JPEGD_HA_U_MASK`	U 分量 AC Huffman table selector
4	`JPEGD_HD_U_MASK`	U 分量 DC Huffman table selector
2:3	`JPEGD_QT_Y_MASK`	Y 分量量化表 selector
1	`JPEGD_HA_Y_MASK`	Y 分量 AC Huffman table selector
0	`JPEGD_HD_Y_MASK`	Y 分量 DC Huffman table selector

当前 HAL 固定使用以下 selector，不在 HAL public API 中暴露选择器配置：

分量	QT	HA/AC	HD/DC
Y	`0`	`0`	`0`
U	`1`	`1`	`1`
V	`1`	`1`	`1`

1.3.3 FORMAT_CTRL

位	宏	说明
0:1	`JPEGD_FORMAT_SEL_MASK`	输出格式：`0` NV12/YUV420，`1` YUYV/YUV422，`2` 单 Y

1.3.4 MARKERS

位	宏	说明
0	`JPEGD_MARKERS_ENABLE_MASK`	Restart marker 解码使能
16:31	`JPEGD_MARKERS_NUMBER_MASK`	Restart interval MCU 数，硬件存实际值减一

1.3.5 GLB_STAT / 中断

寄存器	位	宏	说明
`glb_stat`	31	`JPEGD_FRM_END_MASK`	当前帧解码结束
`glb_stat`	0:23	`JPEGD_RAW_LEN_MASK`	输出 RAW 字节数
`intr_enable/stat/clr`	1	`JPEGD_TIMEOUT_INTR_MASK`	硬件 timeout
`intr_enable/stat/clr`	0	`JPEGD_FRAME_END_INTR_MASK`	frame end

1.4 表寄存器布局

表	寄存器数组	word 数	byte 数	说明
Y QT	`qt_tab_y[16]`	`16`	`64`	Y 分量 8-bit quant table，按 4 byte 打包成 32-bit word
U QT	`qt_tab_u[16]`	`16`	`64`	U 分量 8-bit quant table，按 4 byte 打包成 32-bit word
V QT	`qt_tab_v[16]`	`16`	`64`	V 分量 8-bit quant table，按 4 byte 打包成 32-bit word
Huffman minimum	`huffmin[16]`	`16`	`64`	DC/AC minimum table payload
Huffman base	`huffbase[64]`	`64`	`256`	DC/AC base table payload
Huffman symbol	`huffsymb[336]`	`336`	`1344`	DC/AC symbol table payload

LL 表写入接口逐 word 写这些寄存器数组。HAL 会固定使用上述 word 数。

1.5 硬件限制和几何计算

项	当前 HAL 限制
输出宽度	`8-1920`
输出高度	`8-1440`
输出 RAWY/RAWC 地址	16 字节对齐，且不能为 0
输入 bitstream 地址	HAL 只校验非空
输入 bitstream 长度	必须非 0
Reset cycle	`0-15`，0 在 reset 流程中按 HAL 默认值处理
输出格式	NV12/YUV420、YUYV/YUV422、单 Y
QT 表指针	`qt_y/qt_u/qt_v` 均不能为 `NULL`
Huffman 表指针	`huffmin/huffbase/huffsymb` 均不能为 `NULL`

几何参数计算：

输出格式	对齐宽	对齐高	stride	`code_pix_total` / 输出容量要求	MCU 数
`HAL_JPEGD_PIX_FMT_Y`	8	8	`width_aligned`	`stride * height_aligned`	`(width_aligned / 8) * (height_aligned / 8)`
`HAL_JPEGD_PIX_FMT_NV12`	16	16	`width_aligned`	`stride * height_aligned * 3 / 2`	`(width_aligned / 16) * (height_aligned / 16)`
`HAL_JPEGD_PIX_FMT_YUYV`	16	8	`width_aligned * 2`	`stride * height_aligned`	`(width_aligned / 16) * (height_aligned / 8)`

NV12 输出下，若 frame.dst_uv_addr == NULL，HAL 按紧凑布局推导：

dst_uv_addr = dst_y_addr + stride * height

推导出的 UV 地址仍必须满足 16 字节对齐，输出 buffer 仍必须覆盖 HAL 计算出的完整输出容量。

2. LL JPEGD 接口

详见 code/include/drivers/g32s10/jpegd/ll_jpegd.h。所有函数均为 static inline，直接访问 JPEGD 寄存器。

2.1 LL 层约定

LL 不保存状态，不记录当前帧参数，也不做调用顺序保护
LL 不检查空指针、数组长度、地址对齐、MCU 数范围和输出格式合法性
LL 的 *_mcu_number() 接口接收实际 MCU 数，写寄存器时自动转为硬件需要的 value - 1
LL 表写入接口按 word_count 循环写寄存器数组，调用方必须传固定表长：QT 和 HUFFMIN 为 16，HUFFBASE 为 64，HUFFSYMB 为 336。LL 不自行限制该值：过小会留下旧表项，过大会写过寄存器数组边界
HAL 是当前推荐的寄存器配置入口；只有在 bring-up 或调试时才建议直接调用 LL

2.2 触发和复位

类别	主要函数
reset 状态	`ll_jpegd_get_reset_end`, `ll_jpegd_get_reset_fsm_done`
reset 参数	`ll_jpegd_set_sw_reset_cycle`, `ll_jpegd_enable_sw_seq_rst_regs`, `ll_jpegd_disable_sw_seq_rst_regs`
软件 reset	`ll_jpegd_enable_fsm_reset`, `ll_jpegd_enable_seq_reset`, `ll_jpegd_enable_frm_reset`
start	`ll_jpegd_start`

2.3 CTRL 控制

类别	主要函数
timeout	`ll_jpegd_enable_timeout`, `ll_jpegd_disable_timeout`, `ll_jpegd_set_timeout_thrd`
cross 4K	`ll_jpegd_enable_cross_4k_boundary`
QT selector	`ll_jpegd_set_qt_y`, `ll_jpegd_set_qt_u`, `ll_jpegd_set_qt_v`
AC Huffman selector	`ll_jpegd_set_ha_y`, `ll_jpegd_set_ha_u`, `ll_jpegd_set_ha_v`
DC Huffman selector	`ll_jpegd_set_hd_y`, `ll_jpegd_set_hd_u`, `ll_jpegd_set_hd_v`

2.4 帧参数和地址

类别	主要函数
MCU/宽高/stride	`ll_jpegd_set_mcu_number`, `ll_jpegd_get_mcu_number`, `ll_jpegd_set_frame_width`, `ll_jpegd_set_frame_height`, `ll_jpegd_set_frame_info`, `ll_jpegd_set_line_stride`
源/目的地址	`ll_jpegd_set_src_addr`, `ll_jpegd_set_dst_y_addr`, `ll_jpegd_set_dst_uv_addr`
输出格式	`ll_jpegd_set_output_format`
像素总数	`ll_jpegd_set_code_pixel_number`
restart marker	`ll_jpegd_enable_restart_markers`, `ll_jpegd_disable_restart_markers`, `ll_jpegd_set_restart_marker_mcu_number`

2.5 Debug、状态和中断

类别	主要函数
post-ready key	`ll_jpegd_enable_post_ready_key0`, `ll_jpegd_enable_post_ready_key1`, `ll_jpegd_enable_post_ready_keys`
版本	`ll_jpegd_get_version_num`
输出状态	`ll_jpegd_get_glb_stat`, `ll_jpegd_get_frame_end`, `ll_jpegd_get_raw_len`, `ll_jpegd_get_output_size`
FSM	`ll_jpegd_get_glb_fsm`, `ll_jpegd_get_reset_fsm_done`, `ll_jpegd_get_slv_fsm1`, `ll_jpegd_get_slv_fsm0`, `ll_jpegd_get_reset_fsm`, `ll_jpegd_get_ctrl_fsm`
中断使能	`ll_jpegd_enable_frame_end_intr`, `ll_jpegd_disable_frame_end_intr`, `ll_jpegd_enable_timeout_intr`, `ll_jpegd_disable_timeout_intr`, `ll_jpegd_enable_intr`, `ll_jpegd_disable_intr`, `ll_jpegd_enable_all_intr`, `ll_jpegd_disable_all_intr`
中断状态	`ll_jpegd_get_intr_status`, `ll_jpegd_get_frame_end_info`, `ll_jpegd_get_timeout_info`
中断清除	`ll_jpegd_clear_frame_end_intr`, `ll_jpegd_clear_timeout_intr`, `ll_jpegd_clear_intr`, `ll_jpegd_clear_intr_status`, `ll_jpegd_clear_all_intr`

2.6 QT 和 Huffman 表写入

函数	功能
`ll_jpegd_set_qt_y_table(qt_y, word_count)`	写 Y 分量量化表，即 `qt_tab_y[]`；`word_count` 必须为 16
`ll_jpegd_set_qt_u_table(qt_u, word_count)`	写 U 分量量化表，即 `qt_tab_u[]`；`word_count` 必须为 16
`ll_jpegd_set_qt_v_table(qt_v, word_count)`	写 V 分量量化表，即 `qt_tab_v[]`；`word_count` 必须为 16
`ll_jpegd_set_huffmin_table(huffmin, word_count)`	写 Huffman minimum 表，即 `huffmin[]`；`word_count` 必须为 16
`ll_jpegd_set_huffbase_table(huffbase, word_count)`	写 Huffman base 表，即 `huffbase[]`；`word_count` 必须为 64
`ll_jpegd_set_huffsymb_table(huffsymb, word_count)`	写 Huffman symbol 表，即 `huffsymb[]`；`word_count` 必须为 336