FPGA加速卡安装与固件恢复实战指南

1. 项目背景与问题概述

在科研项目中部署FPGA加速卡是提升计算性能的常见需求。这次我们在Dell PowerEdge R750服务器上尝试安装Xilinx Alveo U200加速卡时，遇到了一个典型但容易被忽视的问题——设备无法被系统识别。经过排查发现，这是由于加速卡之前被固化了特定固件导致的。

这种情况在实际部署中并不少见，特别是当FPGA加速卡在不同项目或团队间流转使用时。很多工程师第一次遇到这种问题时往往会花费大量时间在驱动安装和系统配置上，而忽略了硬件固件状态这个根本原因。

2. 环境准备与基础检查

2.1 硬件环境确认

我们的测试平台采用Dell PowerEdge R750服务器，这是一款2U机架式服务器，配备了：

• 双路Intel Xeon处理器
• 512GB内存
• 1400W冗余电源
• PCIe Gen3 x16插槽

特别需要注意的是，Alveo U200加速卡需要额外的8-pin PCIe辅助电源（AUX Power）。标准PCIe插槽只能提供75W功率，而U200最大功耗可达215W（插槽75W+辅助电源150W）。如果辅助电源未正确连接，虽然卡可能部分工作，但无法被完整识别。

2.2 操作系统与内核配置

我们选择了AlmaLinux 9.6作为操作系统，这是一个RHEL兼容发行版，内核版本为5.14.0-570.39.1.el9_6.x86_64。在开始安装前，需要确认以下基础组件：

bash复制# 确认系统基本信息
cat /etc/os-release
uname -r

# 检查必要的开发工具和内核头文件
sudo yum groupinstall "Development Tools"
sudo yum install kernel-devel-$(uname -r) kernel-headers-$(uname -r)

# 启用EPEL仓库
sudo yum install epel-release

注意：不同Linux发行版的内核头文件安装方式可能不同。在Ubuntu/Debian系统上应使用apt install linux-headers-$(uname -r)。

3. XRT运行时环境安装

3.1 XRT版本选择

Xilinx Runtime (XRT)是FPGA加速卡的软件栈核心。我们最初尝试安装XRT 2024.2版本，但遇到了内核模块编译错误：

bash复制error: too many arguments to function 'eventfd_signal'
eventfd_signal(irq_entry->event_ctx, 1);

这是由于较新Linux内核中eventfd_signal函数签名发生了变化。解决方法有两种：

1. 降级内核版本（不推荐，可能影响系统稳定性）
2. 升级XRT到2025.1版本（推荐）

我们选择了第二种方案，下载并安装XRT 2025.1：

bash复制sudo yum install -y ./xrt_202510.2.19.194_9.0-x86_64-xrt.rpm
source /opt/xilinx/xrt/setup.sh

3.2 DKMS驱动管理

XRT使用DKMS（Dynamic Kernel Module Support）来管理内核模块。安装后需要确认驱动状态：

bash复制# 检查已安装的DKMS模块
sudo dkms status

# 如果遇到模块不匹配问题，可以重新构建
sudo dkms remove xrt/2.19.194 --all
sudo dkms install xrt/2.19.194

# 确认驱动文件生成
ls -lh /lib/modules/$(uname -r)/extra/

正确的输出应该包含xclmgmt.ko.xz和xocl.ko.xz两个驱动模块文件。

4. 固件包安装与配置

4.1 固件包组成

Alveo U200需要多个固件组件协同工作：

1. SC固件（Shell Controller）：xilinx-sc-fw-u200-u250-*.rpm
2. CMC固件（Card Management Controller）：xilinx-cmc-u200-u250-*.rpm
3. Base固件：xilinx-u200-gen3x16-xdma-base-*.rpm
4. 验证工具：xilinx-u200-gen3x16-xdma-validate-*.rpm

安装命令很简单：

bash复制sudo yum install -y ./*.rpm

但关键在于安装后的验证步骤：

bash复制# 检查固件版本
sudo /opt/xilinx/xrt/bin/xbmgmt examine

4.2 驱动加载与验证

正确加载驱动模块是FPGA能被识别的关键：

bash复制# 手动加载驱动（系统启动时会自动加载）
sudo modprobe xclmgmt
sudo modprobe xocl

# 验证驱动状态
lsmod | grep -E "xocl|xclmgmt"

# 检查设备节点
ls -la /dev/xclmgmt* /dev/dri/renderD*

正常情况下，应该能看到/dev/xclmgmt*和/dev/dri/renderD*设备节点。

5. 问题诊断与解决

5.1 症状表现

当我们执行lspci -d 10ee:时，只看到了一个设备：

code复制b1:00.0 Serial controller: Xilinx Corporation Device 903f

而正常情况下应该显示两个设备：

code复制b1:00.0 Processing accelerators: Xilinx Corporation Device 5004
b1:00.1 Processing accelerators: Xilinx Corporation Device 5005

5.2 排查步骤

我们按照以下顺序进行了全面排查：

1. 电源检查：

   • 确认8-pin辅助电源线已牢固连接
   • 使用服务器管理界面检查电源输出状态

2. 冷启动尝试：

   bash复制sudo shutdown -h now
   # 完全断电等待5分钟后重新上电
   

3. PCIe插槽检查：

   • 尝试更换不同PCIe插槽
   • 确认插槽为Gen3 x16规格

4. 固件状态检查：

   bash复制sudo /opt/xilinx/xrt/bin/xbmgmt examine
   

5.3 根本原因

经过以上排查，最终确定问题原因是FPGA卡处于"安全模式"，设备ID被固定为903f。这种情况通常发生在：

• 卡之前被用于Vivado直接编程流程
• 固件刷写过程中被中断
• 卡从其他非标准环境迁移过来

5.4 解决方案：恢复黄金镜像

根据AMD官方文档（参考71757号解决方案），我们需要将卡恢复到出厂状态：

1. 下载黄金镜像文件（通常以.mcs或.bin结尾）
2. 使用XRT工具进行恢复：

   bash复制sudo /opt/xilinx/xrt/bin/xbmgmt flash --update --shell xilinx_u200_gen3x16_xdma_base_2
   

3. 完全断电重启服务器

重要提示：恢复过程中切勿中断电源或移除加速卡，否则可能导致卡无法使用。

6. 安装后的验证与测试

成功恢复黄金镜像后，应该能看到正确的设备信息：

bash复制$ lspci -d 10ee:
b1:00.0 Processing accelerators: Xilinx Corporation Device 5004
b1:00.1 Processing accelerators: Xilinx Corporation Device 5005

$ sudo /opt/xilinx/xrt/bin/xbmgmt examine
...
Device(s) Present
[0000:b1:00.0] : xilinx_u200_gen3x16_xdma_base_2

进一步的验证可以运行简单的测试程序：

bash复制# 安装测试工具
sudo yum install xrt-tools

# 运行基础测试
/opt/xilinx/xrt/bin/xbutil validate

7. 经验总结与注意事项

7.1 关键教训

1. 固件状态优先：遇到FPGA卡无法识别时，首先检查固件状态，而不是盲目重装驱动。
2. 电源完整性：确保辅助电源连接可靠，最好使用原装电源线。
3. 版本兼容性：XRT版本与Linux内核版本需要严格匹配。

7.2 推荐工作流程

对于新的Alveo U200部署，建议按以下顺序操作：

1. 物理安装并确认电源连接
2. 恢复黄金镜像（特别是二手或流转使用的卡）
3. 安装匹配的XRT版本
4. 安装平台固件包
5. 验证设备识别

7.3 排错资源

当遇到问题时，可以参考以下资源：

1. 官方调试指南：https://xilinx.github.io/Alveo-Cards/master/debugging/build/html/README.html
2. XRT文档：https://xilinx.github.io/XRT/master/html/index.html
3. AMD支持论坛：https://adaptivesupport.amd.com/s/?language=en_US

对于中文用户，还可以参考：

1. Alveo中文资源：https://github.com/xupsh/Alveo_Chinese
2. Xilinx中国支持：https://china.xilinx.com/support.html