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 会话状态机
RESET → INITIALIZED · im_mscaler_init()
INITIALIZED → CONFIGURED · 首次 convert 配置成功
CONFIGURED → RUNNING · im_mscaler_convert()
RUNNING → CONFIGURED · frame-end + get_result
RUNNING → RESET · frame-end timeout
状态转换规则:
| 当前状态 | 操作 | 结果 |
|---|---|---|
RESET | im_mscaler_init() 成功 | INITIALIZED |
INITIALIZED | 首次 im_mscaler_convert() 配置成功 | CONFIGURED,随后进入 RUNNING |
INITIALIZED | 配置失败 | 保持 INITIALIZED |
CONFIGURED | im_mscaler_convert() | RUNNING,成功后回到 CONFIGURED |
CONFIGURED | 参数变化后 im_mscaler_convert() | 重新配置后进入 RUNNING |
RUNNING | frame-end 超时 | 释放会话,回到 RESET |
CONFIGURED / INITIALIZED | im_mscaler_deinit() | 释放会话,回到 RESET |
RESET | im_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 后切换时钟不需要重新配置几何。