第二章：Vitis开发环境搭建

说实话，很多初学者一上来就急着写代码，结果卡在环境搭建上大半天。我当年也干过这事——装完Vitis发现跑不了hello world，折腾了两天才发现是XRT没装对。所以这一章，咱们老老实实把环境搭好，后面才能痛快地写代码。

2.1 Vitis软件安装与配置

Vitis是Xilinx的统一开发平台，说白了就是把原来的SDK和SDAccel揉到了一起。我个人习惯先装Vitis，再装XRT，最后搞驱动。这个顺序别搞反了，不然容易出幺蛾子。

2.1.1 下载与安装

去Xilinx官网下载Vitis统一安装包。注意，这个包很大，我记得有几十个G。建议用命令行安装，图形界面有时候会卡住。

# 解压安装包
tar -xzvf Xilinx_Vitis_2023.1_*.tar.gz
cd Xilinx_Vitis_2023.1_*

# 运行安装脚本
./xsetup

安装时选“Vitis”和“Vivado”两个组件。如果你做纯软件加速，可以不装Vivado，但我建议都装上——你永远不知道什么时候需要看波形。

我的小技巧： 安装路径不要有中文和空格。我见过有人装在“C:\Program Files (x86)\赛灵思”下面，结果编译报一堆路径错误。

2.1.2 环境变量配置

装完只是第一步，还得告诉系统去哪找Vitis。我个人习惯把配置写到.bashrc里，一劳永逸。

# 打开.bashrc
vim ~/.bashrc

# 添加以下内容
export XILINX_VITIS=/tools/Xilinx/Vitis/2023.1
export XILINX_VIVADO=/tools/Xilinx/Vivado/2023.1
export PATH=$XILINX_VITIS/bin:$XILINX_VIVADO/bin:$PATH

# 使配置生效
source ~/.bashrc

验证一下：

which vitis
# 应该输出 /tools/Xilinx/Vitis/2023.1/bin/vitis

嗯，这里要注意：如果你用的是Ubuntu 22.04，可能会遇到libtinfo.so.5缺失的问题。别慌，装个兼容包就行：

sudo apt install libtinfo5

2.2 Xilinx Runtime库(XRT)安装

XRT是什么？说白了就是FPGA和CPU之间的“翻译官”。你的程序要往FPGA上发数据、收结果，都得靠它。我在项目中遇到过好几次，代码写得挺好，结果XRT版本不对，跑起来直接崩。

2.2.1 安装XRT

XRT的安装包在Vitis安装目录里就有，不用单独下载。

# 找到XRT安装包
cd /tools/Xilinx/Vitis/2023.1/card_installers/
ls *.deb

# 安装（以Ubuntu为例）
sudo apt install ./xrt_2023*.deb

我曾经踩过的坑： 装XRT之前一定要先装好dkms和linux-headers。不然驱动编译会失败，而且报错信息特别隐晦，就一行“Build failed”。我当时查了一下午才发现是内核头文件没装。

2.2.2 验证XRT安装

装完跑一下这个命令：

xbutil examine
# 如果输出类似下面的信息，说明装好了
# System Configuration
# OS: Ubuntu 22.04 LTS
# XRT: 2.15.0

如果报错说找不到命令，八成是环境变量没配好。检查一下/opt/xilinx/xrt/bin有没有在PATH里。

2.3 开发板驱动与BSP设置

驱动和BSP是连接硬件和软件的桥梁。没有驱动，你的电脑认不出开发板；没有BSP，Vitis不知道你的板子长什么样。

2.3.1 安装开发板驱动

不同的板子驱动不一样。以最常用的Alveo U200为例：

# 安装板卡驱动
sudo /opt/xilinx/xrt/bin/xbutil flash --update

# 重启后检查
lspci | grep Xilinx
# 应该能看到类似 "Xilinx Corporation Device 5000" 的信息

如果你用的是Zynq系列，驱动是内核自带的，一般不需要额外装。但要注意，有些开发板需要手动加载驱动模块：

sudo modprobe xocl
lsmod | grep xocl

2.3.2 板级支持包(BSP)设置

BSP说白了就是板子的“身份证”。Vitis通过它知道你的板子有多少资源、什么接口、时钟频率多少。

我个人习惯把BSP文件放在项目目录下，方便管理：

# 创建BSP目录
mkdir -p my_project/bsp
cd my_project/bsp

# 从官方仓库下载BSP（以ZCU102为例）
wget https://xilinx-bsp.s3.amazonaws.com/zcu102.bsp

# 或者从Vitis安装目录复制
cp /tools/Xilinx/Vitis/2023.1/data/boards/boards.xml ./

  关键点： BSP版本必须和Vitis版本匹配。我见过有人拿2022.2的BSP用在2023.1上，结果编译通过但运行时报“clock mismatch”。这种错误最难查，因为编译不报错。

2.3.3 在Vitis中配置BSP

打开Vitis，新建一个平台工程：

File → New → Platform Project
输入项目名，比如“my_platform”
在“Hardware Specification”里选择你的BSP文件
点击Finish

配置完成后，你会看到类似这样的结构：

my_platform/
├── bsp/
│   ├── zcu102.bsp
│   └── board.xml
├── src/
│   └── ...
└── platform.spr

嗯，这里有个小细节：BSP里的board.xml定义了板子的所有外设。如果你自己画了板子，可以手动修改这个文件来添加自定义外设。我有个项目就是这么干的——在FPGA上挂了个自定义的ADC，改完board.xml后Vitis就认出来了。

2.4 环境验证

所有东西装完后，跑个简单的hello world验证一下：

# 创建一个简单的OpenCL程序
cat > hello.c << EOF
#include <stdio.h>
#include <xrt.h>

int main() {
    xrtDeviceHandle handle = xrtDeviceOpen(0);
    if (handle) {
        printf("Hello from XRT! Device opened successfully.\n");
        xrtDeviceClose(handle);
    } else {
        printf("Failed to open device.\n");
    }
    return 0;
}
EOF

# 编译
gcc -o hello hello.c -lxrt_core

# 运行
./hello

如果输出“Hello from XRT!”，恭喜你，环境搭好了。如果报错，别急，检查一下：

XRT服务有没有启动：sudo systemctl status xrt
板卡有没有被识别：xbutil examine
用户有没有在xrt组里：groups，如果没有就sudo usermod -aG xrt $USER

我的经验： 环境搭建最怕的就是版本不匹配。我建议你装完所有东西后，把版本号记下来：xbutil version、vitis -version、uname -r。下次出问题时，先对比版本号，能省一半时间。

2.5 本章知识体系

下面这张图帮你理清整个环境搭建的脉络：

这张图展示了整个环境搭建的流程。说白了就是三步走：装Vitis、装XRT、配驱动和BSP。每一步都有对应的验证方法，别跳步。

📚 课程目录

第二章：Vitis开发环境搭建

2.1 Vitis软件安装与配置

2.1.1 下载与安装

2.1.2 环境变量配置

2.2 Xilinx Runtime库(XRT)安装

2.2.1 安装XRT

2.2.2 验证XRT安装

2.3 开发板驱动与BSP设置

2.3.1 安装开发板驱动

2.3.2 板级支持包(BSP)设置

2.3.3 在Vitis中配置BSP

2.4 环境验证

2.5 本章知识体系