总述

本文面向  FPGA 工程师和嵌入式工程师，目标是帮助初学者把 Xilinx 官方 PYNQ/PYNQ 的 overlay 在线加载思路移植到自定义  自定义 FPGA 板卡，并能稳定完成 bit 在线加载、RPC 恢复、数据转换子系统 状态查询和 PL DDR 数据通路验证。

本文来自  test 自定义板卡 PYNQ 化过程中的真实排障记录。最终验证通过的稳定路径是：上位机脚本上传 bit/hwh，停止板端 RPC  服务，用独立 systemd-run 进程执行 PYNQ Overlay(download=True)，等待 FPGA manager 回到  operating，重启 RPC，再通过 /health、/converter/status 和 PL DDR waveform  写读闭环做验收。

一、目标架构

官方  PYNQ 的常见使用方式是把 bit、hwh 和 Python overlay driver 打包到镜像中，运行时用 PYNQ Overlay  类加载硬件设计，并通过 HWH 解析 IP 字典。自定义板卡迁移时，关键不是简单复制 ZCU208 的文件结构，而是确保  PS/Linux、FPGA manager、PMUFW、XRT/zocl、PYNQ 虚拟环境、overlay 产物和业务 runtime  在同一个闭环里工作。

推荐架构分为三层。第一层是启动基线，SD  卡 BOOT.BIN/image.ub/boot.scr 必须能稳定启动 Linux，并且 FPGA manager、PMUFW、设备树和  zocl/XRT 状态正常。第二层是在线加载工具，由 host 脚本和板端独立 loader 组成，负责上传 bit/hwh、停止 RPC、执行  Overlay(download=True)、重启 RPC 和生成报告。第三层是业务验证，通过 RPC 做 AXI-Lite  寄存器访问、数据转换子系统 状态读取和 PL DDR 数据读写闭环。

Host Python script  -> scp bit/hwh/runtime  -> ssh stop test-pynq-rpc.service  -> systemd-run test-pynq-online-load --backend overlay  -> wait fpga_manager state operating  -> restart test-pynq-rpc.service  -> poll /health  -> query /converter/status  -> run PL DDR waveform write/readback smoke

二、必备产物和环境

自定义板卡至少需要准备四类产物。硬件产物包括  bit、hwh 和可选的 bin。bit 用于配置 PL，hwh 用于 PYNQ 解析 IP 和地址空间，bin 可用于直接走 Linux  FPGA manager/sysfs 路径排障。启动产物包括 BOOT.BIN、image.ub 和 boot.scr。运行时产物包括  test_pynq 这类板端 Python runtime、systemd service、在线加载 CLI。验证产物包括 host  端远程加载脚本、寄存器读写脚本和 waveform 写读闭环脚本。

test 验证中使用的关键本地产物路径如下。移植到其他板卡时，可以保留目录组织思路，但要替换为自己的工程输出。

build/pynq_online_load_reports/live/vivado_bin_check/test_top_vivado_bin.bitbuild/pynq_online_load_reports/live/vivado_bin_check/test_top_vivado_bin.binbuild/pynq_overlay/test.hwhtools/run_pynq_online_overlay_load_remote.pypynq_rpc/src/test_pynq/online_load.py

三、遇到的问题、原因和解决方法

问题一：RPC 进程内直接在线加载 bit，服务容易卡住或 /health 超时。  根因是 RPC 进程在处理网络请求的同时还持有 PYNQ、数据转换子系统、MMIO 或 AXI-Lite 访问路径。PL 重配期间 AXI  矩阵和 PL IP 会短暂不可用，如果此时继续读写寄存器，容易触发 AXI timeout，表现为 RPC 无响应、/health  超时或需要重启服务。解决方法是保留 /overlay/load 的 metadata 加载能力，但禁止 RPC 内部执行  download=true。真正的 bit 下载由独立在线加载工具完成。

/usr/bin/python3 tools/run_pynq_online_overlay_load_remote.py \  --host BOARD_IP \  --backend overlay \  --bitfile build/pynq_online_load_reports/live/vivado_bin_check/test_top_vivado_bin.bit \  --hwh build/pynq_overlay/test.hwh \  --expect-compile-date 0x20260723 \  --expect-compile-time 0x1542ffff \  --disable-auto-reboot

问题二：Linux FPGA manager/PCAP 加载失败，状态为 write error: 0xffffe9fc。  失败时 dmesg 中可以看到 Xilinx ZynqMP FPGA Manager 写入失败，PMUFW/XilFPGA 侧错误解码指向  XFPGA_ERROR_PCAP_PL_DONE。排查中分别测试了完整 自定义 FPGA bit、最小 canary bit、Vivado 原生  bin、PYNQ 转换 bin、卸载 zocl 后加载，均能复现，说明问题不在 RPC、JSON、zocl 或设计规模本身。JTAG 直接  program 同类 bit 可以成功，DONE/EOS 正常，说明 bit 和物理 DONE 通路没有问题。根因集中在 Linux FPGA  manager 到 PMUFW/XilFPGA 的 runtime PCAP 全量重配置序列。

解决方法是在  PMUFW/XilFPGA 侧补齐 runtime PCAP 序列，使其和 FSBL 启动配置路径更一致。test 工程中通过  PetaLinux meta-user 对 pmu-firmware 增加补丁，并重新生成  BOOT.BIN/image.ub/boot.scr。关键补丁包括等待 PL config reset/init 相关状态，以及增加 PMUFW  侧诊断寄存器，便于后续判断 PCAP 流程走到哪里。

pynq_image/boards/test_board/petalinux_bsp/meta-user/recipes-bsp/embeddedsw/files/0001-xilfpga-pcap-wait-for-pl-cfg-rst-before-pl-init.patchpynq_image/boards/test_board/petalinux_bsp/meta-user/recipes-bsp/embeddedsw/files/0002-xilfpga-pcap-add-test-runtime-diagnostics.patchpynq_image/boards/test_board/petalinux_bsp/meta-user/recipes-bsp/embeddedsw/pmu-firmware_%.bbappend

问题三：直接从 Linux kernel module 读取 CSU/PCAP MMIO 会触发 synchronous external abort。  这说明在该平台上，Linux EL1 直接访问部分 CSU/PCAP 寄存器并不安全。解决方法是不要从 Linux 直接读这些寄存器，而是在  PMUFW/XilFPGA 内部采集状态，再通过安全的 PM_FPGA_READ IPI/readback 路径暴露给 Linux 诊断模块。

问题四：第一次修复后测试仍显示失败，但实际 PCAP 已成功。  根因是测试脚本在加载前停止了 test-pynq-rpc.service，但只在 loader 失败时重启 RPC。loader 成功后  RPC 反而保持 stopped，导致 /health 不可达，于是报告误判为失败。解决方法是无论 loader  成功还是失败，都执行服务恢复；PASS 条件改成 loader 成功、ping 可达、/health 返回 ok=true 三者同时成立。

问题五：手动 Python REPL 执行 PYNQ probe 报 No Devices Found 或 Could not open device with index 0。  根因是手动环境和 systemd-run 的加载环境不同，涉及 root  权限、XILINX_XRT、VIRTUAL_ENV、PATH、zocl 设备节点等因素。test 验证中，普通未隔离 REPL 报错，但通过  systemd-run 执行的 test-pynq-online-load 可以稳定完成  Overlay(download=True)。解决方法是把在线加载做成固定命令和固定环境，不要求工程师在 REPL 中手工 import  Overlay 测试。

四、推荐实现步骤

第一步：先确认 SD 启动基线。 板卡必须能从 SD 启动 Linux，网络可达，SSH 可登录，/sys/class/fpga_manager/fpga0/state 存在并为 operating，板端 PYNQ 虚拟环境可用。

cat /sys/class/fpga_manager/fpga0/statesystemctl is-active test-pynq-rpcip -brief addr show eth0/usr/local/share/pynq-venv/bin/python3 -c "import pynq; print(pynq.__version__)"

第二步：打包 bit/hwh，并提供版本寄存器。 自定义板卡最好在 PL 中保留可读版本寄存器，例如 fpga_version、compile_date、compile_time。在线加载后只要 /health 能读到这些寄存器，就能确认当前运行的固件版本。

fpga_version = 0x0a001000compile_date = 0x20260723compile_time = 0x1542ffff

第三步：实现板端在线加载 CLI。 CLI 默认只做 bit 下载和 fpga_manager 状态等待，不在主加载进程里立刻做大量 AXI 访问。需要读版本时，可以用短超时的子进程读，避免主进程被 AXI timeout 拖死。

/usr/local/share/pynq-venv/bin/test-pynq-online-load \  --bitfile /opt/test/overlays/test.bit \  --backend overlay \  --verify-mode none \  --settle-seconds 3 \  --output /tmp/test-online-overlay-load.json

第四步：实现 host 端事务脚本。 host 脚本负责部署 runtime、上传 bit/hwh、安排 rescue、停止 RPC、调用板端 loader、重启 RPC、轮询 /health、收集诊断报告。这样 FPGA 工程师只需要执行一个稳定入口，不需要记住所有板端细节。

第五步：保留 sysfs/PCAP 旁路排障能力。  当 Overlay(download=True) 失败时，直接走 /sys/class/fpga_manager/fpga0/firmware  可以区分问题是在 PYNQ/XRT 层，还是在 Linux FPGA manager/PMUFW/PCAP 层。如果 sysfs  也失败，应优先查 PMUFW、PCAP、bitstream 格式和启动配置；如果 sysfs 成功但 Overlay 失败，再查  PYNQ/XRT/zocl/HWH。

五、推荐验收流程

在线加载功能不能只看命令返回 0。建议使用分层验收，每层通过后再进入下一层。这样一旦失败，可以快速定位到网络、服务、FPGA manager、PYNQ overlay、数据转换子系统 或业务数据通路。

test  板最终验证结果如下。PCAP/sysfs full bit 连续加载通过，PYNQ Overlay(download=True)  backend 连续加载通过，加载后 RPC 和 数据转换子系统 状态可读，9 KiB waveform 写入 PL DDR 后  readback SHA256 一致。

PYNQ Overlay backend repeat 1: PASS, elapsed 14313.481 msPYNQ Overlay backend repeat 2: PASS, elapsed 14236.748 ms/health: ok=true/converter/status: ok=truereadReg(0xc): 0x202607239 KiB waveform write/readback: PASSwaveform sha256: 04f38e3e0e8f86e1710ca68532154c47f8d05ff387fca4e4fa47d07b7be6f138

六、移植到新板卡时的检查清单

七、常见错误速查

总结

自定义板卡迁移  PYNQ overlay 在线加载时，真正困难的部分通常不在 Python 语法，而在 PS 启动基线、PMUFW/PCAP runtime  重配、XRT/zocl 环境、RPC 与 PL 重配的隔离，以及加载后的分层验收。test 板的经验表明，只要把在线加载做成隔离事务，并补齐  PMUFW/PCAP 路径，PYNQ Overlay(download=True) 可以像官方 PYNQ 板卡一样稳定工作。

初学者移植时建议记住一句话：先让  SD 启动和 FPGA manager 稳，再让 sysfs/PCAP 能加载，再让 PYNQ Overlay 能加载，最后再做  数据转换子系统 和 PL DDR 业务闭环。每一层都留下日志和版本号，问题就会从“玄学掉线”变成可以逐层定位的工程问题。