45 lines
9.1 KiB
Markdown
45 lines
9.1 KiB
Markdown
---
|
||
name: petalinux-emmc
|
||
description: 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](references/hjx9009-tf.md)；其 J1 TF 接 PS SD0、没有 eMMC。其余板卡目前没有通过本 skill 验证的正式系统 profile，阅读 [references/board-intake.md](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 完成其构建/部署/验收，然后返回本流程；保留现有生产系统的可恢复配置，该调用不免除板卡输入和写前边界检查。若过渡系统可启动但目标介质尚未正常枚举，先修复/验证检测链，不能通过格式化解决未枚举问题。
|
||
|
||
## 构建和复用
|
||
|
||
### 与 SDK→Linux 应用迁移配套的驱动门禁
|
||
|
||
若正式 TF/eMMC 系统要运行从 SDK 裸机工程移植的 PS 应用，E1 构建前逐项核对该应用所依赖的 PL AXI MMIO、PS/EMIO GPIO、SPI、ADRV9009/Talise、DMA/中断及物理 DDR 邮箱。对照**当前** bit/HDF、目标 DT、`/proc/iomem`、`/dev`、内核 config/模块和应用 ABI，列出已由 Linux 提供的接口与缺失接口。缺失驱动、DT 节点、模块自动加载、固件或用户态 HAL 时，应把源码和 recipe 放入正式 PetaLinux 工程，在 kernel、DT、rootfs 与 FIT 同源构建并纳入 `build_inputs.json`/哈希门禁；不能只在运行板上临时 `modprobe`、`mknod` 或用旧交付 FIT 冒充完成。
|
||
|
||
尤其不能沿用 SDK 的固定 DDR 地址而直接写 `/dev/mem`：先证明目标范围在 DT `reserved-memory` 中保留，且不与 Linux `System RAM`、kernel code/data、CMA、rootfs 或 DMA buffer 冲突。HJX9009 旧 SDK `0x00400100` 邮箱在 2026-09-16 当前 Linux `/proc/iomem` 中属于 kernel code 范围、DT 无 `reserved-memory`；迁移应用必须停止使用该地址，改为受管理的 IPC/驱动接口或重新协商并保留安全的物理范围。当前板上已有 `/dev/spidev1.0` 和 root 可用的 `/dev/mem`，但这不证明 AD9528/ADRV9009 初始化、JESD 或自动 DPD 控制已移植。若新增 UIO/专用驱动，按新 HDF 确认 `reg` 大小、时钟、复位与中断，加入模块及启动加载规则，并以真实板端探针和功能测试验收。
|
||
|
||
任何上述改动都会改变正式系统输入，须重做相应 G1–G3 和 E1–E4；旧的 QSPI 救援 FIT 与分区边界不得因应用驱动升级而被无条件覆写。
|
||
|
||
采用独立正式工程。保持 `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](references/hjx9009-profile.json) 作 profile 文件。指纹包含 HDF/bit、所有 config/recipe/DT/U-Boot/桥接源、工具版本、BOOT 组成与根文件系统方案；部署时变化的 IP/密码不进指纹。再用 [scripts/emmc_cache.py](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、沉淀会话和可持久结论并同步；分别报告本地/远端/中心同步状态。
|