Vitis2024.1入门实战：从hello_world跑通平台、域与应用工程全流程

1. 为什么还要从 hello_world 开始聊 Vitis如果你最近刚把开发环境升级到 Vitis2024.1打开界面之后第一反应大概率是“这玩意儿怎么比 Vivado 还复杂”。我完全理解这种感受。Vitis 从 2019 年独立成一个统一软件平台之后版本迭代一直在调整工程结构、组件命名和底层调用逻辑到了 2024.1 这个版本很多老教程里的截图和菜单路径已经对不上了。你照着两年前的帖子一步步点走到一半发现按钮没了或者编译报一堆平台相关的错误这种情况太常见了。所以我还是决定拿最经典的 hello_world 来当切入点。别看它简单这一个例子能把 Vitis2024.1 里最核心的几条链路全部串起来平台工程怎么建、应用工程怎么挂上去、BSP 里哪些配置会影响串口输出、编译产物在哪、怎么下载到板子上跑起来。把这套流程走通一遍后面你做裸机驱动、FreeRTOS 移植、甚至更复杂的加速应用底层逻辑都是同一套。这篇文章适合两类人一是刚接触 Xilinx 嵌入式开发、手里有 Zynq 或 MicroBlaze 板子的新手二是从老版本 ISE/SDK 迁过来、被新工程结构搞晕的老工程师。我会把每一步为什么这么做讲清楚参数怎么选、坑在哪、报错怎么查尽量让你看完就能自己复现一遍。2. Vitis2024.1 的工程结构到底变了什么2.1 从 SDK 到 Vitis 的演进逻辑很多人习惯把 Vitis 叫成“新版 SDK”这个说法不算错但容易让你用旧思维去理解新工具。SDK 时代的核心是 workspace 加硬件定义hdf一个 workspace 里可以塞很多应用工程硬件信息是导入进来的。Vitis 把这套东西拆成了更明确的三层平台工程Platform Project、域Domain、应用工程Application Project。平台工程负责描述硬件包括处理器核、外设地址、时钟、DDR 配置域是在平台之上定义软件运行环境比如用哪个核、跑裸机还是 Linux、用哪个编译器应用工程才是你真正写代码的地方。到了 2024.1这个三层结构没有变但界面和底层构建系统做了不少调整。最明显的是 Vitis 现在同时提供经典 IDE 和基于 VS Code 的新界面两种入口安装的时候可以选。经典 IDE 对老用户友好VS Code 版本更轻量但插件依赖多。我建议新手先用经典 IDE 把流程跑通因为社区里大部分截图和问题讨论还是基于经典界面的遇到问题好搜。2.2 平台、域、应用三者的依赖关系理解依赖关系是避免“改了硬件但软件不更新”这类问题的关键。平台工程里包含一个 .xsa 文件这个文件是 Vivado 导出硬件时生成的里面记录了 PS 端的配置、PL 端的 IP 信息、地址映射。域是挂在平台下面的一个平台可以有多个域比如一个 A53 裸机域、一个 R5 裸机域。应用工程又挂在域下面编译的时候会引用域里的 BSP板级支持包。这里有个容易踩的点如果你在 Vivado 里改了硬件重新导出 xsa必须在 Vitis 里更新平台工程然后重新编译 BSP最后再编译应用工程。只更新平台不重编 BSP应用里引用的寄存器地址可能还是旧的跑起来就会出现读写异常或者直接挂死。我见过不止一个同事在这上面浪费半天时间以为是代码问题其实是 BSP 没刷新。2.3 2024.1 版本值得注意的改动2024.1 在构建系统上进一步向 CMake 靠拢应用工程的编译配置底层是 CMake 驱动的。对普通用户来说你不需要直接写 CMakeLists但要知道编译日志里会出现 CMake 相关的输出看到不要慌。另外2024.1 对 Python 脚本化构建的支持更完善了如果你要做 CI/CD 或者批量构建可以用 xsct 命令行工具配合脚本完成不用每次都开图形界面。还有一个细节是串口终端Vitis 自带的串口终端在 2024.1 里对波特率和流控的默认值做了调整如果你发现输出乱码先检查波特率是不是 115200流控是不是 None。3. 动手前的环境准备与检查清单3.1 软件安装与版本匹配Vitis2024.1 的安装包体积不小完整安装加上器件支持动辄几十 GB。安装的时候有几个选择会影响后续使用一是器件家族如果你只玩 Zynq-7000可以只勾 7 系列能省不少空间二是安装路径强烈建议路径里不要有中文和空格Vitis 底层调用的一些工具链对路径很敏感中文路径导致的编译失败排查起来很痛苦。三是记得勾选“Install cable drivers”否则后面下载器识别不到板子。版本匹配这块Vitis2024.1 最好搭配同版本的 Vivado2024.1。虽然理论上 Vitis 可以打开稍旧版本导出的 xsa但跨大版本经常出兼容问题。如果你手里只有旧版 Vivado 导出的 xsa要么升级 Vivado要么在 Vitis 里新建平台时注意选择对应的硬件规格。3.2 硬件连接与驱动确认板子上电之前先把下载器和串口线接好。下载器一般是 JTAG 或 USB-JTAG串口通常是通过 USB-UART 桥接芯片引出的。接好之后在设备管理器里确认两个东西一个是下载器对应的端口有没有识别另一个是串口对应的 COM 号。如果下载器没识别多半是 cable driver 没装好重新跑一遍安装目录下的驱动安装脚本。串口这块记住 COM 号后面配终端要用。提示有些板子的串口和下载器是同一个 USB 口复用的插上之后会同时出现两个设备一个是 JTAG一个是串口别搞混。3.3 新建工作空间的注意事项Vitis 启动时会让你选 workspace 目录。这个目录用来存放你的平台工程和应用工程同样不要放在中文路径下。另外workspace 一旦选定工程元数据就写进去了后面想换目录比较麻烦建议一开始就规划好比如专门建一个D:\vitis_ws这样的纯英文短路径。workspace 里工程多了之后Vitis 启动会变慢因为要扫描所有工程所以做完的实验工程如果不再用可以关掉或者归档别一直堆着。4. 从零创建平台工程的完整流程4.1 新建平台工程并导入 xsa打开 VitisFile 菜单里选 New然后选 Platform Project。给平台起个名字比如hello_platform。下一步会让你选“Create from hardware specification”这里选你 Vivado 导出的 xsa 文件。如果你手上还没有 xsa需要先在 Vivado 里把 Block Design 搭好、综合实现、导出硬件。对于只想跑通 hello_world 的人来说最简单的办法是找一个官方开发板的现成 xsa比如 ZCU102 或 ZedBoard 的示例设计导出即可。导入 xsa 之后Vitis 会自动解析出处理器核和外设信息。你会在平台配置界面看到 processor 列表比如psu_cortexa53_0这种。确认一下你要用的核裸机 hello_world 一般用第一个 A53 核或者 MicroBlaze 核。4.2 配置域Domain的关键参数平台工程建好之后右键选 Add Domain或者在建平台的时候直接勾选生成域。域配置里有几个参数必须搞清楚Processor选哪个核跑代码这个决定了编译用的工具链。OS裸机选 standalone跑 Linux 选 linux。hello_world 选 standalone。Compiler一般用默认的 gcc 或 arm-none-eabi-gcc。LanguageC 或 Chello_world 用 C。这里有个细节2024.1 里域的 BSP 配置项比老版本多了不少比如 stdout 的重定向设置。默认情况下standalone 域的 stdout 会指向串口但具体是哪个串口、波特率多少是在 BSP 的stdout参数里配的。如果你后面发现程序跑了但串口没输出第一件事就是回来检查这个参数。4.3 平台编译与 BSP 生成域配置好之后右键平台工程选 Build。这一步会编译平台相关的库、生成 BSP。编译时间取决于器件和配置第一次可能要几分钟。编译完成后你会在平台工程目录下看到export文件夹里面是导出的平台信息应用工程就是基于这个来创建的。注意平台编译如果报错先看 Console 里的日志常见错误是 xsa 版本不匹配或者器件没安装。器件没安装的话回到安装器里补装对应家族。5. 创建 hello_world 应用工程并跑通5.1 新建应用工程的选项解读平台编译通过后File 菜单选 New Application Project。第一步选平台选你刚建好的hello_platform。下一步选域选那个 standalone 域。然后给应用起名比如hello_world_app。接下来会问你模板Vitis 自带一堆模板包括 Hello World、Empty Application、Peripheral Tests 等。选 Hello World 模板它会自动帮你生成一个带printf的 main 函数省得自己写。这里有个选择模板生成的工程会自带一个helloworld.c里面就是打印一句话然后 return。你可以直接用也可以改成自己的内容。对于第一次跑通流程来说直接用模板最稳妥变量最少。5.2 编译应用工程与产物位置应用工程建好后右键选 Build Project。编译过程会调用 BSP 里的库把helloworld.c编译成 ELF 文件。编译成功后在工程目录下的Debug文件夹里能找到.elf文件这就是最终要下载到板子上运行的可执行文件。同时还会生成.map文件用来查看内存布局调试内存问题时很有用。编译如果报错常见原因有几个一是 BSP 没编译先回去编译平台二是代码里有语法错误看 Console 里的具体行号三是工具链路径问题检查安装是否完整。5.3 下载到硬件并观察串口输出下载之前先确认板子上电、下载器连接正常。在应用工程上右键选 Run As然后选 Launch Hardware或者 Run Configurations 里配。Vitis 会自动调用下载器把 ELF 烧到 DDR 或 OCM 里然后复位处理器开始执行。串口这边打开 Vitis 自带的 Serial Terminal或者用外部工具比如 PuTTY、MobaXterm。配置参数波特率 115200数据位 8停止位 1校验 None流控 None。连接对应的 COM 口。如果一切正常你会在终端里看到类似Hello World的输出。如果没输出按这个顺序排查先确认串口线接的是板子上正确的 UART 口再确认 BSP 里 stdout 指向的串口和实际接线一致然后确认波特率匹配最后确认程序真的跑起来了可以在代码里加个 GPIO 翻转用示波器或 LED 看有没有执行到。6. 常见报错与排查经验实录6.1 编译类问题速查报错现象可能原因处理方式找不到 xsa 或平台无效xsa 版本与 Vitis 不匹配用同版本 Vivado 重新导出BSP 编译失败器件未安装或路径含中文补装器件改纯英文路径应用编译报未定义引用BSP 未编译或库缺失先编译平台再编译应用工具链找不到安装不完整重跑安装器补装工具链6.2 运行类问题排查思路程序下载成功但没输出是最常见的问题。我的排查顺序是先看串口配置再看 BSP stdout再看硬件接线最后看程序是否真的执行。有一次我折腾了半天最后发现是串口线插在了板子的第二个 UART 口上而 BSP 默认指向第一个。这种低级错误在紧张调试的时候特别容易犯所以养成“先确认物理连接”的习惯能省很多时间。还有一种情况是程序跑飞了串口输出乱码或者只输出一半。这通常是时钟配置不对比如 PS 端 UART 的时钟源频率和 BSP 里假设的不一致。回到 Vivado 里检查 PS 配置的 UART 时钟和 BSP 里的设置对齐。6.3 独家避坑心得第一个心得每次改完硬件按“更新平台 → 重编 BSP → 重编应用”的顺序走一遍不要跳步。第二个心得workspace 里工程多了之后Vitis 的索引会变慢定期清理不用的工程。第三个心得串口终端如果一直连不上先关掉 Vitis 自带的终端用外部工具试有时候是终端本身的问题。第四个心得下载器固件有时候需要更新如果下载一直失败检查一下下载器固件版本。7. 从 hello_world 延伸出去的几个方向跑通 hello_world 之后你其实已经掌握了 Vitis 最核心的工作流。接下来可以往几个方向延伸一是加外设驱动比如 GPIO、UART 中断、定时器这些在 BSP 里都有现成的库调用方式在官方文档里有说明二是尝试 FreeRTOS在域配置里把 OS 改成 FreeRTOS然后建任务感受一下和裸机的区别三是玩一下 Vitis 的加速流程把一部分计算放到 PL 端用 HLS 生成 IP再在应用里调用。每一条路都建立在今天这套平台加域加应用的结构之上所以基础打牢了后面学什么都快。我个人在实际操作中的体会是Vitis 这个工具链的学习曲线主要卡在“工程结构理解”和“环境配置”这两块真正写代码反而不难。把 hello_world 这一遍走通把每个环节的依赖关系搞清楚后面遇到问题你就能快速定位是平台层、BSP 层还是应用层的问题而不是盲目地重装软件或者到处搜帖子。最后再分享一个小技巧养成看 Console 日志的习惯Vitis 的报错信息其实挺详细的很多时候答案就在日志里只是被忽略了。