2. 开发环境搭建与工具链

Agilex SoC 的开发不是单一工具能完成的任务。它同时包含 FPGA 逻辑设计（HPS 外设、桥接、PLL、I/O）和 HPS 侧的 ARM Cortex-A53 软件（U-Boot、Linux、裸机程序）。因此工具链天然分成两条主线：一条是 Intel Quartus Prime Pro 负责硬件工程、引脚约束、编译与 SOF 下载；另一条是 SoC EDS 与 Ashling RiscFree IDE 负责 HPS 侧的启动代码、设备树、调试与程序下载。理解这两条主线如何衔接，比记住安装步骤更重要。

工具链分工与衔接关系

Quartus Prime Pro 是 Agilex 系列唯一受支持的版本（Standard 版不支持 Agilex）。它完成从 RTL/Platform Designer 系统到 .sof 的编译，并生成 HPS 相关的硬件信息文件，例如 .sopcinfo（供 SoC EDS 生成设备树和头文件）以及 HPS 配置所需的寄存器描述。SoC EDS 提供 embedded_command_shell.sh、bsp-editor、quartus_hps、arm-none-eabi- 工具链等，用于生成 U-Boot、设备树、preloader 并烧写到 SD 卡或 QSPI。Ashling RiscFree IDE 则是基于 Eclipse 的集成调试环境，用于 HPS 裸机/RTOS 程序的编译、下载与 JTAG 调试。

安装顺序与关键配置

推荐顺序是：先装 Quartus Prime Pro（含 Agilex 器件支持包），再装 SoC EDS，最后装 Ashling RiscFree IDE。Quartus Pro 安装时务必勾选 Agilex 器件系列，否则后续 Platform Designer 中找不到 HPS IP。安装完成后设置环境变量：QUARTUS_ROOTDIR 指向安装目录，QUARTUS_64BIT=1，并把 $QUARTUS_ROOTDIR/bin 加入 PATH。SoC EDS 通过 embedded_command_shell.sh 启动专用 shell，它会自动设置交叉编译工具链路径。

# 启动 SoC EDS 嵌入式命令 shell
$QUARTUS_ROOTDIR/../soceds/embedded/embedded_command_shell.sh

# 验证交叉编译器
arm-none-eabi-gcc --version

# 验证 Quartus 命令行
quartus_sh --version
quartus_hps --version

许可证方面，Quartus Prime Pro 需要有效的 License 文件。设置 LM_LICENSE_FILE 或 QUARTUS_LICENSE_FILE 指向 license.dat，然后用 quartus_licensing 或 Quartus 的 License Setup 页面确认状态为 Licensed。SoC EDS 和 RiscFree IDE 随 Quartus Pro 一起安装，不需要额外授权，但 RiscFree 首次启动时要指定 workspace 和工具链路径。

创建第一个 Agilex SoC 工程

在 Quartus Pro 中新建工程，器件选择 Agilex 系列（例如 AGFB014R24A，具体以开发板为准）。工程建立后打开 Platform Designer，添加 HPS 组件：配置 HPS 的时钟、DDR、外设引脚复用（Pin Muxing）、EMIF 接口等。关键一步是设置 HPS 的启动源（SD/MMC 或 QSPI）和 JTAG 调试接口。完成后 Generate HDL，Platform Designer 会输出 .sopcinfo 和 RTL 文件。

接着在 Quartus 中完成引脚约束（.qsf）和时序约束（.sdc），运行全编译。编译成功后得到 .sof。此时硬件侧准备完毕，可以先用 quartus_pgm 下载 SOF 验证 FPGA 配置是否正常：

quartus_pgm -c "USB-BlasterIII" -m jtag -o "p;output_files/top.sof"

HPS 侧软件与下载

硬件编译完成后，用 SoC EDS 的 bsp-editor 基于 .sopcinfo 生成 HPS 启动所需文件：preloader、U-Boot、设备树。典型流程是：bsp-editor 打开 .sopcinfo，选择启动设备（SD/MMC），生成 uboot 和 preloader 源码，再用 make 编译。生成的 u-boot-with-spl.sfp 可通过 quartus_hps 烧写到 QSPI，或直接写入 SD 卡。

# 用 quartus_hps 烧写 HPS 启动镜像到 QSPI
quartus_hps -c 1 -o P -a 0x0 u-boot-with-spl.sfp

# 或写入 SD 卡（Linux 下）
sudo dd if=u-boot-with-spl.sfp of=/dev/sdX bs=512 seek=2048

对于裸机或 RTOS 程序，在 RiscFree IDE 中新建 “Altera SoC Baremetal” 工程，指定 .sopcinfo 和工具链，编译得到 .elf。通过 RiscFree 的 Debug Configuration 选择 USB-Blaster III 和 HPS JTAG，即可下载并单步调试。判断工程是否成功，可以观察串口是否输出 U-Boot 启动日志、HPS 是否进入 Linux 控制台，或在 RiscFree 中看到程序停在 main 入口。

常见问题与排查

安装与首次工程最容易卡在三个地方：一是 License 未生效，Quartus 能打开但编译报错；二是 Platform Designer 中 HPS 的 Pin Muxing 与开发板原理图不一致，导致外设不工作；三是 bsp-editor 找不到 .sopcinfo 或器件不匹配。排查时先确认 quartus_sh --version 与 License 状态，再核对 HPS 配置中的启动源和引脚分配，最后检查 SoC EDS shell 中的工具链路径是否正确。把这三步走通，后续的 U-Boot 移植和 Linux 启动才有稳定基础。