跳转至
项目
版本
全文检索

公共数据类型与常量说明文档

文档版本 V1.1
修订日期 2026-08-21
代码基线 hi_aiot_solution 8.18
对应头文件 components/media/pipeline/include/hi_mapi_*.h
类型定义 components/media/pipeline/include/hi_mapi_*_define.h、include/adapt/*_adapt_define.h
适用模块 pipeline / HI3516CV610

1 公共数据类型

1 hi_mapi_size

【说明】 定义二维尺寸（宽 × 高），单位像素。

【定义】 

typedef struct {
    td_u32 width;
    td_u32 height;
} hi_mapi_size;

【成员】

成员名称 描述
width 宽，单位像素。
height 高，单位像素。

【注意事项】 无

【相关数据类型及接口】 hi_mapi_rect；被 hi_mapi_sys_base_attr、hi_mapi_vpss_grp_attr 等多处引用。

2 hi_mapi_point

【说明】 定义二维坐标点。

【定义】 

typedef struct {
    td_s32 x;
    td_s32 y;
} hi_mapi_point;

【成员】

成员名称 描述
x 横坐标。
y 纵坐标。

【注意事项】 无

【相关数据类型及接口】 hi_mapi_rect。

3 hi_mapi_rect

【说明】 定义矩形区域（左上角坐标 + 宽高）。

【定义】 

typedef struct {
    td_s32 x;
    td_s32 y;
    td_u32 width;
    td_u32 height;
} hi_mapi_rect;

【成员】

成员名称 描述
x 左上角横坐标。
y 左上角纵坐标。
width 宽，单位像素。
height 高，单位像素。

【注意事项】 无

【相关数据类型及接口】 hi_mapi_point、hi_mapi_size；OSD / VGS 相关接口使用。

4 hi_mapi_mpp_chn

【说明】 定义 MPP 通道三元组，用于 hi_mapi_sys_bind / hi_mapi_sys_unbind 中指定源/宿通道。

【定义】 

typedef struct {
    hi_mapi_module_id mod_id;
    td_s32            dev_id;
    td_s32            chn_id;
} hi_mapi_mpp_chn;

【成员】

成员名称 描述
mod_id 模块 ID，参见 hi_mapi_module_id。
dev_id 设备号。
chn_id 通道号。

【注意事项】 无

【相关数据类型及接口】 hi_mapi_module_id、hi_mapi_sys_bind、hi_mapi_sys_unbind。

5 hi_mapi_module_id

【说明】 定义 MAPI 模块 ID 枚举，用于 hi_mapi_mpp_chn.mod_id 及错误码定位。

【定义】 

typedef enum {
    HI_MAPI_MOD_SYS = 0,
    HI_MAPI_MOD_VCAP,
    HI_MAPI_MOD_VPSS,
    HI_MAPI_MOD_VENC,
    HI_MAPI_MOD_ACAP,
    HI_MAPI_MOD_AENC,
    HI_MAPI_MOD_AO,
    HI_MAPI_MOD_DISP,
    HI_MAPI_MOD_HDMI,
    HI_MAPI_MOD_ADEC,
    HI_MAPI_MOD_VDEC,
    HI_MAPI_MOD_OSD,
    HI_MAPI_MOD_VGS,
    HI_MAPI_MOD_BUTT,
} hi_mapi_module_id;

【成员】

成员名称 描述
HI_MAPI_MOD_SYS 系统管理模块。
HI_MAPI_MOD_VCAP 视频采集模块。
HI_MAPI_MOD_VPSS 视频处理模块。
HI_MAPI_MOD_VENC 视频编码模块。
HI_MAPI_MOD_ACAP 音频采集模块。
HI_MAPI_MOD_AENC 音频编码模块。
HI_MAPI_MOD_AO 音频输出模块。
HI_MAPI_MOD_DISP 显示输出模块。
HI_MAPI_MOD_HDMI HDMI 模块（本版本未提供实现）。
HI_MAPI_MOD_ADEC 音频解码模块。
HI_MAPI_MOD_VDEC 视频解码模块。
HI_MAPI_MOD_OSD OSD 叠加模块。
HI_MAPI_MOD_VGS 图形处理模块。
HI_MAPI_MOD_BUTT 哨兵值，不可使用。

【注意事项】 HI_MAPI_MOD_HDMI 仅保留枚举位，本版本无实际实现。

【相关数据类型及接口】 hi_mapi_mpp_chn。

6 hi_mapi_payload_type

【说明】 定义媒体流负载类型（编码格式）枚举，用于 VENC / AENC 的输出格式描述。

【定义】 

typedef enum {
    HI_MAPI_PAYLOAD_TYPE_H264,
    HI_MAPI_PAYLOAD_TYPE_H265,
    HI_MAPI_PAYLOAD_TYPE_MJPEG,
    HI_MAPI_PAYLOAD_TYPE_JPEG,
    HI_MAPI_PAYLOAD_TYPE_AAC,
    HI_MAPI_PAYLOAD_TYPE_G711A,
    HI_MAPI_PAYLOAD_TYPE_G711U,
    HI_MAPI_PAYLOAD_TYPE_MP3,
    HI_MAPI_PAYLOAD_TYPE_LPCM,
    HI_MAPI_PAYLOAD_TYPE_SVAC3,
    HI_MAPI_PAYLOAD_TYPE_BUTT
} hi_mapi_payload_type;

【成员】

成员名称 描述
HI_MAPI_PAYLOAD_TYPE_H264 H.264 视频。
HI_MAPI_PAYLOAD_TYPE_H265 H.265 视频。
HI_MAPI_PAYLOAD_TYPE_MJPEG Motion JPEG 视频。
HI_MAPI_PAYLOAD_TYPE_JPEG JPEG 图片。
HI_MAPI_PAYLOAD_TYPE_AAC AAC 音频。
HI_MAPI_PAYLOAD_TYPE_G711A G.711 A 律音频。
HI_MAPI_PAYLOAD_TYPE_G711U G.711 μ 律音频。
HI_MAPI_PAYLOAD_TYPE_MP3 MP3 音频。
HI_MAPI_PAYLOAD_TYPE_LPCM LPCM 音频。
HI_MAPI_PAYLOAD_TYPE_SVAC3 SVAC3 视频。
HI_MAPI_PAYLOAD_TYPE_BUTT 哨兵值。

【注意事项】 无

【相关数据类型及接口】 hi_mapi_venc_attr、hi_mapi_aenc_attr。

7 hi_mapi_audio_payload_format

【说明】 定义音频 bitstream 打包格式。当前仅对 OPUS 有意义（其他格式始终为 HI_NATIVE）。

【定义】 

typedef enum {
    HI_MAPI_AUDIO_PAYLOAD_HI_NATIVE = 0,  /* 海思私有：每帧 8 字节大端长度头 */
    HI_MAPI_AUDIO_PAYLOAD_STANDARD,        /* 裸 RTP 负载（RFC 7587 OPUS） */
    HI_MAPI_AUDIO_PAYLOAD_BUTT
} hi_mapi_audio_payload_format;

【成员】

成员名称 描述
HI_MAPI_AUDIO_PAYLOAD_HI_NATIVE 海思私有封装：每帧前缀 8 字节大端长度头。
HI_MAPI_AUDIO_PAYLOAD_STANDARD 标准 RTP 裸负载，无长度前缀（遵循 RFC 7587）。
HI_MAPI_AUDIO_PAYLOAD_BUTT 哨兵值。

【注意事项】 仅 AENC / ADEC 处理 OPUS 流时区分两者。

【相关数据类型及接口】 hi_mapi_aenc_attr、hi_mapi_adec_attr。

8 hi_mapi_audio_format

【说明】 定义音频编码格式枚举，用于 ACAP / AENC / ADEC / AO 属性中。

【定义】 

typedef enum {
    HI_MAPI_AUDIO_FORMAT_AACLC = 0,
    HI_MAPI_AUDIO_FORMAT_G711A,
    HI_MAPI_AUDIO_FORMAT_G711U,
    HI_MAPI_AUDIO_FORMAT_MP3,
    HI_MAPI_AUDIO_FORMAT_LPCM,
    HI_MAPI_AUDIO_FORMAT_OPUS,
    HI_MAPI_AUDIO_FORMAT_BUTT
} hi_mapi_audio_format;

【成员】

成员名称 描述
HI_MAPI_AUDIO_FORMAT_AACLC AAC-LC。
HI_MAPI_AUDIO_FORMAT_G711A G.711 A 律。
HI_MAPI_AUDIO_FORMAT_G711U G.711 μ 律。
HI_MAPI_AUDIO_FORMAT_MP3 MP3。
HI_MAPI_AUDIO_FORMAT_LPCM LPCM。
HI_MAPI_AUDIO_FORMAT_OPUS OPUS。
HI_MAPI_AUDIO_FORMAT_BUTT 哨兵值。

【注意事项】 无

【相关数据类型及接口】 hi_mapi_acap_attr、hi_mapi_aenc_attr、hi_mapi_adec_attr。

9 hi_mapi_pixel_format

【说明】 定义像素格式枚举（RGB / YUV / Bayer / SVP 等），广泛用于 VCAP 输出、VPSS 输出、VGS 输入、DISP 输入等。

【定义】 

typedef enum {
    HI_MAPI_PIXEL_FORMAT_RGB_444 = 0,
    ...
    HI_MAPI_PIXEL_FORMAT_YUV_SEMIPLANAR_422,
    HI_MAPI_PIXEL_FORMAT_YUV_SEMIPLANAR_420,
    HI_MAPI_PIXEL_FORMAT_YUV_SEMIPLANAR_444,
    ...
    HI_MAPI_PIXEL_FORMAT_BUTT
} hi_mapi_pixel_format;

【成员】

取值较多，按族归类：

  • RGB 族：RGB_444/555/565/888、BGR_444/555/565/888、ARGB_*、ABGR_*
  • Bayer 族：RGB_BAYER_8BPP/10BPP/12BPP/14BPP/16BPP 及 _H10/_H12/_H14/_L10/_L12/_L14 变体
  • YUV 平面 / 半平面 / 包装族：YVU_PLANAR_*、YVU_SEMIPLANAR_*、YUV_SEMIPLANAR_*、YUYV/YVYU/UYVY/VYUY_PACKAGE_422 等
  • 单色：YUV_400、UV_420
  • SVP 格式：BGR_888_PLANAR、HSV_888_*、LAB_888_*、S8C1/S16C1/S32C1/S64C1、U8C1/U16C1/U32C1/U64C1 等

【注意事项】 完整取值见 hi_mapi_comm_arch_define.h。

【相关数据类型及接口】 hi_mapi_frame_data、hi_mapi_vcap_attr、hi_mapi_vpss_chn_attr。

10 hi_mapi_video_format

【说明】 定义视频帧内存排布格式（线性 / Tile）。

【定义】 

typedef enum {
    HI_MAPI_VIDEO_FORMAT_LINEAR = 0,
    HI_MAPI_VIDEO_FORMAT_TILE_64x16,
    HI_MAPI_VIDEO_FORMAT_TILE_16x8,
    HI_MAPI_VIDEO_FORMAT_TILE_32x4,
    HI_MAPI_VIDEO_FORMAT_BUTT
} hi_mapi_video_format;

【成员】

成员名称 描述
HI_MAPI_VIDEO_FORMAT_LINEAR 线性逐行排布。
HI_MAPI_VIDEO_FORMAT_TILE_64x16 64 像素 × 16 行 tile。
HI_MAPI_VIDEO_FORMAT_TILE_16x8 16 像素 × 8 行 tile。
HI_MAPI_VIDEO_FORMAT_TILE_32x4 32 像素 × 4 行 tile。
HI_MAPI_VIDEO_FORMAT_BUTT 哨兵值。

【注意事项】 无

【相关数据类型及接口】 hi_mapi_frame_data。

11 hi_mapi_compress_mode

【说明】 定义帧压缩模式。

【定义】 

typedef enum {
    HI_MAPI_COMPRESS_MODE_NONE = 0,
    HI_MAPI_COMPRESS_MODE_SEG,
    HI_MAPI_COMPRESS_MODE_SEG_COMPACT,
    HI_MAPI_COMPRESS_MODE_TILE,
    HI_MAPI_COMPRESS_MODE_LINE,
    HI_MAPI_COMPRESS_MODE_FRAME,
    HI_MAPI_COMPRESS_MODE_FMAP,
    HI_MAPI_COMPRESS_MODE_BUTT
} hi_mapi_compress_mode;

【成员】

成员名称 描述
HI_MAPI_COMPRESS_MODE_NONE 不压缩。
HI_MAPI_COMPRESS_MODE_SEG 段压缩。
HI_MAPI_COMPRESS_MODE_SEG_COMPACT 紧凑段压缩。
HI_MAPI_COMPRESS_MODE_TILE Tile 压缩。
HI_MAPI_COMPRESS_MODE_LINE 行压缩。
HI_MAPI_COMPRESS_MODE_FRAME 帧压缩。
HI_MAPI_COMPRESS_MODE_FMAP FMAP 压缩。
HI_MAPI_COMPRESS_MODE_BUTT 哨兵值。

【注意事项】 无

【相关数据类型及接口】 hi_mapi_frame_data。

12 hi_mapi_video_field

【说明】 定义视频场类型（顶场 / 底场 / 隔行 / 帧）。

【定义】 

typedef enum {
    HI_MAPI_VIDEO_FIELD_TOP         = 1,
    HI_MAPI_VIDEO_FIELD_BOTTOM      = 2,
    HI_MAPI_VIDEO_FIELD_INTERLACED  = 3,
    HI_MAPI_VIDEO_FIELD_FRAME       = 4,
    HI_MAPI_VIDEO_FIELD_BUTT
} hi_mapi_video_field;

【成员】

成员名称 描述
HI_MAPI_VIDEO_FIELD_TOP 偶场（顶场）。
HI_MAPI_VIDEO_FIELD_BOTTOM 奇场（底场）。
HI_MAPI_VIDEO_FIELD_INTERLACED 隔行两场。
HI_MAPI_VIDEO_FIELD_FRAME 帧。
HI_MAPI_VIDEO_FIELD_BUTT 哨兵值。

【注意事项】 无

【相关数据类型及接口】 hi_mapi_frame_data。

13 hi_mapi_dynamic_range

【说明】 定义动态范围（SDR / HDR）。

【定义】 

typedef enum {
    HI_MAPI_DYNAMIC_RANGE_SDR8 = 0,
    HI_MAPI_DYNAMIC_RANGE_SDR10,
    HI_MAPI_DYNAMIC_RANGE_HDR10,
    HI_MAPI_DYNAMIC_RANGE_HLG,
    HI_MAPI_DYNAMIC_RANGE_SLF,
    HI_MAPI_DYNAMIC_RANGE_XDR,
    HI_MAPI_DYNAMIC_RANGE_BUTT
} hi_mapi_dynamic_range;

【成员】

成员名称 描述
HI_MAPI_DYNAMIC_RANGE_SDR8 SDR 8-bit。
HI_MAPI_DYNAMIC_RANGE_SDR10 SDR 10-bit。
HI_MAPI_DYNAMIC_RANGE_HDR10 HDR10。
HI_MAPI_DYNAMIC_RANGE_HLG HLG。
HI_MAPI_DYNAMIC_RANGE_SLF SLF。
HI_MAPI_DYNAMIC_RANGE_XDR XDR。
HI_MAPI_DYNAMIC_RANGE_BUTT 哨兵值。

【注意事项】 无

【相关数据类型及接口】 hi_mapi_frame_data。

14 hi_mapi_color_gamut

【说明】 定义色域标准。

【定义】 

typedef enum {
    HI_MAPI_COLOR_GAMUT_BT601 = 0,
    HI_MAPI_COLOR_GAMUT_BT709,
    HI_MAPI_COLOR_GAMUT_BT2020,
    HI_MAPI_COLOR_GAMUT_USER,
    HI_MAPI_COLOR_GAMUT_BUTT
} hi_mapi_color_gamut;

【成员】

成员名称 描述
HI_MAPI_COLOR_GAMUT_BT601 BT.601。
HI_MAPI_COLOR_GAMUT_BT709 BT.709。
HI_MAPI_COLOR_GAMUT_BT2020 BT.2020。
HI_MAPI_COLOR_GAMUT_USER 用户自定义。
HI_MAPI_COLOR_GAMUT_BUTT 哨兵值。

【注意事项】 无

【相关数据类型及接口】 hi_mapi_frame_data。

15 hi_mapi_frame_data

【说明】 定义帧数据的通用描述结构，被 hi_mapi_vcap_get_chn_frame / hi_mapi_vpss_get_chn_frame / hi_mapi_vdec_get_frame 等返回。

【定义】 

typedef struct {
    hi_mapi_frame_data_type frame_data_type;
    td_u32 width;
    td_u32 height;
    hi_mapi_pixel_format pixel_format;
    hi_mapi_video_format video_format;
    hi_mapi_compress_mode compress_mode;
    td_u64 phy_addr[HI_MAPI_FRAME_DATA_ADDR_NUM];
    td_u64 vir_addr[HI_MAPI_FRAME_DATA_ADDR_NUM];
    td_u32 stride[HI_MAPI_FRAME_DATA_ADDR_NUM];
    hi_mapi_video_field field;
    td_u64 header_phys_addr[HI_MAPI_FRAME_DATA_ADDR_NUM];
    td_u64 heade_virt_addr[HI_MAPI_FRAME_DATA_ADDR_NUM];
    td_u32 heade_stride[HI_MAPI_FRAME_DATA_ADDR_NUM];
    hi_mapi_dynamic_range dynamic_range;
    hi_mapi_color_gamut   color_gamut;
    td_u32 mod_id;
    td_u32 time_ref;
    td_u32 frame_flag;
    td_u64 pts;
    td_u32 pool_id;
    hi_mapi_video_supplement video_supplement;
} hi_mapi_frame_data;

【成员】

成员名称 描述
frame_data_type 帧数据类型（RAW / YUV）。
width / height 帧宽高。
pixel_format 像素格式。
video_format 内存排布（线性 / Tile）。
compress_mode 压缩模式。
phy_addr[] / vir_addr[] / stride[] 各分量物理/虚拟地址及步长。
field 场类型。
header_phys_addr[] / heade_virt_addr[] / heade_stride[] 帧头地址与步长。
dynamic_range 动态范围。
color_gamut 色域。
mod_id 产生该帧的模块 ID。
time_ref 时间参考。
frame_flag 帧标志位。
pts 显示时间戳。
pool_id 所属 VB 池 ID。
video_supplement 附加视频信息。

【注意事项】

  • 获取的 hi_mapi_frame_data 必须通过对应的 release_chn_frame / release_frame 释放。
  • phy_addr / vir_addr 由 MAPI 填充，应用层只读。

【相关数据类型及接口】 hi_mapi_vcap_get_chn_frame、hi_mapi_vpss_get_chn_frame、hi_mapi_vdec_get_frame、hi_mapi_acap_get_frame。

2 关键常量

1 资源上限

常量 取值 说明
HI_MAPI_VCAP_MAX_DEV_NUM 2 VCAP 最大设备数。
HI_MAPI_SENSOR_MAX_LANE_NUM 4 Sensor 最大 MIPI lane 数。
HI_MAPI_VCAP_MAX_PIPE_NUM 2 VCAP 最大 pipe 数。
HI_MAPI_VCAP_PIPE_MAX_CHN_NUM 1 单 pipe 最大通道数。
HI_MAPI_VCAP_DEV_SENSOR_MAX_NUM 4 单设备最多 sensor 数。
HI_MAPI_VCAP_OSD_MAX_NUM 4 VCAP 模块最大 OSD 数。
HI_MAPI_VPSS_PHY_CHN_MAX_NUM 3 VPSS 物理通道最大数。
HI_MAPI_VPSS_EXT_CHN_MAX_NUM 2 VPSS 扩展通道最大数。
HI_MAPI_VPSS_MAX_NUM 6 VPSS group 最大数（OT_VPSS_MAX_GRP_NUM）。
HI_MAPI_VPSS_CHN_MAX_NUM 5 VPSS 单 group 最大通道总数（物理 + 扩展）。
HI_MAPI_VPSS_OSD_MAX_NUM 4 VPSS 模块最大 OSD 数。
HI_MAPI_VENC_MAX_CHN_NUM 8 VENC 最大通道数。
HI_MAPI_VENC_CALLBACK_MAX_NUM 5 VENC 单通道最大回调数。
HI_MAPI_VENC_OSD_MAX_NUM 8 VENC 模块最大 OSD 数。
HI_MAPI_VDEC_MAX_NUM 8 VDEC 最大通道数。
HI_MAPI_DISP_OSD_MAX_NUM 1 DISP 模块最大 OSD 数。
HI_MAPI_OSD_MAX_CNT 16 OSD 模块最大实例数。
HI_MAPI_OSD_MAX_DISP_CNT 4 单 OSD 实例最大显示数。
HI_MAPI_ACAP_CHN_MAX_NUM 4 ACAP 最大通道数。
HI_MAPI_AENC_CHN_MAX_NUM 2 AENC 最大通道数。
HI_MAPI_AENC_CHN_CALLBACK_MAX_NUM 5 AENC 单通道最大回调数。
HI_MAPI_AIO_MAX_POINT_PER_FRAME 2048 音频单帧最大采样点数。
HI_MAPI_AO_MIN_GAIN -121 AO 最小增益（dB）。
HI_MAPI_AO_MAX_GAIN 6 AO 最大增益（dB）。
HI_MAPI_AO_MAX_SUPPORT_SAMPLERATE_NUM 3 AO 最大支持的采样率数量。

2 通用常量

常量 取值 说明
OT_INVALID_HANDLE -1 无效句柄值。
OT_INVALID_VALUE -1 无效通用值。
HI_MAPI_MAX_STR_LEN 64 字符串 OSD 最大长度。
HI_MAPI_MODE_NAME_LEN 8 模式名称最大长度。
HI_MAPI_PTHREAD_NAME_LEN 16 线程名最大长度。
HI_MAPI_PRO_MAX_FRAME_NUM 8 专业抓图最大帧数。
HI_MAPI_NORMAL_MAX_FRAME_NUM 0xFFFFFFFF 普通抓图最大帧数（无限制）。

3 音频 VQE 掩码常量

用作 hi_mapi_audio_talk_vqe_attr.open_mask / hi_mapi_audio_ao_vqe_attr.open_mask 的位标志。

常量 取值 说明
HI_MAPI_AI_TALKV2_MASK_NR 0x2 噪声抑制。
HI_MAPI_AI_TALKV2_MASK_EQ 0x4 均衡器。
HI_MAPI_AI_TALKV2_MASK_AGC 0x8 自动增益。
HI_MAPI_AI_TALKV2_MASK_DRC 0x10 动态范围压缩。
HI_MAPI_AI_TALKV2_MASK_LIMITER 0x20 限幅器。
HI_MAPI_AI_TALKV2_MASK_DEREVERB 0x40 去混响。
HI_MAPI_AI_TALKV2_MASK_FMP 0x80 音乐检测。
HI_MAPI_AI_TALKV2_MASK_WNR 0x100 风噪抑制。
HI_MAPI_AI_TALKV2_MASK_AEC 0x200 回声抵消。
HI_MAPI_AI_TALKV2_MASK_HS 0x400 头机模式。

3 通用错误码

MAPI 错误码为 32 位有符号整数，由 HI_MAPI_DEF_ERR(module, level, errid) 宏合成：

|<1>|<  APP_ID = 0x23  (7 bit)  >|< MOD_ID (8 bit) >|< LEVEL (3 bit) >|< ERR_ID (13 bit) >|

其中 APP_ID 固定为 0x80000000L + 0x23000000L。各模块 ID 参见 hi_mapi_module_id（见第 1 章公共数据类型）。

所有模块共用，errid 范围 0~63。

错误代码（errid） 宏定义 描述
1 MAPI_EN_ERR_INVALID_DEVID 设备号无效。
2 MAPI_EN_ERR_INVALID_CHNID 通道号无效。
3 MAPI_EN_ERR_ILLEGAL_PARAM 参数非法（如越界枚举值）。
4 MAPI_EN_ERR_EXIST 资源已存在。
5 MAPI_EN_ERR_UNEXIST 资源不存在。
6 MAPI_EN_ERR_NULL_PTR 空指针。
7 MAPI_EN_ERR_NOT_CONFIG 未配置即启用/初始化。
8 MAPI_EN_ERR_NOT_SUPPORT 不支持的操作或类型。
9 MAPI_EN_ERR_NOT_PERM 操作未授权（如修改静态属性）。
12 MAPI_EN_ERR_NOMEM 内存分配失败。
13 MAPI_EN_ERR_NOBUF 缓冲区分配失败。
14 MAPI_EN_ERR_BUF_EMPTY 缓冲区无数据。
15 MAPI_EN_ERR_BUF_FULL 缓冲区已满。
16 MAPI_EN_ERR_SYS_NOTREADY 系统未就绪（未初始化或未加载）。
17 MAPI_EN_ERR_BADADDR 非法地址（如 copy_from_user / copy_to_user）。
18 MAPI_EN_ERR_BUSY 资源忙（如未注销回调即销毁通道）。
19 MAPI_EN_ERR_INVALID_FD 文件描述符无效。
20 MAPI_EN_ERR_ILLEGAL_HANDLE 句柄无效（如 pipe ID 越界）。
21 MAPI_EN_ERR_NOT_INITED 模块未初始化（如 VCAP 未 init）。
22 MAPI_EN_ERR_OPERATE_FAIL 操作失败（如 VCAP dev 启动失败）。
23 MAPI_EN_ERR_TIME_OUT 操作超时（如 VCAP dump raw 超时）。
24 MAPI_EN_ERR_SAFEFUNC_OPERATE_FAIL 安全函数操作失败。
25 MAPI_EN_ERR_NO_FONT OSD 模块无字体资源。
26 MAPI_EN_ERR_NO_REGISTER_MSG 模块无注册消息（如 ADEC）。
27 MAPI_EN_ERR_ARRAY_OUT_BOUNDS 数组越界。
28 MAPI_EN_ERR_VALUE_OVERFLOW 值溢出。
63 MAPI_EN_ERR_BUTT 上界哨兵（各模块私有错误码必须大于该值）。

实际返回值为 HI_MAPI_DEF_ERR(<mod>, MAPI_EN_ERR_LEVEL_ERROR, <errid>)，例如 SYS 模块的数组越界错误返回 HI_MAPI_SYS_ARRAY_OUT_BOUNDS。

4 使用注意事项

  1. 句柄范围：所有模块句柄（td_handle）均由 init 系列接口填充，必须原样传给后续接口；不可自行构造或跨模块复用。无效句柄值为 OT_INVALID_HANDLE（-1）。

  2. 时序依赖：遵循以下启停顺序，停止为逆序：

    启动：

    hi_mapi_sys_init()
  → hi_mapi_sys_init_media(...)
  → <模块>_init(...)            // 各模块初始化
  → <模块>_set_attr(...)         // 属性配置（静态属性必须 start 前设置）
  → <模块>_start(...)            // 启动
  → [循环] get_frame → ... → release_frame

    停止（逆序）：

<模块>_stop(...)
  → <模块>_deinit(...)
  → hi_mapi_sys_deinit_media()
  → hi_mapi_sys_deinit()

  1. 资源配对：以下调用必须严格配对：

    • hi_mapi_sys_bind ↔ hi_mapi_sys_unbind
    • get_chn_frame / get_frame ↔ release_chn_frame / release_frame
    • hi_mapi_sys_alloc_buffer ↔ hi_mapi_sys_free_buffer
    • hi_mapi_sys_get_video_block ↔ hi_mapi_sys_release_video_block
    • register_callback ↔ un_register_callback
    • mute ↔ unmute

  2. 属性语义：

    • 静态属性：必须在 start 之前通过 set_attr 设置；运行期间修改会返回 MAPI_EN_ERR_NOT_PERM。
    • 动态属性：可在运行期间通过 set_attr / set_param 修改。
    • get_attr 可随时调用。

  3. 线程安全：同一模块的同一句柄不可被多线程并发调用（set_attr / get_attr 等例外，由模块内部加锁）。不同句柄之间可并发。

  4. 内存对齐：通过 hi_mapi_sys_alloc_buffer 分配的物理内存已按页对齐；用于 DMA 的缓冲区在写入后、硬件读取前必须调用 hi_mapi_sys_flush_cache。

5 附注 / 关联文档

  • 头文件目录：components/media/pipeline/include/
  • 库文件：libhi_mapi.so / libhi_mapi.a
  • 平台：HI3516CV610（OT_CHIP = 0x3516C610）
  • 基础类型定义：sdk/Hi3516CV610/soc/include/ot_defines.h、ot_type.h
  • 媒体处理底层（MPP）接口：参见 SDK 文档 sdk/Hi3516CV610/docs/03.API参考/MPP/