Vivado 2020.2升级踩坑记：从XSA文件到FSBL生成的完整避坑指南
Vivado 2020.2升级实战：XSA迁移与FSBL生成全流程避坑手册
从Vivado 2018升级到2020.2版本的过程，就像在熟悉的城市里突然更换了所有路标——工具链重构、文件格式变更、开发环境整合，每一步都可能遇到意想不到的障碍。最近在将Zynq-7000系列项目的开发环境迁移到Vivado 2020.2时，我亲历了从XSA文件生成到FSBL编译的完整"踩坑"历程。本文将系统梳理这些"版本升级陷阱"的解决方案，特别针对XSA文件处理、Vitis环境适配和Makefile错误修正三大核心痛点，提供可复用的技术路线。
1. 开发环境迁移：从HDF到XSA的范式转换
Vivado 2020.2最显著的变化莫过于硬件描述文件从HDF(Hardware Description File)转变为XSA(Xilinx Support Archive)格式。这个看似简单的文件扩展名变更，背后是整个工具链工作流的重大调整。
1.1 Vitis环境初始化配置
在Vivado 2018时代，我们习惯通过"File > Export > Export Hardware"生成HDF文件，然后在独立启动的SDK中开发嵌入式应用。2020.2版本中，这个流程变为：
- 在Vivado中完成硬件设计后，选择File > Export > Export Hardware
- 在弹出的对话框中勾选Include bitstream选项
- 保存为XSA格式文件（建议选择版本2.0兼容模式）
注意：如果目标设备需要加密bitstream，务必在此步骤启用加密选项，否则后续生成FSBL时会遇到签名验证失败问题。
迁移到Vitis平台后，传统SDK入口的位置发生了根本性变化。正确的启动路径是：
# 在Vivado 2020.2中的调用方式 Tools > Launch Vitis IDE1.2 平台项目创建常见错误
导入XSA文件创建平台项目时，开发者常遇到两类典型问题：
| 错误类型 | 可能原因 | 解决方案 |
|---|---|---|
| XSA版本不兼容 | Vivado导出时选择了新版3.0格式 | 重新导出为2.0兼容格式 |
| 时钟配置丢失 | 硬件设计中存在未约束的时钟 | 检查Vivado中的时钟约束警告 |
| 外设地址冲突 | IP核地址范围重叠 | 在Block Design中验证地址分配 |
我曾遇到一个棘手案例：导入XSA后Vitis无法识别PS端配置。根本原因是硬件设计中AXI互联模块的时钟域配置与PS时钟不匹配。解决方法是在Vivado中重新验证时钟连接：
# 在Vivado Tcl控制台检查时钟连接 report_clock_interaction -name timing_12. FSBL生成过程中的"灰色Finish"问题
生成First Stage Bootloader(FSBL)是Zynq启动流程的关键环节，但版本升级后这个原本简单的操作却成了"重灾区"。
2.1 必备库文件缺失解决方案
当点击Finish按钮呈灰色且提示"xilffs library required"时，说明BSP配置不完整。这个问题源于Vitis 2020.2对文件系统驱动的依赖管理更加严格。正确的处理流程是：
返回Platform Configuration页面
在Board Support Package选项卡中添加以下必备库：
- xilffs (FAT文件系统支持)
- xilsecure (安全启动支持)
- xilpm (电源管理)
保存配置后必须执行以下操作序列：
# 清理旧配置 rm -rf ./zynq_fsbl_bsp/ # 重新生成BSP xsct -eval "platform generate -domains"2.2 外设驱动版本冲突处理
在配置FSBL项目时，另一个常见问题是外设驱动版本不匹配。特别是在使用自定义IP时，可能会出现类似如下的错误日志：
ERROR: [Hsi 55-1545] Problem running tcl command ::hsi::get_drivers: Driver version mismatch for axi_gpio_0这个问题需要通过修改平台项目的BSP设置来解决：
- 在Vitis项目浏览器中展开平台项目 > zynq_fsbl_bsp
- 右键选择Board Support Package Settings
- 在驱动版本选项中切换为Standalone OS兼容模式
3. Platform Out-of-Date与Makefile错误修正
当看到"Platform out-of-date"警告时，多数开发者会本能地点击"Update Platform"，但这往往不能解决根本问题。2020.2版本中，真正的症结通常隐藏在Makefile配置中。
3.1 关键Makefile定位与修改
需要检查的Makefile分布在三个关键位置：
Platform/hw/drivers/<CustomIP_name>/src/MakefilePlatform/ps7_cortex_a9_0/standalone_domain/bsp/ps7_cortex_a9_0/libsrc/<CustomIP_name>/src/MakefilePlatform/zynq_fsbl/zynq_fsbl_bsp/ps7_cortex_a9_0/libsrc/<CustomIP_name>/src/Makefile
这些文件需要统一修改编译参数，以下是标准模板：
DRIVER_LIB_VERSION = 1.0 COMPILER=arm-none-eabi-gcc ARCHIVER=arm-none-eabi-ar CP=cp COMPILER_FLAGS=-Wall -Wextra -O2 -c -fmessage-length=0 -MT"$@" -mcpu=cortex-a9 -mfpu=vfpv3 -mfloat-abi=hard EXTRA_COMPILER_FLAGS=-MMD -MP -MF"$(@:%.o=%.d)" LIB=libxil.a RELEASEDIR=../../../lib/ INCLUDEDIR=../../../include/ INCLUDES=-I./. -I$(INCLUDEDIR) SRCFILES:=$(wildcard *.c) OBJECTS = $(addprefix $(RELEASEDIR), $(addsuffix .o, $(basename $(wildcard *.c)))) libs: $(OBJECTS) DEPFILES := $(SRCFILES:%.c=$(RELEASEDIR)%.d) include $(wildcard $(DEPFILES)) include $(wildcard ../../../../dep.mk) $(RELEASEDIR)%.o: %.c ${COMPILER} $(CC_FLAGS) $(ECC_FLAGS) $(INCLUDES) $(DEPENDENCY_FLAGS) $< -o $@ .PHONY: include include: $(addprefix $(INCLUDEDIR),$(wildcard *.h)) $(INCLUDEDIR)%.h: %.h $(CP) $< $@ clean: rm -rf ${OBJECTS} rm -rf $(DEPFILES)3.2 编译缓存清理技巧
修改Makefile后，必须彻底清理编译缓存才能生效。推荐的操作流程：
- 在Vitis中选择Project > Clean...
- 勾选Clean all projects选项
- 手动删除工程目录下的
Debug和Release文件夹 - 执行重建命令：
# 在Vitis XSCT控制台中执行 exec platform active clean generate4. 固化流程优化与稳定性验证
完成FSBL生成后，最终的固化操作也需要适应新版本的变化。2020.2版本中Flash编程器的配置参数更加严格。
4.1 Boot Image生成配置要点
创建启动镜像时，需要特别注意分区配置：
在Create Boot Image向导中，确保分区顺序为：
- FSBL.elf
- 硬件bitstream文件
- 应用程序elf文件
对于QSPI Flash编程，必须添加正确的Flash偏移地址：
# 典型QSPI分区配置 flash erase 0x00000000 0x1000000 flash write_bank 0x00000000 boot.bin4.2 稳定性验证方法
为确保固化成功，建议在JTAG模式下先验证以下环节：
- 通过Vitis终端检查DDR初始化状态：
# 在XSDB中执行 targets -set -filter {name =~ "PS7"} dow fsbl.elf con监控UART输出中的关键阶段标记：
- "FSBL: Starting Bitstream Load"
- "FSBL: Bitstream Load Complete"
- "SSBL: Starting Application"
使用Flash验证命令确认写入完整性：
# 比较Flash内容与原始文件 flash verify_bank 0x00000000 boot.bin整个升级过程中最深刻的体会是：Vitis 2020.2对工程结构的规范性要求显著提高。保持工程目录清洁、及时清理临时文件、严格管理版本依赖，这些看似基础的习惯在新版本中变得尤为重要。当遇到看似诡异的错误时，不妨先执行一次完整的工程清理和重建，往往能解决一半以上的"灵异问题"。