skills-win/petalinux-emmc/SKILL.md

name, description

name	description
petalinux-emmc	Build, reuse, deploy, recover, and hardware-validate a PetaLinux production system whose kernel and ext4 rootfs reside on eMMC or removable SD/TF while Zynq boots FSBL and U-Boot from QSPI. Use for PR26-style two-stage production deployment; HJX9009 uses TF instead of nonexistent eMMC.

PetaLinux eMMC/TF 正式系统

目标是从已经可恢复的 QSPI 过渡 Linux 部署正式 FIT 内核与持久 ext4 根文件系统，完成真实断电启动和读写验收。名称中的 emmc 指 PR26 的第二阶段；介质和控制器由板卡证据决定，不能从 /dev/mmcblk0 推断是板载 eMMC。PL bit→bin 和应用程序发布属于另外的 Petalinux-pl/ps 任务，不得冒称完成。

板卡和输入

若用户尚未指定板卡，先让用户选择：1. HJX9009 2. emv9.3 3. ipots 4. others。HJX9009 必须阅读 references/hjx9009-tf.md；其 J1 TF 接 PS SD0、没有 eMMC。其余板卡目前没有通过本 skill 验证的正式系统 profile，阅读 references/board-intake.md，取得原理图/HDF 或等效硬件配置并查实存储、启动、恢复和电源细节后才可烧写；不能套用 HJX9009 的 MIO、分区或桥接。

阅读项目 AGENTS/CLAUDE adapter、全局/项目 bmem 和 PR26/Result 原文。将用户交付的当前 Vivado .hdf（2018.1）或相应版本 .xsa、bit、PS7 初始化、板卡修订、PetaLinux/Vivado/SDK 版本、可恢复镜像与串口/JTAG路径绑定。旧参考工程只择项审阅，不整树覆盖；历史同名 HDF、旧 IP 和密码不是当前输入。现场网络地址、TFTP 绑定和介质容量每次实测，不复制笔记。

QSPI 前置门禁

首次安装前实际证明目标板已经从 QSPI 冷启动进入可恢复的过渡 Linux：记录 BootROM/U-Boot/QSPI FIT 来源、initramfs、MTD 布局、网络/TFTP、分区和校验工具、已知良好 QSPI 镜像及恢复链。若板上已是正式 TF/eMMC 系统，先证明 QSPI 救援 FIT 仍在且可通过受控回退路径启动，不能要求默认 bootcmd 重回 QSPI-only，也不能为了检查而无条件重写现有生产 bootenv。不能以 delivery 文件存在或上次成功代替当前门禁。若过渡/救援系统尚未部署或与当前 HDF/板卡不匹配，调用共享 petalinux-qspi skill 完成其构建/部署/验收，然后返回本流程；保留现有生产系统的可恢复配置，该调用不免除板卡输入和写前边界检查。若过渡系统可启动但目标介质尚未正常枚举，先修复/验证检测链，不能通过格式化解决未枚举问题。

构建和复用

采用独立正式工程。保持 boot media = QSPI、BOOT.BIN = 同一硬件交付的 FSBL + U-Boot，正式 image.ub 在经验证的 eMMC/TF BOOT 分区，根文件系统在第二分区 ext4；实际 FIT/启动路径必须与板卡检测条件相容。需要早期桥接 initramfs、软件 CD 旁路或根 UUID 时，把源文件、DT、U-Boot overlay、rootfs 配置和启动参数都算作构建输入，不得仅改环境后仍声称镜像相同。BOOT.BIN 不自动包含 PL bit 或 FIT。QSPI kernel 分区中的过渡 image.ub.qspi 保持可恢复。

先为当前输入生成 build_inputs.json，可用 sibling petalinux-qspi/scripts/qspi_cache.py capture 的通用指纹捕获接口；HJX9009 使用稳定的 references/hjx9009-profile.json 作 profile 文件。指纹包含 HDF/bit、所有 config/recipe/DT/U-Boot/桥接源、工具版本、BOOT 组成与根文件系统方案；部署时变化的 IP/密码不进指纹。再用 scripts/emmc_cache.py 检查当前指纹与交付的 BOOT.BIN、image.ub、rootfs.tar.bz2、build_inputs.json、summary.json、MANIFEST.md 和 SHA256SUMS。构建门禁 G0=输入、G1=HDF 导入、G2=配置、G3=构建打包；仅在检查返回 reusable=true、G0–G3 均 PASS、产物与当前硬件输入/启动方案一致时跳过重建。文件存在、mtime、旧 bit 相同或仅有一次启动日志均不足；旧交付缺可核验指纹/清单时补齐证据或重建。复用构建不能跳过当前介质和板级部署验收。

示例：python <skill>/scripts/emmc_cache.py check --current <new-build_inputs.json> --delivery <production-delivery>。summary.json 中 build_gates.G0..G3.status（或 gates.G0..G3.status）均须为 PASS。若目标板当前已有同哈希 FIT、同根 UUID/内容与同 BOOT，先执行 E4 验收；达到所有门禁可报告“当前部署已是最新”，不必重复分区或烧写。

顺序门禁

1. E0 前置/只读： QSPI 门禁；当前 HDF/板号；U-Boot/SDHCI/MTD；介质 CID、容量、分区、挂载；首尾与拟用地址范围的重复只读校验。TF/eMMC 容量可见不证明高地址可写；出现不稳定范围时缩小到经验证范围或换介质，绝不盲用标称容量。计算唯一分区计划、UUID、空间余量、恢复路径和本轮目标文件哈希。
2. E1 构建： 从同一 HDF 生成/审阅 PS7、设备树和 FSBL；配置正式 kernel/SD 驱动、ext4 rootfs 归档与必要 initramfs；构建并解包审计。生成 FIT、rootfs 归档和仅含 FSBL+U-Boot 的 BOOT.BIN，记录 BIF、版本、SHA-256、启动命令与构建日志。不得直接运行旧 emmc_auto_format.sh/auto_up_emmc.sh：它们写死设备/IP、无严密失败门禁，可能清空分区和 QSPI bootenv。
3. E2 介质部署： 用户的正式系统部署请求包含目标介质重建时，仍先核对 CID/容量/无其它介质、精确设备节点、挂载点与分区计划；写前停用自动挂载并可靠卸载。先把全部产物传输到安全暂存区、检查文件大小/哈希/可用空间，任何传输失败即停止，不允许落入格式化或 Flash 擦除。按已验证范围分区/格式化，回读分区表、fsck；写 FAT BOOT 的 image.ub 并读回哈希；将对应 rootfs.tar.bz2 解包到 ext4，检查 /sbin/init、权限、设备节点及关键文件，sync、卸载、fsck、只读回读。若最终归档与上卡内容有差异，明确记录，不得报告逐字节一致。
4. E3 QSPI 启动更新： 仅在 E2 全通过、旧 QSPI 镜像与 JTAG 恢复可用时，更新必要的 FSBL/U-Boot 或持久 bootcmd。计算 boot/bootenv/kernel 的实际范围；不要清空 bootenv 或覆盖救援 FIT。QSPI 擦写后做全长回读比较与 CRC/哈希，环境回读确认；不能只看 flashcp/sf write 无报错。卡缺失或 FIT 失效时的 QSPI 救援分支必须单独冷启动实测。
5. E4 现场验收： 至少两次完整断电冷启动，串口证明 QSPI FSBL/U-Boot → 目标介质 FIT → 目标 ext4 /；核对 FIT hash、CID、根 SOURCE/FSTYPE/UUID、实际网络、MTD、FPGA manager（仅存在不等于 PL 已部署）。做受控文件写入、sync、断电，再读回持久化；检查 ext4/mmc 错误和 fsck。再单独验证无卡/损坏 FIT 的 QSPI 救援路径。某项未完成记为 PARTIAL/BLOCKED，不称“全功能完成”。

所有 U-Boot/串口命令逐条核对退出状态、期望回显、实际 $filesize 和 CRC。不能让 TFTP 失败后旧 DDR 数据落入写入步骤。把自动状态/log 放在项目 Notes/auto/；manifest 记录门禁、证据路径、板卡/介质身份、输入与产物哈希、实际网络和遗留限制。按项目 bmem 协议导入用户 Notes、沉淀会话和可持久结论并同步；分别报告本地/远端/中心同步状态。