#总览

#总体介绍

• UCP是什么？

  统一计算平台（Unify Compute Platform，以下简称 UCP）定义了一套统一的异构编程接口， 提供应用程序接口（Application Programming Interface，以下简称API）实现对计算平台上所有资源的调用。 UCP将SOC上的功能硬件抽象出来并进行封装，对外提供基于功能的API，用于创建相应的UCP任务（如VP算子任务），并支持设置硬件Backend提交至UCP调度器， UCP可基于硬件资源，完成SOC上任务的统一调度。 具体提供了以下几个功能： 视觉处理(Vision Process)、 神经网络模型推理（Neural Network）、 高性能计算库（High Performance Library）、 自定义算子插件开发。

  

  Backend相关介绍请查看 Backend说明 。

• UCP应用场景:

  单算子调用：可直接使用UCP中的视觉算子、高性能处理算子。

  算子插件开发使用：可进行自定义算子的开发。

  深度学习模型推理：可完成深度学习模型的推理任务，UCP内部完成模型的解析及硬件部署。

• UCP的优势:

  高度抽象：对于单算子的功能，不会受到硬件差异带来的困扰，可通过指定backend选择需要执行的硬件，降低硬件部署难度。

  集成度高：作为地平线统一的异构编程接口，一套接口完成所有需求开发。

#环境及工具

UCP适用于地平线J6及更高架构的计算平台，您需要具备基本的嵌入式开发的知识技能，以完成交叉编译、部署，使用环境及工具要求参考下表：

文中默认以Linux操作系统为例，介绍了UCP的使用方法，其他操作系统请参考文档内容，根据实际情况自行调整相关配置。

#工作模式

UCP框架支持两种主要工作模式：直连模式和中继模式。系统默认运行在直连模式下。QNX操作系统和x86仿真不支持中继模式。

中继模式下，支持多进程任务的统一调度，使用中继模式前，首先启动 ucp_service，service文件位于 deps_aarch64/ucp/bin/service/ 路径下， 并通过设置环境变量 HB_UCP_ENABLE_RELAY_MODE=true 来启用Relay模式，使得用户进程可以通过中继服务进行通信。 无论是直连模式还是中继模式，UCP接口的调用方式保持一致，不会对编程逻辑产生影响。您可以根据实际需求灵活选择这两种模式，以满足系统在性能和灵活性方面的要求。

#接口使用流程

UCP任务执行有三种方式：同步执行、异步执行、注册回调函数执行。 以调用VP接口hbVPRotate(hbVPRotate) 为例，说明三种任务执行方式。

三种方式的选择建议如下：

• 同步执行：调用后阻塞等待任务完成，不支持配置任务控制参数与选择Backend，UCP会根据当前任务可执行的Backend与硬件负载信息选择合适的硬件执行，适合流程简单、对任务调度没有定制要求的场景。

• 异步执行：提交任务后由您自行调用等待接口确认任务完成，支持配置任务控制参数与选择Backend，适合需要指定任务优先级或指定执行硬件的场景。

• 注册回调函数执行：提交任务后由UCP在任务完成时回调通知，无需在提交处阻塞等待，适合在任务执行期间还需要继续处理其他逻辑的流水线场景。

#同步执行

创建任务时，将taskHandle对应的参数传入nullptr，可立即同步执行，参考代码如下：

#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;
}

#异步执行

创建任务时，需要提前将taskHandle参数初始化为nullptr； 提交UCP任务（hbUCPSubmitTask）后，在线程指定位置执行接口（hbUCPWaitTaskDone），等待任务完成，参考代码如下：

#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;
}

#注册回调函数执行

创建任务时，需要提前将taskHandle参数初始化为nullptr； 回调函数需要在任务提交（hbUCPSubmitTask）前注册，否则注册接口会报错。

如下给出设置回调函数的参考代码：

#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部署包

本节介绍UCP提供的DEB部署包，以及安装、升级与卸载的命令示例。当您需要在板端快速准备UCP的运行环境，而不希望逐个上传二进制文件与依赖库时，可以使用DEB部署包完成部署。

阅读本节的前置条件是已经拿到OE发布物中的 ucp_tutorial/tools/deb/ 目录，并且板端可以执行 dpkg 命令。

UCP提供DEB部署包位于 ucp_tutorial/tools/deb/hbucp_aarch64_x.x.x.deb 路径下，该包旨在简化板端的部署过程，确保系统配置更加便捷和高效。 通过自动安装所需的二进制文件和相关依赖库，可以快速设置并运行UCP相关的应用程序。

成功安装DEB包后，二进制文件文件 ucp_service 和 hrt_ucp_monitor 将自动安装到 /usr/bin 目录，可以直接通过命令行访问这些工具。相关的动态库将安装到 /lib/aarch64-linux-gnu 目录， 确保所有运行时依赖都已正确配置。

在安装过程中，系统会自动配置所需的库路径，无需手动干预。这确保了在运行应用程序时，所有依赖库都能够被正确加载，进而保障系统的稳定性和可靠性。

#安装命令示例

首次安装DEB包时，系统会提示安装过程中的版本信息。

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安装命令示例

使用upgrade安装DEB包时，若安装过程失败，系统会自动回滚到安装前的版本。

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

#卸载DEB包

如需卸载已安装的DEB包可参考如下命令：

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 说明

backend是指UCP任务执行时的后端计算硬件，当前UCP支持的backend包括BPU、DSP、GDC、STITCH、JPU、VPU、PYRAMID、ISP。

#硬件特性描述

本节按硬件IP列出各平台的硬件特性指标，用于确认硬件本身的能力边界。若您需要确认某项功能在不同系统与平台上是否支持，请查看 功能支持度对比列表 章节。

#DSP

#GDC

#STITCH

#JPEG Processing Unit

#Video Processing Unit

#PYRAMID

#ISP

#x86仿真说明

除开发板外，UCP还在x86仿真环境下提供了与板端同样的开发能力支撑。

#功能说明

与开发板端相同，UCP在 x86 架构上通过仿真形式提供了同样的视觉处理、模型推理和高性能计算能力，所有的示例及接口代码均可以在仿真环境中等效使用。 您可以在x86环境中进行代码开发和调试，开发过程中获得可即时反馈，并在早期发现和解决问题，从而提高开发效率和代码质量，以确保代码能够无缝迁移到SoC硬件上运行。

UCP支持的各Backend仿真方式如下：

• BPU和DSP硬件采用指令级仿真。
• GDC、JPU 和 VPU（Video Processing Unit）硬件采用CModel可执行文件仿真。
  • GDC硬件使用的CModel可执行文件是 gdc_cmodel 。
  • JPU硬件使用的CModel可执行文件是 Nieuport_JpgEnc 和 Nieuport_JpgDec ，分别用于JPEG编码和解码。
  • VPU硬件使用的CModel可执行文件是 hevc_enc、hevc_dec、avc_enc 和 avc_dec。其中 hevc_enc 和 hevc_dec 分别用于H.265编码和解码，avc_enc 和 avc_dec 分别用于H.264编码和解码。
• STITCH和PYRAMID硬件采用仿真库。

#环境说明

#编译环境

UCP仿真使用Docker镜像自带的编译器环境即可。

#运行环境

1. 使用DSP硬件进行仿真时，需要配置Xtensa开发环境并指定DSP仿真镜像路径。 环境配置方法可参考 DSP工具链安装 。指定DSP仿真镜像路径可以通过设置环境变量 HB_DSP_CMODEL_IMAGE，以确保应用程序能够找到正确的仿真镜像文件。 参考命令如下：

# 定义DSP镜像路径
export HB_DSP_CMODEL_IMAGE=../x86/bin/image/vdsp0

2. 运行CModel可执行文件时，需要将可执行文件路径添加到PATH环境变量中，以便在终端可直接运行，参考命令如下：

# 定义CModel可执行文件路径
root=../x86/bin/

# 设置可执行文件搜索路径
export PATH=${root}:${PATH}

3. 其余硬件仿真运行时不需要进行额外的配置。

#性能说明

但x86仿真环境下的性能通常会低于实际硬件的性能，主要原因如下： 前文我们提到，目前UCP支持的各Backend使用的仿真方式包括指令级仿真、CModel可执行文件仿真以及使用仿真库。

• 指令级仿真：指令级仿真方式需要逐条指令进行模拟和执行，从而导致较高的计算开销和较低的仿真速度。
• CModel 可执行文件仿真：CModel 可执行文件通过读写文件进行输入输出操作，而文件 I/O 操作较为耗时，在一定程度上会对仿真速度有所影响。
• 仿真库：仿真库运行在 CPU 上，CPU 模拟硬件加速器的行为，但 CPU 的架构和设计并不专门针对这些任务，因此运行效率较低。 尽管仿真环境下的性能通常低于实际硬件的性能，但仿真环境提供了完整的API支持和精确的功能验证，能够极大地提高您的开发效率和代码质量，有助于您在早期阶段发现并解决潜在的问题。

#下一步看哪里

• 使用视觉处理相关接口，请查看 视觉处理(Vision Process) 章节。

• 使用神经网络模型推理接口开发板端应用，请查看 模型推理应用开发指导 章节。

• 使用高性能计算库中的算子，请查看 高性能计算库（High Performance Library） 章节。

• 开发自定义算子，请查看 自定义算子插件开发 章节。

• 确认某项功能在您使用的系统与平台上是否支持，请查看 功能支持度对比列表 章节。

• 板端运行出现异常或需要确认错误码含义，请查看 常见问题 与 错误码 章节。