在pynq2.6镜像中安装DPU-PYNQ1.2.0记录

项目场景：

记录我在AXU2CG开发板上安装DPU-PYNQ1.2.0时的步骤和踩坑记录。
首相DPU-PYNQ1.2.0已经是比较老的版本了，一些库和API就要弃用了，有条件最好是升级版本，同时也得升级对应的工具，就是Vitis Vivado那一套，DPU-PYNQ1.2.0对应的VItis AI也是属于比较老的版本了，其支持的框架和算子也比较少比较老，可能有些模型就是无法支持部署的。

---

前言：

DPU-PYNQ1.2.0和DNNDK的关系（AI回答）：

DPU-PYNQ1.2和DNNDK是两个不同层次、不同时期的开发工具，它们之间存在明确的演进关系，通常不能同时安装在同一个板子上（实际上DPU-PYNQ1.2.0依然支持DNNDK，但是亲测高版本的DPU-PYNQ会和DNNDK产生冲突），因为它们在底层运行时库和API层面存在冲突。

DNNDK (Deep Neural Network Development Kit)：这是由深鉴科技（Deephi Tech）开发的、早期用于在Xilinx FPGA上部署深度学习模型的全栈式解决方案。它包含模型压缩（DECENT）、编译器（DNNC）、运行时（N2Cube）等全套工具链。其API（如n2cube.dpuOpen(), n2cube.dpuLoadKernel()）是相对底层的C/C++接口。DPU-PYNQ：这是Xilinx（现AMD）官方推出的、基于PYNQ框架的DPU开发工具。它的核心是一个名为DpuOverlay的Python类，它封装了底层的运行时库（如Vitis AI Runtime, VART），提供了更高级、更易用的Python接口（如overlay.load_model()）。

简单来说，DPU-PYNQ 是 DNNDK 的官方继任者和高级封装。它旨在简化开发流程，让开发者无需关心底层的C++细节，直接在Python环境中调用DPU进行推理。

这两个工具包在底层运行时库和系统配置上存在直接冲突，主要体现在以下几个方面：

运行时库冲突：DNNDK依赖其自带的libn2cube.so等库，而DPU-PYNQ依赖Vitis AI的libvart-runner.so等库。这些库在功能上存在重叠，但接口和实现方式不同，同时存在会导致动态链接库（.so）的符号冲突，程序无法正常运行。系统配置冲突：DPU-PYNQ会修改系统配置文件（如/etc/vart.conf），指向其自身的固件文件（dpu.xclbin）。而DNNDK有自己的配置方式。同时存在会导致系统不知道应该加载哪个版本的固件，从而引发DPU驱动加载失败或行为异常。环境变量和路径冲突：两个工具包都会设置自己的环境变量（如PYTHONPATH, LD_LIBRARY_PATH）来指向各自的库文件。同时设置会导致Python解释器或系统加载器找到错误的库版本，引发导入错误或运行时崩溃。

---

问题描述

提示：这里描述项目中遇到的问题：
因为DPU-PYNQ1.2.0是DNNDK和VART交接的一个版本，而AMD官方又会比较推荐去使用它的新版本，对于旧版本的维护和支持就很少，所以我在安装DPU-PYNQ1.2.0时就遇到了一个它自动升级版本的问题。
首先我在安装完DPU-PYNQ1.2.0后可以导入DpuOverlay，但会显示我的DNNDK库无法导入：

最开始以为这个DNNDK是需要另外安装，但是实际上下载了vitis-ai_v1.2_dnndk.tar.gz安装后还是会报错，然后去搜问题就会发现是动态链接库找不到之类的。
实际上这个问题就是因为你虽然下载的是DPU-PYNQ1.2.0的文件并安装，但是在安装过程中会自动下载DPU-PYNQ1.3.2版本的包，然后你系统中实际上是1.3.2版本的，但是这个版本又不再兼容DNNDK的一些配置，就会产生各种错误。
附上自动升级1.3.2的安装输出：

root@pynq:/home/xilinx/jupyter_notebooks/DPU-PYNQ-1.2.0# pip3 install pynq-dpu
WARNING: pip is being invoked by an old script wrapper. This will fail in a future version of pip.
Please see https://github.com/pypa/pip/issues/5599 for advice on fixing the underlying issue.
To avoid this problem you can invoke Python with '-m pip' instead of running pip directly.
Collecting pynq-dpu
  Downloading pynq_dpu-1.3.2.tar.gz (1.3 MB)
     |████████████████████████████████| 1.3 MB 92 kB/s
Requirement already satisfied: CppHeaderParser in /usr/local/lib/python3.6/dist-packages (from pynq-dpu) (2.7.4)
Collecting mnist
  Downloading mnist-0.2.2-py2.py3-none-any.whl (3.5 kB)
Requirement already satisfied: pybind11 in /usr/local/lib/python3.6/dist-packages (from pynq-dpu) (2.5.0)
Requirement already satisfied: pynq>=2.6.0 in /usr/local/lib/python3.6/dist-packages (from pynq-dpu) (2.6.0)
Requirement already satisfied: ply in /usr/lib/python3/dist-packages (from CppHeaderParser->pynq-dpu) (3.11)
Requirement already satisfied: numpy in /usr/local/lib/python3.6/dist-packages (from mnist->pynq-dpu) (1.16.0)
Requirement already satisfied: cffi in /usr/lib/python3/dist-packages (from pynq>=2.6.0->pynq-dpu) (1.11.5)
Requirement already satisfied: pandas; python_version >= "3.5.3" in /usr/lib/python3/dist-packages (from pynq>=2.6.0->pynq-dpu) (0.22.0)
Requirement already satisfied: setuptools>=24.2.0 in /usr/lib/python3/dist-packages (from pynq>=2.6.0->pynq-dpu) (39.0.1)
Building wheels for collected packages: pynq-dpu
  Building wheel for pynq-dpu (setup.py) ... done
  Created wheel for pynq-dpu: filename=pynq_dpu-1.3.2-cp36-cp36m-linux_aarch64.whl size=1340618 sha256=cbc1d5102cb68c22a4b6ac8960ae1e7d667c2ccc9b7449a1456475c
16ad52df8
  Stored in directory: /root/.cache/pip/wheels/ab/14/ea/86d5e9585898bbe91cbc23e71fbc5f744d27a200c30e976df7
Successfully built pynq-dpu
Installing collected packages: mnist, pynq-dpu
Successfully installed mnist-0.2.2 pynq-dpu-1.3.2

所以即使你下载的是DPU-PYNQ1.2.0的文件目录，安装时还是会自动升级。

---

正确安装步骤：

安装DPU-PYNQ1.2.0版本的正确方式

先去github上下载DPU-PYNQ1.2.0的文件目录到本地，个人喜欢将整个目录下载到本地后再传到开发板上，避免因为网络问题下载失败还有长时间等待。
DPU-PYNQ的github链接，我这里用的是1.2.0版本：

https://github.com/Xilinx/DPU-PYNQ/tree/v1.2.0

将文件拷到开发板后，就按照github上的安装方法进行安装，但是需要注意几个地方。

上图中升级镜像那一步等同于下面代码，如果在线下载必须切换到相应版本的文件目录中去。

git clone --recursive --shallow-submodules https://github.com/Xilinx/DPU-PYNQ.git
git tag
git checkout v1.2.0
cd DPU-PYNQ/upgrade
make

注意这个make步骤是必须的，因为它会在你的系统中安装gcc9的一些包，如果不安装，那在pynq2.6镜像系统中DPU-PYNQ是无法运行的。
在make前先修改一下upgrade中的check_env.sh，因为里面有个检查网络环境的代码，一般会在这个地方卡主，直接删掉就好，修改后如下：

#!/bin/bash

if [ $(id -u) != "0" ]; then
	echo "Error: install scripts require root or sudo."
	exit 1
fi

if [ $(arch) != 'aarch64' ]; then
	echo "Error: only Zynq Ultrascale boards are supported."
	exit 1
fi

if [ $(df -h -BG | grep /dev/root | 
		awk '{print $2}' | sed 's/G//g') -lt 10 ]; then
	echo "Error: not enough disk space; recommend to use >16GB SD card."
	exit 1
fi

# 跳过网络检查 - 直接输出成功信息并继续
echo "Network check skipped - proceeding with offline installation"

make结束后可以看到一些输出：

Fetched 9,928 B in 0s (20.0 kB/s)
(Reading database ... 124441 files and directories currently installed.)
Preparing to unpack .../software-properties-common_0.96.24.32.1_all.deb ...
Unpacking software-properties-common (0.96.24.32.1) over (0.96.24.32.1) ...
Processing triggers for man-db (2.8.3-2) ...
Processing triggers for dbus (1.12.2-1ubuntu1) ...
Setting up software-properties-common (0.96.24.32.1) ...
+ sudo add-apt-repository -y ppa:ubuntu-toolchain-r/test
WARNING:root:could not open file '/etc/apt/sources.list'

WARNING:root:could not open file '/etc/apt/sources.list'

WARNING:root:could not open file '/etc/apt/sources.list'

Get:1 http://ppa.launchpad.net/ubuntu-toolchain-r/test/ubuntu bionic InRelease [21.5 kB]
Hit:2 http://ports.ubuntu.com/ubuntu-ports bionic InRelease
Get:3 http://ppa.launchpad.net/ubuntu-toolchain-r/test/ubuntu bionic/main arm64 Packages [29.1 kB]
Get:4 http://ppa.launchpad.net/ubuntu-toolchain-r/test/ubuntu bionic/main Translation-en [12.6 kB]
Fetched 63.2 kB in 2s (28.5 kB/s)
Reading package lists... Done
+ sudo apt install -y gcc-9 g++-9
Reading package lists... Done
Building dependency tree
Reading state information... Done
The following additional packages will be installed:
  cpp-9 gcc-11-base gcc-13-base gcc-9-base libasan5 libatomic1 libcc1-0 libgcc-9-dev libgcc-s1 libgomp1 libitm1 liblsan0 libstdc++-9-dev libstdc++6 libtsan0
  libubsan1
  
 **********************中间略过***************************

/sbin/ldconfig.real: /usr/local/lib/libopencv_calib3d.so.3.4 is not a symbolic link

/sbin/ldconfig.real: /usr/local/lib/libopencv_bgsegm.so.3.4 is not a symbolic link

/sbin/ldconfig.real: /usr/local/lib/libopencv_hfs.so.3.4 is not a symbolic link

/sbin/ldconfig.real: /usr/local/lib/libprotobuf.so.20 is not a symbolic link

/sbin/ldconfig.real: /usr/local/lib/libopencv_ccalib.so.3.4 is not a symbolic link

/sbin/ldconfig.real: /usr/local/lib/libopencv_tracking.so.3.4 is not a symbolic link

/sbin/ldconfig.real: /usr/local/lib/libopencv_plot.so.3.4 is not a symbolic link

/sbin/ldconfig.real: /usr/local/lib/libopencv_objdetect.so.3.4 is not a symbolic link

/sbin/ldconfig.real: /usr/local/lib/libprotoc.so.20 is not a symbolic link

/sbin/ldconfig.real: /usr/local/lib/libopencv_fuzzy.so.3.4 is not a symbolic link

+ sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-9 90 --slave /usr/bin/g++ g++ /usr/bin/g++-9 --slave /usr/bin/gcov gcov /usr/bin/gcov-9
update-alternatives: using /usr/bin/gcc-9 to provide /usr/bin/gcc (gcc) in auto mode
+ sudo rm /etc/lsb-release
+ sudo mv /etc/lsb-release.tmp /etc/lsb-release

最开始以为这些是有问题，但是实际上是没问题的，只要没报错就行。
3.下面就是正式安装DPU-PYNQ了。注意不要用github上原来的命令：pip3 install pynq-dpu。而是用下面的命令强制安装1.2.0版本：

pip3 install pynq-dpu==1.2.0

安装成功后输出如下：

root@pynq:/home/xilinx/jupyter_notebooks/DPU-PYNQ-1.2.0/upgrade# cd ..
root@pynq:/home/xilinx/jupyter_notebooks/DPU-PYNQ-1.2.0# ls
boards  host  LICENSE  MANIFEST.in  pynq_dpu  pyproject.toml  README.md  setup.py  upgrade  vitis-ai-git
root@pynq:/home/xilinx/jupyter_notebooks/DPU-PYNQ-1.2.0# pip3 install pynq-dpu==1.2.0
WARNING: pip is being invoked by an old script wrapper. This will fail in a future version of pip.
Please see https://github.com/pypa/pip/issues/5599 for advice on fixing the underlying issue.
To avoid this problem you can invoke Python with '-m pip' instead of running pip directly.
Collecting pynq-dpu==1.2.0
  Downloading pynq_dpu-1.2.0.tar.gz (2.0 MB)
     |████████████████████████████████| 2.0 MB 20 kB/s
Requirement already satisfied: CppHeaderParser in /usr/local/lib/python3.6/dist-packages (from pynq-dpu==1.2.0) (2.7.4)
Collecting mnist
  Downloading mnist-0.2.2-py2.py3-none-any.whl (3.5 kB)
Requirement already satisfied: pybind11 in /usr/local/lib/python3.6/dist-packages (from pynq-dpu==1.2.0) (2.5.0)
Requirement already satisfied: pynq>=2.6.0 in /usr/local/lib/python3.6/dist-packages (from pynq-dpu==1.2.0) (2.6.0)
Requirement already satisfied: ply in /usr/lib/python3/dist-packages (from CppHeaderParser->pynq-dpu==1.2.0) (3.11)
Requirement already satisfied: numpy in /usr/local/lib/python3.6/dist-packages (from mnist->pynq-dpu==1.2.0) (1.16.0)
Requirement already satisfied: pandas; python_version >= "3.5.3" in /usr/lib/python3/dist-packages (from pynq>=2.6.0->pynq-dpu==1.2.0) (0.22.0)
Requirement already satisfied: setuptools>=24.2.0 in /usr/lib/python3/dist-packages (from pynq>=2.6.0->pynq-dpu==1.2.0) (39.0.1)
Requirement already satisfied: cffi in /usr/lib/python3/dist-packages (from pynq>=2.6.0->pynq-dpu==1.2.0) (1.11.5)
Building wheels for collected packages: pynq-dpu
  Building wheel for pynq-dpu (setup.py) ... done
  Created wheel for pynq-dpu: filename=pynq_dpu-1.2.0-cp36-cp36m-linux_aarch64.whl size=1956924 sha256=f58e1947fb9b499f09aa3bdf5a4118a573b626e356df55e0ad36e71
423481797
  Stored in directory: /root/.cache/pip/wheels/2d/a8/04/d17cb68a21f61b5bfc72516dafe752f207e5fd75dbc369b761
Successfully built pynq-dpu
Installing collected packages: mnist, pynq-dpu
Successfully installed mnist-0.2.2 pynq-dpu-1.2.0
WARNING: You are using pip version 20.2.4; however, version 21.3.1 is available.
You should consider upgrading via the '/usr/bin/python3 -m pip install --upgrade pip' command.

然后再去获取笔记本：

root@pynq:/home/xilinx/jupyter_notebooks/DPU-PYNQ-1.2.0# cd $PYNQ_JUPYTER_NOTEBOOKS
root@pynq:/home/xilinx/jupyter_notebooks# pynq get-notebooks pynq-dpu -p .
Delivering notebooks './pynq-dpu'...
The notebooks module 'pynq-dpu' could not be delivered. The module has no notebooks, or no valid overlays were found
root@pynq:/home/xilinx/jupyter_notebooks#

这时候去Python文件中导包就不会报错了(最好将板子重启一下，更新一下环境)。

查找pynq-dpu版本方法：

pip3 list | grep pynq-dpu

---