sync: WIN-BOWEI 2026-08-10 fpga_flash 增 Zynq BOOT.bin/QSPI 脚本，rtl-ip-replace 与 sim-rtl-flow 更新
- fpga_flash: 新增 build_zynq_boot.py / program_zynq_qspi.py（bootgen + program_flash， 含备份、SHA-256/容量/marker 守卫）；vivado_env.py 增 resolve_sdk_dir（SDK_ROOT/SDK_PATH）； SKILL.md 补 Zynq 烧写流程，示例去掉写死的 D:\Xilinx\SDK\2018.1，改由 skills_env.md 解析。 - rtl-ip-replace: gen_ip.tcl / namespace_ip.py 更新。 - sim-rtl-flow: SKILL.md 与 run_sim_rtl_flow.py 更新。 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
bowei
+154
-5
@@ -1,13 +1,13 @@
|
||||
---
|
||||
---
|
||||
name: fpga_flash
|
||||
description: |
|
||||
烧写 Artix-7 系列 FPGA 的外部 Flash（SPI NOR Flash）。适用于 EMV7.1 等 Artix-7 板卡，支持 Micron mt25ql128 和 Winbond w25q128bv 两种 Flash 型号。
|
||||
按开发板/器件架构选择正确的 Flash 固化方式。支持 EMV7.1 等 Artix-7 板卡的 MCS/cfgmem 流程，以及 HJX9009（XC7Z100/Zynq-7000）将 FSBL、PL bitstream、PS ELF 打包为 BOOT.bin 后写入双并行 QSPI 的流程。
|
||||
当用户提到"烧写 flash"、"flash 编程"、"固化 bit 文件"、"下载到 flash"、"program flash"、"write flash"、"burn flash"、"Vivado flash"、"SPI flash 烧写"时，必须触发此 skill。
|
||||
---
|
||||
|
||||
# FPGA Flash 烧写流程（Artix-7 / EMV7.1）
|
||||
# FPGA Flash 固化流程（按开发板路由）
|
||||
|
||||
本 skill 由 Claude **全自动执行**完整的 Flash 烧写流程。除了向用户确认必要信息外，所有操作（文件检查、CSV 修改、Vivado 命令执行、硬件编程）均由 Claude 直接完成，不要求用户手动执行任何命令。
|
||||
本 skill 由 Claude **全自动执行**完整的 Flash 固化流程。除了向用户确认必要信息外，所有操作（文件检查、备份、哈希/容量/内容守卫、工具调用、硬件编程）均由 Claude 直接完成，不要求用户手动执行任何命令。执行前必须先识别开发板与 FPGA/SoC 类型；不得把 Artix-7 的 `.mcs/cfgmem` 流程用于 Zynq，也不得把 Zynq 的 `BOOT.bin/program_flash` 流程用于普通 Artix-7。
|
||||
|
||||
---
|
||||
|
||||
@@ -34,6 +34,9 @@ scripts/
|
||||
program_flash.py # 第四、五步：连接目标板并烧写 Flash
|
||||
step3_write_mcs.tcl # gen_mcs.py 使用的 Tcl 模板（勿手动修改）
|
||||
step4_5_program.tcl # program_flash.py 使用的 Tcl 模板（勿手动修改）
|
||||
build_zynq_boot.py # Zynq：FSBL + bit + PS ELF 生成受保护的 BOOT.bin
|
||||
program_zynq_qspi.py # Zynq：哈希/容量/marker 守卫后烧写并强制 verify
|
||||
vivado_env.py # 解析 Vivado/SDK 工具路径
|
||||
```
|
||||
|
||||
**调用方式（Bash 工具）：**
|
||||
@@ -41,10 +44,153 @@ scripts/
|
||||
python "$USERPROFILE/.claude/skills/fpga_flash/scripts/<script>.py" [参数...]
|
||||
```
|
||||
|
||||
各脚本通过命令行参数接受变量（Vivado 安装目录、工程名、bit 文件路径、mcs 文件路径等），内部调用 Vivado `-mode batch -source <tcl模板> -tclargs <参数>` 完成执行，全程不产生临时文件。
|
||||
各脚本通过命令行参数接受变量（Vivado/SDK 安装目录、bit/ELF/MCS/BOOT 路径、容量和 marker 等）。Artix-7 脚本内部调用 Vivado `-mode batch -source <tcl模板> -tclargs <参数>`；Zynq 脚本调用 SDK 的 `bootgen`/`program_flash`。工程路径和板级文件均由参数传入，不在 skill 中硬编码。
|
||||
|
||||
---
|
||||
|
||||
## 第零步：识别板卡并选择唯一流程
|
||||
|
||||
先用工程名、器件型号、原理图/板卡说明和现有部署资料交叉确认，不允许只根据输出文件扩展名猜测。
|
||||
|
||||
| 板卡/器件 | 固化容器 | 写入工具与接口 | 选择的流程 |
|
||||
|---|---|---|---|
|
||||
| HJX9009、`xc7z100`、Zynq-7000（PS+PL） | `BOOT.bin`，顺序为启动 FSBL + PL `.bit` + PS `.elf` | SDK `bootgen` + `program_flash -flash_type qspi_dual_parallel` | 本文“Zynq/HJX9009”流程 |
|
||||
| EMV7.1、`xc7a*`、Artix-7（纯 PL） | `.mcs` | Vivado `write_cfgmem` + Hardware Manager cfgmem | 本文“Artix-7/EMV7.1”流程 |
|
||||
|
||||
硬阻断规则：
|
||||
|
||||
- 发现 `xc7z*`、PS7、FSBL、PS ELF 或工程明确写明 Zynq 时，禁止运行 `gen_mcs.py`、`program_flash.py` 或 `create_hw_cfgmem`。
|
||||
- 发现 `xc7a*` 且无 PS/FSBL 时，禁止生成 `BOOT.bin`。
|
||||
- 板型、Flash 拓扑或容量不明确时，先查原理图/现有已验证部署记录；不得试烧。
|
||||
- HJX9009 已验证为两片 `s25fl128s` 双并行 QSPI，总容量 32 MiB，必须使用 `qspi_dual_parallel`，不能退化为 `qspi_single`。
|
||||
|
||||
---
|
||||
|
||||
## Zynq/HJX9009：同时固化 PS 与 PL
|
||||
|
||||
### Z1. 输入与两个 FSBL 角色
|
||||
|
||||
生成冷启动镜像需要三个输入，BIF 中顺序不可改变：
|
||||
|
||||
```text
|
||||
the_ROM_image:
|
||||
{
|
||||
[bootloader]<boot_fsbl.elf>
|
||||
<implemented_pl.bit>
|
||||
<ps_application.elf>
|
||||
}
|
||||
```
|
||||
|
||||
必须区分两个角色不同的 FSBL：
|
||||
|
||||
- **启动 FSBL**：封装在 `BOOT.bin` 第一分区，板卡冷启动时由 BootROM 加载，随后配置 PL 并启动 PS 应用。
|
||||
- **JTAG 烧写辅助 FSBL**：由 `program_flash -fsbl` 临时下载到 OCM，用于初始化当前板卡的 QSPI MIO/控制器并完成写入。它不等于、也不能默认替换 `BOOT.bin` 内的启动 FSBL。
|
||||
|
||||
对 HJX9009，必须使用已验证能初始化该板 QSPI MIO 的参考 JTAG 辅助 FSBL。若项目提供其期望 SHA-256/MD5，必须作为守卫验证。错误的辅助 FSBL 可能读出 JEDEC `00,00,00`，造成表面执行但没有可靠写入。
|
||||
|
||||
HJX9009 当前工程部署记录中的参考辅助 FSBL 指纹为 MD5 `14232757864453B418E67D63457EE24F`。这只是板级身份参考，不应写死进通用脚本；实际执行仍应从当前项目部署清单取得文件并同时记录 SHA-256。
|
||||
|
||||
### Z2. 安全预检与备份顺序
|
||||
|
||||
执行顺序固定如下：
|
||||
|
||||
1. 确认本次 PS ELF、时序通过的 PL bitstream、启动 FSBL 和 JTAG 辅助 FSBL 的绝对路径。
|
||||
2. 记录四个输入的 SHA-256、字节数和修改时间；若有 `.ltx`，另记录其 SHA-256，确保它与 bitstream 同次构建。
|
||||
3. 在覆盖部署目录中的任何已有 `BOOT.bin`、BIF、FSBL、bit 或 ELF 前，复制到带时间戳的备份目录并写 manifest。不得删除已知可回退镜像。
|
||||
4. 对源文件和 staging 副本逐个比较 SHA-256，任一不一致立即停止。
|
||||
5. 为新固件指定至少一个能区分版本的 ASCII marker，并在 PS ELF 和生成的 `BOOT.bin` 中检查。marker 不匹配立即停止。
|
||||
6. 生成后要求 `BOOT.bin` 严格小于物理 QSPI 容量；HJX9009 上限为 33,554,432 字节。
|
||||
7. 记录最终 `BOOT.bin` 的 SHA-256 和精确长度；烧写命令必须重新校验这两个值，防止旧镜像或 TOCTOU 误烧。
|
||||
|
||||
### Z3. 生成 BOOT.bin
|
||||
|
||||
调用参数化脚本；示例只表示参数结构，实际路径和 marker 必须来自当前项目。
|
||||
Xilinx SDK 安装根目录由脚本自行解析（`SDK_ROOT` / `SDK_PATH`：先查环境变量，再查
|
||||
`~\skills_env.md`），只有需要临时覆盖时才显式传 `--sdk-dir`：
|
||||
|
||||
```powershell
|
||||
python "$env:USERPROFILE\.claude\skills\fpga_flash\scripts\build_zynq_boot.py" `
|
||||
--boot-fsbl "<cold-boot-fsbl.elf>" `
|
||||
--bit-file "<implemented-top.bit>" `
|
||||
--app-elf "<ps-application.elf>" `
|
||||
--boot-bin "<deployment-dir>\BOOT.bin" `
|
||||
--bif-file "<deployment-dir>\boot.bif" `
|
||||
--capacity-bytes 33554432 `
|
||||
--require-marker "<build-identity-marker>"
|
||||
```
|
||||
|
||||
脚本会备份已有 BOOT/BIF、生成候选镜像、执行容量与 marker 守卫、原子替换最终镜像，并输出 JSON manifest。成功标志为：
|
||||
|
||||
```text
|
||||
ZYNQ_BOOTGEN_PASS size=<n> sha256=<64 hex>
|
||||
```
|
||||
|
||||
如果工程采用 staging 目录，复制 FSBL/bit/ELF 后仍要逐项重算并对比 SHA-256。`BOOT.bin` 约 18 MiB 只是 HJX9009 的常见值，不是成功判据。
|
||||
|
||||
### Z4. 启动 Vivado hw_server 并确认 JTAG
|
||||
|
||||
HJX9009 当前机器上必须由 **Vivado** 的 `hw_server` 给 Platform Cable USB II 加载固件；SDK 自带 hw_server 可能无法完成该动作。先启动并等待枚举出 `xc7z100`：
|
||||
|
||||
```powershell
|
||||
& '<Vivado-root>\bin\hw_server.bat' -s tcp::3121
|
||||
```
|
||||
|
||||
保持服务运行，确认 `tcp:127.0.0.1:3121` 可连接且 JTAG 链中只有预期目标。若 3121 被未知进程占用、目标器件不是 `xc7z100`、板卡掉电或线缆未枚举，停止，不得烧写。
|
||||
|
||||
### Z5. 写入 HJX9009 双并行 QSPI 并强制 verify
|
||||
|
||||
从 Z3 的输出/manifest 复制**精确** SHA-256 和长度后执行：
|
||||
|
||||
```powershell
|
||||
python "$env:USERPROFILE\.claude\skills\fpga_flash\scripts\program_zynq_qspi.py" `
|
||||
--image "<deployment-dir>\BOOT.bin" `
|
||||
--jtag-fsbl "<verified-jtag-helper-fsbl.elf>" `
|
||||
--expect-sha256 "<exact-BOOT.bin-sha256>" `
|
||||
--expect-size <exact-byte-length> `
|
||||
--capacity-bytes 33554432 `
|
||||
--flash-type qspi_dual_parallel `
|
||||
--hw-server-url tcp:127.0.0.1:3121 `
|
||||
--expect-jtag-fsbl-sha256 "<exact-helper-FSBL-sha256>" `
|
||||
--require-marker "<build-identity-marker>" `
|
||||
--log-file "<deployment-dir>\program_flash.log"
|
||||
```
|
||||
|
||||
安全约束：
|
||||
|
||||
- offset 必须为 `0`；HJX9009 的 Flash 类型必须保持 `qspi_dual_parallel`。
|
||||
- 参数顺序必须是 `-verify` 在 `-fsbl` 前，`-cable ...` 最后；参数化脚本已固定此顺序。
|
||||
- 擦除、编程、回读校验可能超过 10 分钟；期间禁止断电、拔 JTAG、关闭 hw_server 或终止进程。
|
||||
- 不信任包装层退出码。已验证存在“无法连接 hw_server 但返回码仍为 0”的情况。
|
||||
|
||||
真正成功必须在同一次日志中同时出现：
|
||||
|
||||
```text
|
||||
Erase Operation successful
|
||||
Program Operation successful
|
||||
Verify Operation successful
|
||||
Flash Operation Successful
|
||||
ZYNQ_QSPI_FLASH_VERIFY_PASS
|
||||
```
|
||||
|
||||
若出现 `Verify Operation unsuccessful`、`Flash Operation Failed`，或缺少任一成功行，一律判失败。`End of startup status: HIGH` 只证明易失配置完成，不能证明 Flash 已写入。
|
||||
|
||||
### Z6. 完全断电冷启动与 COM5 验收
|
||||
|
||||
烧写成功后还必须验证自主启动：
|
||||
|
||||
1. 保存烧写日志、BOOT manifest、bit/LTX/ELF 哈希和回退镜像位置。
|
||||
2. 关闭板卡主电源及可能通过 JTAG 反向供电的接口，静置至少 30 秒；JTAG 枚举异常时按板级规程全断 90 秒。
|
||||
3. 保持 JTAG 断开，重新打开主电源，让板卡只从 QSPI 启动。
|
||||
4. 打开 COM5（115200、8N1、无流控），保存带时间戳的启动日志。
|
||||
5. 要求看到本次 PS 固件的唯一 marker/banner，并执行项目定义的只读状态命令。HJX9009 当前固件通常用 `HELP`、`?`，随后按项目规程输入 `R`；验收期望状态和命令必须以本次固件文档为准。
|
||||
6. 若 marker 不匹配、COM5 无输出、PL/PS 版本不一致或只能在重新接入 JTAG 后工作，判定冷启动失败并使用已备份的已知良好镜像回退。
|
||||
|
||||
只有“写入日志完整成功 + verify 成功 + 完全断电后 COM5 确认本次固件自主启动”三者同时成立，才可以向用户报告 HJX9009 PS+PL 已固化。
|
||||
|
||||
---
|
||||
|
||||
## Artix-7/EMV7.1：MCS/cfgmem 流程（保留）
|
||||
|
||||
## 第一步：检查并修复 Vivado Flash 器件表
|
||||
|
||||
**Claude 自动执行：**
|
||||
@@ -156,3 +302,6 @@ ILA core 的 `Dropping logic core` WARNING 是正常现象（载入 loader/golde
|
||||
| DONE 灯不亮 | 启动模式跳线错误 | 检查 MODE 引脚电平，确认为 SPI 启动模式 |
|
||||
| 烧写后板卡跑旧程序 | Flash 未完全擦除 | 确认 `PROGRAM.ERASE 1` 已设置后重新执行 |
|
||||
| `PermissionError` 写 CSV | 权限不足 | 提示用户以管理员身份运行 Claude Code |
|
||||
| Zynq `program_flash` 返回 0 但无成功行 | hw_server 未连接或工具包装层假成功 | 按日志判失败；要求 erase/program/verify/Flash 四组成功标志齐全 |
|
||||
| HJX9009 JEDEC 为 `00,00,00` | JTAG 辅助 FSBL 未正确初始化 QSPI MIO | 使用项目已验证的参考辅助 FSBL并核对哈希，保持 `qspi_dual_parallel` |
|
||||
| `BOOT.bin` 可写但冷启动无 COM5 | 启动 FSBL/PS ELF/PL 不匹配或未自主启动 | 完全断电、断开 JTAG，从 QSPI 冷启动并核对固件 marker；失败则回退备份 |
|
||||
|
||||
Reference in New Issue
Block a user