skills-win/release_zynq7k/SKILL.md

name, description

name

description

release_zynq7k

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 是第一次用本流程做的 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 开始写
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 填好长度和 CRC，IP 留占位符；原来验证过的脚本一并附上。

eMMC / SD（R3）

• 分区计划从证据取：fdisk -l、/proc/partitions、blkid，记录扇区边界、文件系统、卷标和 FAT 容量。
• 从 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 合成。
  • 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 部署脚本模板