---
name: release_zynq7k
description: Package a hardware-verified Zynq-7000 (PetaLinux) product version into a release for colleagues — PetaLinux BSP, QSPI flash files and a whole-flash image, eMMC/SD flash files and deploy script, the final merged rootfs, PL bitstream, PS runtime files, app sources (PS and companion MCUs such as i.MX6), a README and SHA-256 manifest — under ./release/<name>_<version>/. Use when the user asks to make/build/prepare a release package, "release 包", "打包 release", "制作发布包", "交付给同事", hand a Zynq-7000 version to another team, or names a requirement doc (e.g. Notes/PRxx.md) listing release items for a Zynq-7000 board. Not for building or deploying the system itself (petalinux-qspi / petalinux-emmc / petalinux-ps / petalinux-pl do that).
---

# release_zynq7k：Zynq-7000 release 打包

把一个**已经在硬件上验证过**的版本，整理成同事拿到就能部署、能重建的 release 包。
release 只做收集、整理、合成、校验和说明，不重新设计，也不改变已验证的产物。
凡是没在硬件上验证过的东西（新脚本、新合成的文件），README 里必须如实写明。

## 0. 先读

- **项目约定**：项目 adapter（AGENTS.md / CLAUDE.md）、全局与本项目 bmem 记忆、用户指定的需求文档（如 `Notes/PRxx.md`）。
  需求文档列出的条目就是 release 必须交付的条目；它明确排除的内容（例如 "除了 vivado 工程源码"）不放进包里。
- **机器参数**：交叉编译 VM 的地址和账号、PetaLinux / Vivado 路径都从 `~\skills_env.md` 读取，不写死在任何地方。
  plink/pscp 第一次连接时会报未知主机指纹，从报错里取出指纹，用 `-hostkey` 传入。
- **参考案例**：[references/emv93-dvbt2.md](references/emv93-dvbt2.md) 是第一次用本流程做的 release（EMV9.3 DVB-T2），
  里面记录了版式、证据来源，以及这次踩过的坑。

## 1. 确定发布哪个版本（门禁 R0）

1. **定位版本**：在 git tag、bmem 恢复入口和交付目录里找到要发布的版本，列出每个产物的 SHA-256。
2. **核对产物来源**：每个产物都必须有证据表明它就是硬件验收时用的那份。
   证据可以是：交付目录里的哈希、板上读回的哈希，或 VM `images/linux` 里与交付一致的哈希。
   没有证据的文件不进 release；若它确实必需，就在 README 里标成"未验证"。
3. **源码 tag**：源码有 git 就用 tag。没有 git 先问用户；若用户同意，`git init` 后提交并打 tag。
   新建仓库要做三件事：
   - 设置 `core.autocrlf=false`，否则板上的 shell 脚本会被转成 CRLF；
   - 在 `.gitignore` 里排除构建目录和大体积抓包；
   - 排除 Windows 保留文件名（如 `COM3.log`），git 无法打开这类文件。
4. **板子不是必需的**：打包只用已验证的文件。不要为了打包去改板上的状态，也不要重启板子。

## 2. 目录版式

`./release/<NAME>_v<版本>/`（目录名与 git tag 一一对应）：

| 目录 | 内容 |
|---|---|
| `01_petalinux_bsp/` | 每个 PetaLinux 工程一个 `.bsp`（正式系统 + QSPI 救援系统） |
| `02_qspi_flash/` | BOOT.BIN、QSPI 内核 FIT、整片镜像 `qspi_full_0x0.bin`、`uboot_scripts/` |
| `03_emmc_flash/` | `p1_boot_fat/`（FIT + PL bin）、`emmc_deploy.sh`、`EMMC_SHA256SUMS`、`rescue_scripts/`（原来验证过的脚本） |
| `04_rootfs/` | 最终根文件系统 tar.gz，以及生成它的 spec 和脚本 |
| `05_pl_bit/` | 板上实际加载的 `.bin`，同次构建的 `.bit` 和 `.hdf` / `.xsa` |
| `06_ps_runtime/` | 应用二进制、init 脚本、配置、内核模块、运行数据，按板上目录分子目录 |
| `07_ps_app_src/` | 用 `git archive <tag> <dir>` 导出的应用源码和 PetaLinux meta-user 层 |
| `08_<mcu>_app_src/`、`09_<mcu>_runtime/` | 其它处理器（如 i.MX6）的源码和部署件；没有就省略 |
| `10_pc_tools/` | 可选：PC 端验证工具 |
| `README.md` | 说明文档，从 [templates/README_template.md](templates/README_template.md) 开始写 |
| `00_SHA256SUMS` | 全部文件的校验和，`sha256sum -c` 格式 |

另在 `./release/` 下放 `<目录名>.tar.gz` 和对应的 `.sha256`。`.tar.gz` 不入 git（它只是目录的打包，可以随时重新生成），目录本身入 git。

## 3. 逐项制作

### BSP（R1）

- 在 VM 上执行 `petalinux-package --bsp -p <proj> --output <name>.bsp`。
- **先同步应用配方**：打包前确认 `project-spec/meta-user` 里各应用配方的 `files/src` 是本次发布的源码。
  若不是，先把旧配方 tar 备份，再用发布源码替换，并去掉 CR。替换后读回配方里关键文件的 sha 核对。
- 每个归档解到**各自的空目录**，避免两个包混在同一个目录里。
- **HDF 一致性**：比较 BSP 中 `hw-description/ps7_init.c` 与发布 `.hdf` 里的 `ps7_init.c`。
  - 相同：说明只有 PL 不同（PL 由 U-Boot 加载），README 写明"换 PL 不需要重建 Linux"；
  - 不同：必须告诉用户，由用户决定是否用发布的 HDF 重建。
- 检查 `tar tzf` 的结果，确认 BSP 里包含配方、DT 和 U-Boot 补丁，并且没有 `build/` 和 `images/`。

### QSPI（R2）

- **布局从证据取**：U-Boot 烧写脚本、`/proc/mtd`、flash 布局 json，不要猜。
- 生成整片镜像和布局 json：
  ```
  python scripts/qspi_image.py qspi_full_0x0.bin 0x0:BOOT.BIN <KOFF>:image.ub.qspi --erase <ENVOFF>:<ENVLEN> --layout qspi_layout.json
  ```
  每段的 CRC32 必须与证据记录的一致。
- 用 [templates/qspi_program.txt](templates/qspi_program.txt) 填好长度和 CRC，IP 留占位符；原来验证过的脚本一并附上。

### eMMC / SD（R3）

- **分区计划从证据取**：`fdisk -l`、`/proc/partitions`、`blkid`，记录扇区边界、文件系统、卷标和 FAT 容量。
- 从 [templates/emmc_deploy.sh](templates/emmc_deploy.sh) 改出本板脚本：只改顶部 profile 变量，其余照搬已验证脚本的步骤顺序。
  - 写成 LF 换行，在 VM 上跑 `sh -n` 和 `busybox sh -n`；
  - **不要用 `! cmd` 当检查**：`set -e` 不会因为它失败而退出，要写成显式的 `if`。
- 脚本没在板上整体跑过，就在 README 写"未上板实测，首次对照原脚本"。
- `EMMC_SHA256SUMS` 只写文件名，与 TFTP 下载到板上的文件对应。

### rootfs（R4）

- 写一个 spec json，交给 [scripts/merge_rootfs.py](scripts/merge_rootfs.py) 合成。
  - spec 要还原已验证部署脚本的效果：基础 rootfs、覆盖包、替换的文件（带权限）、符号链接、目录。
  - spec 的 `expect` 里写每个关键文件的已验证 sha。
  - 运行 `merge_rootfs.py spec.json out.tar.gz --verify`，结果必须全部 OK。
- 用 tarfile 合成，不在 Windows 上解开再重新打包，否则会丢失属主、权限、符号链接和设备节点。
- 生成后在 VM 上跑一次 `tar tzf`，确认 GNU tar 能读，成员数与预期一致。
- **不放每板唯一的数据**：DPD/校准曲线、主机密钥、序列号、MAC 都不放。若 rootfs 自带这类文件，用 spec 的 `remove` 去掉，并在 README 写明新板如何生成。

### PL / PS 运行文件 / 源码（R5–R7）

- **PL**：发布板上实际加载的 `.bin`（或 bootgen 产物），再附同次构建的 `.bit` 和 `.hdf`。
- **PS 运行文件**：从交付目录或合成的 rootfs 里取，哈希与 rootfs 中的成员一致。
- **源码**：用 `git archive <tag> <dirs> | tar x`，只导出纳入版本控制的源码。
  - 用 `release_check.py scan --src-dirs` 检查源码目录里没有 ELF、`.o` 或 `.ko`；
  - 需求文档排除的部分（如 Vivado 工程）不导出。

### README（R8）

按模板写，必须包括：
- 版本清单（板上位置 + sha 前 16 位）、存储布局表；
- 从全新或出厂板开始的部署步骤，以及冷启动验收的期望值；
- 现场相关设置：每板唯一值和站点值，逐个写出所在文件；
- 从源码构建的方法、已知限制。

写完后自己对照脚本和包内实际内容核对每一步，例如 `install.sh` 是否已经做了某一步。别把旧板专用的步骤写成通用步骤。

## 4. 检查与收尾（R9）

1. **扫描**：
   ```
   python scripts/release_check.py scan <dir> --env ~/skills_env.md --mac <测试板 MAC> ... --src-dirs 07_ps_app_src,08_xxx_app_src
   ```
   - 退出码 2 表示找到了凭据值或 `user:pass@` URL，必须清除后重做，不得发布；
   - 工具脚本里写死的口令，改成从环境变量读取，并在源头（仓库）修正后重新导出，不要只改 release 副本；
   - 例外：厂商出厂默认账户（随固件发布，常常就是品牌名，比如网页里的品牌 URL）。确认属实后，用 `--allow <KEY>` 把它归为 acknowledged，并在 README 写明"出厂默认账户，现场建议修改"；
   - 工具状态文件（`*.upstate.json` 等）从源码目录里删掉；
   - 测试板 MAC：发布用的配置文件要留空或改成占位符，源码和旧脚本里残留的要在 README 列出；
   - 开发机路径、私钥（例如 mini_httpd 自带的示例 pem）：逐项判断后写进 README。
2. **生成并核对校验和**：`release_check.py sums <dir>`，然后 `release_check.py verify <dir>` 必须 0 bad、0 not listed。
3. **打包**：`tar czf` 生成整包，再生成 `.sha256`。
4. **git**：提交 release 目录，打 tag `release-v<版本>`，`.gitignore` 加上 `release/*.tar.gz`。
5. **bmem**：用 `bmem add --prj` 记一条：
   - release 位置、tag、整包 sha；
   - 各目录的要点、VM 上做过的改动（备份位置）、未验证项；
   - 然后执行 `bmem sync`。
6. **向用户汇报**：目录表、未验证项、需要同事注意的每板值和站点值、仓库与 bmem 状态。
   有硬件异常（例如打包中途板子失联）要说明，但不要擅自重启板子。

## 脚本

| 脚本 | 用途 |
|---|---|
| `scripts/qspi_image.py` | 按偏移拼整片 QSPI 镜像（空隙 0xFF），检查重叠，输出每段的 CRC32 和布局 json |
| `scripts/merge_rootfs.py` | 按 spec 无损、可复现地合成 rootfs tar.gz；`--verify` 核对 expect 哈希和符号链接 |
| `scripts/release_check.py` | `sums` / `verify` 生成和核对 `00_SHA256SUMS`；`scan` 查凭据、MAC、开发机路径、源码目录里的二进制、保留文件名 |
| `templates/` | README 骨架、U-Boot QSPI 烧写脚本、eMMC 部署脚本模板 |