PYNQ镜像编译之MPSOC/RFSOC系列芯片

王雨霄

2859人浏览 · 2025-06-20 17:29:59

王雨霄 · 2025-06-20 17:29:59 发布

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

PYNQ镜像编译之MPSOC/RFSOC系列芯片

前言
一、在Win11系统下安装WSL
二、在WSL下安装Vivado工具
三、在WSL下安装PetaLinux工具
四、配置MPSOC处理器并导出硬件文件
五、下载PYNQ预编译镜像
六、编译PYNQ镜像
七、下板测试
附录一：设备树修改之SD卡
附录二：设备树修改之添加GEM
附录三：RFSOC PYNQ

前言

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

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

在上一篇文章中，描述了对ZYNQ-7系列芯片进行PYNQ镜像（v3.0.1）编译的过程，在本篇文章中，将借助正点原子的P4板卡（2EG版）进一步描述MPSOC架构芯片的PYNQ镜像编译过程，涉及相关环境及软件包括：WSL、Ubuntu-20.04、Vivado 2022.1、Petalinux 2022.1（若已按照上一篇文章中的步骤进行过相关环境及软件的安装，则可以跳过第一、二步骤）。

相关工程文件及镜像文件可自取：https://pan.baidu.com/s/1DG1VRWZEJD919kQcRrgnrg?pwd=dmpy。

一、在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。

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

在BD中添加MPSOC核，查阅所用板卡的PS端原理图，根据原理图中外设与MIO接口间的对应关系，对QSPI接口、以太网接口、USB接口、SD卡接口、UART接口、DDR等资源进行配置。

此处使用正点原子的P4板卡，MIO及DDR的相关原理图如下所示：
在这里插入图片描述

对应MIO配置及DDR配置如下：
在这里插入图片描述

配置完成后，应达到如下效果：
在这里插入图片描述

五、下载PYNQ预编译镜像

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

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

六、编译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/aarch64/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，以解决包缺失问题：
在这里插入图片描述

此外，需要注意的是，无论是ZYNQ还是MPSOC，PS端均存在SD0、SD1两个SD控制器资源，在硬件设计中，通常将一个SD控制器连接至外置TF卡，另一个SD控制器则连接至板上EMMC芯片。PYNQ默认从SD0加载启动镜像，这一行为适用于大部分ZYNQ板卡的硬件设计，而MPSOC板卡则习惯于将外置TF卡连接至SD1资源上，P4板卡也是如此，故在制作镜像前，需将PYNQ文件夹中的所有mmcblk0修改为mmcblk1，以便PYNQ启动文件能够从SD1对应的TF卡中加载系统：
在这里插入图片描述

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.aarch64.3.0.1.tar.gz文件路径> ~/code/PYNQ/sdbuild/prebuilt/pynq-rootfs.aarch64.tar.gz
# 在PYNQ/boards路径下创建p4/base和p4/petalinux_bsp/hardware_project文件夹，将第四步中得到的base.bit和system.xsa文件分别移入base和hardware_project文件夹中
cd ~/code/PYNQ/boards
mkdir -p p4/base
mkdir -p p4/petalinux_bsp/hardware_project
cp -r /mnt/c/Users/wyx62/Desktop/outputs/base.bit ./p4/base
cp -r /mnt/c/Users/wyx62/Desktop/outputs/system.xsa ./p4/petalinux_bsp/hardware_project
# 在PYNQ/boards路径下创建p4/petalinux_bsp/meta-user/recipes-bsp/device-tree/files文件夹，并在其中添加system-user.dtsi文件
mkdir -p p4/petalinux_bsp/meta-user/recipes-bsp/device-tree/files
sudo nano system-user.dtsi
# 将PYNQ/boards/ZCU104文件夹中的ZCU104.spec文件拷贝至PYNQ/boards/p4文件夹中，并重命名为p4.spec
cp -r ~/code/PYNQ/boards/ZCU104/ZCU104.spec ~/code/PYNQ/boards/p4/p4.spec

其中，system-user.dtsi文件的具体内容如下（该文件的具体内容与板卡的TF卡硬件设计有关，详情请见附录一）：

/include/ "system-conf.dtsi"
/ {
};
 
/* SD */
&sdhci1 {
    status = "okay";
    max-frequency = <50000000>;
    no-1-8-v;
    disable-wp;
};

运行“sudo nano ~/code/PYNQ/boards/p4/p4.spec”指令，将文件内容修改如下：
在这里插入图片描述

# Copyright (C) 2022 Xilinx, Inc
# SPDX-License-Identifier: BSD-3-Clause
ARCH_p4 := aarch64
BSP_p4 :=
BITSTREAM_p4 := base/base.bit
FPGA_MANAGER_p4 := 1
STAGE4_PACKAGES_p4 := xrt pynq ethernet sensorconf boot_leds pynq_peripherals

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

出现如下信息，代表make成功，此时可以在PYNQ/sdbuild/output文件夹中看到生成的.img镜像文件：
在这里插入图片描述

七、下板测试

于https://sourceforge.net/projects/win32diskimager下载win32diskimager软件，用于将.img镜像文件烧录进TF卡中：
在这里插入图片描述

将烧录成功的TF卡插入SD 1卡槽中，并将板卡PS端的串口、以太网口连接至电脑，设置板卡为SD启动模式后上电重启，在电脑端的MobaXterm中以115200波特率打开对应COM口，看到如下启动信息，证明PYNQ成功启动：
在这里插入图片描述

输入ifconfig指令，查看PYNQ的IP地址及子网掩码：
在这里插入图片描述

设置电脑以太网口的IP与PYNQ处于同一网段下，此时便可通过浏览器、ssh登录、网络共享等方式来访问PYNQ（用户名和密码均为xilinx）：
在这里插入图片描述

注：若需对板卡断电，应先通过sudo shutdown -h now命令执行关机，再关闭电源，直接断电可能对文件系统造成损害。

附录一：设备树修改之SD卡

对于TF卡而言，其工作电压通常为1.8V或3.3V，在不同工作电压下，TF卡具有不同的速度模式：
在这里插入图片描述

在ZCU111等XILINX官方板卡中，为实现TF卡工作速度的切换，通常会选用电压转换芯片，对TF卡的工作电压进行控制（刚上电时，TF卡处于默认的速度模式，PS端将通过CMD命令查询TF卡版本，将其工作速度配置到当前版本所能支持的最高速度）：
在这里插入图片描述

目前使用的TF卡，大多数已经支持SDR104模式（1.8V工作电压），因此，在初始化过程中，PS端将试图切换TF卡的速度模式为SDR104；而在正点原子的P4板卡中，TF卡固定使用了3.3V供电，无法切换为SDR104模式，这将导致初始化环节失败（系统启动时出现如下图所示的“mmc1: error -110 whilst initialising SD card”报错）：
在这里插入图片描述

为解决此问题，对于这类使用3.3v固定电压向TF卡供电的板卡，需要在设备树中禁用相应SD设备的1.8v工作模式，即在第六步中的system-user.dtsi文件中添加“no-1-8-v”约束；由下图可见，加入这一约束后，P4板卡中的TF卡初始化成功，TF卡此时被设置为HS模式：
在这里插入图片描述
此外，对于未设计TF卡写保护引脚（WP）的板卡，设备树中还需添加“disable-wp”约束（即使在vivado中的UI界面关闭了WP引脚，也需要添加这一约束），否则会出现如上图蓝框所示的“VFS: Cannot open root device “mmcblk1p2” or unknown-block(179,2):error -30”报错（上图是在设备树内添加“no-1-8-v”约束、未添加“disable-wp”约束的情况下获得）。

附录二：设备树修改之添加GEM

对其它板卡进行PYNQ编译时，发现有些板卡出现了系统能启动，但网口连不上的情况；查询启动日志发现，问题板卡在启动时提示了“No ethernet found”信息：
在这里插入图片描述

为进一步定位问题，在系统启动后，通过串口运行 find /proc/device-tree/ -name ‘*phy*’ 指令，检查设备树，发现有关网口的设备树信息仅有如下一条：

/proc/device-tree/axi/ethernet@ff0e0000/phy-mode

而正常情况下，有关网口的设备树信息应具有如下三条：

/proc/device-tree/axi/ethernet@ff0e0000/ethernet-phy@c
/proc/device-tree/axi/ethernet@ff0e0000/phy-mode
/proc/device-tree/axi/ethernet@ff0e0000/phy-handle

因此，可以确认问题是由于以太网PHY芯片没有被挂载至设备树导致的（怀疑和PHY芯片的地址设置有关，导致内核没有扫描到PHY芯片）；为解决这一问题，需要在第六步中的system-user.dtsi文件中添加如下设备树信息：

/* GEM3 */
&gem3 {
    status = "okay";
    phy-mode = "rgmii-id";
    phy-handle = <&phyc>;
    #address-cells = <1>;
    #size-cells = <0>;

	phyc: phy@c{
        reg = <0xc>;
        device_type = "ethernet-phy";
        ti,rx-internal-delay = <0x08>;
        ti,tx-internal-delay = <0x08>;
        ti,fifo-depth = <0x01>;
        ti,dp83867-rxctrl-strap-quirk;
	};
};

其中，设备树中的如下信息与板卡的硬件情况相关联：
1、第2行代码中的gem编号应与PS端实际使用的网口保持一致；例如，问题板卡的PS端使用的是GEM3网口，故第2行应为”&gem3“；
2、第9、10行中的”c“应与PHY芯片的实际物理地址保持一致；例如，问题板卡的PHY芯片物理地址为01100，对应16进制为0xc，故第9行为”phy@c“，第10行为”<0xc>“；
3、第12-15行为TI的DP83867芯片专用，若使用其它芯片，无需添加此内容。

PHY芯片的物理地址通常由原理图中的硬件设计决定，通过对PHY芯片的特定引脚端接上拉/下拉电阻，可以实现对PHY芯片物理地址的设置；以ZCU111板卡中使用的DP83867为例，DP83867数据手册中给出的PHY地址设置方式如下：
在这里插入图片描述

可见，DP83867的地址共有5bit，从高位到低位依次为PHY_ADD4~PHY_ADD0，通过设置RX_D0、RX_D2、RX_D4三个引脚的电阻上下拉模式（MODE），可为PHY_ADDx设置不同取值；在ZCU111板卡中，相应的硬件设计如下：

其中，RX_D0、RX_D2、RX_D4的电阻上下拉模式分别为1、4、1，故DP83867的地址为01100，即0xc。

按照上述方法，增添GEM相关设备树信息后，系统启动时不再提示“No ethernet found”信息，gem3被正常识别为eth0网口，在系统启动后可通过以太网正常访问板卡：
在这里插入图片描述

附录三：RFSOC PYNQ

RFSOC PYNQ是Xilinx针对RFSOC系列板卡推出的一种定制化PYNQ系统，本质上是在普通PYNQ系统的基础上加入了一些特殊的库来驱动RFSOC板卡上的外围时钟芯片及RFSOC芯片内部的RFADDA硬核、SDFEC硬核：
在这里插入图片描述

目前，PYNQ工具链中对RFSOC PYNQ系统编译的支持仅限于部分Xilinx官方板卡：
在这里插入图片描述

Xilinx官方并未给出将RFSOC PYNQ系统移植到第三方RFSOC板卡上的方案，但由于RFSOC内的PS端仍采用了MPSOC架构，理论上，只要在MPSOC系列芯片的PYNQ镜像编译流程基础上引入对设备树和库文件的修改，就可以达到RFSOC PYNQ的效果，笔者在此进行了尝试，成功将RFSOC PYNQ系统移植到了一个第三方的RFSOC板卡(28dr)上：
在这里插入图片描述