从零构建：为自定义ZYNQ开发板编译专属PYNQ镜像

1. 为什么需要自定义PYNQ镜像当你拿到一块非官方的ZYNQ开发板时最头疼的问题可能就是找不到适配的PYNQ镜像。PYNQ官方虽然为一些热门开发板提供了预编译镜像但对于大量第三方开发板要么没有适配要么版本过于老旧。这时候自己动手编译专属PYNQ镜像就成了刚需。我去年接手一个项目用的就是一块国产ZYNQ开发板。官方提供的PYNQ镜像版本还是v2.6而最新版本已经到v3.0.1了。新版本不仅修复了大量bug还增加了对Python 3.8的支持和更多硬件库。为了用上新特性我不得不走上了自己编译镜像的道路。编译自定义PYNQ镜像最大的好处是你可以完全掌控系统环境。比如自由选择Ubuntu基础版本18.04/20.04定制预装软件包OpenCV、TensorFlow等优化内核参数以适应特定硬件集成自定义IP核的驱动支持整个过程虽然有些复杂但一旦掌握了方法就能为任何ZYNQ开发板打造专属的PYNQ环境。下面我就把踩过坑后总结的完整流程分享给大家。2. 环境准备搭建编译基地2.1 虚拟机配置要点PYNQ镜像编译强烈建议在虚拟机中进行。我试过直接在物理机安装Ubuntu一旦环境搞乱了恢复起来特别麻烦。VMware Workstation Pro现在对个人用户免费是个不错的选择。几个关键配置参数磁盘空间至少分配400GBVitis和Petalinux这两个大家伙会吃掉大量空间内存建议16GB以上8GB也能跑但编译速度会慢很多CPU核心给满宿主机的核心数并行编译能节省大量时间安装Ubuntu 20.04时有个小技巧把swap分区设置到物理分区而不是swap文件这样可以避免后续编译时因内存不足导致的奇怪错误。2.2 基础软件安装装好系统后先执行这些基础命令sudo apt update sudo apt upgrade -y sudo apt install -y git build-essential libncurses-dev tftp tftpd-hpa特别提醒一定要安装libncurses-dev否则后续编译qemu时会报curses library not found错误。这个坑我踩过三次2.3 禁用sudo密码提示编译过程中会有多次需要sudo权限的操作每次都输密码太烦人。可以这样设置sudo visudo在文件末尾添加记得把username换成你的实际用户名username ALL(ALL) NOPASSWD: ALL3. Xilinx工具链安装3.1 Vitis 2022.1安装实战从Xilinx官网下载Vitis 2022.1的离线安装包时会遇到需要填写美国地址的问题。这里有个小技巧使用美国地址生成器网站获取随机地址即可通过验证。安装时要注意先安装libtinfo5sudo apt install libtinfo5解压安装包后运行./xsetup只勾选你需要的器件型号Zynq-7000或UltraScale安装完成后添加环境变量echo source /tools/Xilinx/Vitis/2022.1/settings64.sh ~/.bashrc3.2 Petalinux 2022.1配置指南Petalinux的安装包同样需要美国地址才能下载。安装步骤chmod 755 petalinux-v2022.1-installer.run ./petalinux-v2022.1-installer.run安装完成后配置环境echo source ~/petalinux/settings.sh ~/.bashrc遇到WARNING: /bin/sh is not bash!提示时执行sudo dpkg-reconfigure dash然后选择No将默认shell保持为bash。4. 获取和准备PYNQ源码4.1 克隆和切换分支使用以下命令获取PYNQ源码并切换到v3.0.1版本git clone https://github.com/Xilinx/PYNQ.git cd PYNQ git checkout origin/image_v3.0.14.2 解决qemu下载问题老版本的PYNQ有个坑qemu下载源已经失效。需要手动修改vim sdbuild/scripts/setup_host.sh找到qemu下载行修改为wget https://download.qemu.org/qemu-$qemuver.tar.bz24.3 预编译文件准备为了节省时间建议从PYNQ官网下载两个预编译文件rootfs根据你的架构选aarch64或armsdist源码包把它们放到sdbuild/prebuild目录下分别重命名为pynq_rootfs.aarch64.tar.gzpynq_sdist.tar.gz5. 硬件描述文件生成5.1 Vivado工程创建启动Vivado创建新工程时关键是要选对芯片型号。这里经常出现的错误是选了封装类似的但不完全相同的型号导致生成的bitstream无法正常工作。创建Block Design时Zynq处理器的配置需要根据开发板原理图来设置DDR控制器参数外设时钟频率MIO/EMIO分配5.2 生成关键文件成功生成bitstream后需要导出硬件得到三个关键文件.bitFPGA配置比特流.hwh硬件描述文件.xsaXilinx支持存档文件我建议在Vivado工程目录下用这个命令快速查找这些文件find . -name *.bit -o -name *.hwh -o -name *.xsa6. 定制开发板描述文件6.1 目录结构规范在PYNQ的boards目录下为你的开发板创建如下结构your_board/ ├── base/ │ ├── base.bit │ ├── base.hwh │ ├── base.xsa │ └── base.py ├── petalinux_bsp/ │ └── hardware_project/ │ └── base.xsa └── your_board.spec6.2 spec文件详解spec文件是编译过程的核心配置文件这里以Zynq Ultrascale为例ARCH_your_board : aarch64 BSP_your_board : BITSTREAM_your_board : base/base.bit FPGA_MANAGER_your_board : 1 STAGE4_PACKAGES_your_board : xrt pynq ethernet关键参数说明ARCHarmZynq-7000或aarch64MPSoCFPGA_MANAGER1表示上电自动加载bitstreamSTAGE4_PACKAGESxrt和pynq是必选项7. 镜像编译与优化7.1 解决sstate-cache问题Petalinux编译时会在线下载sstate-cache国内网络环境经常失败。解决方法提前下载sstate-cache包解压到指定目录创建petalinuxbsp.conf指定路径SSTATE_DIR /path/to/sstate_aarch647.2 开始编译一切就绪后执行编译命令cd sdbuild make BOARDSyour_board编译时间取决于机器性能我的Ryzen 9 5950X大约需要2小时。期间可能会遇到以下问题常见错误1文件系统挂载失败 解决方法检查开发板spec文件中ARCH设置是否正确常见错误2网络下载超时 解决方法手动下载缺失的包放到dl目录8. 烧录与调试技巧8.1 镜像烧录编译成功后在sdbuild/output目录下会生成.img文件。推荐使用balenaEtcher进行烧录比dd命令更安全方便。8.2 串口调试开发板上电后通过串口观察启动过程。常见的启动问题问题现象Kernel panic - VFS无法挂载rootfs可能原因SD卡槽接在SD1但镜像配置为SD0Vivado工程中启用了写保护但硬件未使用解决方案修改设备树禁用写保护sdhci0 { disable-wp; }调整pynq_bootargs.dtsi中的mmcblk编号9. 进阶优化建议9.1 自定义软件包要在镜像中预装额外软件如OpenCV可以修改sdbuild/packages/your_package/添加对应的bb文件定义依赖关系。9.2 内核参数调优对于高性能应用可以调整sdbuild/linux/meta-pynq/recipes-kernel/linux/files/中的内核配置文件优化调度器和内存管理参数。整个流程走下来虽然会遇到各种问题但成功为自定义开发板编译出专属PYNQ镜像的成就感是巨大的。最重要的是这个过程让你对PYNQ系统的理解不再停留在表面而是真正掌握了从硬件描述到系统构建的完整技术链。