第二篇进入真正的构建现场：XSA 如何变成 Linux，PYNQ board repository 如何组织，SD 镜像又该怎样被验证。

从 XSA 到镜像的流水线

最小  Linux 路线可以只使用 PetaLinux：创建工程、导入 XSA、配置内核和设备树、构建、打包启动文件，再把  BOOT.BIN、image.ub、boot.scr 复制到启动分区。若要做 PYNQ 镜像，则在这条链路之外再增加 PYNQ  sdbuild，由它生成 Ubuntu rootfs、PYNQ Python 环境、overlay 包和最终 SD card image。

这两条路线不是互斥关系。PYNQ 的板级支持仍然要依赖 PetaLinux 生成启动文件和 Linux 支持；PetaLinux 是底座，PYNQ 是更高层的开发体验。

Vivado project
  -> export hardware: test_design.xsa
  -> package overlay: base.bit + base.hwh

PetaLinux project
  -> import XSA
  -> configure device tree / rootfs / bootargs
  -> build images/linux
  -> package BOOT.BIN + image.ub + boot.scr

PYNQ sdbuild
  -> external board repository
  -> board spec + overlay package + runtime package
  -> output/test_board-3.1.x.img

准备一个外部 board repository

PYNQ  官方文档支持 third-party board repository。也就是说，你不必改官方 PYNQ  仓库，只要把自己的板卡目录按规则放好，再把 BOARDDIR 指向这个目录。这样做的好处是升级 PYNQ  时更干净，也方便在同一个仓库里维护多块测试板卡。

pynq_image/
  boards/
    test_board/
      test_board.spec
      base/
        base.bit
        base.hwh
        base.py
      petalinux_bsp/
        hardware_project/
          test_design.xsa
        meta-user/
          conf/
          recipes-bsp/
          recipes-kernel/
      packages/
        test_runtime/
          pre.sh
          qemu.sh
          post.sh
          boot.py
          test-board-config.py
          test-board-config.service
          test-pynq-rpc.service
      configs/
        test-board.default.json
        test-board.lab-a.json
        test-board.lab-b.json

这里有三个容易被忽略的文件。第一，overlay  目录里的 `.py` wrapper 即使很薄，也应该存在，否则某些 stage4 包复制规则会找不到 Python  文件。第二，`meta-user` 是你长期维护 device tree、PHY、bootargs、rootfs package  的地方，不建议在构建输出目录里手改。第三，`configs` 可以让多块板共用同一张镜像，把 hostname、静态 IP 和板卡角色放到  `/boot/test-board.json` 里。

spec 文件要写清楚

spec  文件不长，但它决定了 PYNQ 构建系统如何识别你的板卡。Zynq-7000 常见架构是 arm，ZynqMP/RFSoC 常见架构是  aarch64。若没有现成 BSP，可以让构建流程从 `petalinux_bsp/hardware_project/` 下的 XSA  生成板级支持；若已有可靠 BSP，则直接指定 BSP 文件。

ARCH_test_board := aarch64
BSP_test_board :=
BITSTREAM_test_board := base/base.bit
FPGA_MANAGER_test_board := 1
STAGE4_PACKAGES_test_board := pynq ethernet xrt xrfclk xrfdc xsdfec test_runtime

如果你的板卡不是 RFSoC，不需要 RFDC 或 RF clock 相关能力，可以删掉 `xrfclk`、`xrfdc`、`xsdfec`。如果你只是构建最小 Linux，也可以先不接入 PYNQ，把精力集中在 PetaLinux 工程能稳定生成和启动。

PetaLinux 构建要关心三件事

第一是硬件输入。 导入 XSA 后，PetaLinux 会基于硬件描述生成或更新板级配置。XSA 发生变化后，不要只替换 bitstream 就继续用旧设备树；PS 外设、地址映射、中断和时钟变了，Linux 侧也要同步。

第二是启动文件。  AMD UG1144 文档说明，PetaLinux 构建产物会放在 `images/linux`，常见 SD 启动需要把  BOOT.BIN、image.ub、boot.scr 放到启动分区。image.ub 通常包含内核和设备树，BOOT.BIN  则承载第一阶段启动所需内容。

第三是 rootfs。 rootfs 决定系统启动后有哪些工具、服务和库。调试早期建议保留串口登录、网络工具、SSH、Python 基础环境；正式镜像再按体积和安全需求裁剪。

source /tools/Xilinx/PetaLinux/2024.1/settings.sh
petalinux-create -t project --template zynqMP -n test_linux
cd test_linux
petalinux-config --get-hw-description ../hardware
petalinux-config
petalinux-config -c kernel
petalinux-config -c rootfs
petalinux-build
petalinux-package boot --u-boot --force

离线缓存能救很多时间

PetaLinux  和 Yocto 首次构建会拉取大量源码和 sstate。网络不稳定时，失败往往发生在等待很久之后。工程化做法是提前准备 downloads 和  sstate cache，并在 `petalinuxbsp.conf` 中固定路径。离线构建并不是为了“更高级”，而是为了让构建可重复。

DL_DIR = "/tools/petalinux/downloads"
SSTATE_DIR = "/tools/petalinux/sstate-cache"
SOURCE_MIRROR_URL = "file:///tools/petalinux/downloads"
INHERIT += "own-mirrors"
SSTATE_MIRRORS ?= "file://.* file:///tools/petalinux/sstate-cache/PATH"
BB_NO_NETWORK = "1"

如果 downloads 解压后出现嵌套目录，例如 `downloads/downloads`，脚本要检测真正含 tarball 的目录。否则你以为自己已经配置了离线缓存，Yocto 实际仍在找不到源码后失败。

构建完成后先验证镜像文件

不要把“构建命令退出 0”当作镜像可用的证明。烧录前至少看分区、校验和、启动分区内容和关键文件名。尤其是团队协作时，SHA256 可以帮你确认大家讨论的是同一张镜像。

fdisk -l output/test_board-3.1.x.img
sha256sum output/test_board-3.1.x.img
mkdir -p /tmp/test_boot
# 只读挂载启动分区后检查 BOOT.BIN、image.ub、boot.scr 是否存在

第二篇的落点：让构建可重复

一个能偶然启动的镜像还不够。你需要让它可重复构建：硬件产物有版本，PetaLinux  配置进仓库，离线缓存路径固定，PYNQ board repository 独立维护，runtime package  的安装脚本可审查。这样下一次换板、换 bitstream、换 kernel 配置时，你才知道应该改哪里。

参考资料

• PYNQ SD Card image 文档：https://pynq.readthedocs.io/en/v3.1/pynq_sd_card.html
• PYNQ sdbuild README：https://github.com/Xilinx/PYNQ/blob/master/sdbuild/README.md
• AMD UG1144 PetaLinux Copying Image Files：https://docs.amd.com/r/2024.1-English/ug1144-petalinux-tools-reference-guide/Copying-Image-Files