1. 为什么2024.1这个版本值得单独写一篇入门Vitis 2024.1 是 AMD 统一软件平台的一个长期支持版本对做嵌入式、FPGA 加速、异构计算的工程师来说这个版本在安装器、组件管理、平台识别逻辑上都做了不小的调整。很多人在旧版本里养成的操作习惯到了 2024.1 会突然“失灵”——比如找不到 Workspace 的默认路径、新建工程时看不到自己导入的平台、串口终端连上却没有任何输出。这些问题的根源往往不是工具坏了而是版本迭代后流程变了。这篇内容面向三类人第一类是刚接触 Vitis、想跑通第一个 hello_world 的初学者第二类是从 Vivado SDK 或旧版 Vitis 迁移过来、被新界面绕晕的老手第三类是需要给团队写内部上手文档、想找一份可直接复现流程的工程师。我会把从环境确认、平台准备、工程创建、编译到串口验证的完整链路拆开讲重点放在“为什么这一步要这么做”以及“哪一步最容易翻车”。需要先明确一个概念Vitis 本身不负责生成硬件平台。它消费的是由 Vivado 导出的 XSA 文件这个文件里包含了处理器配置、外设地址、时钟等硬件信息。所以 hello_world 能不能跑起来一半取决于 Vitis 里的软件操作另一半取决于 XSA 是否导出正确。很多人卡在“编译通过但串口无输出”十有八九是 XSA 或串口配置的问题而不是代码问题。下面这张表先给出整个流程的骨架后面每个环节再展开。阶段核心动作常见失败点环境确认检查安装组件与许可证漏装嵌入式组件平台准备Vivado 导出 XSA未包含处理器或未使能串口工程创建新建平台工程与应用工程平台未识别、模板选错编译构建应用编译报错、链接脚本不匹配验证下载并查看串口波特率错、串口选错、无输出2. 安装环节里那些没人提醒你的组件勾选项2.1 安装器界面变化与组件选择逻辑Vitis 2024.1 的安装器和 Vivado 是合并在一起的统一安装器。启动后你会看到组件勾选列表这里有一个非常关键的判断如果你只做纯软件层面的开发理论上可以不装 Vivado但只要你需要自己导出 XSA就必须装 Vivado。而嵌入式开发必须勾选的是“Vitis Embedded Software Development”相关的组件以及对应器件家族的器件支持包。我见过最常见的错误是安装时只勾了 Vitis没勾器件支持。结果新建平台工程时器件列表是空的或者导入 XSA 后提示“platform not supported”。这不是软件 bug是器件包没装。器件包体积很大一个系列动辄几十 GB所以安装前一定要想清楚自己用的是哪个系列比如 Zynq-7000、Zynq UltraScale MPSoC、Versal 等按需勾选别全选否则硬盘会被吃光。另一个容易被忽略的是许可证。Vitis 的嵌入式开发部分通常是免费可用的但某些高级功能或特定器件可能需要额外的许可证。安装完成后建议先在帮助菜单里确认许可证状态避免做到一半才发现功能被锁。2.2 安装路径与磁盘空间的实战建议安装路径强烈建议不要带中文、不要带空格。这不是迷信是很多工具链脚本对路径解析的兼容性问题。我习惯用类似D:\Xilinx\2024.1这样的纯英文短路径。磁盘空间方面如果同时装 Vivado 和 Vitis 加器件包预留 200GB 以上比较稳妥SSD 优先因为编译和综合过程对磁盘 IO 很敏感。安装完成后第一次启动 Vitis 会要求选择 Workspace。这个 Workspace 是存放工程元数据和临时文件的目录同样建议纯英文路径并且不要放在安装目录里面。我一般单独建一个D:\vitis_ws之类的目录方便备份和清理。提示安装完成后不要急着新建工程先打开一次 Vitis确认能正常进入主界面再关闭。这一步能提前暴露许可证或环境变量的问题。3. 平台工程XSA 导出与平台识别的完整链路3.1 Vivado 侧导出 XSA 时必须检查的三件事XSA 是 Vitis 和 Vivado 之间的契约文件。导出前在 Vivado 里必须确认三件事。第一Block Design 里确实例化了处理器比如 Zynq Processing System 或 MicroBlaze并且处理器配置正确。第二串口外设已经使能并且引脚约束正确。第三Block Design 已经生成输出产物并且顶层 HDL 已经包装好。导出 XSA 的入口在 File 菜单下的 Export 里选择“Export Hardware”。注意要勾选“Include bitstream”否则后续下载时没有比特流可用。对于 Zynq 这类需要 PS 配置的器件XSA 里会包含 PS 的初始化信息这些信息决定了串口能不能工作。我踩过的一个坑是在 Vivado 里改了串口波特率或引脚但没有重新导出 XSA结果 Vitis 里用的还是旧平台串口自然没输出。所以每次硬件有改动都要重新导出 XSA并在 Vitis 里更新平台工程。3.2 在 Vitis 里创建平台工程的正确姿势Vitis 2024.1 里平台工程和应用工程是分开的。先创建平台工程File - New - Platform Project。给它起个名字比如hello_platform。然后在平台配置里选择“Create from hardware specification (XSA)”指向刚才导出的 XSA 文件。导入后Vitis 会解析 XSA 并列出可用的处理器。这里要选对处理器比如ps7_cortexa9_0或psu_cortexa53_0。选错处理器会导致后续应用工程无法正确链接。平台工程创建完成后右键选择“Build”这一步会生成平台相关的 BSP 和硬件描述。只有平台构建成功应用工程才能引用它。一个常见问题是平台构建时报错提示找不到某些文件。这通常是因为 XSA 导出不完整或者 Vivado 版本和 Vitis 版本不一致。强烈建议 Vivado 和 Vitis 使用同一版本号跨版本兼容性虽然有时能用但出问题时排查成本很高。平台构建状态可能原因处理方式成功XSA 完整、版本一致继续创建应用工程失败找不到处理器XSA 未包含处理器回 Vivado 检查 Block Design失败器件不支持器件包未安装补装对应器件系列失败版本不匹配Vivado/Vitis 版本不同统一版本后重新导出4. 应用工程从模板到可执行文件的每一步4.1 新建应用工程与模板选择平台构建成功后File - New - Application Project。第一步选择目标平台这里会列出你刚创建的平台工程。选中后Vitis 会自动带出处理器信息。第二步是选择模板对于 hello_world直接选“Hello World”模板即可。这个模板会自动生成一个helloworld.c里面调用printf输出字符串。这里有一个细节模板生成的代码里通常包含#include stdio.h和#include platform.h。platform.h是 BSP 提供的头文件负责初始化缓存、中断等底层设置。如果你手动删掉init_platform()调用程序可能仍然能跑但在某些平台上会出现不可预期的问题。所以建议保留模板的初始化结构只改输出内容。工程创建后Vitis 会自动生成 BSP 工程。BSP 里包含了标准库、驱动和链接脚本。链接脚本决定了代码和数据放在哪块内存比如 DDR 还是片上 RAM。对于 hello_world默认链接脚本通常没问题但如果你用的是自定义板卡内存映射不同就需要手动调整链接脚本否则程序可能加载到无效地址。4.2 编译过程中的报错与排查思路编译应用工程时最常见的报错是“undefined reference to printf”或类似的标准库缺失。这通常是因为 BSP 里没有使能标准 IO 库。在 BSP 设置里找到standalone或xiltimer相关配置确认stdin和stdout已经指向正确的串口外设。如果 BSP 里串口没配置printf就没有输出通道。另一个常见报错是链接时提示内存区域溢出。这说明链接脚本分配的内存不够或者代码体积超出了预期。对于 hello_world 这种小工程很少见但如果你加了大量库或调试信息就可能触发。解决办法是调整链接脚本把代码段放到更大的内存区域或者优化编译选项减小体积。编译成功后会在Debug或Release目录下生成.elf文件。这个文件就是最终要下载到板子上的可执行文件。注意Vitis 2024.1 里编译配置默认可能是 DebugDebug 版本包含调试信息体积较大但方便调试Release 版本经过优化体积小但不利于单步调试。跑 hello_world 用哪个都行但建议先用 Debug 确认流程。5. 下载与串口验证为什么你的终端一片空白5.1 下载配置与比特流加载顺序下载环节需要把两个东西送到板子上比特流和 ELF。比特流配置 FPGA 的硬件逻辑ELF 是处理器要执行的程序。在 Vitis 里右键应用工程选择“Run Configurations”新建一个配置。在配置里确认比特流文件路径正确ELF 路径正确然后点击 Run。顺序很重要先加载比特流再加载 ELF。如果只加载 ELF 不加载比特流处理器可能因为硬件逻辑未配置而无法正常运行。Vitis 的 Run 配置通常会自动处理这个顺序但如果你手动用其他工具下载就要注意这个先后关系。下载过程中如果提示“cannot detect cable”或“no target connected”先检查 JTAG 线连接、驱动是否安装、板子是否上电。这些是硬件层面的问题和软件无关。确认硬件正常后再检查 Vitis 里的下载器设置是否选对了 JTAG 频率和目标器件。5.2 串口终端的参数设置与常见误区串口没输出是新手遇到最多的问题。排查顺序应该是先确认板子上的串口物理连接正确TX/RX 没有接反再确认串口终端软件里选的 COM 口是对的然后确认波特率。Zynq 默认波特率通常是 115200但有些设计会改成 9600 或其他值。波特率不对输出就是乱码或空白。数据位、停止位、校验位通常用 8-N-1即 8 数据位、无校验、1 停止位。流控一般关闭。这些参数在 Vivado 的 PS 配置里可以查到Vitis 的 BSP 里也会体现。如果终端软件里设的和 BSP 里不一致就会出问题。还有一个隐蔽的坑有些板子有两个串口一个用于 PS 输出一个用于其他用途。如果你连的是错误的串口自然看不到 hello_world 的输出。确认方法是在 Vivado 的 PS 配置里看哪个 UART 被使能以及对应的引脚。现象可能原因排查动作终端完全空白串口选错、波特率错、程序未运行换串口、改波特率、重新下载输出乱码波特率不匹配核对 BSP 与终端波特率输出部分后卡住程序崩溃或死循环检查代码逻辑、加调试输出下载时报错JTAG 连接或驱动问题检查线缆、驱动、上电状态6. 从 hello_world 延伸到实际项目的几个经验点跑通 hello_world 只是起点。实际项目里你很快会遇到多核启动、中断处理、DMA 传输、自定义 IP 驱动等问题。这些问题的排查思路和 hello_world 有共通之处先确认硬件平台正确再确认软件配置匹配最后才是代码逻辑。一个很实用的习惯是每次硬件改动后重新导出 XSA重新构建平台再重新编译应用。不要试图在旧平台上打补丁那样会积累很多隐性问题。另一个习惯是保留一个最小可用的 hello_world 工程作为“金标准”当新工程出问题时用这个金标准验证板子和工具链是否正常能快速定位是环境问题还是工程问题。还有一点关于版本管理Vitis 工程里有很多自动生成的文件不建议全部纳入版本控制。通常只保留源文件、XSA、链接脚本和配置文件生成物可以重新构建。这样能避免不同机器上路径不一致导致的冲突。最后分享一个我常用的调试技巧如果串口输出不稳定可以在printf后面加fflush(stdout)强制刷新输出缓冲区。有些平台的串口驱动是带缓冲的不加刷新可能导致输出延迟或丢失。这个细节在官方文档里不一定显眼但实际调试时很有用。
Vitis 2024.1 嵌入式开发入门：从环境搭建到串口验证全流程
1. 为什么2024.1这个版本值得单独写一篇入门Vitis 2024.1 是 AMD 统一软件平台的一个长期支持版本对做嵌入式、FPGA 加速、异构计算的工程师来说这个版本在安装器、组件管理、平台识别逻辑上都做了不小的调整。很多人在旧版本里养成的操作习惯到了 2024.1 会突然“失灵”——比如找不到 Workspace 的默认路径、新建工程时看不到自己导入的平台、串口终端连上却没有任何输出。这些问题的根源往往不是工具坏了而是版本迭代后流程变了。这篇内容面向三类人第一类是刚接触 Vitis、想跑通第一个 hello_world 的初学者第二类是从 Vivado SDK 或旧版 Vitis 迁移过来、被新界面绕晕的老手第三类是需要给团队写内部上手文档、想找一份可直接复现流程的工程师。我会把从环境确认、平台准备、工程创建、编译到串口验证的完整链路拆开讲重点放在“为什么这一步要这么做”以及“哪一步最容易翻车”。需要先明确一个概念Vitis 本身不负责生成硬件平台。它消费的是由 Vivado 导出的 XSA 文件这个文件里包含了处理器配置、外设地址、时钟等硬件信息。所以 hello_world 能不能跑起来一半取决于 Vitis 里的软件操作另一半取决于 XSA 是否导出正确。很多人卡在“编译通过但串口无输出”十有八九是 XSA 或串口配置的问题而不是代码问题。下面这张表先给出整个流程的骨架后面每个环节再展开。阶段核心动作常见失败点环境确认检查安装组件与许可证漏装嵌入式组件平台准备Vivado 导出 XSA未包含处理器或未使能串口工程创建新建平台工程与应用工程平台未识别、模板选错编译构建应用编译报错、链接脚本不匹配验证下载并查看串口波特率错、串口选错、无输出2. 安装环节里那些没人提醒你的组件勾选项2.1 安装器界面变化与组件选择逻辑Vitis 2024.1 的安装器和 Vivado 是合并在一起的统一安装器。启动后你会看到组件勾选列表这里有一个非常关键的判断如果你只做纯软件层面的开发理论上可以不装 Vivado但只要你需要自己导出 XSA就必须装 Vivado。而嵌入式开发必须勾选的是“Vitis Embedded Software Development”相关的组件以及对应器件家族的器件支持包。我见过最常见的错误是安装时只勾了 Vitis没勾器件支持。结果新建平台工程时器件列表是空的或者导入 XSA 后提示“platform not supported”。这不是软件 bug是器件包没装。器件包体积很大一个系列动辄几十 GB所以安装前一定要想清楚自己用的是哪个系列比如 Zynq-7000、Zynq UltraScale MPSoC、Versal 等按需勾选别全选否则硬盘会被吃光。另一个容易被忽略的是许可证。Vitis 的嵌入式开发部分通常是免费可用的但某些高级功能或特定器件可能需要额外的许可证。安装完成后建议先在帮助菜单里确认许可证状态避免做到一半才发现功能被锁。2.2 安装路径与磁盘空间的实战建议安装路径强烈建议不要带中文、不要带空格。这不是迷信是很多工具链脚本对路径解析的兼容性问题。我习惯用类似D:\Xilinx\2024.1这样的纯英文短路径。磁盘空间方面如果同时装 Vivado 和 Vitis 加器件包预留 200GB 以上比较稳妥SSD 优先因为编译和综合过程对磁盘 IO 很敏感。安装完成后第一次启动 Vitis 会要求选择 Workspace。这个 Workspace 是存放工程元数据和临时文件的目录同样建议纯英文路径并且不要放在安装目录里面。我一般单独建一个D:\vitis_ws之类的目录方便备份和清理。提示安装完成后不要急着新建工程先打开一次 Vitis确认能正常进入主界面再关闭。这一步能提前暴露许可证或环境变量的问题。3. 平台工程XSA 导出与平台识别的完整链路3.1 Vivado 侧导出 XSA 时必须检查的三件事XSA 是 Vitis 和 Vivado 之间的契约文件。导出前在 Vivado 里必须确认三件事。第一Block Design 里确实例化了处理器比如 Zynq Processing System 或 MicroBlaze并且处理器配置正确。第二串口外设已经使能并且引脚约束正确。第三Block Design 已经生成输出产物并且顶层 HDL 已经包装好。导出 XSA 的入口在 File 菜单下的 Export 里选择“Export Hardware”。注意要勾选“Include bitstream”否则后续下载时没有比特流可用。对于 Zynq 这类需要 PS 配置的器件XSA 里会包含 PS 的初始化信息这些信息决定了串口能不能工作。我踩过的一个坑是在 Vivado 里改了串口波特率或引脚但没有重新导出 XSA结果 Vitis 里用的还是旧平台串口自然没输出。所以每次硬件有改动都要重新导出 XSA并在 Vitis 里更新平台工程。3.2 在 Vitis 里创建平台工程的正确姿势Vitis 2024.1 里平台工程和应用工程是分开的。先创建平台工程File - New - Platform Project。给它起个名字比如hello_platform。然后在平台配置里选择“Create from hardware specification (XSA)”指向刚才导出的 XSA 文件。导入后Vitis 会解析 XSA 并列出可用的处理器。这里要选对处理器比如ps7_cortexa9_0或psu_cortexa53_0。选错处理器会导致后续应用工程无法正确链接。平台工程创建完成后右键选择“Build”这一步会生成平台相关的 BSP 和硬件描述。只有平台构建成功应用工程才能引用它。一个常见问题是平台构建时报错提示找不到某些文件。这通常是因为 XSA 导出不完整或者 Vivado 版本和 Vitis 版本不一致。强烈建议 Vivado 和 Vitis 使用同一版本号跨版本兼容性虽然有时能用但出问题时排查成本很高。平台构建状态可能原因处理方式成功XSA 完整、版本一致继续创建应用工程失败找不到处理器XSA 未包含处理器回 Vivado 检查 Block Design失败器件不支持器件包未安装补装对应器件系列失败版本不匹配Vivado/Vitis 版本不同统一版本后重新导出4. 应用工程从模板到可执行文件的每一步4.1 新建应用工程与模板选择平台构建成功后File - New - Application Project。第一步选择目标平台这里会列出你刚创建的平台工程。选中后Vitis 会自动带出处理器信息。第二步是选择模板对于 hello_world直接选“Hello World”模板即可。这个模板会自动生成一个helloworld.c里面调用printf输出字符串。这里有一个细节模板生成的代码里通常包含#include stdio.h和#include platform.h。platform.h是 BSP 提供的头文件负责初始化缓存、中断等底层设置。如果你手动删掉init_platform()调用程序可能仍然能跑但在某些平台上会出现不可预期的问题。所以建议保留模板的初始化结构只改输出内容。工程创建后Vitis 会自动生成 BSP 工程。BSP 里包含了标准库、驱动和链接脚本。链接脚本决定了代码和数据放在哪块内存比如 DDR 还是片上 RAM。对于 hello_world默认链接脚本通常没问题但如果你用的是自定义板卡内存映射不同就需要手动调整链接脚本否则程序可能加载到无效地址。4.2 编译过程中的报错与排查思路编译应用工程时最常见的报错是“undefined reference to printf”或类似的标准库缺失。这通常是因为 BSP 里没有使能标准 IO 库。在 BSP 设置里找到standalone或xiltimer相关配置确认stdin和stdout已经指向正确的串口外设。如果 BSP 里串口没配置printf就没有输出通道。另一个常见报错是链接时提示内存区域溢出。这说明链接脚本分配的内存不够或者代码体积超出了预期。对于 hello_world 这种小工程很少见但如果你加了大量库或调试信息就可能触发。解决办法是调整链接脚本把代码段放到更大的内存区域或者优化编译选项减小体积。编译成功后会在Debug或Release目录下生成.elf文件。这个文件就是最终要下载到板子上的可执行文件。注意Vitis 2024.1 里编译配置默认可能是 DebugDebug 版本包含调试信息体积较大但方便调试Release 版本经过优化体积小但不利于单步调试。跑 hello_world 用哪个都行但建议先用 Debug 确认流程。5. 下载与串口验证为什么你的终端一片空白5.1 下载配置与比特流加载顺序下载环节需要把两个东西送到板子上比特流和 ELF。比特流配置 FPGA 的硬件逻辑ELF 是处理器要执行的程序。在 Vitis 里右键应用工程选择“Run Configurations”新建一个配置。在配置里确认比特流文件路径正确ELF 路径正确然后点击 Run。顺序很重要先加载比特流再加载 ELF。如果只加载 ELF 不加载比特流处理器可能因为硬件逻辑未配置而无法正常运行。Vitis 的 Run 配置通常会自动处理这个顺序但如果你手动用其他工具下载就要注意这个先后关系。下载过程中如果提示“cannot detect cable”或“no target connected”先检查 JTAG 线连接、驱动是否安装、板子是否上电。这些是硬件层面的问题和软件无关。确认硬件正常后再检查 Vitis 里的下载器设置是否选对了 JTAG 频率和目标器件。5.2 串口终端的参数设置与常见误区串口没输出是新手遇到最多的问题。排查顺序应该是先确认板子上的串口物理连接正确TX/RX 没有接反再确认串口终端软件里选的 COM 口是对的然后确认波特率。Zynq 默认波特率通常是 115200但有些设计会改成 9600 或其他值。波特率不对输出就是乱码或空白。数据位、停止位、校验位通常用 8-N-1即 8 数据位、无校验、1 停止位。流控一般关闭。这些参数在 Vivado 的 PS 配置里可以查到Vitis 的 BSP 里也会体现。如果终端软件里设的和 BSP 里不一致就会出问题。还有一个隐蔽的坑有些板子有两个串口一个用于 PS 输出一个用于其他用途。如果你连的是错误的串口自然看不到 hello_world 的输出。确认方法是在 Vivado 的 PS 配置里看哪个 UART 被使能以及对应的引脚。现象可能原因排查动作终端完全空白串口选错、波特率错、程序未运行换串口、改波特率、重新下载输出乱码波特率不匹配核对 BSP 与终端波特率输出部分后卡住程序崩溃或死循环检查代码逻辑、加调试输出下载时报错JTAG 连接或驱动问题检查线缆、驱动、上电状态6. 从 hello_world 延伸到实际项目的几个经验点跑通 hello_world 只是起点。实际项目里你很快会遇到多核启动、中断处理、DMA 传输、自定义 IP 驱动等问题。这些问题的排查思路和 hello_world 有共通之处先确认硬件平台正确再确认软件配置匹配最后才是代码逻辑。一个很实用的习惯是每次硬件改动后重新导出 XSA重新构建平台再重新编译应用。不要试图在旧平台上打补丁那样会积累很多隐性问题。另一个习惯是保留一个最小可用的 hello_world 工程作为“金标准”当新工程出问题时用这个金标准验证板子和工具链是否正常能快速定位是环境问题还是工程问题。还有一点关于版本管理Vitis 工程里有很多自动生成的文件不建议全部纳入版本控制。通常只保留源文件、XSA、链接脚本和配置文件生成物可以重新构建。这样能避免不同机器上路径不一致导致的冲突。最后分享一个我常用的调试技巧如果串口输出不稳定可以在printf后面加fflush(stdout)强制刷新输出缓冲区。有些平台的串口驱动是带缓冲的不加刷新可能导致输出延迟或丢失。这个细节在官方文档里不一定显眼但实际调试时很有用。
