API GUIDE / MSCALER / Middleware

G32S10 MSCALER Middleware 接口

Middleware 层接口:状态字段是 volatile,因为 frame-end 回调会在中断上下文读取它。

1. 公开数据类型

1.1 im_mscaler_state_t

状态含义
IM_MSCALER_STATE_RESET没有活动会话;需要先调用 im_mscaler_init()
IM_MSCALER_STATE_INITIALIZED会话已建立,尚未成功完成静态配置
IM_MSCALER_STATE_CONFIGURED静态配置已生效,硬件空闲,可以启动下一帧
IM_MSCALER_STATE_RUNNING已启动一帧,正在等待 frame-end

状态字段是 volatile,因为 frame-end 回调会在中断上下文读取它。

2. MSCALER MID 会话状态机

STATE  RESET
→
STATE  INITIALIZED
→
STATE  CONFIGURED
→
STATE  RUNNING

RESET → INITIALIZED · im_mscaler_init()

INITIALIZED → CONFIGURED · 首次 convert 配置成功

CONFIGURED → RUNNING · im_mscaler_convert()

RUNNING → CONFIGURED · frame-end + get_result

RUNNING → RESET · frame-end timeout

状态转换规则:

当前状态操作结果
RESETim_mscaler_init() 成功INITIALIZED
INITIALIZED首次 im_mscaler_convert() 配置成功CONFIGURED,随后进入 RUNNING
INITIALIZED配置失败保持 INITIALIZED
CONFIGUREDim_mscaler_convert()RUNNING,成功后回到 CONFIGURED
CONFIGURED参数变化后 im_mscaler_convert()重新配置后进入 RUNNING
RUNNINGframe-end 超时释放会话,回到 RESET
CONFIGURED / INITIALIZEDim_mscaler_deinit()释放会话,回到 RESET
RESETim_mscaler_deinit()返回 IM_OK,不做任何操作

3. API 详细说明

3.1 im_mscaler_set_clk_rate()

error_code_t im_mscaler_set_clk_rate(uint32_t rate_hz);

用于切换 MSCALER 模块时钟。父时钟固定为 MPLL,HAL 只调整分频比,分频结果 向上取整,因此实际频率不会高于请求值。当前控制器上限为 170 MHz。

参数说明
rate_hz == 0选择不超过控制器上限的最高频率
rate_hz > 0请求的模块时钟频率

需要恢复初始化后的默认时钟时,显式调用 im_mscaler_set_clk_rate(0U)。

调用约束:

状态行为
RESET返回 IM_ERR_NOT_READY
INITIALIZED允许设置
CONFIGURED允许设置,不需要重新做静态配置
RUNNING返回 IM_ERR_BUSY

频率超过控制器上限时 HAL 返回 IM_ERR_INVALID_PARAM,CPM 错误会原样 向上返回。

3.2 im_mscaler_get_clk_rate()

uint32_t im_mscaler_get_clk_rate(void);

读取 CPM 当前实际生效的 MSCALER 模块频率。该接口不检查会话状态;无法测量 时返回 0。因为内部也使用同一把 MID 互斥锁,一次正在执行的im_mscaler_convert() 可能使该调用等待到转换结束。

3.3 im_mscaler_get_state()

im_mscaler_state_t im_mscaler_get_state(void);

返回当前状态快照。该函数不加锁,适合诊断或超时后确认会话是否仍然存在; 返回值只代表读取瞬间的状态。

3.4 im_mscaler_deinit()

error_code_t im_mscaler_deinit(void);

释放 HAL、frame-end 回调、IRQ 和等待器资源,并把状态置为IM_MSCALER_STATE_RESET。

情况结果
没有活动会话IM_OK,空操作
有活动会话且空闲释放资源并返回 IM_OK
RUNNING返回 IM_ERR_BUSY

frame-end 超时后 MID 已经自动释放会话,此时再次调用im_mscaler_deinit() 是空操作。

4. 典型用法

4.1 连续帧

ret = im_mscaler_init(0U);
if (ret != IM_OK) {
    return ret;
}

for (frame_index = 0U; frame_index < frame_count; frame_index++) {
    msca.frame.src_y_addr = get_source(frame_index);
    msca.frame.src_uv_addr = NULL; /* NV12:由 HAL 按 stride * height 推导 */
    msca.frame.dst_y_addr = get_destination(frame_index);
    msca.frame.dst_uv_addr = NULL;

    ret = im_mscaler_convert(&msca);
    if (ret != IM_OK) {
        break;
    }
}

if (im_mscaler_get_state() != IM_MSCALER_STATE_RESET) {
    (void)im_mscaler_deinit();
}

只要 param 不变,MID 就不会在循环内重复配置几何和算法。

4.2 设置并确认模块时钟

uint32_t actual_hz;
error_code_t ret;

ret = im_mscaler_init(0U);
if (ret != IM_OK) {
    return ret;
}

ret = im_mscaler_set_clk_rate(150000000U);
if (ret == IM_OK) {
    actual_hz = im_mscaler_get_clk_rate();
    if (actual_hz == 0U) {
        /* CPM 读数不可用,或 stub 构建。 */
    }
}

时钟设置应在帧启动前完成。达到 CONFIGURED 后切换时钟不需要重新配置几何。