2. HLS开发环境搭建：Intel oneAPI与Quartus安装、HLS工具链配置、环境变量设置与验证

搭建稳定、高效的HLS开发环境是开展Agilex架构下DSP算力开发的前提。本章围绕Intel oneAPI基础工具包、Quartus Prime Pro及HLS工具链的安装、配置与验证展开，确保开发人员能够快速进入算法设计与硬件映射阶段。

2.1 环境概览与组件依赖

Agilex FPGA的HLS开发依赖以下核心软件栈，各组件版本需严格匹配，否则可能导致编译失败或时序异常。

2.2 安装流程与关键步骤

以下安装顺序经过验证，可避免环境变量冲突与库依赖缺失。

1. 安装 Quartus Prime Pro：从 Intel FPGA 官网下载完整安装包，选择包含 Arria/Stratix/Agilex 设备支持的 Pro 版本。安装时勾选 HLS Compiler 与 DSP Builder 组件。
2. 安装 oneAPI Base Toolkit：使用离线安装器或在线安装命令，选择 Intel® oneAPI DPC++/C++ Compiler 与 Intel® oneAPI Math Kernel Library (oneMKL)。
3. 安装 FPGA Add-on：运行 fpga_addon.sh 脚本，指定 oneAPI 安装路径与 Quartus 安装路径，完成后端工具链注册。
4. 安装设备驱动与许可：Agilex 开发板需安装 jtag 驱动；Quartus 与 oneAPI 均需配置 LM_LICENSE_FILE 或 INTELFPGA_LICENSE_FILE 环境变量。

2.3 环境变量配置清单

安装完成后，需在 ~/.bashrc 或 ~/.bash_profile 中设置以下环境变量，确保工具链可被正确调用。

# Quartus 与 HLS Compiler 路径
export QUARTUS_ROOTDIR=/opt/intelFPGA_pro/24.1/quartus
export PATH=$QUARTUS_ROOTDIR/bin:$QUARTUS_ROOTDIR/../hls/bin:$PATH

# oneAPI 基础环境
export ONEAPI_ROOT=/opt/intel/oneapi
source $ONEAPI_ROOT/setvars.sh --force

# FPGA Add-on 注册
export FPGA_BOARD=agilex7
export BOARD_PACKAGE_ROOT=/opt/intelFPGA_pro/24.1/board/agilex7

# 许可文件
export INTELFPGA_LICENSE_FILE=/path/to/license.dat
export LM_LICENSE_FILE=$INTELFPGA_LICENSE_FILE

2.4 HLS工具链配置与验证

HLS 工具链的核心是 i++ 编译器（Intel oneAPI DPC++ FPGA 编译器）与 quartus_fit 布局布线器。以下流程图展示从源代码到比特流的完整工具链调用关系。

2.5 环境验证测试用例

完成配置后，建议运行以下最小验证工程，确认工具链各环节正常。

// vector_add.cpp — 最小HLS验证程序
#include <sycl/sycl.hpp>
using namespace sycl;

constexpr int N = 256;

int main() {
  queue q{ accelerator_selector{} };
  std::cout << "Device: " << q.get_device().get_info<info::device::name>() << "\n";

  int *a = malloc_shared<int>(N, q);
  int *b = malloc_shared<int>(N, q);
  int *c = malloc_shared<int>(N, q);

  for (int i = 0; i < N; i++) { a[i] = i; b[i] = i * 2; }

  q.parallel_for(range<1>(N), [=](id<1> i) { c[i] = a[i] + b[i]; }).wait();

  bool pass = true;
  for (int i = 0; i < N; i++) if (c[i] != a[i] + b[i]) { pass = false; break; }
  std::cout << (pass ? "PASS" : "FAIL") << "\n";

  free(a, q); free(b, q); free(c, q);
  return 0;
}

编译与运行命令：

# 编译为FPGA硬件镜像（耗时较长，首次约30-60分钟）
i++ -fintelfpga -fsycl vector_add.cpp -o vector_add.fpga -Xshardware

# 在Agilex开发板上运行
./vector_add.fpga

2.6 常见问题与排查

2.7 开发环境目录结构建议

为便于多项目管理和工具链复用，推荐以下目录布局：

agilex_hls_workspace/
├── projects/
│   ├── vector_add/
│   ├── fir_filter/
│   └── fft_dsp/
├── libraries/
│   ├── dsp_kernels/
│   └── common_utils/
├── scripts/
│   ├── build_fpga.sh
│   └── run_sim.sh
├── boards/
│   └── agilex7_devkit/
└── env_setup.sh