快速上手
本章节介绍了UCP示例包 ucp_tutorial 中HPL模块的示例使用方法，以及如何配置开发环境、编译并运行示例应用代码，帮助快速上手UCP中的HPL功能模块。其主要架构如下：
示例包使用
示例包结构如下所示：
ucp_tutorial
├── deps_aarch64 // aarch64 公共依赖目录
│ ├── some libs // 其他三方依赖库
│ └── ucp // UCP 依赖库及头文件，包含dnn/vp/ucp/hpl/dsp开发
├── deps_x86 // x86仿真 公共依赖目录
│ ├── some libs // 其他三方依赖库
│ └── ucp // UCP 依赖库及头文件
├── dnn // dnn示例
├── tools // 工具
├── vp // vp示例
└── hpl // hpl示例
├── code // 示例源码目录
| ├── 01_fft_ifft_transform // fft ifft转换示例
| ├── util // 公共代码目录
│ ├── build_aarch64.sh // aarch64示例编译脚本
| ├── build.sh // 编译hpl示例最小可执行环境脚本
│ ├── build_x86.sh // x86仿真示例编译脚本
| └── CMakeLists.txt // cmake文件
└── hpl_samples // hpl示例最小可执行环境
├── data // 数据目录
├── script // aarch64示例脚本目录
│ ├── 01_fft_ifft_transform // 示例脚本目录
| └── dsp_deploy.sh // 部署板上的dsp运行环境脚本
└── script_x86 // x86仿真示例脚本目录
├── 01_fft_ifft_transform // 示例脚本目录
└── README.md // readme文件
其中 ucp_tutorial/hpl 文件夹为HPL模块的示例，包括了快速傅里叶变换示例等，可同时支持板端运行编译和x86仿真编译两种方式。
具体的示例原理及实现流程请查阅 示例 章节。
编译示例算子
在编译运行示例应用代码前，您需要确保环境满足要求，根据 环境部署 部分的指引，您的开发机中应该已经安装有相关环境，要求如下：
在示例的 ucp_tutorial/hpl/code 目录下有预先配置好的编译脚本 build.sh，当前支持编译选项 -a x86 和 -a aarch64 两种编译方式，
直接执行 build.sh 脚本即可完成一键编译，生成的文件会被保存到 ucp_tutorial/hpl/hpl_samples 目录下。
此外，目录中也包含了 build_aarch64.sh 和 build_x86.sh 两个编译脚本，分别对应了两个编译选项，
使用这两个脚本进行编译与使用 build.sh 脚本等效。
编译x86仿真的HPL示例需要执行的命令如下：
cd ucp_tutorial/hpl/code
sh build_x86.sh
执行编译脚本后，会生成运行示例所需要的执行程序和依赖文件，保存在 ucp_tutorial/hpl/hpl_samples 目录下。
以HPL为例，其生成物如下所示，包含图片数据、示例运行脚本、运行依赖库、可执行文件以及运行示例的脚本目录，共同组成了完整的运行环境和运行依赖。
hpl_samples
├── data // 数据目录
└── script_x86 // x86仿真示例脚本目录
├── 01_fft_ifft_transform // 示例脚本目录
├── x86 // 编译产生可执行文件、依赖库目录
└── README.md // readme文件
运行示例
正确地完成编译的全部步骤后，可执行示例会被配置完毕并保存在 hpl_samples 文件夹内。下面根据执行环境不同，介绍上板与仿真两种运行示例的方式。
上板运行
将 hpl_samples 文件夹整个拷贝到开发板上，进入 hpl_samples/script 文件夹，直接执行示例文件夹中提供的运行脚本即可看到示例的运行结果。
开发板上执行脚本的参考指令如下：
cd hpl_samples
cd script
# 由于部分算子依赖dsp后端，因此需要刷新dsp镜像，此操作可选，对于不需要dsp执行或者x86仿真可跳过
sh dsp_deploy.sh
# 运行示例
cd 01_fft_ifft_transform
sh run_fft_ifft_tranform.sh.sh
x86仿真运行
进入 hpl_samples/script_x86 文件夹，直接执行示例文件夹中提供的运行脚本即可看到示例的运行结果。
执行脚本的参考指令如下：
cd hpl_samples
cd script_x86
# 运行示例
cd 01_fft_ifft_transform
sh run_fft_ifft_tranform.sh.sh
注解
地平线J6 SOC使用的是Cadence公司的Tensilica Vision Q8 DSP，因此x86仿真实例中dsp算子运行依赖Cadence提供的一套工具链，环境配置可参考 DSP工具链安装 的指引， 需要正确配置 License 以及环境变量 XTENSA_ROOT 即可。
输出物说明
以x86仿真运行为例，示例运行时会在控制台内打印流程日志并生成对应输出文件。日志中会包含全部算子的调用流程，输出结果会被保存在 data 文件夹中。示例部分输出如下：
[user@machine 01_fft_ifft_transform]$ sh run_fft_ifft_tranform.sh
x86 only support direct mode
[UCP]: log level = 3
[UCP]: UCP version = 3.0.3
[VP]: log level = 3
[DNN]: log level = 3
[I][24033][02-29][16:07:46:652][fft_ifft_process.cpp:171][fft_ifft_transform_sample][FFT_IFFT_TRANSFO] FFT IFFT process begin
......
[I][24033][02-29][16:08:25:265][fft_ifft_process.cpp:181][fft_ifft_transform_sample][FFT_IFFT_TRANSFO] FFT IFFT process finish
[C][24070][02-29][16:08:25:272][cmodel_cli.cpp:172][fft_ifft_transform_sample][dsp] [C] DSP ISS exit
生成物会被保存到 hpl_samples/data 目录下，内容如下：
user@machine:/ucp_sample/hpl_samples/data# ls
fft1d_input_f32.txt fft1d_output_f32.txt ifft1d_output_f32.txt input_image_f32.jpg output_image_f32.jpg README.md
HPL算子使用实例
本节通过一个简单的算子调用展示了如何使用HPL封装的算子实现快速傅里叶变换的功能。主要步骤包含了数据载入、任务创建、任务提交、任务完成、销毁任务、保存输出等。您可以阅读相应源码和注释进行学习。
该示例的作用为使用hbFFT1D算子对输入数据进行FFT变换，具体实现如下：
#include <cstring>
#include "util.h"
#include "log_util.h"
#include "hobot/hpl/hb_fft.h"
// 初始化输入输出内存
hbUCPSysMem src_re_mem, src_im_mem, dst_re_mem, dst_im_mem;
int32_t src_length = 1024 * 4;
hbUCPMallocCached(&src_re_mem, src_length, 0);
hbUCPMallocCached(&src_im_mem, src_length, 0);
hbUCPMallocCached(&dst_re_mem, src_length, 0);
hbUCPMallocCached(&dst_im_mem, src_length, 0);
// 将数据填充到输入内存中
std::string src_img = "./fft_input.txt";
std::ifstream ifs(src_path, std::ios::in | std::ios::binary);
ifs.read(static_cast<char *>(src_re_mem.virAddr), src_length);
ifs.read(static_cast<char *>(src_im_mem.virAddr), src_length);
hbUCPMemFlush(&src_re_mem, HB_SYS_MEM_CACHE_CLEAN);
hbUCPMemFlush(&src_im_mem, HB_SYS_MEM_CACHE_CLEAN);
// 填充输入输出信息
hbHPLImaginaryData src, dst;
src.realDataVirAddr = src_re_mem.virAddr;
src.realDataPhyAddr = src_re_mem.phyAddr;
src.imDataVirAddr = src_im_mem.virAddr;
src.imDataPhyAddr = src_im_mem.phyAddr;
src.numDimensionSize = 1;
src.dataType = HB_HPL_DATA_TYPE_I16;
src.imFormat = HB_IM_FORMAT_SEPARATE;
src.dimensionSize[0] = src_length / sizeof(int16_t);
dst.realDataVirAddr = dst_re_mem.virAddr;
dst.realDataPhyAddr = dst_re_mem.phyAddr;
dst.imDataVirAddr = dst_im_mem.virAddr;
dst.imDataPhyAddr = dst_im_mem.phyAddr;
dst.numDimensionSize = 1;
dst.dataType = HB_HPL_DATA_TYPE_I16;
dst.imFormat = HB_IM_FORMAT_SEPARATE;
dst.dimensionSize[0] = src_length / sizeof(int16_t);
// 填充算子参数
hbFFTParam param;
param.pSize = HB_HPL_FFT32;
param.normalize = 0;
// 通过HPL提供的算子接口创建任务，任务句柄支持设置为nullptr，使用异步模式执行此任务
hbUCPTaskHandle_t task_handle{nullptr};
// 设置调度参数调整任务优先级、选择执行终端等参数
hbUCPSchedParam sched_param;
HB_UCP_INITIALIZE_SCHED_PARAM(&sched_param);
sched_param.backend = HB_UCP_DSP_CORE_0; // 指定执行设备ID
sched_param.priority = 0; // 指定任务优先级
hbFFT1D(&task_handle, // UCP任务句柄
&dst, // 输出数据
&src, // 输入数据
¶m // 算子参数
);
// 设置调度参数调整任务优先级、选择执行终端等参数
hbScheParam sched_param;
HB_UCP_INITIALIZE_SCHED_PARAM(&sched_param);
sched_param.backend = HB_UCP_DSP_CORE_0; /*指定执行设备ID*/
// 提交任务，sched_param 支持设置为nullptr，使用默认调度参数
hbUCPSubmitTask(task_handle, &sched_param);
// 等待任务完成，设置超时参数，值为0时表示一直等待
hbUCPWaitTaskDone(task_handle, 0);
// 释放任务句柄
hbUCPReleaseTask(task_handle);
// 释放内存资源
hbUCPFree(&src_re_mem);
hbUCPFree(&src_im_mem);
hbUCPFree(&dst_re_mem);
hbUCPFree(&dst_im_mem);
