eMMC 启动完整操作手册 V2

角色分工概览HPS 工程师 FPGA 工程师 ────────────────────────── ────────────────────────── 编译 Yocto生成软件镜像 接收 HPS 文件生成 JIC 交付文件 生成文件 ├── u-boot-spl-dtb.hex ──────────→ helper.jic初次写 eMMC 用 ├── u-boot.itb ──────────→ full.jic 最终正式使用 └── gsrd-console-image.wic split 后放 TFTPPHASE 1HPS 工程师操作1.1 确认 Yocto 编译输出文件bashCopycd ~/013b_sd_build/agilex5_soc_devkit_ghrd/software/yocto_linux/build/tmp-glibc/deploy/images/agilex5e_013b/ # 确认以下关键文件存在 ls -lh u-boot-spl-dtb.hex \ u-boot.itb \ gsrd-console-image-agilex5e_013b.rootfs.wic1.2 准备 TFTP 文件bashCopy# 切割 wic 镜像为 1GB 分块U-Boot TFTP 单次传输限制 split --bytes1G gsrd-console-image-agilex5e_013b.rootfs.wic # 生成 xaa第一块、xab第二块若镜像 1GB # 拷贝到 TFTP 目录 sudo cp xaa /tftpboot/ sudo cp xab /tftpboot/ # 若存在 # 确认 TFTP 服务运行 systemctl status tftpd-hpa # 确认 Host PC IP后续 U-Boot 中填写 ip addr show # 示例得到192.168.1.1001.3 交付给 FPGA 工程师 HPS 工程师 → FPGA 工程师 ├── u-boot-spl-dtb.hex SPL即 FSBL └── u-boot.itb U-Boot Proper ATF bl31PHASE 2FPGA 工程师操作收到u-boot-spl-dtb.hex和u-boot.itb后执行。2.1 准备环境bashCopyexport QUARTUS_ROOTDIR~/altera_pro/25.3.1/quartus/ export PATH$QUARTUS_ROOTDIR/bin:$QUARTUS_ROOTDIR/linux64:$PATH2.2 生成 helper.jic用途初次写 eMMC 时使用包含完整 U-Boot烧写后可进入 U-Boot 命令行bashCopymkdir helper_jic cd helper_jic # 下载官方 pfg 模板定义 QSPI Flash 分区布局 wget https://releases.rocketboards.org/2026.01/emmc/agilex5_dk_a5e065bb32aes1_emmc/uboot-only.pfg # 修改 pfg 中的 sof 文件名适配自己的设计 sed -i s/ghrd_a5ed065bb32ae6sr0\.sof/legacy_baseline.sof/g uboot-only.pfg # 准备 u-boot.itb改名为 .bin填充到 2MBquartus_pfg 格式要求 cp ../u-boot.itb u-boot.bin uboot_size$(wc -c u-boot.bin) uboot_pad$((2*1024*1024 - uboot_size)) truncate -s ${uboot_pad} u-boot.bin # 建立文件链接 ln -s ../u-boot-spl-dtb.hex . ln -s ../legacy_baseline.sof . # 生成 helper JIC quartus_pfg -c uboot-only.pfghelper.jic 内容QSPI Flash 布局 ├── FPGA 配置数据 ← legacy_baseline.sof ├── U-Boot SPL (FSBL) ← u-boot-spl-dtb.hex └── U-Boot Proper ← u-boot.bin必须包含否则无法进命令行生成文件 生成 └── agilex_flash_image.hps.jic 即 helper.jic2.3 生成 full.jic用途最终正式使用包含完整 FPGA 配置 完整 U-BootbashCopycd .. quartus_pfg \ -c baseline.sof full.jic \ -o deviceMT25QU128 \ -o flash_loaderA5ED065BB32AE6SR0 \ -o hps_pathu-boot-spl-dtb.hex \ -o modeASX4 \ -o hps1注意此命令生成的 full.jic 只包含 SPL不含 U-Boot Proper。 若需要 full.jic 也包含 U-Boot Proper推荐保证 eMMC 损坏时可恢复 同样使用 pfg 文件方式生成参考 helper.jic 的做法替换为完整的 baseline.sof。full.jic 内容QSPI Flash 布局 ├── FPGA 配置数据完整 ← baseline.sof ├── U-Boot SPL (FSBL) ← u-boot-spl-dtb.hex └── U-Boot Proper ← u-boot.itb推荐包含生成文件 生成 └── full.jic2.4 交付给联调 / HPS 工程师 FPGA 工程师 → 联调工程师 ├── agilex_flash_image.hps.jic helper.jic第一步用 └── full.jic 正式 JIC第三步用PHASE 3烧写与启动操作Step 1烧写 helper.jic 到 QSPI目的让板子能进入 U-Boot 命令行以便写 eMMC硬件操作 ① 断电 ② SW3 → ONHPS NAND Board 使能 eMMC ③ SW27 → JTAG 模式OFF-OFF-OFF-OFF ④ 接好 micro USB JTAG 线 ⑤ 上电bashCopy# Host PC 执行 jtagconfig --setparam 1 JtagClock 16M quartus_pgm -c 1 -m jtag -o pvi;agilex_flash_image.hps.jic # 出现 100% 表示烧写成功Step 2通过 U-Boot 将镜像写入 eMMC目的通过 TFTP 把 .wic 镜像写到 eMMC硬件操作 ① 断电 ② SW27 → QSPI 模式OFF-ON-ON-OFF ③ 接好 mini USB 串口线HPS Daughtercard 上 ④ 打开串口终端115200, 8N1, 无流控 ⑤ 上电 ⑥ 看到 U-Boot 倒计时时立即按任意键在U-Boot 命令行执行bashCopy# 获取网络 setenv autoload no dhcp # 输出示例DHCP client bound to address 192.168.1.153 # 设置 TFTP 服务器 IPHost PC 的 IP setenv serverip 192.168.1.100 # 写入第一块 tftp ${loadaddr} xaa setexpr blkcnt1 ${filesize} / 0x200 mmc write ${loadaddr} 0 ${blkcnt1} # 写入第二块若镜像 1GB 才有 xab tftp ${loadaddr} xab setexpr blkcnt2 ${filesize} / 0x200 mmc write ${loadaddr} ${blkcnt1} ${blkcnt2}Step 3烧写 full.jic 到 QSPI目的用含完整 FPGA 配置的正式 JIC 替换 helper.jic硬件操作 ① 断电 ② SW27 → JTAG 模式OFF-OFF-OFF-OFF ③ 上电bashCopy# Host PC 执行 jtagconfig --setparam 1 JtagClock 16M quartus_pgm -c 1 -m jtag -o pvi;full.jicStep 4从 eMMC 启动 Linux硬件操作 ① 断电 ② SW27 → QSPI 模式OFF-ON-ON-OFF ③ 上电 ④ 等待 Linux 启动约 30 秒 ⑤ 串口登录用户名 root无密码后续更新镜像无需重烧 JIC日常迭代开发时只要打断 U-Boot 重写 eMMC 即可。① SW27 保持 QSPI 模式OFF-ON-ON-OFF不需要改 ② 上电串口看到倒计时时按任意键 ③ 执行与 Step 2 相同的 U-Boot 命令 ④ reset 重启验证全流程文件流转总图HPS 工程师 FPGA 工程师 板子硬件 ───────────────────────── ────────────────────── ───────────── [Yocto 编译输出] u-boot-spl-dtb.hex ─────────→ [生成 JIC] u-boot.itb ─────────→ │ ├─→ helper.jic ───────→ QSPI (Step1) └─→ full.jic ───────→ QSPI (Step3) gsrd-console-image.wic └─ split ──→ xaa/xab ───→ TFTP 服务器 │ └────────────────────→ eMMC (Step2)最终存储布局QSPI Flashfull.jic 烧入后 ├── FPGA 配置完整 ├── U-Boot SPL └── U-Boot Proper eMMCwic 写入后 ├── FAT32 分区 │ ├── u-boot.itb ← U-Boot Proper ATF │ ├── kernel.itb ← Linux Kernel DTB core.rbf │ ├── boot.scr.uimg ← 启动脚本 │ └── uboot.env ← U-Boot 环境变量 └── EXT4 分区 └── rootfs最终启动链上电QSPI 模式 │ ▼ QSPI → U-Boot SPLFSBL │ 初始化 DDR、时钟 │ 搜索 U-Boot ProperSD Card无→ eMMC找到 ▼ eMMC FAT32 → u-boot.itbU-Boot Proper ATF bl31 │ 解析 boot.scr.uimg ▼ eMMC FAT32 → kernel.itb │ ├── Linux Kernel │ ├── Device Tree │ └── core.rbf → 配置 FPGA FabricPhase 2 ▼ eMMC EXT4 → Root Filesystem │ ▼ Linux 启动完成需要重烧 JIC vs 只需重写 eMMC更新内容操作Linux 内核 / DTB / rootfs / 应用打断 U-Boot → 重写 eMMCU-Boot Proper打断 U-Boot → 重写 eMMCFPGA Phase 2 配置core.rbf打断 U-Boot → 重写 eMMCU-Boot SPLFSBL重新生成 JIC → 重烧 QSPIFPGA 顶层设计.sof重新生成 JIC → 重烧 QSPISPL 如何知道从哪里加载 U-Boot ProperSPL 的加载来源是编译时配置决定的不是运行时动态判断的。编译时配置在 Yocto 构建时U-Boot 的defconfig文件中定义了 SPL 的启动介质CONFIG_SPL_MMCy # 启用从 MMC/eMMC 加载 CONFIG_SPL_FS_FATy # 启用 FAT 文件系统支持 CONFIG_SPL_LOAD_FITy # 加载 FIT 镜像即 .itb 格式以及加载的文件名CONFIG_SPL_FS_LOAD_PAYLOAD_NAMEu-boot.itb这些配置在编译时就固化进了 SPL 的二进制文件中。SPL 运行时的查找逻辑SPL 启动 ↓ 按优先级依次尝试启动介质编译时定义的顺序 1. eMMC分区1 FAT32 → 找 u-boot.itb → 找到则加载 2. SD Card → 找 u-boot.itb 3. QSPI若配置了 fallback→ 直接读取内嵌的 u-boot.itb ↓ 找到则执行找不到则报错停止当emmc为空哪个所有help.jic有U-boot可以实现启动从QSPI的U-boot启动。当emmc已经有镜像有U-bootSPL启动emmc的U-boot。实际上 Agilex 5 GSRD 的情况可能是helper.jic 和 full.jic 用的是同一个 SPL区别只在于 FPGA 配置内容.sof不同SPL 的 fallback 行为是固定编译进去的两者都有只是 full.jic 使用时 eMMC 已经有内容所以 fallback 从未被触发