Sgs NVR Application Development Guide¶
This document introduces the development process, key concepts, and usage methods of Sgs NVR applications, helping developers quickly master NVR application development based on the SGS MI system.
REVISION HISTORY¶
| Revision No. | Description |
Date |
|---|---|---|
| 1.0 | 01/20/2026 |
1. Introduction to Basic Concepts¶
1.1 Sgs MI System Overview¶
Sgs MI (Module Interface) system is a multimedia software development kit for the SGS SoC platform, providing a complete set of unified API interfaces to access underlying hardware IPs. Through modular design, the MI system abstracts complex hardware operations into simple and easy-to-use interfaces, enabling developers to focus on application layer logic without worrying about underlying hardware details.
Core Features:
- Hardware Abstraction: Shields hardware differences between different chips
- Modular Design: Each functional module is independently managed, including VDEC, DISP, VENC, SCL, etc.
- Unified Interface: All modules follow the same calling convention
- Cross-platform Support: Supports multiple operating systems including PureRTOS, PureLinux, DualOS, LightningBoot, etc.
1.2 NVR Key Module Description¶
1.2.1 MI_SYS (System Module)¶
Purpose: Core system module, responsible for global initialization, resource management, and data transfer between modules.
Main Functions:
- System initialization and exit (
MI_SYS_Init/MI_SYS_Exit) - Inter-module channel binding (
MI_SYS_BindChnPort) - Memory management (MMA heap allocation)
- Buffer management (Buffer allocation and transfer)
- Timestamp management (PTS synchronization)
Header Files:
mi_sys.h: Main API interfacesmi_sys_datatype.h: Data type definitions
1.2.2 MI_VDEC (Video Decoding Module)¶
Purpose: Decodes video streams in formats such as H.264/H.265/JPEG
Main Functions:
- Decode device creation/destruction (
MI_VDEC_CreateDev/MI_VDEC_DestroyDev) - Decode channel creation/destruction (
MI_VDEC_CreateChn/MI_VDEC_DestroyChn) - Decode parameter configuration (stream type, resolution, etc.)
- Stream input (
MI_VDEC_SendStream) - Decode channel control (
MI_VDEC_StartChn/MI_VDEC_StopChn)
Header Files:
mi_vdec.hmi_vdec_datatype.h
Key Data Types:
typedef enum {
E_MI_VDEC_CODEC_TYPE_H264 = 0, // H.264 encoding
E_MI_VDEC_CODEC_TYPE_H265, // H.265 encoding
// ...
} MI_VDEC_CodecType_e;
1.2.3 MI_DISP (Display Module)¶
Purpose: Outputs video data to display devices, including HDMI, VGA, MIPI, etc.
Main Functions:
- Display device creation/destruction (
MI_DISP_CreateDevice/MI_DISP_DestroyDevice) - Display layer management (Layer)
- Channel management (
MI_DISP_CreateChn/MI_DISP_DestroyChn) - Output timing configuration (
MI_DISP_SetOutputTiming) - Display area setting (
MI_DISP_SetChnDispRect)
Header Files:
mi_disp.hmi_disp_datatype.h
Supported Output Interfaces:
- HDMI
- VGA
- MIPI
- TTL
- BT1120
1.2.4 MI_SCL (Scaling Module)¶
Purpose: Performs image scaling processing, supporting multiple outputs with different resolutions
Main Functions:
- Image scaling
- Cropping
- Multiple outputs
- Rotation support
Header Files:
mi_scl.hmi_scl_datatype.h
1.2.5 MI_VENC (Video Encoding Module)¶
Purpose: Encodes YUV images into formats such as H.264/H.265/JPEG
Main Functions:
- Encoding channel creation/destruction (
MI_VENC_CreateChn/MI_VENC_DestroyChn) - Encoding parameter configuration (bitrate, GOP, QP, etc.)
- Stream acquisition (
MI_VENC_GetStream) - IDR frame request (
MI_VENC_RequestIdr)
Header Files:
mi_venc.hmi_venc_datatype.h
1.2.6 MI_GFX (Graphics Processing Module)¶
Purpose: Provides graphics processing functions (scaling, rotation, overlay, etc.)
Main Functions:
- BitBlit (bitmap copying)
- Image scaling
- Image rotation (0°/90°/180°/270°)
- Mirror flip
- Alpha blending
Header Files:
mi_gfx.hmi_gfx_datatype.h
1.2.7 MI_FB (Frame Buffer Module)¶
Purpose: Manages Framebuffer for UI display
Main Functions:
- Framebuffer device management
- Alpha value setting (Global/Pixel Alpha)
- ColorKey setting
- Get Framebuffer address
Header Files:
mi_fb.hmi_fb_datatype.h
1.2.8 MI_HDMI (HDMI Output Module)¶
Purpose: Configures HDMI output parameters
Main Functions:
- HDMI initialization and exit
- Output timing setting
- Color space conversion configuration
- Signal gain and sharpness adjustment
Header Files:
mi_hdmi.hmi_hdmi_datatype.h
1.3 Data Flow and Control Flow¶
1.3.1 Data Flow¶
The data flow of NVR applications is unidirectional, with typical data flow as follows:
Detailed Flow Description:
- Stream Input: Read H.264/H.265 streams from files or network
- VDEC Decoding: VDEC module decodes the stream and outputs YUV data
- SCL Processing: SCL scales YUV data to target resolution, can output multiple paths with different resolutions, and can also perform rotation output
- DISP Display: DISP outputs YUV data to display devices (HDMI, VGA, etc.)
Typical Pipeline (4 streams as example):
+----------+ +-------+ +-----------+ +--------------------+
| Stream 0 | --> | VDEC0 | --> | SCL0(rot) | --> | Port0 | |
+----------+ +-------+ +-----------+ +-------+ |
| |
+----------+ +-------+ +-------+ |
| Stream 1 | --> | VDEC1 | --------------------> | Port1 | |
+----------+ +-------+ +-------+ |
| DISP0 | --> Screen (multi-screen display)
+----------+ +-------+ +-------+ |
| Stream 2 | --> | VDEC2 | --------------------> | Port2 | |
+----------+ +-------+ +-------+ |
| |
+----------+ +-------+ +-------+ |
| Stream 3 | --> | VDEC3 | --------------------> | Port3 | |
+----------+ +-------+ + -------------------+
1.3.2 Control Flow¶
Control flow refers to the process of configuring and managing each module, mainly including:
-
Initialization Phase:
MI_SYS_Init(): Initialize the system- Read configuration file (JSON format)
- Create devices:
MI_VDEC_CreateDev(),MI_DISP_CreateDevice(), etc. - Configure parameters: Set module attributes
- Create channels:
MI_VDEC_CreateChn(),MI_DISP_CreateChn(), etc.
-
Binding Phase:
MI_SYS_BindChnPort(): Establish data transfer channels between modules
-
Startup Phase:
- Enable devices:
MI_DISP_EnableInputPort(), etc. - Start channels for decoding:
MI_VDEC_StartChn()
- Enable devices:
-
Running Phase:
- Read streams: Read H.264/H.265 streams from files
- Send streams:
MI_VDEC_SendStream() - Handle user input: Screen switching, snapshot, etc.
-
Shutdown Phase:
- Stop channels:
MI_VDEC_StopChn() - Disable devices:
MI_DISP_DisableInputPort(), etc. - Unbind channels:
MI_SYS_UnBindChnPort() - Destroy channels/devices
MI_SYS_Exit(): Exit system
- Stop channels:
1.4 Channel and Port Concepts¶
1.4.1 Device¶
- Definition: Represents a hardware device instance
- Examples: VDEC device 0, DISP device 0, VENC device 8, etc.
- Purpose: Manages global configuration of hardware resources
1.4.2 Channel¶
- Definition: Independent data channel on a device
- Examples: VDEC channel 0~63 (supports multi-stream decoding), DISP channel 0~63 (supports multi-screen display)
- Purpose: Supports multiple independent data streams
1.4.3 Port¶
-
Definition: Input or output interface on a channel
-
Types:
- InputPort: Input port, receives data from upstream modules
- OutputPort: Output port, sends data to downstream modules
-
Purpose: Bridge for data transfer between modules
1.4.4 ChnPort (Channel Port)¶
-
Definition: A structure composed of ModuleId, DevId, ChnId, PortId
-
Structure:
typedef struct { MI_ModuleId_e eModId; // Module ID (e.g., E_MI_MODULE_ID_VDEC) MI_U32 u32DevId; // Device ID MI_U32 u32ChnId; // Channel ID MI_U32 u32PortId;// Port ID } MI_SYS_ChnPort_t; -
Purpose: Uniquely identifies an input or output port of a module
1.5 BindType (Binding Mode)¶
Binding mode defines the way data is transferred between modules, mainly specified through the MI_SYS_BindType_e enumeration type.
1.5.1 Common Binding Modes for NVR¶
| Binding Mode | Enumeration Value | Hexadecimal | Abbreviation |
|---|---|---|---|
| Frame Mode | E_MI_SYS_BIND_TYPE_FRAME_BASE | 0x00000001 (1) | F |
2. Application Development Process¶
2.1 Development Environment Preparation¶
2.1.1 Hardware Requirements¶
- SGS SoC development board (chip supporting NVR functionality)
- Display device (HDMI/VGA/MIPI screen)
- Storage device (for storing stream files)
2.1.2 Software Dependencies¶
- Cross-compilation toolchain: Select based on target chip (e.g., aarch64-linux-gnu-gcc)
- MI libraries:
libmi_sys.so,libmi_vdec.so,libmi_disp.so, etc. - Third-party libraries:
libcjson.so(configuration file parsing) - System libraries:
libpthread.so
2.1.3 Header File Paths¶
MI header files are located in the project/release/include/ directory.
Common header files:
#include "mi_sys.h" // System module
#include "mi_vdec.h" // Decoding module
#include "mi_disp.h" // Display module
#include "mi_scl.h" // Scaling module
#include "mi_venc.h" // Encoding module
#include "mi_gfx.h" // Graphics processing module
#include "mi_fb.h" // Frame buffer module
#include "mi_hdmi.h" // HDMI module
2.2 Standard MI API Development Process¶
2.2.1 Initialization Process¶
// 1. Initialize system
MI_SYS_Init(0);
// 2. Create VDEC device
MI_VDEC_InitParam_t vdecInitParam;
// ... configure vdecInitParam
MI_VDEC_CreateDev(0, &vdecInitParam);
// 3. Create DISP device
MI_DISP_InitParam_t dispInitParam;
// ... configure dispInitParam
MI_DISP_CreateDevice(0, &dispInitParam);
// 4. Create VDEC channel
MI_VDEC_ChnAttr_t vdecChnAttr;
// ... configure vdecChnAttr
MI_VDEC_CreateChn(0, vdecChn, &vdecChnAttr);
// 5. Create DISP channel
MI_DISP_ChnAttr_t dispChnAttr;
// ... configure dispChnAttr
MI_DISP_CreateChn(0, dispChn, &dispChnAttr);
2.2.2 Binding Process¶
// Define source and destination ports
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
};
// Bind (Frame Mode)
MI_SYS_BindChnPort(0, &srcPort, &dstPort,
30, 30, // Frame rate
E_MI_SYS_BIND_TYPE_FRAME_BASE, 0);
2.2.3 Startup Process¶
// 1. Enable DISP channel
MI_DISP_EnableChn(0, dispChn);
// 2. Enable DISP input port
MI_DISP_EnableInputPort(layerId, dispPortId);
// 3. Start channel decoding
MI_VDEC_StartChn(0, vdecChn);
2.2.4 Running and Data Input¶
// Read stream from file and send to decoder
FILE *fp = fopen("stream.h265", "rb");
MI_VDEC_Stream_t stream;
MI_VDEC_Data_t data;
while (running) {
// Read stream data
size_t readSize = fread(buffer, 1, buffer_size, fp);
if (readSize <= 0) break;
// Fill data structure
data.pu8Addr = buffer;
data.u32Len = readSize;
data.u64PTS = pts;
data.bEndOfFrame = TRUE;
stream.pstData = &data;
stream.u32DataCount = 1;
// Send stream
MI_VDEC_SendStream(0, vdecChn, &stream, -1);
}
fclose(fp);
2.2.5 Cleanup Process¶
// 1. Stop channel decoding
MI_VDEC_StopChn(0, vdecChn);
// 2. Disable modules
MI_DISP_DisableInputPort(layerId, dispPortId);
MI_DISP_DisableChn(0, dispChn);
// 3. Unbind
MI_SYS_UnBindChnPort(0, &srcPort, &dstPort);
// 4. Destroy channels and devices
MI_DISP_DestroyChn(0, dispChn);
MI_DISP_DestroyDevice(0);
MI_VDEC_DestroyChn(0, vdecChn);
MI_VDEC_DestroyDev(0);
// 5. Exit system
MI_SYS_Exit(0);
2.3 Key Development Points¶
2.3.1 Configuration File Management¶
NVR demo uses JSON format configuration files, containing the following main configurations.
- disp configuration: Display device parameters, including interface type, timing, channel count, etc.
- fb configuration: Framebuffer parameters, including Alpha type, UI file path, etc.
- vdec configuration: Decoding device parameters, including channel count, compression enable, stream attributes, etc.
Configuration file example:
{
"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 Error Handling¶
All MI APIs return MI_S32 type.
MI_SUCCESS(0): Success- Non-zero: Failure (see
mi_common_datatype.hfor specific error codes)
2.3.3 Resource Management¶
- Creation order: System → Device → Channel
- Destruction order: Channel → Device → System (reverse of creation)
- Memory management: Use MMA heap to allocate memory, remember to free
2.3.4 Thread Safety¶
- MI APIs are generally thread-safe
- The same channel of the same device cannot be operated simultaneously in multiple threads
- Recommend using mutex locks to protect shared resources
2.3.5 Performance Optimization¶
- Reasonably set buffer depth (
MI_SYS_SetChnOutputPortDepth) - Use compression mode (LSYC) to reduce bandwidth
- Avoid frequent creation and destruction operations
- Choose appropriate binding mode
3. nvr_demo Compilation and Usage¶
3.1 Demo Function Overview¶
nvr_demo demonstrates a complete NVR video Pipeline.
- Read H.264/H.265 streams from files
- Decode via VDEC
- Scale and rotate via SCL (optional)
- Display to screen via DISP
- Support various test scenarios, including screen switching, snapshot, PIP, etc.
Pipeline Diagram:
+----------+ +-------+ +------+ +-------+
| Stream 0 | --> | VDEC0 | --> | SCL0 | --> | DISP0 | --> Screen
+----------+ +-------+ +------+ +-------+
|
v
+-------+
| VENC8 | --> File (snapshot)
+-------+
3.2 Compilation Method¶
3.2.1 Project Directory Structure¶
sdk/verify/sample_code/demo/
├── nvr/nvr/ # nvr demo directory
│ ├── sgs_demo_nvr.c # Main program
│ ├── nvr.mk # Compilation configuration
│ ├── dep.mk # Dependency configuration
│ ├── config_nvr.json # Configuration file
│ └── readme_zh.md # Usage instructions
| ...
├── nvr/internal/ # Internal components
│ ├── common/ # Common components
│ ├── sys/ # System components
│ ├── vdec/ # Decoding components
│ ├── disp/ # Display components
│ ├── scl/ # Scaling components
│ ├── venc/ # Encoding components
│ ├── gfx/ # Graphics components
│ ├── fb/ # Frame buffer components
│ └── hdmi/ # HDMI components
| ...
3.2.2 Compilation Steps¶
Prerequisites: Ensure cross-compilation toolchain is configured.
Method 1: Compile nvr demo alone
# Enter SDK root directory
cd SourceCode/sdk/verify/sample_code
# Compile nvr demo
make demo/nvr/nvr
# Clean compilation outputs
make demo/nvr/nvr_clean
Method 2: Full package compilation
# Enter project directory
cd SourceCode/project
# Select defconfig (based on board model)
# For example: 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
# Compile full package
make clean && make image -j8
3.2.3 Compilation Output¶
After successful compilation, the executable file is located at:
Where <arch> is determined by the build configuration, for example arm64.
3.2.4 Dependency Library Description¶
According to nvr.mk, the following libraries are depended on.
LIBS += -lmi_common # Common library
LIBS += -lmi_disp # Display module
LIBS += -lmi_hdmi # HDMI module
LIBS += -lmi_vdec # Decoding module
LIBS += -lmi_jpd # JPEG decoding
LIBS += -lmi_venc # Encoding module
LIBS += -lmi_scl # Scaling module
LIBS += -lmi_gfx # Graphics processing
LIBS += -lmi_vdisp # Virtual display
pthread/cjson are automatically linked via dep.mk dependency and build system; they are not explicitly listed in nvr.mk.
3.3 Usage Method¶
3.3.1 Preparation Before Running¶
-
Prepare Stream Files
- Prepare H.264/H.265 stream files
- Place in the same directory as the executable
-
Prepare UI Resource Files (optional)
- Mouse icon file:
cursor_argb1555.bin - UI file:
1920x1080_argb1555.bin - Place in the same directory as the executable
- Mouse icon file:
-
Modify Configuration File
- Modify
config_nvr.jsonaccording to actual requirements - Configure display parameters, decoding parameters, etc.
- Modify
Stream files and resource files are located at SourceCode/sdk/verify/sample_code/demo/nvr/nvr/resource.
3.3.2 Command Line Arguments¶
Parameter Description:
config_file: Path to JSON format configuration file
Example:
3.3.3 Configuration File Details¶
disp Parameter Description:
| Parameter | Description | Optional Values |
|---|---|---|
dispDevNum |
Number of display devices | 1 or 2 |
intfType |
Output interface type | hdmi, vga, mipi, ttl, bt1120, hdmi&vga, etc. |
timing |
Output timing | 720P_60, 1080P_60, 3840x2160_30, etc. |
chnNum |
Number of screens | disp0: 1~64, disp1: 1~32 |
rotate |
Rotation angle | 0: 0°, 1: 90°, 2: 180°, 3: 270°, 4: no rotation |
vdec Parameter Description:
| Parameter | Description | Optional Values |
|---|---|---|
vdecDevNum |
Number of decoding devices | 1 (only use vdec0) |
chnNum |
Number of channels | 1~64 |
compressEn |
Compression enable | 0: no compression, 1: LSYC0 compression |
vdecAttr |
Channel attribute configuration | See below |
The vdecDevNum field is not used in config_nvr.json.
vdecAttr Parameter Description:
| Parameter | Description | Optional Values |
|---|---|---|
chnId |
Channel ID | 0~63 |
picWidth |
Stream width | Auto or manually specified |
picHeight |
Stream height | Auto or manually specified |
codecType |
Stream type | 0: H.264, 1: H.265 |
refFrameNum |
Number of reference frames | Configure according to actual stream, such as 0, 1, 2, etc. |
esAddHead |
Add stream header | 0: no header, 1: add header |
filePath |
Stream file path | Relative or absolute path |
3.3.4 Usage Examples¶
Example 1: 4-stream decoding and display
Configuration file 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"}
]
}
}
Run:
Copy sgs_demo_nvr and config_nvr.json to a shared path (e.g., E:\platform\test on the PC side).
Enter the shared path on the board (e.g., /mnt/test) and run the following command:
Example 2: 16-stream decoding and display
Modify chnNum in the configuration file to 16 and add corresponding stream file configurations.
3.4 Test Case Commands¶
nvr_demo supports various test scenarios. After running, it will prompt for command input:
| Case ID | Description |
|---|---|
| 0 | Exit program |
| 1 | Manual screen switching |
| 2 | Automatic cyclic random screen switching (5s switch) |
| 3 | Manual resolution switching |
| 4 | Automatic cyclic random resolution switching (5s switch) |
| 5 | Full-screen display with PIP |
| 6 | DISP zoom function |
| 7 | Snapshot (VDEC→VENC→File) |
| 8 | Static frame function (pause decoding) |
| 9 | VDISP Case (VDEC→SCL→VDISP→DISP) |
| 10 | Get all VDEC channel status |
| 11 | Set HDMI output parameters |
| 12 | Mouse display and movement |
| 13 | Set VDEC frame sending interval |
| 14 | Set Alpha value (0~ff) |
| 15 | GFX operations (scaling, rotation, mirror, Alpha blending) |
| 16 | YUV rotation and save to file |
| 17 | Read UI file to framebuffer |
| 18 | SCL stretch |
| 20 | GFX quickfill to framebuffer |
| 21 | FB zoom (1920x1080→4K) |
| 22 | Same-source/different-source switching |
| 23 | Zero-channel encoding (WBC→VENC→File) |
| 24 | EPTZ Case (1 Pano + 5 eptz) |
| 25 | Set ColorKey value |
| 26 | Dual-layer UI fusion display |
3.5 Running Results¶
3.5.1 Successful Startup Indicator¶
Terminal output:
At this point:
- VDEC channels have been created and started
- DISP channels have been created and started
- Streams have started decoding and displaying
3.5.2 Verify Decoding Status¶
Check VDEC channel status:
Check DISP channel status:
3.5.3 Snapshot Function¶
When running, input Case 7, and the program will encode the specified channel data to JPEG and save to file.
3.5.4 Exit Program¶
Input Case 0, and the program will automatically:
- Stop VDEC decoding
- Stop DISP display
- Unbind all channels
- Destroy all devices
- Release all resources
4. MI Documentation Usage Guide¶
4.1 MI Documentation Structure¶
MI documentation mainly consists of two parts: API header files and API reference documentation.
4.1.1 API Header Files¶
Located in project/release/include/, containing:
- Interface declarations: Function prototypes, parameter descriptions
- Data types: Structures, enumerations, macro definitions
- Comment descriptions: Brief functional descriptions
4.1.2 API Reference Documentation¶
Located in project/release/docs/ (if exists), containing:
- Detailed functional descriptions
- Detailed parameter descriptions
- Return value descriptions
- Usage examples
- Notes
4.2 Methods for Finding API Documentation¶
4.2.1 Search by Module¶
Each functional module has a corresponding header file.
| Functional Module | Header File |
|---|---|
| System management | mi_sys.h |
| Decoding | mi_vdec.h |
| Display | mi_disp.h |
| Encoding | mi_venc.h |
| Scaling | mi_scl.h |
| Graphics processing | mi_gfx.h |
| Frame buffer | mi_fb.h |
| HDMI | mi_hdmi.h |
4.2.2 Search by Function¶
Use grep to search for key functions.
# Search for functions in header files
cd project/release/include
grep -r "MI_VDEC_SendStream" . --include="*.h"
# Search for data types
grep -r "MI_VDEC_ChnAttr_t" . --include="*.h"
4.2.3 View Module IDs¶
All module IDs are defined in the mi_common_datatype.h file.
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 Tips for Reading Header Files¶
4.3.1 Key Focus Areas¶
- Function declarations: Understand function names, parameters, return values
- Data type definitions: Understand structure member meanings
- Enumeration values: Understand available configuration options
- Macro definitions: Common constants and boundary values
- Comments: Brief usage instructions
4.3.2 Typical Header File Structure¶
Take mi_vdec.h as an example.
#ifndef _MI_VDEC_H_
#define _MI_VDEC_H_
#include "mi_common.h" // Common types
#include "mi_vdec_datatype.h" // Data type definitions
#define MI_VDEC_API_VERSION ... // Version information
#ifdef __cplusplus
extern "C" {
#endif
// Core APIs
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 Understanding Data Types¶
4.4.1 Basic Data Types¶
All basic types are defined in the mi_common_datatype.h file.
typedef unsigned char MI_U8; // 1 byte
typedef unsigned short MI_U16; // 2 bytes
typedef unsigned int MI_U32; // 4 bytes
typedef unsigned long long MI_U64; // 8 bytes
typedef signed char MI_S8; // 1 byte
typedef signed short MI_S16; // 2 bytes
typedef signed int MI_S32; // 4 bytes
typedef signed long long MI_S64; // 8 bytes
4.4.2 Module Common Types¶
Each channel and device type definition is as follows.
typedef MI_S32 MI_VDEC_DEV; // VDEC device type
typedef MI_S32 MI_VDEC_CHN; // VDEC channel type
typedef MI_S32 MI_DISP_DEV; // DISP device type
typedef MI_S32 MI_DISP_CHN; // DISP channel type
4.5 Error Code Handling¶
4.5.1 Error Code Definitions¶
Common error codes are defined in the mi_common_datatype.h file.
typedef enum {
E_MI_ERR_INVALID_DEVID = 1, // Invalid device ID
E_MI_ERR_INVALID_CHNID = 2, // Invalid channel ID
E_MI_ERR_ILLEGAL_PARAM = 3, // Illegal parameter
E_MI_ERR_EXIST = 4, // Resource exists
E_MI_ERR_UNEXIST = 5, // Resource does not exist
E_MI_ERR_NULL_PTR = 6, // Null pointer
E_MI_ERR_NOT_CONFIG = 7, // Not configured
E_MI_ERR_NOT_SUPPORT = 8, // Not supported
E_MI_ERR_NOMEM = 12, // Out of memory
E_MI_ERR_NOBUF = 13, // Insufficient buffer
E_MI_ERR_NOT_INIT = 21, // Not initialized
E_MI_ERR_BUSY = 18, // Resource busy
// ...
} MI_ErrCode_e;
4.6 Version Information¶
Each module has a version number macro.
// 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"
Get version at runtime: