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

Agilex 平台的开发不是单一工具能完成的任务。FPGA 逻辑、HPS（Hard Processor System，硬核处理器系统）软件、片内互联与外部接口配置分布在不同的工具链中，最终又必须协同工作。因此，搭建开发环境的核心目标不是“把软件装上”，而是让 Quartus Prime、Platform Designer、HPS 工具链、驱动与 SDK 形成一条可编译、可下载、可调试的完整通路。本节以 Agilex 器件为例，说明各工具的分工、安装配置要点，并给出首个工程的创建与编译流程。

一、工具链分工与版本匹配

Agilex 开发涉及以下核心组件：

• Quartus Prime Pro Edition：负责 RTL 综合、布局布线、时序分析和比特流生成。Agilex 器件仅由 Pro Edition 支持，Standard Edition 不覆盖该系列。
• Platform Designer：原 Qsys，用于构建片内系统，把 HPS、PCIe、EMIF、NoC 等硬核 IP 与用户逻辑通过 Avalon 或 AXI 互联集成，生成系统级 RTL 和地址映射。
• HPS 工具链：包括 Arm 交叉编译器、U-Boot、Linux 内核、设备树以及根文件系统构建工具（如 Yocto 或 Buildroot），用于生成运行在 HPS 上的软件镜像。
• 驱动与 SDK：Agilex 的 FPGA 配置驱动、HPS-FPGA 桥接驱动、SoC FPGA 嵌入式设计套件（EDS）以及用于软件开发的调试器与库。

版本匹配是首要原则。Quartus Prime、Platform Designer、SoC EDS、器件支持包（Device Support）以及 HPS 引导工具必须来自同一发布版本，例如 Quartus Prime Pro 24.1 对应 SoC EDS 24.1 和 Agilex 器件支持 24.1。混用版本常导致 IP 生成失败、地址映射不一致或引导镜像无法加载。安装时建议勾选 Agilex 器件系列、Pro Edition 以及对应的 EDS 组件，避免后续补装。

二、安装与许可配置

Quartus Prime Pro 安装包体积较大，安装路径应避免中文和空格。安装完成后需配置许可证：将 LICENSE.dat 中的 HOSTID 替换为本机网卡 MAC 地址，设置环境变量 LM_LICENSE_FILE 指向该文件，然后通过 quartus_sh --version 和 quartus_sh --licenses 验证许可是否被识别。若使用浮动许可，还需确认许可服务器可达。

HPS 工具链方面，SoC EDS 提供 Arm GNU 工具链和预编译引导组件。安装后需将 arm-none-eabi-gcc 或 aarch64-linux-gnu-gcc 加入 PATH，并用 aarch64-linux-gnu-gcc -v 确认版本。若使用 Yocto 构建根文件系统，还需安装 poky 及对应 BSP 层。

三、首个工程创建与编译流程

下面以一个最小 Agilex 工程为例，说明从建工程到生成比特流的完整过程。示例参数为教学假设，实际应以所用开发板原理图和器件型号为准。

1. 新建工程：启动 Quartus Prime Pro，选择 File → New Project Wizard，指定工程目录、工程名（如 agilex_led_blink）和顶层实体名。器件选择 Agilex 系列中与开发板一致的型号，例如 AGFB014R24A2E2V，并确认封装与速度等级。
2. 添加设计文件：加入 Verilog 或 VHDL 源文件。一个最小示例如下：

module agilex_led_blink (
    input  wire clk_50m,
    input  wire rst_n,
    output reg  led
);
    reg [25:0] cnt;
    always @(posedge clk_50m or negedge rst_n) begin
        if (!rst_n) begin
            cnt <= 26'd0;
            led <= 1'b0;
        end else if (cnt == 26'd49_999_999) begin
            cnt <= 26'd0;
            led <= ~led;
        end else begin
            cnt <= cnt + 1'b1;
        end
    end
endmodule

该示例以 50 MHz 时钟计数，每 5000 万个周期翻转一次 LED，即约 1 秒闪烁一次。计数上限 49_999_999 对应 50 MHz 下 1 秒周期，属于教学示例值。

3. 引脚约束：在 .qsf 或 Pin Planner 中把 clk_50m、rst_n、led 分配到实际引脚，并设置 I/O 标准（如 3.3-V LVCMOS）。引脚编号必须来自开发板原理图，不能凭经验填写。
4. 时序约束：在 SDC 文件中声明时钟，例如 create_clock -name clk_50m -period 20.000 [get_ports clk_50m]，周期 20 ns 对应 50 MHz。缺少时钟约束会导致时序分析不完整。
5. 编译：依次执行 Analysis & Synthesis、Fitter、Assembler。也可用命令行：

quartus_sh --flow compile agilex_led_blink

编译完成后，在 output_files 目录下生成 .sof（SRAM Object File）和 .rbf（Raw Binary File）。.sof 用于 JTAG 下载，.rbf 用于 HPS 或配置器件加载。

四、Platform Designer 系统集成

若设计需要 HPS 或 PCIe，应在 Platform Designer 中建立系统。典型步骤是：添加 HPS 组件、配置 DDR 与时钟、添加用户 Avalon 从设备、连接时钟与复位、分配基地址，然后 Generate HDL。生成后会得到系统级 RTL、地址映射文件和 .qip，需将其加入 Quartus 工程并重新编译。此时应核对地址映射与 HPS 软件中的设备树是否一致，否则会出现访问越界或驱动加载失败。

五、HPS 软件与驱动配置

当工程包含 HPS 时，还需生成引导镜像。典型流程是：用 Quartus 生成 .sof，用 quartus_cpf 转换为 .rbf，再用 mkimage 或 SoC EDS 的引导工具把 .rbf、U-Boot、设备树和内核打包为 u-boot-with-spl.sfp 或 boot.bin。设备树中必须包含与 Platform Designer 一致的 HPS 外设地址、中断号和时钟频率。驱动方面，Agilex 的 FPGA 配置驱动和 HPS-FPGA 桥接驱动通常已包含在 Linux 内核中，需在设备树中使能对应节点，并通过 dmesg 确认桥接设备枚举成功。

六、常见问题与判断依据