Vitis_Libraries vision L3 isppipeline U50/ZCU102流程示例

作者：Yin Chaowen，AMD工程师；来源：AMD 开发者社区

1. 关于Vitis Vision Library

Vitis Vision 库是一组 90 多个内核，基于 OpenCV 计算机视觉库，针对 Xilinx™ FPGA、AI Engine™ 和 SoC 进行了优化。 Vitis Vision 库中的内核在 Xilinx Vitis™ 工具套件中进行了优化和支持。下面是用户手册的链接：
https://docs.xilinx.com/r/2022.2-English/Vitis_Libraries/vision/index.html

2. 硬件和软件要求

Vitis Vision 库设计用于与 Zynq™、Zynq Ultrascale+™、VCK190™ 和 Alveo™ FPGA 配合使用。 该库已在 zcu102、zcu104、vck190、U50 和 U200 板上经过验证。

必要条件：

• 有效安装 Vitis™ 2022.2 或更高版本以及相应的许可证。
• 必须安装 Xilinx (XRT)。 XRT 为 Xilinx FPGA 提供软件接口。
• 安装 OpenCV-4.4.0 x86 库（兼容 libjpeg.so）。 x86 库必须用于

  a) L1 flow irrespective of target FPGA device being PCIe or embedded.
b) L2/L3 flow when the target device is PCIe based
c) L2/L3 flow when performing software emulation for an embedded platform.
对于针对嵌入式平台的 L2/L3 Flow（针对hardware emulation and hardware build），应使用 sysroot 中附带的 aarch32/aarch64 版本 OpenCV。

• 如果 libOpenCL.so 不存在，则必须安装。
• 安装 Vitis 2022.2 或更高版本支持该平台的卡。
• 如果针对嵌入式平台，请安装它并设置评估板。

3. OpenCV 安装指导

建议全新安装 OpenCV 4.4.0，不要使用系统的现有库，因为它们可能适用于 Vitis 环境，也可能不适用于。

请确保更新和升级系统的软件包和操作系统库，并安装 cmake 版本>3.5，然后再继续。不然可能遇到如下的错误：#CMake Error: The source directory "/home/***/Desktop/source/source/build/WITH_V4L=ON" does not exist.

以下步骤可帮助安装编译和链接 Vitis Vision 主机代码中的 OpenCV 调用所需的基本库。

1. create a directory "source" and clone opencv-4.4.0 into it.
2. create a directory "source_contrib" and clone opencv-4.4.0-contrib into it.
3. create 2 more directories: build , install
4. open a bash terminal and cd to build directory
5. Run the command: export LIBRARY_PATH=/usr/lib/x86_64-linux-gnu/
6. Run the command: cmake -D CMAKE_BUILD_TYPE=RELEASE -D CMAKE_INSTALL_PREFIX=< path-to-install-directory> -D CMAKE_CXX_COMPILER=< path-to-Vitis-installation-directory>/tps/lnx64/gcc-6.2.0/bin/g++ -D OPENCV_EXTRA_MODULES_PATH=< path-to-source_contrib-directory>/modules/ -D WITH_V4L=ON -DBUILD_TESTS=OFF -DBUILD_ZLIB=ON -DBUILD_JPEG=ON -DWITH_JPEG=ON -DWITH_PNG=ON -DBUILD_EXAMPLES=OFF -DINSTALL_C_EXAMPLES=OFF -DINSTALL_PYTHON_EXAMPLES=OFF -DWITH_OPENEXR=OFF -DBUILD_OPENEXR=OFF ..
7. Run the command: make all -j8
8. Run the command: make install

下面是一个完整的示例，基于Ubuntu 22.04/bash，在/home/ycw/Desktop路径下操作。

cd /home/ycw/Desktop
git clone https://github.com/opencv/opencv --branch 4.4.0 source
git clone https://github.com/opencv/opencv_contrib --branch 4.4.0 source_contrib
cd ./source/
mkdir build
mkdir install
cd ./build
export LIBRARY_PATH=/usr/lib/x86_64-linux-gnu/

# 下面的注意点
# 1. 最后两个..不能少
# 2. CMAKE_INSTALL_PREFIX 是输出目录，可以自己指定
# 3. CMAKE_CXX_COMPILER的指向的是Vitis_HLS, 并不是Vitis.
# 4. OPENCV_EXTRA_MODULES_PATH 是之前git clone下来的source_contrib文件路径。
# 5. 这里的camke (usr/bin/cmake) 是3.27的版本cmake.
# 6. 这里执行下面命令的当前目录是在build内： ycw@chaoweny:~/Desktop/source/build$
/usr/bin/cmake -D CMAKE_BUILD_TYPE=RELEASE -D CMAKE_INSTALL_PREFIX="/home/ycw/Desktop/install" -D CMAKE_CXX_COMPILER="/tools/Xilinx/Vitis_HLS/2022.2/tps/lnx64/gcc-6.2.0/bin/g++" -D OPENCV_EXTRA_MODULES_PATH="/home/ycw/Desktop/source_contrib/modules" -D WITH_V4L=ON -DBUILD_TESTS=OFF -DBUILD_ZLIB=ON -DBUILD_JPEG=ON -DWITH_JPEG=ON -DWITH_PNG=ON -DBUILD_EXAMPLES=OFF -DINSTALL_C_EXAMPLES=OFF -DINSTALL_PYTHON_EXAMPLES=OFF -DWITH_OPENEXR=OFF -DBUILD_OPENEXR=OFF ..

#这里完成之后会有类似的的输出
#-- Install to: /home/ycw/Desktop/install
#-- -----------------------------------------------------------------
#-- Configuring done (27.6s)
#-- Generating done (0.3s)
#-- Build files have been written to: /home/ycw/Desktop/source/build
make all -j8 VERBOSE=1
make install

一些可能遇到的问题：

Q1: 遇到下面的这个错误，可能cmake的版本没有大于3.5。
#CMake Error: The source directory "/home/ycw/Desktop/source/source/build/WITH_V4L=ON" does not exist.

Q2：FATAL: In-source builds are not allowed.
# 需要安装上面的步骤mkdir build文件夹，注意如果已经创建了build目录，还是出现这个 FATAL ERROR 注意 cd回 source目录内，尝试使用如下命令清理一下cache：rm -rf CMakeCache.txt CMakeFiles

Q3：CMAKE_CXX_COMPILER=< path-to-Vitis-installation-directory>.
# 这里的path-to-Vitis-installation-directory应该设置成Vitis_HLS的路径。
见上面的完整示例。

4. 一些其他的信息：

https://github.com/Xilinx/Vitis_Libraries/tree/2022.2/vision#source-file...
https://github.com/Xilinx/Vitis_Libraries/tree/2022.2/vision#application...
https://github.com/Xilinx/Vitis_Libraries/tree/2022.2/vision#other-infor...
https://github.com/Xilinx/Vitis_Libraries/tree/2022.2/vision#acknowledge...

5. 两种platform的master/vision/L3/examples/isppipeline的流程：

Level 3: Pipeline Applications:
https://github.com/Xilinx/Vitis_Libraries/tree/master/vision/L3#level-3-...

不同设备和行为流程如下：

实例：

1. Pcie设备示例(U50)：xilinx_u50_gen3x16_xdma_5_202210_1.xpfm的编译make流程：

a. OPENCV_INCLUDE、OPENCV_LIB指向的是步骤3（OpenCV 安装指导）CMAKE_INSTALL_PREFIX设置的目录内。
b. U50的platform（xilinx_u50_gen3x16_xdma_5_202210_1.xpfm）如果没有部署，可以按照下面 的链接部署。
https://www.xilinx.com/products/boards-and-kits/alveo/u50.html#gettingSt...

该示例xilinx_u50_gen3x16_xdma_5_202210_1.xpfm默认部署在下图的路径。

c. 示例代码：

cd /home/ycw/Desktop/Vitis_Libraries-2022.2/vision/L3/examples/isppipeline
source /tools/Xilinx/Vitis/2022.2/settings64.sh
source /opt/xilinx/xrt/setup.sh
export PLATFORM=/opt/xilinx/platforms/xilinx_u50_gen3x16_xdma_5_202210_1/xilinx_u50_gen3x16_xdma_5_202210_1.xpfm
# export OPENCV_INCLUDE=

/include/opencv4
# export OPENCV_LIB=

/lib
# export LD_LIBRARY_PATH=

/lib:$LD_LIBRARY_PATH
# e.g.
export OPENCV_INCLUDE=/home/ycw/Desktop/install/include/opencv4
export OPENCV_LIB=/home/ycw/Desktop/install/lib
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/home/ycw/Desktop/install/lib
#make host xclbin TARGET=< sw_emu|hw_emu|hw >
#make run TARGET=< sw_emu|hw_emu|hw >
make all TARGET=hw

2. Embedded设备示例（ZCU102）：xilinx_zcu102_base_202220_1.xpfm的编译make流程：
注意点：
a. OPENCV_INCLUDE、OPENCV_LIB指向的是步骤3（OpenCV 安装指导）CMAKE_INSTALL_PREFIX设置的目录内。
b. SYSROOT可以通过如下的方式获取：
2.1:在下面的链接下载zynqmp的common image : https://www.xilinx.com/member/forms/download/xef.html?filename=xilinx-zy...
2.2 解压之后，cd到common-image目录内，使用命令（./sdk.sh -y -d ./ -p）安装sysroot。该示例安装完成之后，安装在下图显示的目录：/home/ycw/Desktop/xilinx-zynqmp-common-v2022.2/sysroots/

c. 示例代码：

# For Embedded Devices:
# Hardware Emulation and Hardware Build:
#EX: ZCU102
cd /home/ycw/Desktop/Vitis_Libraries-2022.2/vision/L3/examples/isppipeline
source /tools/Xilinx/Vitis/2022.2/settings64.sh
source /opt/xilinx/xrt/setup.sh
export PLATFORM=/tools/Xilinx/Vitis/2022.2/base_platforms/xilinx_zcu102_base_202220_1/xilinx_zcu102_base_202220_1.xpfm
export SYSROOT=/home/ycw/Desktop/xilinx-zynqmp-common-v2022.2/sysroots/cortexa72-cortexa53-xilinx-linux
make all TARGET=hw PLATFORM=/tools/Xilinx/Vitis/2022.2/base_platforms/xilinx_zcu102_base_202220_1/xilinx_zcu102_base_202220_1.xpfm

# Software Emulation:
#EX: ZCU102
cd /home/ycw/Desktop/Vitis_Libraries-2022.2/vision/L3/examples/isppipeline
source /tools/Xilinx/Vitis/2022.2/settings64.sh
source /opt/xilinx/xrt/setup.sh
export PLATFORM=/tools/Xilinx/Vitis/2022.2/base_platforms/xilinx_zcu102_base_202220_1/xilinx_zcu102_base_202220_1.xpfm
export SYSROOT=/home/ycw/Desktop/xilinx-zynqmp-common-v2022.2/sysroots/cortexa72-cortexa53-xilinx-linux
export OPENCV_INCLUDE=/home/ycw/Desktop/install/include/opencv4
export OPENCV_LIB=/home/ycw/Desktop/install/lib
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/home/ycw/Desktop/install/lib
make run TARGET=sw_emu

6. 板上运行：

U50的HW运行示例：
1.使用make run TARGET=hw运行的示例代码：

cd /home/ycw/Desktop/Vitis_Libraries-2022.2/vision/L3/examples/isppipeline
source /tools/Xilinx/Vitis/2022.2/settings64.sh
source /opt/xilinx/xrt/setup.sh
export PLATFORM=/opt/xilinx/platforms/xilinx_u50_gen3x16_xdma_5_202210_1/xilinx_u50_gen3x16_xdma_5_202210_1.xpfm
export OPENCV_INCLUDE=/home/ycw/Desktop/install/include/opencv4
export OPENCV_LIB=/home/ycw/Desktop/install/lib
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/home/ycw/Desktop/install/lib
make run TARGET=hw

注：运行之后可以看到在/home/ycw/Desktop/Vitis_Libraries-2022.2/vision/L3/examples/isppipeline/目录下生成了hls_output.png文件。

2. build hw之后生成的app运行示例：

cd /home/ycw/Desktop/Vitis_Libraries-2022.2/vision/L3/examples/isppipeline/build_dir.hw.xilinx_u50_gen3x16_xdma_5_202210_1/
source /tools/Xilinx/Vitis/2022.2/settings64.sh
source /opt/xilinx/xrt/setup.sh
export PLATFORM=/opt/xilinx/platforms/xilinx_u50_gen3x16_xdma_5_202210_1/xilinx_u50_gen3x16_xdma_5_202210_1.xpfm
export OPENCV_INCLUDE=/home/ycw/Desktop/install/include/opencv4
export OPENCV_LIB=/home/ycw/Desktop/install/lib
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/home/ycw/Desktop/install/lib
./isppipeline /home/ycw/Desktop/Vitis_Libraries-2022.2/vision/L3/examples/isppipeline/input.png

注：
1.当前在/home/ycw/Desktop/Vitis_Libraries-2022.2/vision/L3/examples/isppipeline/build_dir.hw.xilinx_u50_gen3x16_xdma_5_202210_1/路径内，isppipeline需要带入输入图片的绝对路径参数，这里输入图片的路径是：/home/ycw/Desktop/Vitis_Libraries-2022.2/vision/L3/examples/isppipeline/input.png
2.生成的图片默认也在/home/ycw/Desktop/Vitis_Libraries-2022.2/vision/L3/examples/isppipeline/build_dir.hw.xilinx_u50_gen3x16_xdma_5_202210_1/路径内。

7. 2022.2一些已知的问题：
Vitis GUI projects on RHEL83 and CEntOS82 may fail because of a lib conflict in the LD_LIBRARY_PATH setting. User needs to remove ${env_var:LD_LIBRARY_PATH} from the project environment settings for the function to build successfully.
rgbir2bayer, isppipeline_rgbir PL functions are not supplied with input images
lkdensepyroptflow fails to meet timing when URAM is enabled
AWB, ISPStats output will not match with reference only on VCK190, because of a known XRT issue.

8.Vitis_Libraries Vision更多的示例和信息可以参考GitHub的链接：

https://github.com/Xilinx/Vitis_Libraries/tree/main/vision