前言¶
目的¶
随着神经网络模型越来越大，占用的资源越来越多，端到端的全流程的性能优化变的越来越重要。对端到端的全流程进行分析，全流程的耗时中，我们发现除了神经网络模型，前后处理的耗时也占了很大的比重，随着神经网络模型的优化的深入以及相关芯片算力的提高，前后处理的耗时比重变得越来越大。
在过往的经历中，经常会发现神经网络模型在某一种配置的服务器上运行性能很好，在另外一种配置的服务器上运行性能不达预期，调查发现是在端到端的全流程中，有很多操作，如前后处理等，运行在服务器的 CPU 上，导致 CPU 的性能指标直接影响神经网络模型的实际运行性能。在云端服务器的使用场景中，CPU 还将执行容器运行及相关业务代码运行等任务，如果神经网络模型占用了较多的 CPU 资源，则会影响实际的业务运行性能。
为了更好的优化端到端的全流程性能，我们需要对前后处理做优化，同时由于前后处理运行在 CPU 上，为了在不同的 CPU 型号上有稳定的性能表现，我们需要减少 CPU 的依赖，将前后处理从 CPU 转移到 GCU 上运行。
为了完成前后处理相关的任务在 GCU 上运行，我们需要构造一个全新的软件用于运行前后处理程序。考虑到 CV 类神经网络在 CPU 上的前后处理基本上使用了开源代码 OpenCV 的 API 来实现，因此，结合燧原科技的软件栈品牌 Tops，我们将这个软件命名为 TopsCV。
本用户手册介绍了 TopsCV 的设计理念，以及支持的功能，读者通过阅读本手册，可以了解到 TopsCV 支持的功能，以及如何使用 TopsCV 相关的 API 进行相关计算。
术语¶
术语缩写 |
说明 |
|---|---|
GCU |
General Compute Unit, 燧原的芯片产品代号 |
VPU |
Vision & Video Process Unit |
VCU |
Video Codec Unit, 主要用于视频和图像编解码 |
VPP |
Video Pre & Post Processing |
CVA |
Computer Vision Accelerator |
EVP |
Enflame Video Pre & Post Processing Unit |
EFC |
Enflame Find Contours Unit |
CV |
Computer Vision |
CSC |
Color Space Conversion |
IFC |
Input Format Conversion |
OFC |
Output Format Conversion |
BDUC |
Bit Depth Up Conversion |
BDDC |
Bit Depth Down Conversion |
CUS |
Color Up Sample |
CDS |
Color Down Sample |
AP |
Application Processor |
ARM |
Advanced Risc Machine |
ARM AP |
通常指使用 ARM 作为 vendor, 内置在 GCU 中的 ARM AP, 结合上下文一般以 AP 代指 ARM AP |
Host |
通常指主控 CPU, 云端以 X86/ARM 为 Host |
JIT |
代码编译方式, Just In Time, 运行时编译 |
AOT |
代码编译方式, Ahead Of Time, 运行前编译 |
OpSet |
Operator Set, 算子操作的集合 |
JPEG Decoder |
JPEG 图片解码器 |
PNG Decoder |
PNG 图片解码器 |
TopsCV 概述¶
功能概述¶
TopsCV 是一个 CV 前后处理加速库，提供 C API 供用户使用，TopsCV 不包含 Runtime 相关的功能，包括但不限于如下操作，如：
设备管理
Stream 创建和销毁
H2D/D2H 相关的内存操作
TopsCV 基于 Runtime Stream 的机制，构造 CV 类的任务，并且提交任务到 Stream 中运行，提交任务的 API 是异步 API，但是在 Stream 内部是串行同步执行的。
为了更好的针对不同场景做加速，GCU 内部除了 NN 计算相关的 IP 以外，GCU 增加了其他的 IP 来支持多样的业务，如处理视频编解码的 VCU IP，前后处理加速的 VPP IP，视觉算法加速的 CVA IP（VCU/VPP/CVA 共同组成了 VPU 子系统），通用计算的 CPU IP。为了灵活的调度 GCU 内部的异构 IP，TopsCV 使用了 Backend 的机制，使用统一的 API 方式，方便用户提交不同的任务到不同的 IP 中执行。
Note
✓：目前已经支持（SIP 作为 GCU 内部的可编程单元，任何功能都可以支持，如果有需求，可以向燧原科技相关的同事提出需求）
功能 |
VCU |
CVA |
VPP |
SIP |
AP |
|---|---|---|---|---|---|
图片解码 |
✓ |
||||
找轮廓 |
✓ |
||||
颜色空间转换 |
✓ |
||||
缩放 |
✓ |
||||
仿射变换 |
TBD |
||||
投射变换 |
TBD |
||||
裁剪 |
✓ |
||||
填充 |
✓ |
系统调用示意图¶
在 GCU 软件栈中，任何任务都经过调度器调度，TopsCV API 的本质是产生供调度器调度的 packet，插入到 Stream 中，同一个 Stream 中的 packet 会自动建立前后依赖关系，同一个 Stream 中的 packet，只有前面的 packet 运行结束后，下一个 packet 才会运行。
Runtime API 中存在异步 API，这里的异步 API 是以 Host 为视角而言，对于同一个 Stream 中的 packet 而言，SP AMOS 全部是顺序且同步执行。
为了便于读者理解，考虑到 TopsCV 会跟神经网络一起工作，有些概念会互相交叉使用，因此在此处进行概念的声明，下文中的任务/功能/OP 等均表达同样的含义，不做刻意区分，具体含义需要结合上下文理解。
软件设计方案¶
方案概述¶
如同在系统架构图章节介绍的那样，TopsCV API 的本质是产生供调度器调度的 Packet，TopsCV 框架内部做的所有优化，就是如何按照用户的需求产生正确的 Packet，以及隐藏内部硬件的差异，提供易用的用户接口。
TopsCV 内部主要模块有：
Op Factory，针对多后端和多平台，通过 Op Factory 的机制，实现了算子注册与发射解耦，算子开发可以独立的注册进 Op Factory，实现了自动化的机制进行算子功能的开发与注册
Image，针对 CV 类业务，提供 Image 接口来实现 Image 的创建，销毁，并且表达 Image 相关的属性，如
width/height/pitch/slice_height等VPP&CVA Image Helper，针对 VPP&CVA 硬件的限制，提供了自动 Padding&Crop 的机制来构造 VPP 硬件需要的输入和输出数据，方便用于使用
Task Profiling，自动的进行发射任务的 Profiling，用于评估任务的执行耗时，与硬件本身 Profiling 得到的耗时不同的是，Task Profiling 得到的耗时是整个任务的耗时，不只是单一 IP 的耗时
TopsCV 内部示意图如下：
Image & 内存管理¶
功能简述¶
TopsCV 内部主要数据结构的内存申请和释放，在用户层表现为 topscvImage 的创建和销毁。
我们针对图像领域，定义了 4 个参数来描述图像分辨率与内存布局相关的信息：
width，图像的真实分辨率，宽
height，图像的真实分辨率，高
pitch，图像分辨率宽在内存中的占用，以 Byte 为单位，例如，分辨率为 50*20 的 RGB888 Packed 的图像，由于是 Packed 的内存布局，因此分辨率是 50，一行的内存是 50x3=150，假设 pitch 按照 128 进行对齐，则 pitch 为 256。
slice_height，图像分辨率高在内存中的占用，以 Byte 为单位
由于不同硬件对内存布局的需求不一样，为了让用户不感知到底层硬件的差异，用户拿到的 topscvImage 的 width 与 pitch 相等，height 与 slice_height 相等。
Note
目前 VPP&CVA 后端对内存布局有要求，因此为 VPP&CVA 后端加入了自动的 Padding&Crop 机制。因此，用户如果送给 VPP&CVA 后端的图像不是 128x2 对齐的，会有额外的 Padding&Crop 的操作发生，增加执行耗时。
设计细节¶
TopsCV 支持两种内存管理方式
TopsCV 管理内存，也称之为基础模式
用户手动管理内存，也称之为高级模式，高级模式可以内存复用，如果存在大量的动态内存的申请和释放的场景，推荐使用高级模式
TopsCV 作为 Runtime 的用户，可以使用 Runtime 的 API 进行内存申请和分配，同时，用户也可以直接使用 Runtime API 进行内存申请和分配。因此 TopsCV 必须具备能力，将 TopsCV 的内存转给用户使用以及将用户的内存转给 TopsCV 使用。
在 CV 领域里，处理的图像所占用的内存，一般具有两点信息，内存的地址/大小（也称之为 data），以及内存中内容的描述信息（也称之为 metadata）。
TopsCV 提供的 topscvImage_t 结构体融合了 data 和 metadata 信息，方便用户使用，同时，由于 TopsCV 对外提供的是 C 级别的 API，而 TopsCV 内部使用 C++实现，因此存在一个 C 结构体与 C++对象的映射关系，topscvImage_t 是用户可以操作的 C 级别的变量，对应内部的对象。topscvImageData_t 是 TopsCV 导出的 C++对象的信息，包含 metadata 和 data。
具体的使用方式如下
/********************* 基础模式 *********************/
int64_t width = 100, height = 100;
topscvImage_t image = nullptr;
// 由TopsCV创建一个topscvImage, 并且自动分配内存
auto stats = topscvImageCreate(width, height, fmt, &image);
// 销毁TopsCV创建的topscvImage, 并且自动释放内存
stats = topscvImageDestroy(&image);
/********************* 高级模式 *********************/
int64_t width = 100, height = 100;
void* mem = nullptr;
topscvImage_t image = nullptr;
// 基于宽高和格式申请内存，如RGB的内存是width*height*3，可以超大分配（*2是示例）
int64_t total_mem_size = width*height*3*2;
int64_t image_size = width*height*3;
// 用户需要手动分配内存
auto ret = topsMalloc(&mem, total_mem_size);
// 由topscvImageCreateEx创建一个topscvImage, 关联给定的内存，不会额外分配内存
auto stats = topscvImageCreateEx(width, height, TOPSCV_IMAGE_FORMAT_RGB_PACKED_U8, mem, image_size, &image);
// 销毁TopsCV创建的topscvImage, 不会释放用户提供的内存
stats = topscvImageDestroy(&image);
// 用户需要手动销毁内存
ret = topsFree(mem);
Task Profiling 机制¶
功能简述¶
为了方便用户评估每个任务在执行过程中的耗时，TopsCV 提供了一种自动 Profiling 的机制。
TopsCV 为每一个创建 packet 的 API 自动的在 API 的前后插入了 profiling 的 debug packet，用于自动的记录 packet 在 SP AMOS 侧执行的时间。
设计细节¶
在每一次的 API 调用过程中，TopsCV 在每一个 API 调用的开始和结束，自动的插入了 Profiling 的 Debug Packet，Debug Packet 可以记录当前 Packet 在 Stream 内的执行时间，并且通过 Enflame 的 Tools 工具将时间线画出来。
有了 API 开始和结束的执行时间，就可以知道 API 本身创建的实际工作的 Packed 的执行时间，同时，硬件也提供了硬件执行时间的信息，同样反应在时间线上，那么通过两段时间线的差异对比，也可以看到我们调度系统是否还有更多的性能优化空间。
目前 Profiling 机制使用的是 host callback + host profiling 的机制。
OP 详细介绍¶
操作 Image 数据结构的所有的 OP，输入和输出支持 YUV444/BGR/RGB 三种颜色格式，以及 Packed/Planar 两种内存排列方式，再加上 GRAY 格式，共 3*2+1=7 种格式。
值得注意的是，虽然输入输出支持这 7 种格式，但是并不代表可以隐式的做颜色空间转换，只有颜色空间转换OP支持颜色空间转换，其他的OP输入和输出只可以做同色域空间的转换，不可以做色域空间的转换。
如：
RGB Packed 的输入格式，可以输出 RGB Packed/Planar, BGR Packed/Planar，共 4 种格式，但是不可以输出 YUV444/GRAY 的格式。
另外，有的算法对输入格式有要求，此时不支持任意格式的输入，需要以算法要求的为准，例如 FindContours，输入需要是 GRAY 格式。
图片解码 Image Decoder¶
ARCH |
VCU |
CVA |
VPP |
SIP |
AP |
|---|---|---|---|---|---|
GCU 3.0 |
✓ |
GCU 3.0 的 VCU 只支持 JPEG 解码器，只支持 YUV420/422 的 JPEG 图像，支持的最大分辨率为 32k*32k。
为了让用户在使用 GCU 时更方便的处理多种类型的数据集，如 YUV444 的 JPEG 图像和 PNG 图像，我们在 GCU 内部的 CPU IP 里面通过 CPU 软件的形式，增加了 JPEG 解码器和 PNG 解码器的支持。CPU IP 的解码器可以支持 YUV444 的 JPEG 图像和 PNG 图像。
找轮廓 Find Contours¶
ARCH |
VCU |
CVA |
VPP |
SIP |
AP |
|---|---|---|---|---|---|
GCU 3.0 |
✓ |
TopsCV 提供 findContours 功能，与 OpenCV 的 findContours 功能相比，支持的参数略有区别
只支持 OpenCV 的
CV_RETR_EXTERNAL模式只支持 OpenCV 的
CV_CHAIN_APPROX_NONE保存轮廓的方法输入数据为 U8 类型，支持自动二值化功能（与 OpenCV 保持一致）
OpenCV 的 findContours 功能，以非 0 的值为 1 来自动做二值化，TopsCV 使用了同样的处理方式，因此无需用户手动的做二值化，只需要输入 Gray 图像即可。
颜色空间转换 Color Space Conversion(CSC)¶
ARCH |
VCU |
CVA |
VPP |
SIP |
AP |
|---|---|---|---|---|---|
GCU 3.0 |
✓ |
VPP 支持针对 U8 类型的定点数据的 CSC 操作，数据精度与 OpenCV 一致。（RGB2YUV 除外，实现方式与 OpenCV 的 CPU 实现略有差异）
Resize 缩放¶
ARCH |
VCU |
CVA |
VPP |
SIP |
AP |
|---|---|---|---|---|---|
GCU 3.0 |
✓ |
仿射变换 Warp Affine¶
ARCH |
VCU |
CVA |
VPP |
SIP |
AP |
|---|---|---|---|---|---|
GCU 3.0 |
TBD |
投射变换 Warp Perspective¶
ARCH |
VCU |
CVA |
VPP |
SIP |
AP |
|---|---|---|---|---|---|
GCU 3.0 |
TBD |
裁剪 Crop¶
ARCH |
VCU |
CVA |
VPP |
SIP |
AP |
|---|---|---|---|---|---|
GCU 3.0 |
✓ |
填充 Padding¶
ARCH |
VCU |
CVA |
VPP |
SIP |
AP |
|---|---|---|---|---|---|
GCU 3.0 |
✓ |
安装使用¶
TopsCV 需要与 TopsRider 中的其他组件一起工作，为了防止产生未知的问题，建议用户在安装软件的时候务必保证软件版本的一致。
应用举例¶
请参考 TopsCV 提供的示例代码。