G32S10 I2D HAL 接口

1. 分层关系与依赖

1.1 HAL 中每类操作调用的 LL 接口

2. 构建配置与文件组织

2.1 Kconfig

menuconfig DRIVER_I2D
    bool "I2D driver"
    default n
    help
      Build the G32S10 I2D image rotation driver.

• 打开 CONFIG_DRIVER_I2D=y 才会编译 hal_i2d.c。

• HAL 依赖 CPM（CONFIG_DRIVER_CPM=y）；回调示例还依赖 IRQ 框架 （CONFIG_DRIVER_IRQ=y）。

• LL 只依赖头文件，但直接操作寄存器前必须先打开时钟（见 §6.8）。

2.2 CMake

if(CONFIG_DRIVER_I2D)
    imde_component_register(NAME g32s10_i2d SRCS
        "${CMAKE_CURRENT_LIST_DIR}/hal_i2d.c")
endif()

3. 资源模型与公开类型

3.1 公开类型

3.1.1 hal_i2d_format_t

3.1.2 hal_i2d_rotate_t

90°/270° 时输出宽高互换，HAL 用这一点校验目标 stride 并计算布局。

3.1.3 hal_i2d_state_t

3.1.4 hal_i2d_irq_t / hal_i2d_event_t

HAL 的 IRQ 位与 event 值刻意保持一致，便于寄存器 mask 直接映射。

3.1.5 hal_i2d_error_t

错误标志是锁存的或运算结果，只能通过 hal_i2d_error_clear() 清除。

3.1.6 hal_i2d_init_config_t

3.1.7 hal_i2d_config_t

3.1.8 hal_i2d_layout_t

hal_i2d_layout_get() 的输出，供调用方做容量检查与 cache 维护：

3.1.9 hal_i2d_handle_t

3.2 默认值

hal_i2d_init_config_default() 不访问硬件：

hal_i2d_config_default() 清零整个结构体，只把 format 设为 NV12、rotate 设为ROTATE_0。宽高、地址与 stride 必须在使用前填写。

3.3 缓冲区所有权与对齐

• 源/目标 buffer 完全由调用方分配、填充和释放；HAL 只拿地址。

• 容量至少是 hal_i2d_layout_get() 返回的 src_buffer_size / dst_buffer_size。 90°/270° 时两者可能不同，按各自的值准备，不要假设相等。

• 推荐按 HAL_I2D_BUFFER_ALIGN（64 字节）对齐——它同时是 cache 行大小。三个 官方示例都申请 size + 64 再向上对齐，硬件地址取对齐后的指针。

• 同一块目标 buffer 在 I2D 完成前不能交给 CPU 读或另一路 DMA 写；完成后再做 cache invalidate 才能读。

4. 接口规范

4.1 调用顺序速查

5. 行为约束与实现说明

5.1 布局推导公式

hal_i2d_layout_get() 的规则：

算例：

两个容易错的点：

1. NV12 的 Y 平面按 16 行对齐。1080 行会占 1088 行：1920 * 1088 = 2,088,960，UV 从这之后开始；直接用 width * height 推 UV 地址会错位。

2. 90°/270° 后源/目标大小不同。NV12 1920x1080 转 90° 时源 3,125,760、 目标 3,110,400；按 max(src, dst) 分配即可，但 cache 维护要按各自的真实大小做。

5.2 参数校验规则

hal_i2d_start() 与 hal_i2d_layout_get() 共用同一套校验：

config_default() 的默认格式是 NV12，因此不填 src_uv_buf 时 HAL 会按 Y 平面推导 UV 地址。如果要处理单平面/打包格式，必须显式设置 format，否则校验和布局都会 按 NV12 处理。

5.3 中断分发、事件回调与屏蔽语义

• irq_state 是锁存状态，读不清除；清除要写 irq_clear。

• irq_mask 是「1 = 屏蔽」。HAL 初始化按 frame_done_irq_enable /timeout_irq_enable / outstanding_irq_enable 写一次掩码；之后可以用hal_i2d_irq_config() 改。

• hal_i2d_irq_handler() 只处理 latched & enabled；被屏蔽的位保持锁存，留给 轮询读 irq_state 的人。

• 回调按 TIMEOUT → OUTSTANDING → FRAME_DONE 顺序逐个触发；一次入口可能回调多次。

• 回调里只做「置标志/计数/唤醒」；cache 维护与日志放到任务上下文。

6. 典型用法：从零开始

本节假设你手上有一块能跑 SDK 的板子，想把「内存里的图 → 旋转/镜像 → 内存里的图」 直接做在 HAL 或 LL 上。

6.1 第二步：算布局

hal_i2d_layout_get() 是纯软件计算，可以在 hal_i2d_init() 之前调用。还不知道 buffer 地址时用占位地址（函数只校验非空，不解引用）：

static error_code_t i2d_probe(uint32_t width, uint32_t height,
                              hal_i2d_format_t format, hal_i2d_rotate_t rotate,
                              hal_i2d_layout_t *layout)
{
    hal_i2d_config_t probe;

    (void)hal_i2d_config_default(&probe);
    probe.src_buf  = (void *)(uintptr_t)HAL_I2D_BUFFER_ALIGN;        /* 占位 */
    probe.dst_buf  = (void *)(uintptr_t)(HAL_I2D_BUFFER_ALIGN * 2U); /* 占位 */
    probe.width    = width;
    probe.height   = height;
    probe.format   = format;
    probe.rotate   = rotate;

    return hal_i2d_layout_get(&probe, layout);
}

例：640x480 YUV422 顺时针 90°，得到 480x640、源 stride 1280 / 目标 stride 960、 两边各 614,400 字节。算例见 §6.3。

7. 示例程序解读

三个示例结构相同，只是「谁负责等待、谁负责时钟」不同：

8. 集成到你自己的工程

8.1 三种等待形态怎么选

不要混用轮询与 ISR：两者都会清 IRQ_STATE，事件会被对方吃掉。