API GUIDE / I2D / Middleware

G32S10 I2D Middleware 接口

Middleware 层接口:中间件是阻塞式的:im_i2d_process() 占用调用任务,直到这次变换完成、超时或被 取消才返回。

1. 分层关系与依赖

1.1 分层与调用方向

APPLICATION  Application / Example / Driver  业务代码、板级支持与示例入口
↓
MIDDLEWARE  MID I2D  状态机、IRQ 门控、等待、超时与 cache 维护
对外隐藏硬件复位和错误恢复细节
↓
HAL  HAL I2D  实例状态、参数校验、寄存器编程与中断分发
提供面向图像处理流程的语义接口
↓
LL  LL I2D  寄存器访问与字段级控制
↓
HARDWARE REGISTERS  I2D Registers · 0x13330000  实例地址、寄存器布局与位域定义
IRQ  IRQ_I2D / PLIC  硬件中断源与平台分发入口
DISPATCH  im_irq dispatcher  把中断路由到 MID 注册的处理函数
EVENT  MID event waiter  将硬件完成转换为等待线程可消费的事件

中断路径:IRQ_I2D → PLIC → im_irq → HAL IRQ handler → MID event waiter

1.2 各层职责

层负责不负责
应用 / 示例 / 测试提供源/目标 buffer,填写几何与格式;调用 im_i2d_process() 并处理返回码;buffer 的容量、对齐与生命周期寄存器、中断
im_i2d单实例设备对象;公共枚举到 HAL 配置的映射;IRQ_I2D 的申请/使能;事件位图与等待;超时;按 manage_cache 维护 cache分配内存、像素格式转换、缩放
HAL I2D参数校验、stride/平面大小推导、寄存器编程、启停、中断状态读取与清除cache 维护、SoC 中断申请
LL I2D寄存器字段级读写、shadow 更新、安全复位、启动/停止、时钟门控参数语义

中间件是阻塞式的:im_i2d_process() 占用调用任务,直到这次变换完成、超时或被 取消才返回。公共接口没有「启动后立即返回」的版本,也没有状态查询接口。

2. 构建配置与文件组织

2.1 Kconfig

code/middleware/i2d/Kconfig:

config MIDDLEWARE_I2D
    bool "I2D image conversion middleware"
    depends on DRIVER_I2D && OS_API
配置作用
CONFIG_DRIVER_I2D编译 I2D LL/HAL(code/drivers/g32s10/i2d/)
CONFIG_OS_API / CONFIG_OS任务/延时与 thread_waiter
CONFIG_DRIVER_IRQim_irq_* 注册与分发框架
CONFIG_DRIVER_PLICIRQ_I2D 的 PLIC 使能(G32S10 上默认随 core 打开)
CONFIG_MIDDLEWARE_I2D编译 im_i2d

2.2 CMake

code/middleware/i2d/CMakeLists.txt 在 CONFIG_MIDDLEWARE_I2D 打开时注册组件im_i2d:

if(CONFIG_MIDDLEWARE_I2D)
    imde_component_register(NAME im_i2d
        SRCS "${CMAKE_CURRENT_LIST_DIR}/src/im_i2d.c"
        INCLUDE_DIRS
        "${CMAKE_CURRENT_LIST_DIR}/include")
endif()

应用只需要 #include "im_i2d.h" 并打开 CONFIG_MIDDLEWARE_I2D。示例目录code/middleware/i2d/example/CMakeLists.txt 会在没有打开中间件时直接FATAL_ERROR,避免「配置忘开、构建却通过」。

2.3 文件职责

文件职责
include/im_i2d.h对外唯一头文件:枚举、两个结构体、六个函数
src/im_i2d.c全部实现,struct im_i2d 只在这里可见
example/main/main.c示例入口,只调用 i2d_single_transform_run()
example/main/i2d_single_transform.c示例本体:可改配置、缓冲、图案、一次变换、抽样校验
example/README.md示例的用户说明(构建、日志、改参数)
example/i2d_example_defconfig示例的 defconfig(打开 I2D 驱动与中间件)

3. 资源模型与公开类型

3.1 设备状态机

STATE  RESET
→
STATE  READY
→
STATE  RUNNING
→
STATE  STOPPING
→
STATE  TIMEOUT
→
STATE  ERROR

RESET → READY · im_i2d_init()

READY → RUNNING · im_i2d_process() begin + start

RUNNING → STOPPING · finish() 屏蔽中断并收尾

STOPPING → READY · IM_OK / 取消

STOPPING → TIMEOUT · 等待或硬件超时

STOPPING → ERROR · outstanding 或硬件错误

READY / TIMEOUT / ERROR → RESET · im_i2d_deinit()

状态含义可继续做的操作
RESET未初始化或已反初始化im_i2d_init();im_i2d_deinit() 返回 IM_OK;im_i2d_process() 返回 IM_ERR_NOT_READY;im_i2d_cancel() 返回 last_status
READY空闲,可以启动下一次变换im_i2d_process()、im_i2d_deinit();im_i2d_cancel() 返回 last_status
RUNNING已启动,等待完成事件等待由 im_i2d_process() 内部完成;另一任务可 im_i2d_cancel()
STOPPINGfinish 的中间态,仅在函数内部短暂出现应用不应观察到
TIMEOUT上一次变换超时只能 im_i2d_deinit() 后重新初始化
ERROR上一次变换遇到硬件错误或缺少完成事件只能 im_i2d_deinit() 后重新初始化

关键点:

  • TIMEOUT/ERROR 是终态。 此时再调用 im_i2d_process(),begin 阶段会因状态 不是 READY 而返回 IM_ERR_BUSY。恢复方式是 im_i2d_deinit() + im_i2d_init()。

  • begin 阶段的参数/布局错误、start 阶段的 HAL 错误都不会进入 RUNNING,状态保持READY,修正参数或降低负载后可以直接重试。

  • 正常完成或 im_i2d_cancel() 会把状态送回 READY。

3.2 缓冲区所有权

对象谁分配谁释放谁维护 cache
im_i2d_t 设备对象中间件(静态)中间件不涉及
源 buffer调用方调用方默认中间件(manage_cache = true)
目标 buffer调用方调用方默认中间件

中间件不持有 buffer,im_i2d_process() 返回后不会再用它们(除了 finish 阶段对目标 做一次 invalidate)。因此调用方可以在返回后立刻读取或释放目标 buffer。

4. 接口规范

4.1 im_i2d_cancel

error_code_t im_i2d_cancel(im_i2d_t *dev);
  • 只在 RUNNING 时生效:置 STOPPING,走 finish,停止硬件并唤醒等待者;正在阻塞的im_i2d_process() 返回 IM_ERR_INVALID_STATE。

  • 没有运行中的变换时,返回 last_status,不做任何事。

典型用法是另一个任务中止阻塞中的变换。取消后状态回 READY,可以继续启动下一帧。 不要用「cancel + 立刻 deinit」代替正常等待:取消路径同样会停止硬件并 invalidate 目标, 但应用拿不到完成的图像。

4.2 对外接口速查

函数说明上下文
im_i2d_config_struct_init()填默认配置任意
im_i2d_transform_default()填默认变换(NV12 / 0°)任意
im_i2d_init()初始化模块、申请 IRQ、初始化 HAL任务/初始化上下文
im_i2d_process()启动一次变换并阻塞等待完成任务上下文
im_i2d_cancel()中止正在运行的变换任务上下文
im_i2d_deinit()停止并释放 IRQ/HAL/时钟任务/关闭上下文

需要并发时,由一个任务串行执行变换,另一个任务用 im_i2d_cancel() 中止。

5. 行为约束与实现说明

5.1 连续处理多帧

static error_code_t i2d_run_frames(im_i2d_t **dev,
                                   const im_i2d_config_t *cfg,
                                   im_i2d_transform_t *t,
                                   uint32_t count)
{
    error_code_t ret = IM_OK;

    for (uint32_t i = 0U; i < count; i++) {
        ret = im_i2d_process(*dev, t, 500U);
        if (ret != IM_OK) {
            /* 只有 READY 状态能启动下一次变换:TIMEOUT/ERROR 必须先重开会话。 */
            if ((ret == IM_ERR_TIMEOUT) || (ret == IM_ERR_HARDWARE) ||
                (ret == IM_ERR_NOT_READY)) {
                (void)im_i2d_deinit(*dev);
                ret = im_i2d_init(dev, cfg);
                if (ret != IM_OK) {
                    return ret;
                }
            } else {
                return ret;
            }
        }
        /* 正常路径下目标 buffer 已经可以直接读(cache 已 invalidate)。 */
    }
    return IM_OK;
}

两帧之间可以改 t 的地址、尺寸、格式、旋转;下一次 begin 会重新解析布局。

6. 典型用法:从零开始

本节假设你手上有一块能跑 SDK 的板子,想用 im_i2d 做「内存里的图 → 旋转/镜像 → 内存里的图」。整个过程是固定的五步。

6.1 第一步:打开设备

#include "im_i2d.h"

static im_i2d_t *s_i2d;

static error_code_t open_i2d(void)
{
    im_i2d_config_t cfg;

    im_i2d_config_struct_init(&cfg);   /* 默认 400 ms、manage_cache = true */
    return im_i2d_init(&s_i2d, &cfg);
}
  • 整个系统只开一次;再次调用会返回 IM_ERR_BUSY。

  • 打开后 IRQ_I2D 与 I2D 时钟都归中间件管,应用不要再申请/关闭。

  • 普通 cacheable 内存不要关 manage_cache。

6.2 第四步:填变换对象并执行

im_i2d_transform_t t;
error_code_t ret;

im_i2d_transform_default(&t);       /* 先给所有字段一个合法默认值 */
t.src.y        = src;
t.src.stride_y = layout.src_y_stride;   /* 源行字节数;相机帧来自 line_length */
t.dst.y        = dst;
t.dst.stride_y = layout.dst_y_stride;   /* 输出行字节数,旋转后可能不同 */
t.width        = 640U;                  /* 源尺寸 */
t.height       = 480U;
t.format       = IM_I2D_FORMAT_YUV422;
t.rotate       = IM_I2D_ROTATE_90;      /* 顺时针 */
t.horizontal_mirror = false;
t.vertical_flip     = false;

ret = im_i2d_process(s_i2d, &t, 500U);
if (ret != IM_OK) {
    /* 按 §5.6 处理:参数错修正后重试;超时/硬件错 deinit + init */
}
/* 到这里 dst 里就是旋转后的图像,cache 已被中间件 invalidate 过 */

打包格式(RAW8 / RGB565 / ARGB8888 / YUV422)的 src.uv / dst.uv 保持默认的NULL。NV12 也可以用连续布局(uv = NULL),此时 UV 紧跟在对齐后的 Y 平面之后, 地址由 HAL 推导。

6.3 第五步:关闭

(void)im_i2d_deinit(s_i2d);   /* 停硬件、释放 IRQ、关时钟 */
s_i2d = NULL;

发生超时/硬件错误后同样走这一步,再重新 im_i2d_init()。

6.4 连续处理多帧

同一 dev 可以反复调用 im_i2d_process(),帧间不需要 deinit/init。见 §6.5 的循环 写法。需要注意:

  • 只有 IM_ERR_TIMEOUT / IM_ERR_HARDWARE / IM_ERR_NOT_READY 需要重开会话;IM_ERR_INVALID_PARAM 直接修正参数重试即可。

  • 每帧的 transform 可以不同(分辨率、旋转都能变),但同一时刻只能有一次变换。

  • 双缓冲:目标 buffer 在 im_i2d_process() 返回后就可以交给下游;下游还在读的时候, 下一帧要写到另一块 buffer,否则会撕裂。

6.5 把结果交给下游

I2D 只负责写内存,之后的目标 buffer 怎么送出去由下游决定:

下游要注意的
JPEGE只接受 NV12 / YUV422(YUYV) / 灰度(Y)等,具体以 im_jpege 的格式枚举为准;宽高填输出尺寸;stride 要等于 宽 × bpp,否则编码器会按连续布局读错
显示(DPU/framebuffer)宽高、stride、像素格式必须与显示配置一致;RGB565/ARGB8888 是常见选择
USB/UVC同 JPEGE;另外要 flush_dcache_force()(或等价操作)再交给 USB DMA
另一个 I2D直接传目标 buffer 即可,中间件会 clean 源
存文件按 stride × 行数 写;若 stride 大于 宽 × bpp,文件里会带行尾填充

如果目标 stride 比 输出宽 × bpp 大(例如为了对齐),下游必须知道这个 stride;不支持 自定义 stride 的下游(例如某些 JPEG 编码配置)就要让 I2D 输出紧凑布局——把dst.stride_y 设为 0 或 输出宽 × bpp。

7. 示例程序解读

示例位于 code/middleware/i2d/example/。它把一张 1280x1280 ARGB8888 的图像顺时针 旋转 90°,抽样校验后打印结论,全程不接相机、不读 SD 卡、不显示。它是「最小可运行」 的 im_i2d 用法,也是 §7 那五步的完整落地。

7.1 内存账

示例同时持有源、目标两帧,参考板默认堆约 15.8 MB(其它板以实际堆大小为准):

配置单帧两帧结果
1280x1280 ARGB8888(默认)6,553,60013.1 MB放得下
640x480 YUV422614,4001.2 MB放得下
1920x1080 NV123,125,7606.2 MB放得下
1920x1080 ARGB88888,294,40016.6 MB大概率 IM_ERR_NO_MEMORY
3840x2160 NV1212,441,60024.9 MBIM_ERR_NO_MEMORY
3840x2160 ARGB888833,177,60066 MBIM_ERR_NO_MEMORY

分配失败是 heap 的限制,不是 I2D 的限制;示例会打印 alloc ... failed, ret=-... 后退出。

8. 把 sensor 画面旋转

真实工程里更常见的需求是:相机采到一帧,方向不对,转正后再送去编码/显示/USB。参考 用例是 test/g32s10/module/vic/slt_103/gc0308_i2d_jpeg_usb/(位于独立的 test/仓库)。它把 GC0308 的 640x480 YUV422 画面顺时针转 90°,编码成 MJPEG,通过 UVC 送给 PC;主机看到的是 480x640 的竖图。

8.1 旋转函数

用例里只有一个薄封装,核心就是填 im_i2d_transform_t:

static error_code_t gc0308_i2d_jpeg_usb_rotate_90cw(im_i2d_t *dev,
                                                   const void *src,
                                                   uint32_t src_stride,
                                                   void *dst,
                                                   uint32_t dst_stride,
                                                   uint32_t width,
                                                   uint32_t height)
{
    im_i2d_transform_t transform;

    im_i2d_transform_default(&transform);
    transform.src.y        = (void *)src;
    transform.src.uv       = NULL;          /* packed 格式必须为 NULL */
    transform.src.stride_y = src_stride;
    transform.dst.y        = dst;
    transform.dst.uv       = NULL;
    transform.dst.stride_y = dst_stride;
    transform.width        = width;         /* 源尺寸;输出尺寸由 HAL 按 rotate 推出 */
    transform.height       = height;
    transform.format       = IM_I2D_FORMAT_YUV422;
    transform.rotate       = IM_I2D_ROTATE_90;   /* 顺时针 */
    transform.horizontal_mirror = false;
    transform.vertical_flip     = false;

    return im_i2d_process(dev, &transform, GC0308_I2D_JPEG_USB_ROTATE_TIMEOUT_MS);
}

几点值得照抄:

  • im_i2d_transform_default() 先清零,保证 uv/stride_uv 等未用字段是合法值;

  • width/height 是源尺寸,旋转后尺寸不填;

  • 打包 YUV422 的 uv = NULL;

  • 超时 500 ms(ROTATE_TIMEOUT_MS),比默认 400 ms 略宽,给总线拥塞留余量;

  • cache 用默认策略,函数里没有任何 im_cache_* 调用。

8.2 迁移到你自己的工程:检查清单

  1. 先确认源格式:YUV422/NV12/RAW8……决定 uv 是否为 NULL、每像素几字节。camera_get_status() 里的 format/line_length 是唯一可信来源。

  2. 源 stride 用生产者给的值(相机的 line_length、解码器的行宽),不要用width × bpp 硬算。

  3. 目标 stride 按输出几何算:90°/270° 时输出宽 = 源高。

  4. 目标 buffer 至少是 layout 的 dst_buffer_size,并 64 字节对齐(后面还要接 JPEGE 时按它的 256 字节要求来)。

  5. cache:保持 manage_cache = true。如果源 buffer 由另一个 DMA 引擎写、且你 在外层已经 clean 过,中间件再 clean 一次是安全的。不要在 im_i2d_process() 返回后 再对目标做 clean——目标此时只有 DMA 写入的新数据,clean 会把 CPU 里的旧脏行 写回、盖掉结果;多一次 invalidate 倒不会出错,只是多余。

  6. 超时:默认 400 ms;大分辨率或总线同时被 IPU/USB 占用时给到 500~1000 ms。

  7. 失败处理:单帧失败计数并丢帧;IM_ERR_TIMEOUT/IM_ERR_HARDWARE 连续出现时 重开会话(deinit + init)。

  8. 下游尺寸:编码器/显示配置必须用输出尺寸和输出 stride,而不是源尺寸。

  9. 方向验证:第一次接入时跑一次 §9.5 的图案自测,确认顺时针/逆时针符合预期。

8.3 sensor 旋转特有现象

现象常见原因排查
画面转了但方向反ROTATE_90 是顺时针;想要逆时针用 ROTATE_270用图案自测确认
画面上下颠倒相机装反或需要 vertical_flip叠加 vertical_flip,不是换 rotate
红蓝对调YUV 字节序(YVYU/UYVY)由上游决定查相机中间件的 dump_data_order,不是 I2D
每行错位/斜条纹dst_stride 用了源 stride用输出宽 × bpp
输出整片 0 或旧数据目标 buffer 太小、cache 未 invalidate、I2D 没启动看自测的「目标非零」计数;检查返回码
第一帧正确、后续花目标 buffer 被下游同时复用双缓冲,或等下游读完再写
偶发 IM_ERR_TIMEOUT总线被 IPU/USB 抢、分辨率大放宽超时;必要时调 outstanding_limit

9. 调试与验证

9.1 可观测性

中间件本身没有任何日志,也没有状态查询接口。定位问题只能依靠:

  • im_i2d_process() / im_i2d_init() 的返回码(§5.6);

  • 应用自己在调用前后打印的几何、stride、buffer 地址与耗时;

  • 目标 buffer 的内容(图案自测、抽样比对);

  • 直接读 I2D 寄存器(VERSION、IRQ_STATE、IRQ_MASK、OUTSTANDING)。

9.2 上板诊断顺序

  1. 先跑 register,确认 I2D 寄存器窗口可访问;

  2. 再跑 code/middleware/i2d/example,确认单帧旋转与抽样校验通过;

  3. 再跑 function,确认所有格式与几何组合;

  4. 出现 IM_ERR_TIMEOUT/IM_ERR_HARDWARE 时,先降分辨率、降 outstanding 压力, 排除总线带宽因素;

  5. 出现数据不一致时,优先检查 stride、NV12 的 UV 偏移、旋转后的 buffer 尺寸和 cache 维护;

  6. 需要判断是否是总线拥塞时,用 test/g32s10/module/i2d/outstanding 的扫描方法, 而不是继续怀疑几何。