3.1. Example Code Introduction

This chapter mainly introduces example code for functional modules on the chip, primarily including usage examples of multimedia hardware acceleration modules. It contains single-module function examples, multi-module cascaded combination examples, and application solution examples. Users can use these examples to quickly complete functional evaluations, and by referring to the implementation code, they can rapidly get started and develop applications tailored to their own needs.

For an introduction to the multimedia-related hardware acceleration modules covered in this chapter and their relationships, please refer to Multimedia Development Guide - System Overview.

By using the examples provided in this chapter, users will be able to:

Understand the basic functions and applicable scenarios of each hardware acceleration module.
Learn how to efficiently combine multiple modules to solve practical problems.
Quickly master the usage of example code, thereby saving development time.

3.1.1. Example Source Code Directory Structure

All example code source files are stored under the app/samples/platform_samples directory in the BSP source code.

The source code directory structure is organized and named according to functionality and use cases:

.
├── chip_base_test    # Driver unit test; refer to [BSP Development Guide - Driver Unit Test] for usage
├── Makefile          # Central compilation entry for all modules (sunrise_camera does not use this Makefile)
├── Makefile.in       # Configuration file for Makefile, including toolchain, header and library paths
├── README.md
├── sample_audio      # Audio recording and playback examples based on ALSA (Advanced Linux Sound Architecture) library
├── sample_codec      # Example code for video/image encoding and decoding modules, including H264\H265\JPEG\MJPEG encoding and decoding
├── sample_crypto     # Demonstrates usage of common security operation interfaces through multiple operation examples
├── sample_dsp        # Mainly illustrates how to simply use DSP for task processing on the chip
├── sample_gdc        # Example code for various transformation modes supported by the GDC module
├── sample_gpu_2d     # Example code for various functions supported by 2D GPU
├── sample_hbmem      # This example introduces the API usage of a memory management library based on ION
├── sample_imu        # This example is a command-line case for using inertial navigation sensors
├── sample_isp        # Example code for the ISP module, including how to initialize ISP, obtain data after ISP processing, and dynamically set ISP parameters
├── sample_osd        # Introduction on how to use OSD functionality
├── sample_pipeline   # Example code for cascading multiple functional modules, e.g., VIN->ISP->VSE->CODEC for encoding data path testing
├── sample_usb        # Provides examples for USB UVC and UAC functions
├── sample_trustzone  # Simple example code for TA and CA
├── sample_vin        # Initialize Camera Sensor and obtain images from the VIN module
├── sample_vot        # Provides video/image display functionality based on the DRM framework
├── sample_vse        # Initialize the VSE module and perform image scaling operations using VSE
├── sunrise_camera    # Application-level example code integrating most modules, supporting smart cameras and intelligent analysis boxes, with video and AI algorithm results viewable via web interface
├── tuning_tool       # This program is required for ISP image quality tuning
├── utils             # Contains common functions and structures
└── vp_sensors        # Camera Sensor configuration code, used by other modules requiring Camera Sensor

Note: The vp_sensors directory contains supported Camera Sensor devices and configuration files; it is not a standalone example program. For instructions on adding Camera Sensor, please refer to vp_sensors/README.md.

3.1.2. Example Usage Guide

All example programs and their dependent resource files are by default installed under the /app/platform_samples directory on the development board. Users can directly log in to the board and use these examples. For instance, to use the sample_vse example, run the following commands:

cd /app/platform_samples/sample_vse

# Run sample_vse to get program help information

./sample_vse
Usage: sample_vse [OPTIONS]
Options:
  -i, --input_file FILE   Input NV12 file path
  -w, --input_width W     Input width in pixels
  -h, --input_height H    Input height in pixels
  -f, --feedback          Feedback mode (hbn_vnode_start)
  -V, --verbose           Verbose dump of frame structures
  -a, --async             Use hbn_vnode_sendframe_async (default: sync sendframe)
  -b, --buf-num N         Ichn buffer index rotation count [1..16], default 1
  -n, --frames N          Send/Get frame loop iterations (default 1)
  -y, --save-yuv          Save ochn NV12 to ./vse_output_nv12_run*_chn*.yuv

Other examples can be used in the same way.

3.1.3. Example Development Guide

3.1.3.1. Compilation Methods

When compiling the example code in this module, dependencies include the hbre header files and library files generated from the BSP build, as well as headers and shared libraries (e.g., ffmpeg) from the root filesystem. The relevant path references have already been configured in the Makefile.in file as follows:

-I ${HR_BUILD_OUTPUT_DIR}/build/hbre_deps/include
-L ${HR_BUILD_OUTPUT_DIR}/build/hbre_deps/usr/lib
-L ${HR_BUILD_OUTPUT_DIR}/deploy/system/usr/lib

Therefore, before compiling the code in this module, the BSP must first be compiled to generate the required header and library files. For detailed BSP compilation instructions, please refer to Environment Setup and Build Instructions.

Build All Examples Together

After completing the full BSP build, all example codes will be compiled and installed into the BSP’s out/deploy/app/platform_samples directory:
```
./bd.sh
```
Build Individual Example

After completing the full BSP build, individual examples under app/samples/platform_samples can be developed and compiled separately. Two compilation methods are provided below:
1. Direct Compilation from Module Directory
  
  Enter the target module directory and execute the make command. For example, to compile the sample_vin example individually:
```
cd samples/platform_samples/sample_vin/get_vin_data
make
```
  Programs compiled directly with make are generated under the current example’s source directory and will not be installed into the BSP’s out/deploy/app/platform_samples directory.
2. Compilation via BSP Build Framework
  
  Use the BSP build framework by running the following command from the BSP root directory to compile a specific example:
```
./bd.sh app samples/platform_samples
```
  Programs compiled via the BSP build framework are not only generated in the example’s source directory but also will be installed into the BSP’s out/deploy/app/platform_samples directory.

3.1.4. Common Issues

3.1.4.1. Insufficient Space in /app Directory Causes Example Execution Failure

Cause: The /app directory is mounted from the app partition, which has limited space. Some example programs generate large amounts of video/image data during execution, easily filling up the space and causing unexpected program behavior.

Solution: Copy the program to the /userdata directory for execution. The /userdata directory offers significantly more space compared to /app.

3.1.4.2. Kernel Logs Flooding the Console in Serial Terminal

On the target board, run the following command to reduce the kernel log level and prevent excessive log output from interfering with program execution monitoring:

echo 4 > /proc/sys/kernel/printk