PYNQ镜像编译之ZYNQ系列芯片

王雨霄

2156人浏览 · 2025-06-13 17:23:50

王雨霄 · 2025-06-13 17:23:50 发布

提示：文章写完后，目录可以自动生成，如何生成可参考右边的帮助文档

PYNQ镜像编译之ZYNQ系列芯片

前言
一、在Win11系统下安装WSL
二、在WSL下安装Vivado工具
三、在WSL下安装PetaLinux工具
四、配置ZYNQ处理器并导出硬件文件
五、下载PYNQ预编译镜像
六、编译PYNQ镜像
七、下板测试

前言

PYNQ是Xilinx提出的一种运行于ZYNQ、MPSOC、RFSOC系列芯片PS端上的操作系统，该操作系统建立在Ubuntu系统的基础上，将部分底层操作封装为Python函数，使用户能够通过Python语言对PS端进行开发。

对于部分官方开发板，Xilinx在PYNQ官网直接提供了相应的系统镜像文件；而大多数情况下，我们使用的是第三方板卡，对于第三方板卡，Xilinx同样提供了一套工具链，用于生成定制化的PYNQ镜像。

本文旨在描述对ZYNQ-7系列芯片进行PYNQ镜像（v3.0.1）编译的过程，并针对当前XIlinx官方工具链中的包缺失等问题进行了修复，涉及相关环境及软件包括：WSL、Ubuntu-20.04、Vivado 2022.1、Petalinux 2022.1。

一、在Win11系统下安装WSL

在Windows命令窗中运行wsl --install -d Ubuntu-20.04指令，安装wsl环境下的20.04版本Ubuntu：
在这里插入图片描述

运行wsl -l -v指令，出现如下信息，证明安装成功：
在这里插入图片描述

上述步骤无法设置安装路径，默认将WSL环境安装在C盘中，若C盘空间较小（低于200G），则需将WSL迁移至其它空间较大的硬盘，以迁移至D盘为例，需依次运行如下四条指令：

wsl --shutdown
wsl --export Ubuntu-20.04 d:\Ubuntu-20.04.tar
wsl --unregister Ubuntu-20.04
wsl --import Ubuntu-20.04 d:\Ubuntu2004 d:\Ubuntu-20.04.tar

在这里插入图片描述

运行完成后，D盘中出现名为“Ubuntu2004”的文件夹，且文件夹中包含一个硬盘映像文件，说明迁移成功：
在这里插入图片描述

迁移完成后，在Windows命令窗中运行diskpart指令，此时会弹出一个新的命令窗口:
在这里插入图片描述

在新的命令窗口中运行Select vdisk file=<硬盘映像文件地址>和detail vdisk两条指令，查看子系统的默认空间：
在这里插入图片描述
此时子系统的默认空间为1024GB，足够后续使用，无需进行扩容（倘若需要扩容，运行expand vdisk maximum=<目标大小> 指令即可）。

需要注意的是，迁移后wsl的默认登录用户会变为root，为避免出现权限问题，需运行sudo nano /etc/wsl.conf指令，在配置文件中加入如下内容，将默认登录用户重新设置为普通用户：
在这里插入图片描述

修改完成后，重启wsl，配置生效：
在这里插入图片描述

二、在WSL下安装Vivado工具

下载Vivado安装包

根据下图中的版本对应关系，于XILINX官网https://www.xilinx.com/support/download.html下载与目标PYNQ版本相匹配的Vivado工具（版本必须严格对应）：
在这里插入图片描述

本教程以PYNQ v3.0.1镜像为例，需下载2022.1版本的Vivado离线安装包：
在这里插入图片描述
注：也可通过https://pan.baidu.com/s/1cPF_Wb2suwQRYOBZcuaGkQ?pwd=o6q7下载。

安装依赖包

Vivado安装包体积较大，下载耗时较长，在下载过程中可先进行安装环境的准备工作。

运行sudo dpkg-reconfigure dash指令，选择“No”选项，修改shell命令为bash模式：
在这里插入图片描述

运行sudo apt update指令，更新包列表：
在这里插入图片描述

运行sudo apt install x11-apps指令，安装x11图形化界面：
在这里插入图片描述

安装完成后，运行export LANG=C和xclock指令，若弹出时钟界面，则证明x11功能安装成功：
在这里插入图片描述
注：x11是图形化界面，不等同于桌面，仅安装x11并不能在Linux系统下打开桌面。

随后，依次运行如下指令，安装依赖包：

sudo apt install libncurses5 build-essential openjdk-11-jdk
sudo apt install build-essential
sudo apt install gcc gdb
sudo apt install libtinfo5
sudo apt-get --reinstall install libc6 libc6-dev
sudo apt install libc6-dev-i386
sudo ln -s /usr/lib/x86_64-linux-gnu /usr/lib64
export LIBRARY_PATH=/usr/lib/x86_64-linux-gnu:$LIBRARY_PATH

安装Vivado

在Linux系统根目录下创建“/tools/Xilinx”文件夹（“/tools/Xilinx”为VIVADO工具在Linux系统下的默认安装路径），并使用 sudo chmod 777 指令开启文件夹的读写权限：
在这里插入图片描述

将下载好的Vivado安装包复制进WSL内：
在这里插入图片描述

进入安装包文件夹中，运行sudo chmod a+x ./xsetup指令，为安装包程序添加可执行权限：
在这里插入图片描述

运行./xsetup指令，启动安装包程序：
在这里插入图片描述

安装完成后，运行sudo nano ~/.bashrc指令，编辑环境变量：
在这里插入图片描述

source /tools/Xilinx/Vitis/2022.1/settings64.sh
source /tools/Xilinx/Vitis_HLS/2022.1/settings64.sh
source /tools/Xilinx/Vivado/2022.1/settings64.sh

运行source ~/.bashrc指令刷新环境变量后，可通过vivado指令于命令行直接启动Vivado，证明安装成功：
在这里插入图片描述

加载License

安装完成后，需对Vivado进行破解，可于https://pan.baidu.com/s/1mtA371JhAtDN4epgq0QpGQ?pwd=tzhk下载相应license文件：
在这里插入图片描述

三、在WSL下安装PetaLinux工具

于官网下载PetaLinux安装包：
在这里插入图片描述

注：也可通过https://pan.baidu.com/s/1vRq3PpZ3AJQoy76S3q0UBg?pwd=1v0i下载。

在“/tools/Xilinx”路径下手动创建“petalinux/2022.1”文件夹（切勿使用“sudo mkdir”命令）：
在这里插入图片描述

将安装包复制进WSL内：
在这里插入图片描述

运行sudo chmod a+x ./petalinux-v2022.1-04191534-installer.run指令，赋予安装包可执行权限：
在这里插入图片描述

执行./petalinux-v2022.1-04191534-installer.run --dir /tools/Xilinx/petalinux/2022.1指令，进行安装：
在这里插入图片描述
安装过程中会首先进行环境检查，并列出未安装的依赖包，上图红框中列出的包可通过如下指令来安装：

sudo apt-get install net-tools iproute2 xterm autoconf libtool texinfo zlib1g-dev libncurses5 libncurses5-dev
sudo dpkg --add-architecture i386
sudo apt-get update
sudo apt-get install zlib1g:i386

安装依赖包后，重新运行 ./petalinux-v2022.1-04191534-installer.run --dir /tools/Xilinx/petalinux/2022.1 指令即可：
在这里插入图片描述

PetaLinux安装完成后，运行sudo nano ~/.bashrc指令，编辑环境变量，在文件末尾加入source /tools/Xilinx/petalinux/2022.1/settings.sh：
在这里插入图片描述

运行 source ~/.bashrc 指令，刷新环境变量：
在这里插入图片描述
此时出现两条警告：第一条警告是因为当前使用的Ubuntu版本20.04与XILINX官方推荐版本16.04/18.04不吻合，实际使用中尚未发现PetaLinux-2022.1在Ubuntu-20.04下存在异常行为，该警告不影响PetaLinux工具的正常使用；第二条警告是因为没有安装TFTP服务，本教程仅利用PetaLinux工具生成启动镜像，不涉及PetaLinux与ZYNQ板卡之间的在线通信，无需安装TFTP。

四、配置ZYNQ处理器并导出硬件文件

对PS端处理器的设置，主要分为MIO外设设置、时钟设置、DDR设置三部分。

MIO外设设置

在BD中添加ZYNQ核，关闭多余接口，仅保留“DDR”和“FIXED_IO”接口并引出：
在这里插入图片描述
查阅所用板卡的PS端原理图：

根据PS端原理图中外设与MIO接口间的对应关系，对ZYNQ核的QSPI接口、以太网接口、USB接口、SD卡接口、UART接口等资源进行配置。

配置时，首先在“Peripheral I/O Pins”菜单中设置外设与MIO间的映射关系，并设置PS端BANK0及BANK1的电平标准，例如，本教程所使用的板卡的原理图中，PS端的千兆网口利用了16-27号MIO，则在ZYNQ核中对应勾选Ethernet0资源：
在这里插入图片描述

电平标准同样需在原理图中查阅，通常BANK0（下图中的xx_500）电压为LVCMOS 3.3V，BANK1（下图中的xx_501）电压为LVCMOS 1.8V：
在这里插入图片描述

需要注意的是，以太网接口、USB接口及I2C接口的复位引脚需在GPIO MIO资源中单独设置（本教程所使用的板卡在硬件设计时仅将USB接口的复位引脚接入了MIO资源中）：
在这里插入图片描述

完成上述设置后，在“MlO Configuration”菜单中将以太网接口、USB接口及SD卡接口设置为高速模式（Speed选项会影响相应MIO接口的驱动能力，选择合适的Speed模式有助于降低EMI；对于以太网口等高速接口而言，此参数应选择“fast”）：
在这里插入图片描述

在这里插入图片描述

同时，对于SD卡，还应关注其CD引脚与WP引脚：
在这里插入图片描述
CD（Card Detect）引脚用于检测SD卡是否插入卡槽中；WP（Write Protect）引脚用于设置SD卡是否处于写保护状态，通过设置WP引脚，可以限制对SD卡的写入权限，防止意外的数据修改或删除；在本教程所使用的板卡中，仅对WP引脚进行了设计，故此处只勾选了WP引脚。

此外，对于一些没有连接至标准外设的MIO引脚，可作为GPIO由用户自定义使用：在这里插入图片描述
例如，在本教程所使用的板卡中，MIO 0、MIO 50、MIO 51分别被连接至板上的KEY1、LED1、LED2。

时钟设置

进入Clock Configuration界面，设置红框中的PS端时钟频率与板上的PS晶振频率保持一致（通常为33.333333MHz）：在这里插入图片描述

DDR设置

ZYNQ-7系列芯片仅支持使用DDR2/DDR3，不支持使用DDR4，配置DDR时，仅需设置DDR器件型号（根据板卡实际使用的DDR型号来设置），其余参数保持默认：
在这里插入图片描述

导出硬件文件

配置完成后，由BD设计生成顶层Verilog文件（由于开启了USB功能，此时的ZYNQ核相比最初多出了一组USBIND_0信号，这是PS端向PL端提供的信号，无需引出）：
在这里插入图片描述

生成顶层Verilog文件后，执行生成比特流操作：
在这里插入图片描述

生成比特流后，将比特流文件重命名为“base.bit”，并导出xsa硬件信息文件（自Vivado 2019.2版本起，硬件信息文件的后缀由.hdf变为.xsa）：
在这里插入图片描述

生成的硬件信息文件需重命名为“system.xsa”。

五、下载PYNQ预编译镜像

于官网https://www.pynq.io/boards.html下载PYNQ-v3.0.1预编译镜像：
在这里插入图片描述
上图红框中的aarch64版本主要面向MPSOC架构的A53内核，arm版本主要面向ZYNQ架构的A9内核；本教程针对ZYNQ-7系列芯片的PYNQ制作方法进行演示，需要选用arm版本的预编译镜像，下载成功后得到如下文件：

注：也可通过https://pan.baidu.com/s/183A9ld8JMVAl8uPOxOhUHw?pwd=o8vd下载。

六、编译PYNQ镜像

官方PYNQ工具链下载

运行 git clone https://github.com/xilinx/PYNQ.git 指令，将PYNQ库克隆至WSL中：
在这里插入图片描述

进入PYNQ文件夹内，运行 git tag 指令，列出当前的发布版本：
在这里插入图片描述

运行 git checkout v3.0.1 指令，切换至对应分支：
在这里插入图片描述

官方PYNQ工具链问题修复

使用VSCode打开PYNQ文件夹，修改PYNQ文件夹中的sdbuild/scripts/setup_host.sh文件，在94行末尾加入下图所示的”--no-check-certificate”，以解决wget链接HTTPS证书过期的问题：
在这里插入图片描述

修改PYNQ文件夹中的sdbuild/scripts/create_rootfs.sh文件，将其中第81、 82行的源链接由Ubuntu官方源http://ports.ubuntu.com/ubuntu-ports替换为国内源，以加快编译过程中依赖包的下载速度：
在这里插入图片描述

修改PYNQ文件夹中的sdbuild/ubuntu/jammy/arm/multistrap.config文件，将其中第9行的源链接由Ubuntu官方源http://ports.ubuntu.com/ubuntu-ports替换为国内源，原因同上：
在这里插入图片描述

常用国内源：
清华源：https://mirrors.tuna.tsinghua.edu.cn/ubuntu-ports
阿里源：http://mirrors.aliyun.com/ubuntu-ports
中科大源：http://mirrors.ustc.edu.cn/ubuntu-ports

修改PYNQ文件夹中的所有git://gcc.gnu.org/git/gcc.git为https://github.com/gcc-mirror/gcc.git，以解决包缺失问题：
在这里插入图片描述

PYNQ镜像编译

运行export PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple指令，将python源切换为清华镜像：
在这里插入图片描述

依次运行cd ./sdbuild/scripts 、 sudo chmod +x setup_host.sh 、 sudo ./setup_host.sh三条指令，执行自检脚本，安装依赖库环境：
在这里插入图片描述

依赖库环境安装完成后，运行sudo nano ~/.bashrc指令，编辑环境变量，在文件末尾加入export PATH=/opt/qemu/bin:/opt/crosstool-ng/bin:$PATH：
在这里插入图片描述
编辑完成后，保存并退出，运行source ~/.bashrc指令，刷新环境变量。

随后，依次运行如下指令，进行PYNQ镜像编译前的文件准备工作：

# 将第五步得到的两个.gz文件移入PYNQ/sdbuild/prebuilt文件夹中并重命名
cp -r <pynq-3.0.1.tar.gz文件路径> ~/code/PYNQ/sdbuild/prebuilt/pynq_sdist.tar.gz
cp -r <jammy.arm.3.0.1.gz文件路径> ~/code/PYNQ/sdbuild/prebuilt/pynq-rootfs.arm.tar.gz

# 在PYNQ/boards路径下创建zynq7020/base和zynq7020/petalinux_bsp/hardware_project文件夹，将第四步中得到的base.bit和system.xsa文件分别移入base和hardware_project中
cd ~/code/PYNQ/boards
mkdir -p zynq7020/base
mkdir -p zynq7020/petalinux_bsp/hardware_project
cp -r <base.bit文件路径>./zynq7020/base
cp -r <system.xsa文件路径> ./zynq7020/petalinux_bsp/hardware_project

# 将PYNQ/boards/Pynq-Z2文件夹中的Pynq-Z2.spec文件拷贝至PYNQ/boards/zynq7020文件夹下，并重命名为zynq7020.spec
cp -r ~/code/PYNQ/boards/Pynq-Z2/Pynq-Z2.spec ~/code/PYNQ/boards/zynq7020/zynq7020.spec

在这里插入图片描述

完成上述步骤后，运行sudo nano ~/code/PYNQ/boards/zynq7020/zynq7020.spec指令，将文件内容修改如下：
在这里插入图片描述

# Copyright (C) 2022 Xilinx, Inc
# SPDX-License-Identifier: BSD-3-Clause
ARCH_zynq7020 := arm
BSP_zynq7020 :=
BITSTREAM_zynq7020 := base/base.bit
FPGA_MANAGER_zynq7020 := 1
STAGE4_PACKAGES_zynq7020 := xrt pynq boot_leds ethernet pynq_peripherals sdcardshrink precached_metadata

最后，在PYNQ/sdbuild文件夹下运行make REBUILD_PYNQ_ROOTFS=True BOARDS=zynq7020指令，启动镜像编译：
在这里插入图片描述
注：
1、make过程中需要在线下载依赖包，最好将电脑连接至稳定的有线网络并在非高峰期执行make；
2、电脑内存不足将导致make失败，建议在make期间关闭无关程序；
3、必须使用“make ……”指令，不能使用“sudo make ……”或“make -j ……”来更改运行权限或并发执行。