Vitis Accelerated Libraries 学习笔记--Vision 库的组织结构

1. 简介

Vision 库的组织结构如下：

├── L1/
│   ├── README.md
│   ├── examples/
│   ├── include/
│   ├── lib/
│   └── tests/
├── L2/
│   ├── README.md
│   ├── examples/
│   └── tests/
├── L3/
│   ├── README.md
│   ├── benchmarks/
│   ├── examples/
│   └── tests/
├── data/
├── LICENSE.txt
├── README.md
├── docs/
│   ├── images/
│   ├── include/
│   ├── Makefile
│   ├── Makefile.sphinx
│   ├── rst files
│   ├── conf.py
│   ├── conf_bhp.py
│   ├── env.csh
├── ext/
│   └── xcl2/
└── library.json

2. 分类介绍

2.1 L1/examples

包含示例测试平台代码，以方便在 Vitis/Vivado HLS 上运行单元测试。 example/ 包含带有算法名称的文件夹。每个算法文件夹包含 testbench、accel、config、Makefile、Json 文件和“build”文件夹。

2.2 L1/include/aie

包含基础设施标头和 AIE 内核定义。

2.3 L1/include/common

包含公共库基础结构标头，例如特定于库的类型。

2.4 L1/include/core

包含核心库功能标头，例如 math 函数。

2.5 L1/include/features

包含特征提取核函数定义。例如，Harris。

2.6 L1/include/imgproc

包含与图像处理定义相关的所有内核函数定义。

2.7 L1/include/video

包含所有与视频处理功能相关的内核函数定义。例如：光流。

2.8 L1/include/dnn

包含与深度学习预处理相关的所有核函数定义。

2.9 L1/tests

包含用于运行模拟、综合和导出 RTL 的所有测试文件夹。测试文件夹包含带有算法名称的文件夹。每个算法文件夹还包含配置文件夹，其中包含用于运行测试的 makefile 和 tcl 文件。

2.10 L1/examples/build

包含 xf_config_params.h 文件，其中具有与特定示例相关的可配置宏和变量。

2.11 L1/lib/sw

包含 AIE 数据移动器库对象文件。

2.12 L2/examples

包含示例测试平台代码，以方便在 Vitis 上运行单元测试。 example/ 包含带有算法名称的文件夹。每个算法文件夹包含 testbench、accel、config、Makefile、Json 文件和“build”文件夹。

2.13 L2/tests

包含用于运行软件、硬件仿真和硬件构建的所有测试文件夹。测试包含带有算法名称的文件夹。每个算法文件夹还包含配置文件夹，其中包含用于运行 PL 测试的 makefile 和配置文件。

2.14 L2/tests/aie

包含运行 x86 模拟、硬件模拟和硬件构建的所有测试文件夹。测试包含带有算法名称的文件夹。每个算法文件夹还包含配置文件夹，其中包含 makefile、testbench、config 和运行 AIE 测试所需的其他文件。

2.15 L2/examples/build

包含 xf_config_params.h 文件，其中具有与特定示例相关的可配置宏和变量。

2.16 L3/examples

包含用于在 Vitis 上构建管道功能的示例测试台代码。 example/ 包含带有算法名称的文件夹。每个算法文件夹包含 testbench、accel、config、Makefile、Json 文件和“build”文件夹。

2.17 L3/tests

包含运行软件、硬件仿真和硬件构建的所有测试文件夹。测试包含带有算法名称的文件夹。每个算法名称文件夹都包含配置文件夹，配置文件夹内的 makefile 用于运行测试。

2.18 L3/examples/build

包含 xf_config_params.h 文件，其中具有与特定示例相关的可配置宏和变量。

2.19 L3/benchmarks

包含基准示例，用于比较软件实现与使用 Vitis 视觉库的 FPGA 实现。

2.20 ext

包含与 opencl 主机代码相关的实用函数。

3. 脚本解析

3.1 TCL 脚本

set CSIM 0
set CSYNTH 0
set COSIM 0
set VIVADO_SYN 0
set VIVADO_IMPL 0
set CUR_DIR [pwd]
set OPENCV_INCLUDE $::env(OPENCV_INCLUDE)
set OPENCV_LIB $::env(OPENCV_LIB)
set XF_PROJ_ROOT $CUR_DIR/../../../..
set XPART xcu200-fsgd2104-2-e

set PROJ "resize.prj"
set SOLN "sol1"

if {![info exists CLKP]} {
  set CLKP 3.3
}

open_project -reset $PROJ

add_files "${XF_PROJ_ROOT}/L1/examples/resize/xf_resize_accel.cpp" -cflags " -I ${XF_PROJ_ROOT}/L1/tests/resize/resize_NPPC1_8UC1_8UC1_AREA -I${XF_PROJ_ROOT}/L1/include -I ./ -D__SDSVHLS__ -std=c++0x" -csimflags " -I ${XF_PROJ_ROOT}/L1/tests/resize/resize_NPPC1_8UC1_8UC1_AREA -I${XF_PROJ_ROOT}/L1/include -I ./ -D__SDSVHLS__ -std=c++0x"
add_files -tb "${XF_PROJ_ROOT}/L1/examples/resize/xf_resize_tb.cpp" -cflags " -I ${XF_PROJ_ROOT}/L1/tests/resize/resize_NPPC1_8UC1_8UC1_AREA -I${OPENCV_INCLUDE} -I${XF_PROJ_ROOT}/L1/include -I ./ -D__SDSVHLS__ -std=c++0x" -csimflags " -I ${XF_PROJ_ROOT}/L1/tests/resize/resize_NPPC1_8UC1_8UC1_AREA -I${XF_PROJ_ROOT}/L1/include -I ./ -D__SDSVHLS__ -std=c++0x"
set_top resize_accel

open_solution -reset $SOLN



set_part $XPART
create_clock -period $CLKP

if {$CSIM == 1} {
  csim_design -ldflags "-L ${OPENCV_LIB} -lopencv_imgcodecs -lopencv_imgproc -lopencv_core -lopencv_highgui -lopencv_flann -lopencv_features2d" -argv "  ${XF_PROJ_ROOT}/data/128x128.png"
}

if {$CSYNTH == 1} {
  csynth_design
}

if {$COSIM == 1} {
  cosim_design -ldflags "-L ${OPENCV_LIB} -lopencv_imgcodecs -lopencv_imgproc -lopencv_core -lopencv_highgui -lopencv_flann -lopencv_features2d" -argv "  ${XF_PROJ_ROOT}/data/128x128.png"
}

if {$VIVADO_SYN == 1} {
  export_design -flow syn -rtl verilog
}

if {$VIVADO_IMPL == 1} {
  export_design -flow impl -rtl verilog
}

exit

设置环境变量和项目参数：初始化一些变量，包括仿真、综合、联合仿真、Vivado综合和实现的标志，当前目录，OpenCV库和头文件路径，项目根目录，FPGA部件型号（XPART），项目名和解决方案名。
打开或创建项目和解决方案：通过open_project和open_solution命令重置并打开一个名为"resize.prj"的项目和名为"sol1"的解决方案。
添加文件和设置顶层函数：使用add_files命令添加加速器实现文件和测试平台（testbench）文件，并通过set_top设置顶层函数为resize_accel。
设置FPGA部件和时钟：通过set_part和create_clock命令设置FPGA部件型号和时钟周期。
条件执行仿真和综合任务：根据设置的标志（CSIM、CSYNTH、COSIM、VIVADO_SYN、VIVADO_IMPL），条件性地执行C语言仿真、高层次综合、联合仿真、Vivado综合和Vivado实现。例如，如果CSIM标志设置为1，则执行C语言仿真。
处理OpenCV库：在C语言仿真和联合仿真时，通过-ldflags传递OpenCV库的链接选项，以便能够在仿真中使用OpenCV函数。
退出：最后，脚本使用exit命令退出。

3.2 Makefile 脚本

############################## Setting up Project Variables ##############################
MK_PATH := $(abspath $(lastword $(MAKEFILE_LIST)))
export CUR_DIR := $(patsubst %/,%,$(dir $(MK_PATH)))
export XF_PROJ_ROOT ?= $(shell bash -c 'export MK_PATH=$(MK_PATH); echo $${MK_PATH%/L1/*}')

# setting default value
PLATFORM ?= xilinx_u200_gen3x16_xdma_2_202110_1

export PATH := $(XILINX_VIVADO)/bin:$(PATH)
WORK_DIR ?= hls
TARGET ?= csim
CONFIG_FILE ?= $(CUR_DIR)/hls_config.cfg
CONFIG_TMPL ?= $(CUR_DIR)/hls_config.tmpl

ifneq (,$(wildcard $(XILINX_VITIS)/bin/ldlibpath.sh))
export LD_LIBRARY_PATH := $(shell $(XILINX_VITIS)/bin/ldlibpath.sh $(XILINX_VITIS)/lib/lnx64.o):$(LD_LIBRARY_PATH)
endif

ifeq ($(TARGET), vivado_syn)
TARGET_REL = impl
export VIVADO_FLOW := syn
else
export VIVADO_FLOW := impl
ifeq ($(TARGET), vivado_impl)
TARGET_REL = impl
else
TARGET_REL = $(TARGET)
endif
endif

############################## Checking value ##############################
.PHONY: check_vivado
check_vivado:
ifeq (,$(wildcard $(XILINX_VIVADO)/bin/vivado))
	@echo "Cannot locate Vivado installation. Please set XILINX_VIVADO variable." && false
endif

.PHONY: check_vpp
check_vpp:
ifeq (,$(wildcard $(XILINX_VITIS)/bin/v++))
	@echo "Cannot locate Vitis installation. Please set XILINX_VITIS variable." && false
endif

.PHONY: check_part
ifeq (,$(XPART))
# MK_INC_BEGIN vitis_set_platform.mk

ifneq (,$(wildcard $(PLATFORM)))
# Use PLATFORM as a file path
XPLATFORM := $(PLATFORM)
else
# Use PLATFORM as a file name pattern
DEVICE_L := $(shell echo $(PLATFORM) | tr A-Z a-z)
# 1. search paths specified by variable
ifneq (,$(PLATFORM_REPO_PATHS))
# 1.1 as exact name
XPLATFORM := $(strip $(foreach p, $(subst :, ,$(PLATFORM_REPO_PATHS)), $(wildcard $(p)/$(DEVICE_L)/$(DEVICE_L).xpfm)))
# 1.2 as a pattern
ifeq (,$(XPLATFORM))
XPLATFORMS := $(foreach p, $(subst :, ,$(PLATFORM_REPO_PATHS)), $(wildcard $(p)/*/*.xpfm))
XPLATFORM := $(strip $(foreach p, $(XPLATFORMS), $(shell echo $(p) | awk '$$1 ~ /$(DEVICE_L)/')))
endif # 1.2
endif # 1
# 2. search Vitis installation
ifeq (,$(XPLATFORM))
# 2.1 as exact name vitis < 2022.2
XPLATFORM := $(strip $(wildcard $(XILINX_VITIS)/platforms/$(DEVICE_L)/$(DEVICE_L).xpfm))
ifeq (,$(XPLATFORM))
# 2.2 as exact name vitis >= 2022.2
XPLATFORM := $(strip $(wildcard $(XILINX_VITIS)/base_platforms/$(DEVICE_L)/$(DEVICE_L).xpfm))
# 2.3 as a pattern vitis < 2022.2
ifeq (,$(XPLATFORM))
XPLATFORMS := $(wildcard $(XILINX_VITIS)/platforms/*/*.xpfm)
XPLATFORM := $(strip $(foreach p, $(XPLATFORMS), $(shell echo $(p) | awk '$$1 ~ /$(DEVICE_L)/')))
# 2.4 as a pattern vitis > 2022.2
ifeq (,$(XPLATFORM))
XPLATFORMS := $(wildcard $(XILINX_VITIS)/base_platforms/*/*.xpfm)
XPLATFORM := $(strip $(foreach p, $(XPLATFORMS), $(shell echo $(p) | awk '$$1 ~ /$(DEVICE_L)/')))
endif # 2.4
endif # 2.3
endif # 2.2
endif # 2
# 3. search default locations
ifeq (,$(XPLATFORM))
# 3.1 as exact name
XPLATFORM := $(strip $(wildcard /opt/xilinx/platforms/$(DEVICE_L)/$(DEVICE_L).xpfm))
# 3.2 as a pattern
ifeq (,$(XPLATFORM))
XPLATFORMS := $(wildcard /opt/xilinx/platforms/*/*.xpfm)
XPLATFORM := $(strip $(foreach p, $(XPLATFORMS), $(shell echo $(p) | awk '$$1 ~ /$(DEVICE_L)/')))
endif # 3.2
endif # 3
endif
XPLATFORM := $(firstword $(XPLATFORM))

XDEVICE := $(basename $(notdir $(XPLATFORM)))

ifeq (1, $(words $(XPLATFORM)))
# Query the part name of device
ifneq (,$(wildcard $(XILINX_VITIS)/bin/platforminfo))
override XPART := $(shell $(XILINX_VITIS)/bin/platforminfo --json="hardwarePlatform.devices[0].fpgaPart" --platform $(XPLATFORM) | sed 's/^[^:]*://g' | sed 's/[^a-zA-Z0-9]/-/g' | sed 's/-\+/-/g')
endif
else
PART_ERROR := "To add more platform directories, set the PLATFORM_REPO_PATHS variable or point PLATFORM variable to the full path of platform .xpfm file."
endif

check_part: check_vpp
ifeq (,$(XPART))
	@echo "$(PART_ERROR)"
	@echo "XPART is not set and cannot be inferred. Please run \`make help\` for usage info." && false
endif
else # XPART
check_part:
	@echo "Using part $(XPART)"
endif # XPART

.PHONY: check_opencv
check_opencv:
ifeq (,$(OPENCV_INCLUDE))
    @echo "Cannot find OpenCV include path. Please set OPENCV_INCLUDE variable" && false
endif
ifeq (,$(OPENCV_LIB))
    @echo "Cannot find Opencv lib path. Please set OPENCV_LIB variable" && false
endif

define CONFIG_GEN_PY
import os, string
with open('$(CONFIG_TMPL)', 'r') as fr:
	t = fr.read()
with open('$(CONFIG_FILE)', 'w') as f:
	f.write(string.Template(t).substitute(**dict(os.environ)))
endef
export CONFIG_GEN_PY

VITIS_PYTHON3 = LD_LIBRARY_PATH=$(XILINX_VITIS)/tps/lnx64/python-3.8.3/lib $(XILINX_VITIS)/tps/lnx64/python-3.8.3/bin/python3

$(CONFIG_FILE): $(CONFIG_TMPL)
	@echo "$${CONFIG_GEN_PY}" | (${VITIS_PYTHON3})
	
all: check_vivado check_part check_opencv $(CONFIG_FILE)
ifneq ($(TARGET_REL), csim)
	v++ -c --mode hls --config $(CONFIG_FILE) --work_dir $(WORK_DIR) --part $(XPART)
endif

run: all
ifneq ($(TARGET_REL), csynth)
	@echo $(TARGET_REL)
	vitis-run --mode hls --config $(CONFIG_FILE) --$(TARGET_REL) --work_dir $(WORK_DIR)  --part $(XPART)
endif

clean:
	rm -rf $(CONFIG_FILE) *_hls.log $(WORK_DIR)

设置项目变量：定义了一些环境变量，如PLATFORM和WORK_DIR，以及如何找到Vitis和Vivado的安装路径。
检查值：包含了一系列检查，确保必要的环境变量已经设置，例如XILINX_VIVADO和XILINX_VITIS，以及OpenCV的包含路径和库路径。
配置文件生成：使用Python脚本从模板(CONFIG_TMPL)生成配置文件(CONFIG_FILE)。
编译和运行：定义了如何编译HDL代码和运行硬件仿真。
清理 (clean)：删除生成的文件和日志。

4. 总结

本文档提供了Vision库的组织结构和详细分类介绍，包括各级目录（L1、L2、L3）下的示例代码、测试、库文件等的详细说明。此外，还包括了TCL和Makefile脚本的解析，这些脚本是在项目开发过程中用于自动化构建和测试的重要工具。TCL脚式主要用于设置环境变量、项目参数、添加文件、设置FPGA部件和时钟，以及条件执行仿真、综合等任务。而Makefile脚本则涉及到设置项目变量、检查环境配置、生成配置文件、编译和运行指令等。

通过这些脚本，用户可以更方便地管理和执行项目构建和测试过程，提高开发效率。同时，通过对Vision库结构的详细介绍，用户可以快速了解如何使用库中的不同组件，进行图像处理、视频处理、深度学习预处理等操作。