Sgs NVR 应用开发指南¶
本文档介绍 Sgs NVR 应用的开发流程、关键概念和使用方法，帮助开发者快速掌握基于 SGS MI 系统的 NVR 应用开发。
REVISION HISTORY¶
| Revision No. | Description |
Date |
|---|---|---|
| 1.0 | 01/20/2026 |
1. 基础概念介绍¶
1.1 Sgs MI 系统概述¶
Sgs MI（Module Interface）系统是 SGS SoC 平台的多媒体软件开发套件，提供了一整套统一的 API 接口来访问底层硬件 IP。MI 系统通过模块化的设计，将复杂的硬件操作抽象为简单易用的接口，使开发者能够专注于应用层逻辑，而无需关心底层硬件细节。
核心特点：
- 硬件抽象：屏蔽不同芯片间的硬件差异
- 模块化设计：每个功能模块独立管理，包括 VDEC、DISP、VENC、SCL 等
- 统一接口：所有模块遵循相同的调用规范
- 跨平台支持：支持 PureRTOS、PureLinux、DualOS、LightningBoot 等多种操作系统
1.2 NVR 关键模块说明¶
1.2.1 MI_SYS（系统模块）¶
作用：系统核心模块，负责全局初始化、资源管理和模块间数据传输。
主要功能：
- 系统初始化与退出（
MI_SYS_Init/MI_SYS_Exit） - 模块间通道绑定（
MI_SYS_BindChnPort） - 内存管理（MMA heap 分配）
- 缓冲区管理（Buffer 分配与传递）
- 时间戳管理（PTS 同步）
头文件：
mi_sys.h：主要 API 接口mi_sys_datatype.h：数据类型定义
1.2.2 MI_VDEC（视频解码模块）¶
作用：解码 H.264/H.265/JPEG 等格式的视频码流
主要功能：
- 解码设备创建/销毁（
MI_VDEC_CreateDev/MI_VDEC_DestroyDev） - 解码通道创建/销毁（
MI_VDEC_CreateChn/MI_VDEC_DestroyChn） - 解码参数配置（码流类型、分辨率等）
- 码流输入（
MI_VDEC_SendStream） - 解码通道控制（
MI_VDEC_StartChn/MI_VDEC_StopChn）
头文件：
mi_vdec.hmi_vdec_datatype.h
关键数据类型：
typedef enum {
E_MI_VDEC_CODEC_TYPE_H264 = 0, // H.264 编码
E_MI_VDEC_CODEC_TYPE_H265, // H.265 编码
// ...
} MI_VDEC_CodecType_e;
1.2.3 MI_DISP（显示模块）¶
作用：将视频数据输出到显示设备，包括 HDMI、VGA、MIPI 等。
主要功能：
- 显示设备创建/销毁（
MI_DISP_CreateDevice/MI_DISP_DestroyDevice） - 显示层管理（Layer）
- 通道管理（
MI_DISP_CreateChn/MI_DISP_DestroyChn） - 输出时序配置（
MI_DISP_SetOutputTiming） - 显示区域设置（
MI_DISP_SetChnDispRect）
头文件：
mi_disp.hmi_disp_datatype.h
支持的输出接口：
- HDMI
- VGA
- MIPI
- TTL
- BT1120
1.2.4 MI_SCL（缩放模块）¶
作用：对图像进行缩放处理，支持多路不同分辨率输出
主要功能：
- 图像缩放
- 裁剪
- 多路输出
- 旋转支持
头文件：
mi_scl.hmi_scl_datatype.h
1.2.5 MI_VENC（视频编码模块）¶
作用：将 YUV 图像编码为 H.264/H.265/JPEG 等格式
主要功能：
- 编码通道创建/销毁（
MI_VENC_CreateChn/MI_VENC_DestroyChn） - 编码参数配置（码率、GOP、QP 等）
- 码流获取（
MI_VENC_GetStream） - IDR 帧请求（
MI_VENC_RequestIdr）
头文件：
mi_venc.hmi_venc_datatype.h
1.2.6 MI_GFX（图形处理模块）¶
作用：提供图形处理功能（缩放、旋转、叠加等）
主要功能：
- 位图拷贝（BitBlit）
- 图像缩放
- 图像旋转（0°/90°/180°/270°）
- 镜像翻转
- Alpha 混合
头文件：
mi_gfx.hmi_gfx_datatype.h
1.2.7 MI_FB（帧缓冲模块）¶
作用：管理 Framebuffer，用于 UI 显示
主要功能：
- Framebuffer 设备管理
- Alpha 值设置（Global/Pixel Alpha）
- ColorKey 设置
- 获取 Framebuffer 地址
头文件：
mi_fb.hmi_fb_datatype.h
1.2.8 MI_HDMI（HDMI 输出模块）¶
作用：配置 HDMI 输出参数
主要功能：
- HDMI 初始化与退出
- 输出时序设置
- 色彩空间转换配置
- 信号增益和锐度调整
头文件：
mi_hdmi.hmi_hdmi_datatype.h
1.3 数据流程与控制流程¶
1.3.1 数据流程¶
NVR 应用的数据流程是 单向流动 的，典型的数据流向如下：
详细流程说明：
- 码流输入：从文件或网络读取 H.264/H.265 码流
- VDEC 解码：VDEC 模块解码码流，输出 YUV 数据
- SCL 处理：SCL 将 YUV 数据缩放到目标分辨率，可输出多路不同分辨率，也可以进行rotat输出
- DISP 显示：DISP 将 YUV 数据输出到显示设备（HDMI、VGA 等）
典型 Pipeline（4 路码流为例）：
+----------+ +-------+ +-----------+ +--------------------+
| Stream 0 | --> | VDEC0 | --> | SCL0(rot) | --> | Port0 | |
+----------+ +-------+ +-----------+ +-------+ |
| |
+----------+ +-------+ +-------+ |
| Stream 1 | --> | VDEC1 | --------------------> | Port1 | |
+----------+ +-------+ +-------+ |
| DISP0 | --> Screen (多画面显示)
+----------+ +-------+ +-------+ |
| Stream 2 | --> | VDEC2 | --------------------> | Port2 | |
+----------+ +-------+ +-------+ |
| |
+----------+ +-------+ +-------+ |
| Stream 3 | --> | VDEC3 | --------------------> | Port3 | |
+----------+ +-------+ + -------------------+
1.3.2 控制流程¶
控制流程是指 配置和管理 各模块的流程，主要包括：
-
初始化阶段：
MI_SYS_Init()：初始化系统- 读取配置文件（JSON 格式）
- 创建设备：
MI_VDEC_CreateDev()、MI_DISP_CreateDevice()等 - 配置参数：设置各模块属性
- 创建通道：
MI_VDEC_CreateChn()、MI_DISP_CreateChn()等
-
绑定阶段：
MI_SYS_BindChnPort()：建立模块间的数据传输通道
-
启动阶段：
- 使能设备：
MI_DISP_EnableInputPort()等 - 启动通道开始解码：
MI_VDEC_StartChn()
- 使能设备：
-
运行阶段：
- 读取码流：从文件读取 H.264/H.265 码流
- 发送码流：
MI_VDEC_SendStream() - 处理用户输入：切屏、抓拍等功能
-
停止阶段：
- 停止通道：
MI_VDEC_StopChn() - 禁用设备：
MI_DISP_DisableInputPort()等 - 解绑通道：
MI_SYS_UnBindChnPort() - 销毁通道/设备
MI_SYS_Exit()：退出系统
- 停止通道：
1.4 Channel 与 Port 概念¶
1.4.1 Device（设备）¶
- 定义：代表一个硬件设备实例
- 示例：VDEC 设备 0、DISP 设备 0、VENC 设备 8 等
- 作用：管理硬件资源的全局配置
1.4.2 Channel（通道）¶
- 定义：设备上的独立数据通道
- 示例：VDEC 通道 0~63（支持多路解码）、DISP 通道 0~63（支持多画面显示）
- 作用：支持多个独立的数据流
1.4.3 Port（端口）¶
-
定义：通道上的输入或输出接口
-
类型：
- InputPort：输入端口，接收上游模块的数据
- OutputPort：输出端口，向下游模块发送数据
-
作用：模块间数据传输的桥梁
1.4.4 ChnPort（通道端口）¶
-
定义：由 ModuleId、DevId、ChnId、PortId 组成的结构体
-
结构：
typedef struct { MI_ModuleId_e eModId; // 模块 ID（如 E_MI_MODULE_ID_VDEC） MI_U32 u32DevId; // 设备 ID MI_U32 u32ChnId; // 通道 ID MI_U32 u32PortId;// 端口 ID } MI_SYS_ChnPort_t; -
作用：唯一标识一个模块的输入或输出端口
1.5 BindType（绑定模式）¶
绑定模式定义了模块间数据传输的方式，主要通过 MI_SYS_BindType_e 枚举类型指定。
1.5.1 NVR 常用绑定模式¶
| 绑定模式 | 枚举值 | 十六进制 | 简称 |
|---|---|---|---|
| Frame Mode | E_MI_SYS_BIND_TYPE_FRAME_BASE | 0x00000001（1） | F |
2. 应用开发流程¶
2.1 开发环境准备¶
2.1.1 硬件要求¶
- SGS SoC 开发板（支持 NVR 功能的芯片）
- 显示设备（HDMI/VGA/MIPI 显示屏）
- 存储设备（存放码流文件）
2.1.2 软件依赖¶
- 交叉编译工具链：根据目标芯片选择（例如 aarch64-linux-gnu-gcc）
- MI 库：
libmi_sys.so、libmi_vdec.so、libmi_disp.so等 - 第三方库：
libcjson.so（配置文件解析） - 系统库：
libpthread.so
2.1.3 头文件路径¶
MI 头文件位于 project/release/include/ 目录下。
常用头文件：
#include "mi_sys.h" // 系统模块
#include "mi_vdec.h" // 解码模块
#include "mi_disp.h" // 显示模块
#include "mi_scl.h" // 缩放模块
#include "mi_venc.h" // 编码模块
#include "mi_gfx.h" // 图形处理模块
#include "mi_fb.h" // 帧缓冲模块
#include "mi_hdmi.h" // HDMI 模块
2.2 MI API 开发标准流程¶
2.2.1 初始化流程¶
// 1. 初始化系统
MI_SYS_Init(0);
// 2. 创建 VDEC 设备
MI_VDEC_InitParam_t vdecInitParam;
// ... 配置 vdecInitParam
MI_VDEC_CreateDev(0, &vdecInitParam);
// 3. 创建 DISP 设备
MI_DISP_InitParam_t dispInitParam;
// ... 配置 dispInitParam
MI_DISP_CreateDevice(0, &dispInitParam);
// 4. 创建 VDEC 通道
MI_VDEC_ChnAttr_t vdecChnAttr;
// ... 配置 vdecChnAttr
MI_VDEC_CreateChn(0, vdecChn, &vdecChnAttr);
// 5. 创建 DISP 通道
MI_DISP_ChnAttr_t dispChnAttr;
// ... 配置 dispChnAttr
MI_DISP_CreateChn(0, dispChn, &dispChnAttr);
2.2.2 绑定流程¶
// 定义源和目标端口
MI_SYS_ChnPort_t srcPort = {
.eModId = E_MI_MODULE_ID_VDEC,
.u32DevId = 0,
.u32ChnId = 0,
.u32PortId = 0
};
MI_SYS_ChnPort_t dstPort = {
.eModId = E_MI_MODULE_ID_DISP,
.u32DevId = 0,
.u32ChnId = 0,
.u32PortId = 0
};
// 绑定（Frame Mode）
MI_SYS_BindChnPort(0, &srcPort, &dstPort,
30, 30, // 帧率
E_MI_SYS_BIND_TYPE_FRAME_BASE, 0);
2.2.3 启动流程¶
// 1. 使能 DISP 通道
MI_DISP_EnableChn(0, dispChn);
// 2. 使能 DISP 输入端口
MI_DISP_EnableInputPort(layerId, dispPortId);
// 3. 开始通道解码
MI_VDEC_StartChn(0, vdecChn);
2.2.4 运行与数据输入¶
// 从文件读取码流并发送给解码器
FILE *fp = fopen("stream.h265", "rb");
MI_VDEC_Stream_t stream;
MI_VDEC_Data_t data;
while (running) {
// 读取码流数据
size_t readSize = fread(buffer, 1, buffer_size, fp);
if (readSize <= 0) break;
// 填充数据结构
data.pu8Addr = buffer;
data.u32Len = readSize;
data.u64PTS = pts;
data.bEndOfFrame = TRUE;
stream.pstData = &data;
stream.u32DataCount = 1;
// 发送码流
MI_VDEC_SendStream(0, vdecChn, &stream, -1);
}
fclose(fp);
2.2.5 清理流程¶
// 1. 停止通道解码
MI_VDEC_StopChn(0, vdecChn);
// 2. 禁用各模块
MI_DISP_DisableInputPort(layerId, dispPortId);
MI_DISP_DisableChn(0, dispChn);
// 3. 解绑
MI_SYS_UnBindChnPort(0, &srcPort, &dstPort);
// 4. 销毁通道和设备
MI_DISP_DestroyChn(0, dispChn);
MI_DISP_DestroyDevice(0);
MI_VDEC_DestroyChn(0, vdecChn);
MI_VDEC_DestroyDev(0);
// 5. 退出系统
MI_SYS_Exit(0);
2.3 关键开发要点¶
2.3.1 配置文件管理¶
NVR demo 使用 JSON 格式的配置文件，包含以下主要配置。
- disp 配置：显示设备参数，包括接口类型、时序、通道数等
- fb 配置：Framebuffer 参数，包括 Alpha 类型、UI 文件路径等
- vdec 配置：解码设备参数，包括通道数、压缩使能、码流属性等
配置文件示例：
{
"dispDevNum": 2,
"dispArgs_0": {
"intfType": "hdmi",
"timing": "3840x2160_30",
"chnNum": 32,
"rotate": 4
},
"vdecDevNum": 1,
"vdecArgs_0": {
"chnNum": 64,
"compressEn": 1,
"vdecAttr": [
{
"chnId": 0,
"picWidth": 720,
"picHeight": 576,
"codecType": 1,
"refFrameNum": 2,
"esAddHead": 1,
"filePath": "720x576@30.h265"
}
]
}
}
2.3.2 错误处理¶
所有 MI API 返回 MI_S32 类型。
MI_SUCCESS（0）：成功- 非 0：失败（具体错误码见
mi_common_datatype.h）
2.3.3 资源管理¶
- 创建顺序：系统 → 设备 → 通道
- 销毁顺序：通道 → 设备 → 系统（与创建相反）
- 内存管理：使用 MMA heap 分配内存，记得释放
2.3.4 线程安全¶
- MI API 通常是线程安全的
- 同一设备的同一通道不能在多线程中同时操作
- 建议使用互斥锁保护共享资源
2.3.5 性能优化¶
- 合理设置缓冲区深度（
MI_SYS_SetChnOutputPortDepth） - 使用压缩模式（LSYC）降低带宽
- 避免频繁的创建和销毁操作
- 合理选择绑定模式
3. nvr_demo 编译与使用¶
3.1 Demo 功能概述¶
nvr_demo 演示了完整的 NVR 视频 Pipeline。
- 从文件读取 H.264/H.265 码流
- 经由 VDEC 解码缩放
- 通过 SCL 缩放和旋转（可选）
- 通过 DISP 显示到屏幕
- 支持多种测试场景，包括切屏、抓拍、PIP 等
Pipeline 图示：
+----------+ +-------+ +------+ +-------+
| Stream 0 | --> | VDEC0 | --> | SCL0 | --> | DISP0 | --> Screen
+----------+ +-------+ +------+ +-------+
|
v
+-------+
| VENC8 | --> File（抓拍）
+-------+
3.2 编译方法¶
3.2.1 项目目录结构¶
sdk/verify/sample_code/demo/
├── nvr/nvr/ # nvr demo 目录
│ ├── sgs_demo_nvr.c # 主程序
│ ├── nvr.mk # 编译配置
│ ├── dep.mk # 依赖配置
│ ├── config_nvr.json # 配置文件
│ └── readme_zh.md # 使用说明
| ...
├── nvr/internal/ # 内部组件
│ ├── common/ # 公共组件
│ ├── sys/ # 系统组件
│ ├── vdec/ # 解码组件
│ ├── disp/ # 显示组件
│ ├── scl/ # 缩放组件
│ ├── venc/ # 编码组件
│ ├── gfx/ # 图形组件
│ ├── fb/ # 帧缓冲组件
│ └── hdmi/ # HDMI 组件
| ...
3.2.2 编译步骤¶
前提条件：确保交叉编译工具链已配置。
方法 1：单独编译 nvr demo
# 进入 SDK 根目录
cd SourceCode/sdk/verify/sample_code
# 编译 nvr demo
make demo/nvr/nvr
# 清理编译产物
make demo/nvr/nvr_clean
方法 2：整包编译
# 进入 project 目录
cd SourceCode/project
# 选择 defconfig（根据板子型号）
# 例如：nvr_mhera.spinand.glibc-12.4.0-arm64-squashfs.ssm004a.s01a.1024x1024.fccsp16_ddr4_defconfig
make nvr_mhera.spinand.glibc-12.4.0-arm64-squashfs.ssm004a.s01a.1024x1024.fccsp16_ddr4_defconfig
# 编译整包
make clean && make image -j8
3.2.3 编译输出¶
编译成功后，可执行文件位于：
其中 <arch> 由构建配置决定，例如 arm64。
3.2.4 依赖库说明¶
根据 nvr.mk，依赖以下库。
LIBS += -lmi_common # 公共库
LIBS += -lmi_disp # 显示模块
LIBS += -lmi_hdmi # HDMI 模块
LIBS += -lmi_vdec # 解码模块
LIBS += -lmi_jpd # JPEG 解码
LIBS += -lmi_venc # 编码模块
LIBS += -lmi_scl # 缩放模块
LIBS += -lmi_gfx # 图形处理
LIBS += -lmi_vdisp # 虚拟显示
pthread/cjson 通过 dep.mk 依赖与构建系统自动链入，nvr.mk 中未显式列出。
3.3 使用方法¶
3.3.1 运行前准备¶
-
准备码流文件
- 准备 H.264/H.265 码流文件
- 放在与可执行文件同目录下
-
准备 UI 资源文件（可选）
- 鼠标图标文件：
cursor_argb1555.bin - UI 文件：
1920x1080_argb1555.bin - 放在与可执行文件同目录下
- 鼠标图标文件：
-
修改配置文件
- 根据实际需求修改
config_nvr.json - 配置显示参数、解码参数等
- 如果需要使用SCL模块，需要将config_nvr.json的"rotate"参数改为0/½/3的其中一个值
- 根据实际需求修改
码流文件和资源文件位于 SourceCode/sdk/verify/sample_code/demo/nvr/nvr/resource。
3.3.2 命令行参数¶
参数说明：
config_file：JSON 格式的配置文件路径
示例：
3.3.3 配置文件详解¶
disp 参数说明：
| 参数 | 说明 | 可选值 |
|---|---|---|
dispDevNum |
显示设备数量 | 1 或 2 |
intfType |
输出接口类型 | hdmi, vga, mipi, ttl, bt1120, hdmi&vga 等 |
timing |
输出时序 | 720P_60, 1080P_60, 3840x2160_30 等 |
chnNum |
画面数量 | disp0: 1~64, disp1: 1~32 |
rotate |
旋转角度 | 0: 0°, 1: 90°, 2: 180°, 3: 270°, 4: 不旋转 |
vdec 参数说明：
| 参数 | 说明 | 可选值 |
|---|---|---|
vdecDevNum |
解码设备数量 | 1（仅使用 vdec0） |
chnNum |
通道数量 | 1~64 |
compressEn |
压缩使能 | 0: 不压缩, 1: LSYC0 压缩 |
vdecAttr |
通道属性配置 | 见下方 |
其中vdecDevNum字段在config_nvr.json 中未使用。
vdecAttr 参数说明：
| 参数 | 说明 | 可选值 |
|---|---|---|
chnId |
通道 ID | 0~63 |
picWidth |
码流宽度 | 自动或手动指定 |
picHeight |
码流高度 | 自动或手动指定 |
codecType |
码流类型 | 0: H.264, 1: H.265 |
refFrameNum |
参考帧数量 | 依据实际码流配置，如0,1,2等 |
esAddHead |
码流加头 | 0: 不加头, 1: 加头 |
filePath |
码流文件路径 | 相对或绝对路径 |
3.3.4 使用示例¶
示例 1：4 路码流解码显示
配置文件 config_nvr.json：
{
"dispDevNum": 1,
"dispArgs_0": {
"intfType": "hdmi",
"timing": "720x576_30",
"chnNum": 4,
"rotate": 4
},
"vdecDevNum": 1,
"vdecArgs": {
"chnNum": 4,
"compressEn": 1,
"vdecAttr": [
{"chnId": 0, "codecType": 1, "filePath": "720x576@30.h265"},
{"chnId": 1, "codecType": 1, "filePath": "720x576@30.h265"},
{"chnId": 2, "codecType": 1, "filePath": "720x576@30.h265"},
{"chnId": 3, "codecType": 1, "filePath": "720x576@30.h265"}
]
}
}
运行：
把sgs_demo_nvr和config_nvr.json拷贝到共享路径（比如PC端的E:\platform\test路径）。
进入共享路径（比如进入板子路径/mnt/test下）执行以下命令：
示例 2：16 路码流解码显示
修改配置文件中的 chnNum 为 16，并添加对应的码流文件配置。
3.4 测试 Case 命令¶
nvr_demo 支持多种测试场景，运行后会提示输入命令：
| Case ID | 说明 |
|---|---|
| 0 | 退出程序 |
| 1 | 手动切屏 |
| 2 | 自动循环随机切屏（5s 切换） |
| 3 | 手动切换分辨率 |
| 4 | 自动循环随机切换分辨率（5s 切换） |
| 5 | 全屏画面显示 PIP |
| 6 | DISP zoom 功能 |
| 7 | 抓图（VDEC→VENC→File） |
| 8 | 静帧功能（暂停解码） |
| 9 | VDISP Case（VDEC→SCL→VDISP→DISP） |
| 10 | 获取所有 VDEC 通道状态 |
| 11 | 设定 HDMI 输出参数 |
| 12 | 鼠标显示和移动 |
| 13 | 设置 VDEC 送帧间隔时间 |
| 14 | 设置 Alpha 值（0~ff） |
| 15 | GFX 操作（缩放、旋转、镜像、Alpha 混合） |
| 16 | YUV 旋转并保存到文件 |
| 17 | 读 UI 文件到 framebuffer |
| 18 | SCL stretch |
| 20 | GFX quickfill 到 framebuffer |
| 21 | FB 放大（1920x1080→4K） |
| 22 | 同源/异源切换 |
| 23 | 零通道编码（WBC→VENC→File） |
| 24 | EPTZ Case（1 路 Pano + 5 路 eptz） |
| 25 | 设置 ColorKey 值 |
| 26 | 双层 UI 融合显示 |
3.5 运行结果¶
3.5.1 成功启动标志¶
终端输出：
此时：
- VDEC 通道已创建并启动
- DISP 通道已创建并启动
- 码流开始解码并显示
3.5.2 验证解码状态¶
查看 VDEC 通道状态：
查看 DISP 通道状态：
3.5.3 抓拍功能¶
运行时输入 Case 7，程序会将指定通道的数据编码为 JPEG 并保存到文件。
3.5.4 退出程序¶
输入 Case 0，程序会自动：
- 停止 VDEC 解码
- 停止 DISP 显示
- 解绑所有通道
- 销毁所有设备
- 释放所有资源
4. MI 文档使用指南¶
4.1 MI 文档结构¶
MI文档主要由两部分组成：API头文件和API参考文档。
4.1.1 API 头文件¶
位于 project/release/include/，包含：
- 接口声明：函数原型、参数说明
- 数据类型：结构体、枚举、宏定义
- 注释说明：简要功能描述
4.1.2 API 参考文档¶
位于 project/release/docs/（如果存在），包含：
- 详细功能描述
- 参数详细说明
- 返回值说明
- 使用示例
- 注意事项
4.2 查找 API 文档的方法¶
4.2.1 按模块查找¶
每个功能模块有对应的头文件。
| 功能模块 | 头文件 |
|---|---|
| 系统管理 | mi_sys.h |
| 解码 | mi_vdec.h |
| 显示 | mi_disp.h |
| 编码 | mi_venc.h |
| 缩放 | mi_scl.h |
| 图形处理 | mi_gfx.h |
| 帧缓冲 | mi_fb.h |
| HDMI | mi_hdmi.h |
4.2.2 按功能查找¶
使用 grep 搜索关键函数。
# 在头文件中搜索函数
cd project/release/include
grep -r "MI_VDEC_SendStream" . --include="*.h"
# 搜索数据类型
grep -r "MI_VDEC_ChnAttr_t" . --include="*.h"
4.2.3 查看模块 ID¶
所有模块 ID 定义在 mi_common_datatype.h 文件中。
typedef enum {
E_MI_MODULE_ID_SYS = 9,
E_MI_MODULE_ID_VDEC = 1,
E_MI_MODULE_ID_DISP = 5,
E_MI_MODULE_ID_VENC = 2,
E_MI_MODULE_ID_SCL = 34,
E_MI_MODULE_ID_GFX = 4,
// ...
} MI_ModuleId_e;
4.3 阅读头文件的技巧¶
4.3.1 重点关注内容¶
- 函数声明：了解函数名称、参数、返回值
- 数据类型定义：理解结构体成员含义
- 枚举值：了解可选的配置选项
- 宏定义：常用的常量和边界值
- 注释：简要的使用说明
4.3.2 典型头文件结构¶
以 mi_vdec.h 为例。
#ifndef _MI_VDEC_H_
#define _MI_VDEC_H_
#include "mi_common.h" // 公共类型
#include "mi_vdec_datatype.h" // 数据类型定义
#define MI_VDEC_API_VERSION ... // 版本信息
#ifdef __cplusplus
extern "C" {
#endif
// 核心 API
MI_S32 MI_VDEC_CreateDev(MI_U32 u32DevId, MI_VDEC_InitParam_t *pstInitParam);
MI_S32 MI_VDEC_DestroyDev(MI_U32 u32DevId);
MI_S32 MI_VDEC_CreateChn(MI_U32 u32DevId, MI_VDEC_ChnId_t Chn, MI_VDEC_ChnAttr_t *pstAttr);
// ...
#ifdef __cplusplus
}
#endif
#endif
4.4 理解数据类型¶
4.4.1 基础数据类型¶
所有基础类型定义在 mi_common_datatype.h 文件中。
typedef unsigned char MI_U8; // 1 字节
typedef unsigned short MI_U16; // 2 字节
typedef unsigned int MI_U32; // 4 字节
typedef unsigned long long MI_U64; // 8 字节
typedef signed char MI_S8; // 1 字节
typedef signed short MI_S16; // 2 字节
typedef signed int MI_S32; // 4 字节
typedef signed long long MI_S64; // 8 字节
4.4.2 模块通用类型¶
每个通道和设备类型的定义如下。
typedef MI_S32 MI_VDEC_DEV; // VDEC 设备类型
typedef MI_S32 MI_VDEC_CHN; // VDEC 通道类型
typedef MI_S32 MI_DISP_DEV; // DISP 设备类型
typedef MI_S32 MI_DISP_CHN; // DISP 通道类型
4.5 错误码处理¶
4.5.1 错误码定义¶
通用错误码定义在 mi_common_datatype.h 文件中。
typedef enum {
E_MI_ERR_INVALID_DEVID = 1, // 无效设备 ID
E_MI_ERR_INVALID_CHNID = 2, // 无效通道 ID
E_MI_ERR_ILLEGAL_PARAM = 3, // 非法参数
E_MI_ERR_EXIST = 4, // 资源已存在
E_MI_ERR_UNEXIST = 5, // 资源不存在
E_MI_ERR_NULL_PTR = 6, // 空指针
E_MI_ERR_NOT_CONFIG = 7, // 未配置
E_MI_ERR_NOT_SUPPORT = 8, // 不支持
E_MI_ERR_NOMEM = 12, // 内存不足
E_MI_ERR_NOBUF = 13, // 缓冲区不足
E_MI_ERR_NOT_INIT = 21, // 未初始化
E_MI_ERR_BUSY = 18, // 资源忙
// ...
} MI_ErrCode_e;
4.6 版本信息¶
每个模块都有版本号宏。
// mi_vdec.h
#define VDEC_MAJOR_VERSION 3
#define VDEC_SUB_VERSION 18
#define MI_VDEC_API_VERSION "mi_vdec_version_3.18"
// mi_disp.h
#define DISP_MAJOR_VERSION 3
#define DISP_SUB_VERSION 14
#define MI_DISP_API_VERSION "mi_disp_version_3.14"
运行时获取版本：