SYS（系统管理）接口说明文档
| 文档版本 | V1.1 |
|---|---|
| 修订日期 | 2026-08-21 |
| 代码基线 | hi_aiot_solution 8.18 |
| 对应头文件 | components/media/pipeline/include/hi_mapi_sys.h |
| 类型定义 | components/media/pipeline/include/hi_mapi_sys.h、components/media/pipeline/include/hi_mapi_comm_define.h、include/adapt/*_adapt_define.h |
| 适用模块 | SYS / HI3516CV610 |
1 概述
SYS 模块负责 pipeline 的全局初始化、媒体子系统（VCAP/VPSS/VENC/ACAP/AENC/AO/DISP）的启动编排、MMZ 物理内存与 VB 视频块分配跟踪，以及模块之间的软/硬绑定维护。任何媒体操作之前必须先调用 hi_mapi_sys_init 与 hi_mapi_sys_init_media。
2 接口总览
| 编号 | 接口 | 功能概述 |
|---|---|---|
| 1 | hi_mapi_sys_init |
初始化系统模块，包含 LiteOS 与 Linux 之间的消息通道初始化；必须作为 MAPI 的第一个入口调用，HuaweiLite 与 Linux 双端的应用均需要调用。 |
| 2 | hi_mapi_sys_deinit |
反初始化系统模块，释放内部 bind 关系并调用 HAL 层 deinit。 |
| 3 | hi_mapi_sys_get_default_media_attr |
根据基础媒体属性 base_attr 推导并填充一个可直接使用的默认 media_attr（含 VI/VPSS 工作模式、VB 配置、VENC/ISP/Audio 默认参数），供 hi_mapi_sys_init_media 使用。 |
| 4 | hi_mapi_sys_init_media |
初始化媒体子系统，依次创建 VB 池、视频模块（VCAP/ISP/VPSS/VENC/DISP）、音频模块（ACAP/AENC/AO）、VB 分配跟踪上下文与 soft_bind 轮询线程。必须在 hi_mapi_sys_init 之后、任何模块接口（如 hi_mapi_vcap_*、hi_mapi_vpss_*、hi_mapi_venc_*、hi_mapi_ao_*）之前调用。 |
| 5 | hi_mapi_sys_deinit_media |
反初始化媒体子系统，依次关闭 VENC、音频、VPSS、DISP、VCAP、VB 分配跟踪上下文、SYS media，并停止 soft_bind 轮询线程。 |
| 6 | hi_mapi_sys_alloc_buffer |
从 MMZ 分配一段物理连续内存，返回物理地址与虚拟地址。 |
| 7 | hi_mapi_sys_free_buffer |
释放由 hi_mapi_sys_alloc_buffer 分配的 MMZ 缓冲区。 |
| 8 | hi_mapi_sys_flush_cache |
对 cache 型 MMZ 缓冲区执行 cache 刷新（clean + invalidate），保证 CPU 与设备看到的数据一致。 |
| 9 | hi_mapi_sys_get_video_block |
从 VB 池申请一个视频块，返回其物理地址与 mmap 后的虚拟地址；与 hi_mapi_sys_release_video_block 配对使用。 |
| 10 | hi_mapi_sys_release_video_block |
释放由 hi_mapi_sys_get_video_block 申请的视频块，归还 VB 池。 |
| 11 | hi_mapi_sys_register_font_attr |
注册 OSD 字体库属性，包括字号（宽/高）与字符点阵回调；同一进程只能注册一次。 |
| 12 | hi_mapi_sys_bind |
将源通道（src）绑定到目标通道（dst）。内部维护一个 bind 表，同一 (src, dst) 重复绑定直接返回成功且不派发到底层 SDK；每个 dst 只能绑定一个 src。 |
| 13 | hi_mapi_sys_unbind |
解绑之前由 hi_mapi_sys_bind 建立的 (src, dst) 绑定。若该对未在内部 bind 表中，直接返回成功且不派发到底层 SDK。 |
3 API 参考
1 hi_mapi_sys_init
【描述】 初始化系统模块，包含 LiteOS 与 Linux 之间的消息通道初始化；必须作为 MAPI 的第一个入口调用，HuaweiLite 与 Linux 双端的应用均需要调用。
【语法】
【参数】 无。
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
成功。 |
非0 |
失败，其值为错误码。 |
【需求】
- 头文件：
hi_mapi_sys.h - 库文件：
libhi_mapi.so
【注意】
- 必须最先调用；
hi_mapi_sys_bind/hi_mapi_sys_unbind会在本接口内初始化内部 bind 关系表，调用失败则返回对应错误码。 - 与
hi_mapi_sys_deinit配对使用。
【举例】 无
【相关主题】
hi_mapi_sys_deinit、hi_mapi_sys_init_media
2 hi_mapi_sys_deinit
【描述】 反初始化系统模块，释放内部 bind 关系表并调用 HAL 层 deinit。
【语法】
【参数】 无。
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
成功。 |
非0 |
失败，其值为错误码。 |
【需求】
- 头文件：
hi_mapi_sys.h - 库文件：
libhi_mapi.so
【注意】
- 必须先调用
hi_mapi_sys_deinit_media释放媒体资源，再调用本接口。
【举例】 无
【相关主题】
hi_mapi_sys_init
3 hi_mapi_sys_get_default_media_attr
【描述】
根据基础媒体属性 base_attr 推导并填充一个可直接使用的默认 media_attr（含 VI/VPSS 工作模式、VB 配置、VENC/ISP/Audio 默认参数），供 hi_mapi_sys_init_media 使用。
【语法】
td_s32 hi_mapi_sys_get_default_media_attr(const hi_mapi_sys_base_attr *base_attr, hi_mapi_sys_media_attr *media_attr);
【参数】
| 参数名称 | 输入/输出 | 类型 | 描述 |
|---|---|---|---|
base_attr |
输入 | const hi_mapi_sys_base_attr * |
基础属性指针，不能为 NULL。成员描述见下表。 |
media_attr |
输出 | hi_mapi_sys_media_attr * |
输出的媒体属性，不能为 NULL。 |
hi_mapi_sys_base_attr 成员：
| 成员名称 | 描述 |
|---|---|
vcap_dev_num |
VCAP 设备数，HI3516CV610 上取值范围 [0, 2]。 |
vcap_reso_size[vcap_dev_num] |
每个 VCAP 设备 sensor 输出分辨率（宽×高）。 |
vcap_online[vcap_dev_num] |
每个 VCAP 设备是否 online 工作；多设备时必须全部为 TD_FALSE。 |
raw_bit_width |
RAW 数据位宽（8/10/12/14/16）。 |
is_wdr |
是否启用 WDR。 |
vpss_grp_num |
VPSS 组数，取值范围 [0, 6]（HI3516CV610）。 |
vpss_chn_num |
每组 VPSS 的通道数。 |
vpss_reso_size[vpss_grp_num][vpss_chn_num] |
每路 VPSS 通道输出分辨率。 |
vpss_online[vpss_grp_num] |
每路 VPSS 是否 online 工作。 |
vpss_wrap_en[vpss_grp_num] |
每路 VPSS 通道 0 是否启用卷绕（wrap）省内存模式。 |
vi_wrap_en[vcap_dev_num] |
每路 VI pipe 是否启用卷绕；双设备时两路必须相同。 |
sensor_full_lines_std[vcap_dev_num] |
sensor 标准帧总行数，用于 wrap buf_line 计算。 |
frame_rate[vcap_dev_num] |
sensor 帧率。 |
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
成功。 |
非0 |
失败，其值为错误码。 |
HI_MAPI_SYS_ENULL_PTR |
base_attr 或 media_attr 为 NULL。 |
HI_MAPI_SYS_EILLEGAL_PARAM |
vcap_dev_num > 2 或 vpss_grp_num > 6，或 online/offline 组合不合法（双设备必须 offline；VCAP online + VPSS online 仅允许 vpss_grp_num == 1；若任一 vpss_online[i] 为真，则所有 vpss_online[i] 必须为真）。 |
【需求】
- 头文件：
hi_mapi_sys.h - 库文件：
libhi_mapi.so
【注意】
- 应在
hi_mapi_sys_init之后、hi_mapi_sys_init_media之前调用。 - 双输入场景（
vcap_dev_num > 1）下所有vi_wrap_en[]必须相同，否则返回HI_MAPI_SYS_EILLEGAL_PARAM。
【举例】 无
【相关主题】
hi_mapi_sys_init_media、hi_mapi_sys_base_attr、hi_mapi_sys_media_attr
4 hi_mapi_sys_init_media
【描述】
初始化媒体子系统，依次创建 VB 池、视频模块（VCAP/ISP/VPSS/VENC/DISP）、音频模块（ACAP/AENC/AO）、VB 分配跟踪上下文与 soft_bind 轮询线程。必须在 hi_mapi_sys_init 之后、任何模块接口（如 hi_mapi_vcap_*、hi_mapi_vpss_*、hi_mapi_venc_*、hi_mapi_ao_*）之前调用。
【语法】
【参数】
| 参数名称 | 输入/输出 | 类型 | 描述 |
|---|---|---|---|
media_attr |
输入 | const hi_mapi_sys_media_attr * |
媒体属性指针，不能为 NULL；通常由 hi_mapi_sys_get_default_media_attr 填充。 |
hi_mapi_sys_media_attr 成员：
| 成员名称 | 描述 |
|---|---|
media_config |
媒体配置（vi_vpss_mode 与 vb_config）。 |
venc_mod_para |
VENC 低功耗模式参数（默认各 TD_TRUE）。 |
isp_mod_para |
ISP 工作模式参数（param_valid=TD_FALSE 时跳过 ISP 模式配置）。 |
audio_mod_para |
音频配置（audio_bypass=TD_TRUE 则跳过音频初始化）。 |
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
成功。 |
非0 |
失败，其值为错误码。 |
HI_MAPI_SYS_ENULL_PTR |
media_attr 为 NULL。 |
TD_SUCCESS（重复调用） |
若媒体已初始化，直接返回成功（幂等）。 |
HI_MAPI_SYS_ENOTREADY |
soft_bind 互斥量初始化失败。 |
HI_MAPI_SYS_EBUSY |
soft_bind 轮询线程创建失败。 |
【需求】
- 头文件：
hi_mapi_sys.h - 库文件：
libhi_mapi.so
【注意】
- 必须在
hi_mapi_sys_init之后调用。 - 失败时会自动回滚已初始化的音频/视频/SYS media 资源。
【举例】 无
【相关主题】
hi_mapi_sys_deinit_media、hi_mapi_sys_get_default_media_attr
5 hi_mapi_sys_deinit_media
【描述】 反初始化媒体子系统，依次关闭 VENC、音频、VPSS、DISP、VCAP、VB 分配跟踪上下文、SYS media，并停止 soft_bind 轮询线程。
【语法】
【参数】 无。
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
成功。 |
非0 |
失败，其值为错误码。 |
TD_SUCCESS（未初始化） |
若媒体未初始化，直接返回成功（幂等）。 |
HI_MAPI_SYS_EBUSY |
任意子模块 deinit 返回失败（best-effort，不会中断流程）。 |
【需求】
- 头文件：
hi_mapi_sys.h - 库文件：
libhi_mapi.so
【注意】
- 调用前应先
hi_mapi_sys_unbind所有绑定并停止所有 VCAP/VPSS/VENC/ACAP/AENC/AO 设备。 - 必须与
hi_mapi_sys_init_media配对。
【举例】 无
【相关主题】
hi_mapi_sys_init_media
6 hi_mapi_sys_alloc_buffer
【描述】 从 MMZ 分配一段物理连续内存，返回物理地址与虚拟地址。
【语法】
td_s32 hi_mapi_sys_alloc_buffer(td_u64 *phy_addr, td_void **virt_addr, td_u32 buf_len, const td_char *buf_name,
td_bool is_cache);
【参数】
| 参数名称 | 输入/输出 | 类型 | 描述 |
|---|---|---|---|
phy_addr |
输出 | td_u64 * |
输出物理地址，不能为 NULL。 |
virt_addr |
输出 | td_void ** |
输出虚拟地址，不能为 NULL。 |
buf_len |
输入 | td_u32 |
缓冲区长度，单位字节，必须 > 0。 |
buf_name |
输入 | const td_char * |
缓冲区名称（便于调试），不能为 NULL。 |
is_cache |
输入 | td_bool |
是否分配 cache 型内存；TD_TRUE 表示 cache，TD_FALSE 表示 non-cache。 |
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
成功。 |
非0 |
失败，其值为错误码。 |
HI_MAPI_SYS_ENULL_PTR |
phy_addr/virt_addr/buf_name 任一为 NULL。 |
HI_MAPI_SYS_ENOTREADY |
媒体未初始化（hi_mapi_sys_init_media 未调用）。 |
HI_MAPI_SYS_EILLEGAL_PARAM |
buf_len == 0。 |
【需求】
- 头文件：
hi_mapi_sys.h - 库文件：
libhi_mapi.so
【注意】
- 必须与
hi_mapi_sys_free_buffer配对。 - 使用 cache 型内存时需配合
hi_mapi_sys_flush_cache保证一致性。
【举例】 无
【相关主题】
hi_mapi_sys_free_buffer、hi_mapi_sys_flush_cache
7 hi_mapi_sys_free_buffer
【描述】
释放由 hi_mapi_sys_alloc_buffer 分配的 MMZ 缓冲区。
【语法】
【参数】
| 参数名称 | 输入/输出 | 类型 | 描述 |
|---|---|---|---|
phy_addr |
输入 | td_u64 |
缓冲区的物理地址。 |
virt_addr |
输入 | td_void * |
缓冲区的虚拟地址，不能为 NULL。 |
buf_len |
输入 | td_u32 |
缓冲区长度（当前版本未使用，保留参数）。 |
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
成功。 |
非0 |
失败，其值为错误码。 |
HI_MAPI_SYS_ENULL_PTR |
virt_addr 为 NULL。 |
HI_MAPI_SYS_ENOTREADY |
媒体未初始化。 |
【需求】
- 头文件：
hi_mapi_sys.h - 库文件：
libhi_mapi.so
【注意】
- 必须与
hi_mapi_sys_alloc_buffer成对使用，物理/虚拟地址须一致。
【举例】 无
【相关主题】
hi_mapi_sys_alloc_buffer
8 hi_mapi_sys_flush_cache
【描述】 对 cache 型 MMZ 缓冲区执行 cache 刷新（clean + invalidate），保证 CPU 与设备看到的数据一致。
【语法】
【参数】
| 参数名称 | 输入/输出 | 类型 | 描述 |
|---|---|---|---|
phy_addr |
输入 | td_u64 |
缓冲区的物理地址。 |
virt_addr |
输入 | td_void * |
缓冲区的虚拟地址，不能为 NULL。 |
buf_len |
输入 | td_u32 |
刷新长度，单位字节。 |
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
成功。 |
非0 |
失败，其值为错误码。 |
HI_MAPI_SYS_ENULL_PTR |
virt_addr 为 NULL。 |
HI_MAPI_SYS_ENOTREADY |
媒体未初始化。 |
【需求】
- 头文件：
hi_mapi_sys.h - 库文件：
libhi_mapi.so
【注意】
- 仅对
is_cache=TD_TRUE分配的缓冲区有意义。
【举例】 无
【相关主题】
hi_mapi_sys_alloc_buffer
9 hi_mapi_sys_get_video_block
【描述】
从 VB 池申请一个视频块，返回其物理地址与 mmap 后的虚拟地址；与 hi_mapi_sys_release_video_block 配对使用。
【语法】
td_s32 hi_mapi_sys_get_video_block(td_handle *pool_hdl, td_u64 *phy_addr, td_void **vir_addr, td_u64 blk_size,
const td_char *mmz_name);
【参数】
| 参数名称 | 输入/输出 | 类型 | 描述 |
|---|---|---|---|
pool_hdl |
输入 | td_handle * |
VB 池句柄指针，不能为 NULL（一般取已创建池句柄的地址）。 |
phy_addr |
输出 | td_u64 * |
视频块物理地址，不能为 NULL。 |
vir_addr |
输出 | td_void ** |
视频块虚拟地址，不能为 NULL。 |
blk_size |
输入 | td_u64 |
块大小，单位字节；必须不超过 td_u32 最大值。 |
mmz_name |
输入 | const td_char * |
所在 DDR 的 MMZ 名字；可为 NULL 表示使用默认 MMZ。 |
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
成功。 |
非0 |
失败，其值为错误码。 |
HI_MAPI_SYS_ENULL_PTR |
pool_hdl/phy_addr/vir_addr 任一为 NULL。 |
HI_MAPI_SYS_ENOTREADY |
媒体未初始化。 |
HI_MAPI_SYS_EILLEGAL_PARAM |
blk_size 超过上限，或 mmap 失败，或分配记录写入失败。 |
HI_MAPI_SYS_ENOMEM |
分配记录节点内存申请失败。 |
【需求】
- 头文件：
hi_mapi_sys.h - 库文件：
libhi_mapi.so
【注意】
- 必须与
hi_mapi_sys_release_video_block配对，phy_addr/vir_addr必须一致。 hi_mapi_sys_deinit_media会强制回收未释放的残留块。
【举例】 无
【相关主题】
hi_mapi_sys_release_video_block
10 hi_mapi_sys_release_video_block
【描述】
释放由 hi_mapi_sys_get_video_block 申请的视频块，归还 VB 池；与 hi_mapi_sys_get_video_block 配对使用。
【语法】
【参数】
| 参数名称 | 输入/输出 | 类型 | 描述 |
|---|---|---|---|
phy_addr |
输入 | td_u64 |
视频块物理地址，必须非 0 且为当前持有的（get 后尚未 release）。 |
vir_addr |
输入 | td_void * |
视频块虚拟地址，必须与 get 时返回的一致；不能为 NULL。 |
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
成功。 |
非0 |
失败，其值为错误码。 |
HI_MAPI_SYS_ENULL_PTR |
vir_addr 为 NULL。 |
HI_MAPI_SYS_ENOTREADY |
媒体未初始化。 |
HI_MAPI_SYS_EILLEGAL_PARAM |
phy_addr == 0，或该地址未被跟踪（未 get 或已 release），或 vir_addr 与记录不符。 |
【需求】
- 头文件：
hi_mapi_sys.h - 库文件：
libhi_mapi.so
【注意】
- 不得重复释放同一
phy_addr。
【举例】 无
【相关主题】
hi_mapi_sys_get_video_block
11 hi_mapi_sys_register_font_attr
【描述】 注册 OSD 字体库属性，包括字号（宽/高）与字符点阵回调；同一进程只能注册一次。
【语法】
【参数】
| 参数名称 | 输入/输出 | 类型 | 描述 |
|---|---|---|---|
font_attr |
输入 | const hi_mapi_sys_font_attr * |
字体属性指针，不能为 NULL。 |
hi_mapi_sys_font_attr 成员：
| 成员名称 | 描述 |
|---|---|
font_width |
字体宽度，单位像素，必须 > 0 且为 MAPI_FONT_BYTE_BITS（8）的整数倍。 |
font_height |
字体高度，单位像素，必须 > 0。 |
get_font_mod_cb |
字符点阵获取回调，不能为 NULL。 |
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
成功。 |
非0 |
失败，其值为错误码。 |
HI_MAPI_SYS_ENULL_PTR |
font_attr 为 NULL，或 font_attr->get_font_mod_cb 为 NULL。 |
HI_MAPI_SYS_EILLEGAL_PARAM |
font_width 或 font_height 为 0，或 font_width 不是 8 的倍数。 |
HI_MAPI_SYS_ENOT_PERM |
已重复注册（每个进程仅可注册一次）。 |
【需求】
- 头文件：
hi_mapi_sys.h - 库文件：
libhi_mapi.so
【注意】
- 必须在 OSD 使用前完成注册，重复调用返回
HI_MAPI_SYS_ENOT_PERM。
【举例】 无
【相关主题】
hi_mapi_sys_font_attr
12 hi_mapi_sys_bind
【描述】
将源通道（src）绑定到目标通道（dst）。内部维护一个 bind 表，同一 (src, dst) 重复绑定直接返回成功且不派发到底层 SDK；每个 dst 只能绑定一个 src。
【语法】
【参数】
| 参数名称 | 输入/输出 | 类型 | 描述 |
|---|---|---|---|
src_chn |
输入 | const hi_mapi_mpp_chn * |
源通道描述符，不能为 NULL。 |
dst_chn |
输入 | const hi_mapi_mpp_chn * |
目标通道描述符，不能为 NULL。 |
hi_mapi_mpp_chn 成员：
| 成员名称 | 描述 |
|---|---|
mod_id |
模块 ID，必须在 bind 白名单内：HI_MAPI_MOD_VCAP、HI_MAPI_MOD_VPSS、HI_MAPI_MOD_VENC、HI_MAPI_MOD_VDEC、HI_MAPI_MOD_DISP、HI_MAPI_MOD_ACAP、HI_MAPI_MOD_AENC、HI_MAPI_MOD_ADEC、HI_MAPI_MOD_AO。 |
dev_id |
设备 ID，必须 >= 0。 |
chn_id |
通道 ID，必须 >= 0。 |
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
成功（含重复绑定）。 |
非0 |
失败，其值为错误码。 |
HI_MAPI_SYS_ENOTREADY |
内部 bind 上下文未初始化（未调用 hi_mapi_sys_init）。 |
HI_MAPI_SYS_ENULL_PTR |
src_chn 或 dst_chn 为 NULL。 |
HI_MAPI_SYS_EILLEGAL_PARAM |
通道 mod_id 不在白名单，或 dev_id < 0/chn_id < 0，或 src == dst。 |
HI_MAPI_SYS_EBUSY |
dst_chn 已被其它 src 绑定，或 soft bind 条目数已满（最多 2 个 DISP 软绑定），或 bind 表已满（最多 64 个）。 |
【需求】
- 头文件：
hi_mapi_sys.h - 库文件：
libhi_mapi.so
【注意】
- 目标为
HI_MAPI_MOD_DISP的绑定走软绑定路径：内部启动一个轮询线程周期从源取帧并下发到 DISP。 - 与
hi_mapi_sys_unbind配对使用。
【举例】
hi_mapi_mpp_chn src, dst;
src.mod_id = HI_MAPI_MOD_VCAP; src.dev_id = 0; src.chn_id = 0;
dst.mod_id = HI_MAPI_MOD_VPSS; dst.dev_id = 0; dst.chn_id = 0;
ret = hi_mapi_sys_bind(&src, &dst);
【相关主题】
hi_mapi_sys_unbind、hi_mapi_mpp_chn
13 hi_mapi_sys_unbind
【描述】
解绑之前由 hi_mapi_sys_bind 建立的 (src, dst) 绑定。若该对未在内部 bind 表中，直接返回成功且不派发到底层 SDK。
【语法】
【参数】
| 参数名称 | 输入/输出 | 类型 | 描述 |
|---|---|---|---|
src_chn |
输入 | const hi_mapi_mpp_chn * |
源通道描述符，不能为 NULL，字段约束同 hi_mapi_sys_bind。 |
dst_chn |
输入 | const hi_mapi_mpp_chn * |
目标通道描述符，不能为 NULL。 |
【返回值】
| 返回值 | 描述 |
|---|---|
0 |
成功（含未绑定时直接返回成功）。 |
非0 |
失败，其值为错误码。 |
HI_MAPI_SYS_ENOTREADY |
内部 bind 上下文未初始化。 |
HI_MAPI_SYS_ENULL_PTR |
src_chn 或 dst_chn 为 NULL。 |
HI_MAPI_SYS_EILLEGAL_PARAM |
通道 mod_id 不在白名单，或 dev_id < 0/chn_id < 0。 |
【需求】
- 头文件：
hi_mapi_sys.h - 库文件：
libhi_mapi.so
【注意】
- 与
hi_mapi_sys_bind配对使用；hi_mapi_sys_deinit时会一次性 flush 所有绑定。
【举例】
hi_mapi_mpp_chn src, dst;
src.mod_id = HI_MAPI_MOD_VCAP; src.dev_id = 0; src.chn_id = 0;
dst.mod_id = HI_MAPI_MOD_VPSS; dst.dev_id = 0; dst.chn_id = 0;
(void)hi_mapi_sys_unbind(&src, &dst);
【相关主题】
hi_mapi_sys_bind
4 数据类型
1 hi_mapi_sys_base_attr
【说明】
描述媒体子系统的基础属性，包含 VCAP / VPSS 的设备数、分辨率、在线模式、VB 卷绕、sensor 帧率等信息，由 hi_mapi_sys_get_default_media_attr 根据它推导出一套可用的 media_attr。
【定义】
typedef struct {
td_u32 vcap_dev_num;
hi_mapi_size vcap_reso_size[HI_MAPI_VCAP_MAX_DEV_NUM];
td_bool vcap_online[HI_MAPI_VCAP_MAX_DEV_NUM];
td_u32 raw_bit_width;
td_bool is_wdr;
td_u32 vpss_grp_num;
td_u32 vpss_chn_num;
hi_mapi_size vpss_reso_size[HI_MAPI_VPSS_MAX_NUM][HI_MAPI_VPSS_CHN_MAX_NUM];
td_bool vpss_online[HI_MAPI_VPSS_MAX_NUM];
td_bool vpss_wrap_en[HI_MAPI_VPSS_MAX_NUM];
td_bool vi_wrap_en[HI_MAPI_VCAP_MAX_DEV_NUM];
td_u32 sensor_full_lines_std[HI_MAPI_VCAP_MAX_DEV_NUM];
td_u32 frame_rate[HI_MAPI_VCAP_MAX_DEV_NUM];
} hi_mapi_sys_base_attr;
数组维度在 HI3516CV610 上解析为：
HI_MAPI_VCAP_MAX_DEV_NUM = 2、HI_MAPI_VPSS_MAX_NUM = 6、HI_MAPI_VPSS_CHN_MAX_NUM = 5。
【成员】
| 成员名称 | 描述 |
|---|---|
vcap_dev_num |
使用的 VCAP 设备数量，范围 [1, 2]。 |
vcap_reso_size[i] |
第 i 个 VCAP 设备的 sensor 输出分辨率（宽 × 高，单位像素），i ∈ [0, 1]。 |
vcap_online[i] |
第 i 个 VCAP 设备是否在线模式，HI_TRUE 在线 / HI_FALSE 离线。 |
raw_bit_width |
RAW 数据位宽，单位 bit，常用取值 8 / 10 / 12 / 14 / 16。 |
is_wdr |
是否启用 WDR（宽动态），HI_TRUE 启用 / HI_FALSE 禁用。 |
vpss_grp_num |
使用的 VPSS group 数量，范围 [0, 6]。 |
vpss_chn_num |
每个 VPSS group 使用的通道数量，范围 [0, 5]。 |
vpss_reso_size[i][j] |
第 i 个 group 第 j 个通道的输出分辨率，i ∈ [0, 5]、j ∈ [0, 4]。 |
vpss_online[i] |
第 i 个 VPSS group 是否在线模式。 |
vpss_wrap_en[i] |
第 i 个 VPSS group 的通道 0 是否启用卷绕（buffer wrap）。 |
vi_wrap_en[i] |
第 i 个 VCAP 设备的 VI pipe 是否启用卷绕（仅 offline 模式有效）。 |
sensor_full_lines_std[i] |
第 i 个 sensor 的总行高（含 VBlank），单位行。 |
frame_rate[i] |
第 i 个 VCAP 设备的 sensor 输出帧率，单位 fps。 |
【注意事项】
- 数组下标按 CV610 实际维度使用，越界将返回
HI_MAPI_SYS_ARRAY_OUT_BOUNDS。 is_wdr = HI_TRUE时需保证raw_bit_width与 sensor WDR 模式匹配。
【相关数据类型及接口】
hi_mapi_size、hi_mapi_sys_media_attr；hi_mapi_sys_get_default_media_attr、hi_mapi_sys_init_media。
2 hi_mapi_sys_media_config
【说明】 描述媒体初始化所需的 VI/VPSS 工作模式与 VB 池配置。
【定义】
typedef struct {
hi_mapi_sys_vi_vpss_mode vi_vpss_mode;
hi_mapi_sys_vb_config vb_config;
} hi_mapi_sys_media_config;
【成员】
| 成员名称 | 描述 |
|---|---|
vi_vpss_mode |
VI / VPSS 在线-离线工作模式数组，长度 HI_MAPI_VI_VPSS_MAX_MODE_NUM = 4；每个元素取值参见 hi_mapi_vi_vpss_mode（VI_OFFLINE_VPSS_OFFLINE / VI_OFFLINE_VPSS_ONLINE / VI_ONLINE_VPSS_OFFLINE / VI_ONLINE_VPSS_ONLINE / VI_PARALLEL_VPSS_OFFLINE / VI_PARALLEL_VPSS_PARALLEL）。 |
vb_config |
视频缓冲池配置；max_pool_cnt 范围 (0, 96]，comm_pool 数组长度 HI_MAPI_VB_MAX_COMMON_POOLS = 16；每个池条目含 blk_size、blk_cnt、remap_mode、mmz_name[32]。 |
【注意事项】
hi_mapi_sys_get_default_media_attr会根据hi_mapi_sys_base_attr自动填充本结构，应用层通常无需手工构造。
【相关数据类型及接口】
hi_mapi_sys_vi_vpss_mode、hi_mapi_sys_vb_config、hi_mapi_sys_vb_pool_config；hi_mapi_sys_media_attr、hi_mapi_sys_init_media。
3 hi_mapi_sys_media_attr
【说明】
聚合媒体子系统初始化所需的全部参数（VI/VPSS 模式、VB 配置、VENC/ISP/音频工作模式），作为 hi_mapi_sys_init_media 的入参。
【定义】
typedef struct {
hi_mapi_sys_media_config media_config;
hi_mapi_sys_venc_mode_param venc_mod_para;
hi_mapi_isp_param_mode isp_mod_para;
hi_mapi_audio_param_mode audio_mod_para;
} hi_mapi_sys_media_attr;
【成员】
| 成员名称 | 描述 |
|---|---|
media_config |
VI/VPSS 工作模式与 VB 池配置，参见 hi_mapi_sys_media_config。 |
venc_mod_para |
VENC 模块低功耗模式参数，参见 hi_mapi_sys_venc_mode_param。 |
isp_mod_para |
ISP 模块工作模式参数，参见 hi_mapi_isp_param_mode。 |
audio_mod_para |
音频模块旁路与 VQE 配置，参见 hi_mapi_audio_param_mode。 |
【注意事项】 无
【相关数据类型及接口】
hi_mapi_sys_media_config、hi_mapi_sys_venc_mode_param、hi_mapi_isp_param_mode、hi_mapi_audio_param_mode；hi_mapi_sys_init_media、hi_mapi_sys_get_default_media_attr。
4 hi_mapi_sys_venc_mode_param
【说明】 描述 VENC 模块各编码格式的低功耗模式参数。
【定义】
typedef struct {
td_u32 h264e_low_power_mode;
td_u32 h265e_low_power_mode;
td_u32 svac3e_low_power_mode;
} hi_mapi_sys_venc_mode_param;
【成员】
| 成员名称 | 描述 |
|---|---|
h264e_low_power_mode |
H.264 编码低功耗模式，取值范围 [0, 2]。 |
h265e_low_power_mode |
H.265 编码低功耗模式，取值范围 [0, 2]。 |
svac3e_low_power_mode |
SVAC3 编码低功耗模式，取值范围 [0, 2]。 |
【注意事项】 无
【相关数据类型及接口】
hi_mapi_sys_media_attr；hi_mapi_sys_init_media。
5 hi_mapi_isp_param_mode
【说明】 描述 ISP 模块的工作模式参数（参数有效性、快速启动、中断底半部）。
【定义】
typedef struct {
td_bool param_valid;
td_bool quick_start;
td_bool int_bottom_half;
} hi_mapi_isp_param_mode;
【成员】
| 成员名称 | 描述 |
|---|---|
param_valid |
参数是否有效，HI_TRUE 使用本结构中的参数 / HI_FALSE 使用默认值。 |
quick_start |
是否启用 ISP 快速启动，HI_TRUE 启用 / HI_FALSE 禁用。 |
int_bottom_half |
是否启用中断底半部处理，HI_TRUE 启用 / HI_FALSE 禁用。 |
【注意事项】 无
【相关数据类型及接口】
hi_mapi_sys_media_attr；hi_mapi_sys_init_media。
6 hi_mapi_audio_param_mode
【说明】 描述音频模块的旁路与 VQE（语音质量增强）配置。
【定义】
【成员】
| 成员名称 | 描述 |
|---|---|
audio_bypass |
音频旁路开关，HI_TRUE 启用旁路（不经过 VQE） / HI_FALSE 正常处理。 |
vqe_attr |
VQE 配置，包含 talk_vqe_attr.open_mask（对讲 VQE 掩码）与 ao_vqe_attr.open_mask（AO VQE 掩码），掩码位定义参见关键常量中音频 VQE 掩码常量。 |
【注意事项】 无
【相关数据类型及接口】
hi_mapi_audio_vqe_attr、hi_mapi_audio_talk_vqe_attr、hi_mapi_audio_ao_vqe_attr；hi_mapi_sys_media_attr、hi_mapi_sys_init_media。
7 hi_mapi_sys_font_attr
【说明】 描述 OSD 字体库属性，包括字号与字符点阵回调。同一进程只能注册一次。
【定义】
typedef struct {
td_u32 font_width;
td_u32 font_height;
hi_mapi_sys_get_font_mod_cb get_font_mod_cb;
} hi_mapi_sys_font_attr;
其中回调类型定义为：
typedef td_s32 (*hi_mapi_sys_get_font_mod_cb)(const td_char *character,
td_u8 **font_mod,
td_s32 *font_mod_len);
【成员】
| 成员名称 | 描述 |
|---|---|
font_width |
字体宽度，单位像素。 |
font_height |
字体高度，单位像素。 |
get_font_mod_cb |
字符点阵回调：输入 UTF-8 字符 character，返回点阵数据指针 font_mod 与长度 font_mod_len（字节），成功返回 0，失败返回非 0。 |
【注意事项】
hi_mapi_sys_register_font_attr同一进程只能注册一次，重复注册将返回错误。- 回调函数必须线程安全。
【相关数据类型及接口】
hi_mapi_sys_register_font_attr、hi_mapi_osd_init。
5 错误码
模块编号
mod=0，错误码基址0xA3008000。
| 错误代码 | 宏定义 | 描述 |
|---|---|---|
0xA3008018 |
HI_MAPI_SYS_ESAFEFUNC_OPERATE_FAIL |
安全函数操作失败。 |
0xA300801B |
HI_MAPI_SYS_ARRAY_OUT_BOUNDS |
数组越界。 |
0xA300801C |
HI_MAPI_SYS_VALUE_OVERFLOW |
值溢出。 |