API GUIDE / JPEGD / OVERVIEW

G32S10 JPEGD API 概述

模块概述：本文只覆盖 JPEGD driver 内的三层接口：

1. 文档范围

本文只覆盖 JPEGD driver 内的三层接口：

本文不描述 JPEG 头部语义处理、测试资源入口或完整业务流程。HAL 层只接收调用方已经准备好的硬件表、restart marker 配置、entropy bitstream 地址和输出 buffer 信息。

APPLICATION Upper Layer 解码业务或上层驱动

→

HAL HAL JPEGD struct_init / init / sequence_configure
callback_register / irq_handler / get_result

→

LL LL JPEGD static inline 寄存器访问

→

REGISTERS jpegd_regs.h 结构体、实地址、位域与 QT/Huffman 寄存器

jpegd_regs.h：定义 JPEGD 寄存器布局、基地址、位域 mask、QT/Huffman 表寄存器数组
LL JPEGD：只读写寄存器，不维护状态，不做参数完整性校验
HAL JPEGD：负责参数校验、几何参数计算、寄存器配置、cache 维护、中断状态清除和回调分发
上层调用方：负责准备 hal_jpegd_tables_t、restart marker 参数、entropy bitstream 起始地址、输入长度和输出 buffer

错误码	HAL/LL 常见原因
`IM_OK`	成功
`IM_ERR_INVALID_PARAM`	空指针、尺寸越界、像素格式非法、tables 指针为空、输出地址未 16 字节对齐、restart interval 非法、reset cycle 非法、bitstream 为空或长度为 0
`IM_ERR_NOT_READY`	HAL 未初始化、sequence 未配置、systick 未初始化
`IM_ERR_BUSY`	已有帧正在运行时重复配置 sequence 或启动新帧
`IM_ERR_UNSUPPORTED`	debug helper 未打开时调用 `hal_jpegd_regs_dump()`
`IM_ERR_TIMEOUT`	软件 reset 等待 `RESET_END` 超时；硬件帧 timeout 通过 `HAL_JPEGD_IRQ_EVENT_TIMEOUT` 回调通知
`IM_ERR_NO_SPACE`	输出 RAW 长度或 HAL 计算的输出容量超过 `dst_buf_size`

LL 层函数本身不返回错误码。LL 调用方需要自行保证参数合法性和寄存器访问顺序。

开关	说明
`CONFIG_DRIVER_JPEGD`	构建 G32S10 JPEGD HAL/LL driver
`CONFIG_JPEGD_ENABLE_DEBUG_HELPERS`	构建 JPEGD debug helper，例如 `hal_jpegd_regs_dump()`

HAL 不负责 JPEG 头部语义处理；调用方必须传入硬件可直接使用的 QT/Huffman 表、restart marker 配置和 entropy bitstream 地址。
frame.bitstream_addr 应指向 entropy bitstream 起始位置，而不是完整 JPEG buffer 起始地址。
param.tables 中的所有指针都不能为 NULL。即使 U/V 使用同一张量化表，也应给 qt_u 和 qt_v 都提供有效表地址。
当前 HAL 固定 Y 使用 table 0、U/V 使用 table 1，因此 table selector 不对上层开放。
HAL 不分配内存，也不搬运 buffer；输出 buffer 的分配、容量和 16 字节对齐由调用方保证。
NV12 输出若不传 dst_uv_addr，HAL 会按 dst_y_addr + stride * height 推导 UV 地址；调用方要保证推导出的地址仍满足 16 字节对齐且 buffer 容量足够。
推荐始终先调用 hal_jpegd_struct_init()，再覆盖必要字段。若调用方手工构造 config 并启用 timeout_en，应显式设置合理的 timeout_threshold。
当前 HAL 使用模块级静态 context，不支持多实例并发或无锁多线程访问。