#Overview

#General Introduction

• What is UCP?

  The Unify Compute Platform(Unify Compute Platform, hereafter referred to UCP) defines a unified set of heterogeneous programming interfaces, and provides APIs(Application Programming Interface, hereafter referred to API) to enable calls to all resources on the computing platform. UCP abstracts and encapsulates the functional hardware on the SOC, and externally provides function-based APIs for creating corresponding UCP tasks (e.g., VP operator tasks), and supports the setting of a hardware backend to be submitted to the UCP scheduler, which can complete the unified scheduling of tasks on the Soc based on hardware resources.

  Specifically, the following features are provided: Vision Process, Neural Network Inference, High Performance Library and Custom Operator Plugin Development.

  

  For details of the Backend, you can refer to the section Backend Instruction .

• UCP scenarios:

  Call single operator: vision operators and high performance processing operators in UCP can be used directly.

  Operator plugin development and usage: custom operator development is available.

  Deep Learning Model Inference: deep learning model inference tasks can be accomplished, and model parsing and hardware deployment are completed within UCP.

• UCP advantages:

  Highly abstract: for the function of single operator, no need to be troubled by hardware differences, hardware that needs to be executed can be selected by specifying the backend, reducing the difficulty of hardware deployment.

  Highly integrated: as Horizon's unified heterogeneous programming interface, all the requirements development can be completed by a set of interfaces.

#Environment and Tools

UCP is applicable for the Horizon J6 and higher architecture computing platforms, you need to have basic embedded development knowledge and skills to complete the cross-compilation and deployment, the usage of the environment and tool requirements refer to the following table:

The usage of UCP is described in this document with Linux as the default operating system. For other operating systems, please refer to the documentation and adjust the related configurations according to the actual situation.

#Operating Modes

The UCP framework supports two main operating modes: Direct Mode and Relay Mode. The QNX operating system and x86 simulation does not support Relay mode.

By default, the system operates in Direct Mode. In Relay Mode, UCP enables unified scheduling of multi-process tasks. To use Relay Mode, you must first start the ucp_service, which is located at deps_aarch64/ucp/bin/service/. You also need to enable Relay Mode by setting the environment variable HB_UCP_ENABLE_RELAY_MODE=true, allowing user processes to communicate via the relay service. Regardless of whether Direct Mode or Relay Mode is used, the UCP interface calls remain consistent, without impacting the programming logic. You can flexibly choose between these two modes based on the system’s performance and flexibility requirements.

#Interface Usage Flow

There are three ways to execute UCP task structure calls: synchronous execution, asynchronous execution, and registered callback function execution. Here is an example of calling the VP interface hbVPRotate(hbVPRotate) to illustrate the three task execution modes.

#Synchronous Execution

When creating a task, pass the corresponding parameter of the taskHandle into the nullptr, which can be immediately synchronously executed, with the following reference code:

#include "hobot/hb_ucp.h"
#include "hobot/vp/hb_vp_rotate.h"

int main() {
    // step1: execute a rotate task
    hbVPImage src_img;  //do something to init src image
    hbVPImage dst_img;  //do something to init dst image
    hbVPRotate(nullptr, &dst_img, &src_img, HB_VP_ROTATE_90_CLOCKWISE);
    return 0;
}

#Asynchronous Execution

When creating a task, the taskHandle parameter needs to be initialized to nullptr in advance. After submitting a UCP task (hbUCPSubmitTask), executing the interface (hbUCPWaitTaskDone) at the specified location in the thread. Waiting for the task to complete, with the following reference code:

#include "hobot/hb_ucp.h"
#include "hobot/vp/hb_vp_rotate.h"

int main() {
    // step1: create a rotate task
    hbUCPTaskHandle_t task_handle{nullptr};
    hbVPImage src_img;  //do something to init src image
    hbVPImage dst_img;  //do something to init dst image
    hbVPRotate(&task_handle, &dst_img, &src_img, HB_VP_ROTATE_90_CLOCKWISE);

    // step2：complete the commit and execution of the task
    hbUCPSchedParam sched_param;
    sched_param.backend = HB_UCP_DSP_CORE_0;
    sched_param.priority = 0;
    hbUCPSubmitTask(task_handle, &sched_param);
    hbUCPWaitTaskDone(task_handle, 100);
    hbUCPReleaseTask(task_handle);
    return 0;
}

#Registered Callback Function Execution

When creating a task, the taskHandle parameter needs to be initialized to nullptr in advance. The callback function needs to be registered before the task is submitted (hbUCPSubmitTask).

The reference code for setting the callback function is as follows:

#include "hobot/hb_ucp.h"
#include "hobot/vp/hb_vp_rotate.h"

typedef struct {
  std::mutex mutex;
  std::condition_variable cv;
  int32_t status;
} UserData;

void CallBack(hbUCPTaskHandle_t handle, int32_t status, void *userdata) {
  auto data = static_cast<UserData *>(userdata);
  data->status = status;
  data->cv.notify_all();
}

void ProcessThread(void *userdata) {
  auto data = static_cast<UserData *>(userdata);
  {
    std::unique_lock<std::mutex> lk{data->mutex};
    data->cv.wait(lk);
  }
  // do something here
}

int main() {
    // step1: create a rotate task
    hbUCPTaskHandle_t task_handle{nullptr};
    hbVPImage src_img;  //do something to init src image
    hbVPImage dst_img;  //do something to init dst image
    hbVPRotate(&task_handle, &dst_img, &src_img, HB_VP_ROTATE_90_CLOCKWISE);

    // step2: create userdata and custom process thread
    UserData userdata;
    userdata.status = 0;
    std::thread worker(ProcessThread, &userdata);

    // step3：set callback function before submit task
    hbUCPSetTaskDoneCb(task_handle, CallBack, &userdata);

    // step4: submit task
    hbUCPSchedParam sched_param;
    HB_UCP_INITIALIZE_SCHED_PARAM(&sched_param);
    sched_param.backend = HB_UCP_DSP_CORE_0;

    hbUCPSubmitTask(task_handle, &sched_param);

    worker.join();
    hbUCPReleaseTask(task_handle);
    return 0;
}

#DEB Deployment Package

UCP provides a DEB deployment package located at ucp_tutorial/tools/deb/hbucp_aarch64_x.x.x.deb. This package is designed to simplify deployment on the board, ensuring easier and more efficient system configuration. By automatically installing the necessary binaries and dependent libraries, By automatically installing the necessary binaries and dependent libraries, the UCP-related applications can be quickly set up and running.

After successfully installing the DEB package, the binaries ucp_service and hrt_ucp_monitor will automatically be installed in the /usr/bin directory, allowing you to access these tools via the command line. The related dynamic libraries will be installed in the /lib/aarch64-linux-gnu directory, ensuring that all runtime dependencies are correctly configured.

During the installation, the system automatically configures the required library paths, removing the need for manual intervention. This ensures that all dependent libraries are correctly loaded when running applications, thus ensuring the stability and reliability of the system.

#Installation Command Example

When installing the DEB package for the first time, the system will display.

root@hobot:/map/deb# dpkg -i hbucp_aarch64_3.1.4.deb
Selecting previously unselected package hbucp.
(Reading database ... 24647 files and directories currently installed.)
Preparing to unpack hbucp_aarch64_3.1.4.deb ...
Start preinst process with parameter: install
This is a new installation, no checks or backups are required.
Finish preinst process
Unpacking hbucp (3.1.4) ...
Setting up hbucp (3.1.4) ...
Start postinst process with parameter: configure
This is a new installation.
UCP Monitor version: 1.1.0
[UCP]: log level = 3
[UCP]: UCP version = 3.1.4
[VP]: log level = 3
[DNN]: log level = 3
[HPL]: log level = 3
[UCPT]: log level = 6
[DSP]: log level = 3
[DNN] HBTL_EXT_DNN log level:6
UCP SERVICE version: 3.1.4
Finish postinst process

#Upgrade Installation Command Example

When upgrading the DEB package, if the installation process fails, the system will automatically roll back to the previous version.

root@hobot:/map/deb# dpkg -i hbucp_aarch64_3.1.4.deb
(Reading database ... 24661 files and directories currently installed.)
Preparing to unpack hbucp_aarch64_3.1.4.deb ...
Start prerm process with parameter: upgrade
All specified binaries are not running and can be safely processed.
All specified shared libraries and their dependencies are not being used and can be safely processed.
Finish prerm process
Start preinst process with parameter: upgrade
This is an upgrade installation. Performing backups.
Temporary backup directory '/var/tmp/hbucp_backup' created successfully.
Backup completed successfully.
Finish preinst process
Unpacking hbucp (3.1.4) over (3.1.4) ...
Start postrm process with parameter: upgrade
Finish postrm process
Setting up hbucp (3.1.4) ...
Start postinst process with parameter: configure
This is an upgrade installation.
UCP Monitor version: 1.1.0
[UCP]: log level = 3
[UCP]: UCP version = 3.1.4
[VP]: log level = 3
[DNN]: log level = 3
[HPL]: log level = 3
[UCPT]: log level = 6
[DSP]: log level = 3
[DNN] HBTL_EXT_DNN log level:6
UCP SERVICE version: 3.1.4
Upgrade installation was successful. Deleting backup files...
Finish postinst process

#Uninstalling the DEB Package

To uninstall an already installed DEB package, refer to the following command:

root@hobot:/map/deb# dpkg -r hbucp
(Reading database ... 24661 files and directories currently installed.)
Removing hbucp (3.1.4) ...
Start prerm process with parameter: remove
All specified binaries are not running and can be safely processed.
All specified shared libraries and their dependencies are not being used and can be safely processed.
Finish prerm process
Start postrm process with parameter: remove
This is a remove operation.
Finish postrm process

#Backend Instruction

The backend refers to the back-end computing hardware for UCP task execution. The current backends supported by UCP include BPU, DSP, GDC, STITCH, JPU, VPU(Video Process Unit), PYRAMID, ISP.

#HardWare Feature Description

#DSP

#GDC

#STITCH

#JPU

#VPU(Video Process Unit)

#PYRAMID

#ISP

#x86 Simulation Description

In addition to the development board, UCP also provides the same development support in an x86 simulation environment as it does on the board.

#Function Description

Similar to the development board, UCP provides the same visual processing, model inference, and high-performance computing capabilities in an x86 architecture through simulation. All samples and interface code can be equivalently used in the simulation environment. You can develop and debug code in the x86 environment, gaining immediate feedback during the development process. This allows you to identify and resolve issues early, improving development efficiency and code quality, and ensuring seamless migration of the code to run on SoC hardware.

The simulation methods for each backend supported by UCP are as follows:

• BPU and DSP hardware use instruction-level simulation.
• GDC, JPU, and VPU hardware use CModel executable file simulation.
  • The CModel executable file for GDC hardware is gdc_cmodel .
  • The CModel executable files for JPU hardware are Nieuport_JpgEnc and Nieuport_JpgDec, used for JPEG encoding and decoding, respectively.
  • The CModel executable files for VPU(Video Process Unit) hardware are hevc_enc, hevc_dec, avc_enc and avc_dec. Among them, hevc_enc and hevc_dec are used for H.265 encoding and decoding respectively, while avc_enc and avc_dec are used for H.264 encoding and decoding respectively.
• STITCH and PYRAMID hardware use simulation libraries.

#Environment Description

#Compilation Environment

The UCP simulation uses the compiler environment provided by the Docker image.

#Runtime Environment

1. When using DSP hardware for simulation, you need to configure the Xtensa development environment and specify the DSP simulation image path. For environment configuration, refer to Install DSP Toolchain And Configure Core. You can specify the DSP simulation image path by setting the environment variable HB_DSP_CMODEL_IMAGE to ensure the application can locate the correct simulation image file. The reference command is as follows:

# define the DSP image path
export HB_DSP_CMODEL_IMAGE=../x86/bin/image/vdsp0

2. When running CModel executable files, you need to add the executable file path to the PATH environment variable so that they can be run directly from the terminal. The reference command is as follows:

# define the CModel executable file path
root=../x86/bin/

# set the executable file search path
export PATH=${root}:${PATH}

3. No additional configuration is required for running simulation of the other hardware.

#Performance Description

However, the performance of the x86 simulation environment is usually lower than that of the actual hardware due to the following reasons: As previously mentioned, the simulation methods used by the various backends supported by UCP include instruction-level simulation, CModel executable file simulation, and simulation libraries.

• Instruction-level simulation: This method simulates and executes each instruction individually, resulting in higher computational overhead and lower simulation speed.

• CModel executable file simulation: CModel executable files perform input and output operations through file read/write processes. File I/O operations are time-consuming and can impact the simulation speed to some extent.

• Simulation libraries: These run on the CPU, which simulates the behavior of hardware accelerators. However, the CPU's architecture and design are not specifically optimized for these tasks, leading to lower execution efficiency. Although the performance of the simulation environment is typically lower than that of actual hardware, the simulation environment provides comprehensive API support and precise functional verification. This significantly enhances your development efficiency and code quality, helping you identify and resolve potential issues at an early stage.