Vitis SDK 建工程实战：GUI 与 TCL 命令创建 HelloWorld 应用

SEO 摘要本文详解 Vitis SDK 应用工程创建全流程对比 GUI 向导与 TCL 命令两种方式覆盖处理器选择、HelloWorld 模板配置、库文件添加、串口验证与常见报错排查附完整可复用脚本助你快速跑通第一个嵌入式 HelloWorld 工程。在嵌入式 SDK 开发中快速搭建一个可运行的工程往往是上手的第一步而不同开发者对图形化向导和命令行脚本各有偏好。本文分别演示如何通过 GUI 界面和 TCL 命令两种方式创建 SDK 应用工程并逐步说明处理器选择、模板工程与库文件配置等关键环节。读完本文你可以根据自己的开发习惯选择更高效的建工程方式并顺利跑通第一个 HelloWorld 应用。TL;DRGUI 方式适合新手按“选择工作空间 → Create Application Project → 选择处理器 → 选择 Hello World 模板 → 添加库文件”的顺序操作即可完成建工程。TCL 命令方式适合批量与自动化场景通过脚本一次性完成工程创建便于复用和版本管理。两种方式最终得到的工程结构一致区别只在操作入口建议先跑通 GUI 流程理解各步骤含义再切换到 TCL 命令提升效率。目录1. 使用 GUI 界面建立 SDK 应用工程2. 使用 TCL 命令建立 SDK 应用工程2.1 完整 TCL 脚本示例2.2 关键命令与参数说明2.3 验证工程是否创建成功2.4 使用注意事项2.4.1 常见报错与排查3. 总结参考资料1. 使用 GUI 界面建立 SDK 应用工程选择建立应用的工作空间图 1在 Workspace 输入框中填写或浏览选择工程存放目录点击 Launch 进入主界面。Create Application Project图 2在菜单栏点击 File → New → Application Project或直接点击工具栏的 New Application Project 按钮。选择处理器图 3在 Processor 下拉框中选择目标处理器实例如 ps7_cortexa9_0并确认 Target 与硬件平台一致。选择模板工程 Hello World图 4在 Templates 列表中勾选 Hello World并在 Project Name 输入框中填写工程名点击 Finish 完成创建。添加需要的各种类型的库文件。工程创建完成后通常还需要在 BSP 设置中按需勾选库文件。常见需要添加的库类型及选择依据如下基础输出库如 xil_printf用于串口打印调试信息几乎每个裸机工程都会用到建议默认添加。定时器库如 xiltimer工程中需要延时、定时中断或时间戳时添加依赖处理器私有定时器资源。通信与总线库如 xilmailbox、xilpm涉及多核通信、电源管理或核间消息传递时添加需与硬件设计中实际启用的 IP 对应。外设驱动库如 GPIO、UART、SPI、I2C 等按工程实际使用的外设勾选未使用的外设不必添加以免增大代码体积。第三方或中间件库如 lwIP、FatFS、xilffs需要网络、文件系统等上层功能时添加注意同时补齐其依赖的底层库。选择依据可以概括为先看工程功能需求再看硬件设计中实际例化的外设与 IP最后确认库之间的依赖关系只添加真正被调用的库。2. 使用 TCL 命令建立 SDK 应用工程与 GUI 向导逐步点击不同TCL 命令方式把建工程的每个步骤都写成脚本一次执行即可完成。下面给出一个完整的脚本示例覆盖创建工程、选择处理器、指定 Helloworld 模板和添加库文件四个关键环节并逐行注释说明参数含义。2.1 完整 TCL 脚本示例# --------------------------------------------------------------- # 使用 TCL 命令创建 SDK 应用工程以 Xilinx Vitis/SDK 为例 # 执行方式xsct create_app.tcl # --------------------------------------------------------------- # 1. 设置工作空间目录工程文件将生成在该路径下 setws ./workspace # 2. 创建平台工程若已有平台工程可跳过此步 # -name 平台工程名称 # -hw 硬件描述文件.xsa由 Vivado 导出 # -proc 处理器名称需与硬件设计中的实例名一致 platform create -name my_platform -hw ./design_1_wrapper.xsa -proc ps7_cortexa9_0 # 3. 基于平台工程生成 BSP板级支持包提供驱动与库 platform generate # 4. 创建应用工程 # -name 应用工程名称 # -platform 指定所依赖的平台工程 # -domain 指定使用的 BSP 域默认域为 standalone_domain app create -name hello_world -platform my_platform -domain standalone_domain # 5. 指定 Hello World 模板工程 # -template 模板名称Vitis 内置模板包括 Empty Application、Hello World 等 # -lang 源码语言可选 c 或 cpp app config -name hello_world -set template Hello World -set lang c # 6. 添加需要的库文件 # -add 追加库名可多次调用常见库如 xil_printf、xiltimer、xilmailbox app config -name hello_world -add libraries xil_printf app config -name hello_world -add libraries xiltimer # 7. 生成应用工程源码与编译配置 app build -name hello_world # 8. 输出工程创建结果便于脚本化校验 puts Application project hello_world created successfully.2.2 关键命令与参数说明命令作用关键参数setws指定工作空间目录路径参数支持相对路径与绝对路径platform create创建平台工程-name平台名-hw硬件描述文件-proc处理器实例名app create创建应用工程-name工程名-platform依赖平台-domainBSP 域app config配置模板与库-set template模板名-set lang语言-add libraries追加库app build编译应用工程-name目标工程名2.3 验证工程是否创建成功工程创建并编译完成后最直接的验证方式是通过串口终端查看 HelloWorld 的打印输出。将开发板的 UART 调试口连接到主机打开串口终端工具如 PuTTY、Tera Term、MobaXterm 或 minicom按下表配置串口参数后给开发板上电或复位即可观察启动与打印信息。参数典型取值说明波特率Baud Rate115200需与 BSP 中 UART 驱动的配置一致若打印乱码优先检查波特率是否匹配数据位Data Bits8标准 8 位数据位绝大多数裸机工程默认使用停止位Stop Bits11 位停止位与常见 UART 配置一致校验位ParityNone无校验若硬件设计启用了校验需同步修改为 Even 或 Odd流控Flow ControlNone一般关闭硬件流控避免因 RTS/CTS 未连接导致无法收发配置完成后在串口终端中应能看到类似下面的预期输出--- Entering main() --- Hello World Successfully ran Hello World application --- Exiting main() ---编译产物默认位于工作空间的工程目录下常见路径如下ELF 可执行文件./workspace/hello_world/Debug/hello_world.elf可直接用于下载与调试。编译中间文件./workspace/hello_world/Debug/目录下的.o、.d等文件用于增量编译。BSP 与库文件./workspace/my_platform/export/my_platform/sw/standalone_domain/包含驱动源码与编译生成的静态库。链接脚本与映射文件./workspace/hello_world/Debug/下的lscript.ld与hello_world.map可用于确认内存布局与符号地址。如果串口终端没有任何输出可以按以下顺序逐项排查确认串口号与连接检查 USB 转串口设备是否被主机识别串口终端中选择的 COM 口是否与设备管理器中一致。确认串口参数核对波特率、数据位、停止位、校验位是否与 BSP 配置一致波特率不匹配通常表现为乱码而非完全无输出。确认程序已下载运行检查是否已将hello_world.elf下载到板卡并执行或是否已通过 JTAG 启动调试会话。确认 UART 引脚与硬件设计核对硬件设计中 UART 控制器是否使能、引脚约束是否正确以及板卡上调试串口是否与设计对应。确认 BSP 中 UART 驱动检查 BSP 设置中是否启用了对应 UART 外设的驱动必要时重新生成 BSP 并重新编译。确认打印函数配置若使用xil_printf确认已添加xil_printf库若使用printf确认已配置stdout指向 UART。2.4 使用注意事项处理器名称必须匹配-proc的取值要与硬件设计中实际例化的处理器实例名完全一致否则平台工程创建会失败。模板名称区分大小写不同版本工具链的模板名称可能略有差异可通过app list -templates查看当前环境支持的模板列表。库文件按需添加只添加工程实际依赖的库避免引入不必要的代码体积若库之间存在依赖需一并添加。脚本可复用把工程名、处理器名等提取为变量即可在不同项目间复用同一份建工程脚本适合批量构建与持续集成场景。2.4.1 常见报错与排查TCL 脚本建工程时报错信息往往比较简短定位问题需要结合命令参数和工程目录一起看。下表整理了四类典型问题的报错现象、原因与解决方式。问题类型报错现象原因解决命令或修改方法处理器名称不匹配ERROR: [Common 17-55] set_property expects at least one object.或No processor named ps7_cortexa9_0 found in the hardware design-proc参数与硬件设计中实际例化的处理器实例名不一致例如写成了ps7_cortexa9_0而实际实例名为psu_cortexa53_0或大小写、下划线写法有差异先执行platform report -name my_platform或report_property [get_property PROCESSOR [get_hw_devices]]查看可用处理器名再用正确名称重建platform create -name my_platform -hw ./design_1_wrapper.xsa -proc psu_cortexa53_0模板名称不存在ERROR: Template Helloworld not found或app config failed: invalid template name模板名称拼写或大小写与工具链内置模板不一致例如写成Helloworld而实际模板名为Hello World不同版本工具链的模板集合也有差异先执行app list -templates查看当前环境支持的模板列表再按实际名称配置app config -name hello_world -set template Hello World -set lang c库文件缺失依赖undefined reference to xil_printf、cannot find -lxiltimer或编译阶段出现大量未定义符号只添加了上层库未添加其依赖的底层库或库名拼写错误、该库在当前 BSP 域中不可用按依赖顺序补齐库app config -name hello_world -add libraries xiltimer再app config -name hello_world -add libraries xil_printf可用app config -name hello_world -get libraries确认已添加的库用repo -apps查看可用库清单.xsa 路径错误ERROR: File ./design_1_wrapper.xsa does not exist或Failed to open hardware handoff file-hw指定的路径为相对路径而脚本执行目录与预期不一致或文件名、扩展名写错文件未从 Vivado 正确导出改用绝对路径或先切换目录cd [file dirname [info script]]再platform create -name my_platform -hw [file normalize ./design_1_wrapper.xsa] -proc psu_cortexa53_0执行前用file exists ./design_1_wrapper.xsa校验文件是否存在排查时建议按“先校验输入文件、再校验名称参数、最后校验库依赖”的顺序逐项确认并在脚本开头加上setws与路径校验能避免大部分因环境差异导致的报错。3. 总结GUI 方式的关键步骤选择工作空间 → Create Application Project → 选择处理器 → 选择 Helloworld 模板 → 添加库文件全程向导式点击适合新手快速理解建工程的每个环节。TCL 方式的关键步骤setws设置工作空间 →platform create创建平台工程 →platform generate生成 BSP →app create创建应用工程 →app config指定模板与库 →app build编译一条脚本即可完成全部流程。两种方式结果一致无论走 GUI 还是 TCL最终生成的平台工程、BSP 与应用工程结构相同区别只在操作入口因此可以先用 GUI 熟悉流程再用 TCL 复现。选型建议单次调试、学习阶段优先用 GUI直观且便于观察每一步需要批量创建、版本管理或持续集成时优先用 TCL脚本可参数化复用减少重复点击带来的误差。验证与排错工程创建后务必通过串口终端确认 HelloWorld 打印输出遇到报错时按“先校验输入文件、再校验名称参数、最后校验库依赖”的顺序定位可覆盖大部分常见问题。参考资料AMDXilinxVitis 统一软件平台文档首页Vitis Unified Software Platform Documentation (UG1416)platform create命令参考Vitis Embedded Software Development Command Reference — platform createapp create命令参考Vitis Embedded Software Development Command Reference — app createapp config命令参考Vitis Embedded Software Development Command Reference — app configXSCT 命令行工具与 TCL 脚本说明Vitis Embedded Software Development Command Reference — XSCT CommandsXilinx SDK历史版本命令与工程管理文档Xilinx Software Development Kit (SDK) Documentation (UG782)