做AD9361相关的板子也有些年了，这次要在Vivado里用ADI官方TCL脚本从头生成AD9361的HDL工程，本来以为就是跑个脚本的事，结果版本、路径、IP核升级这些坑一个个冒出来。折腾完回头一看，整个流程其实非常有规律，只要把原理搞明白，后面的操作就很顺。这篇文章就把我实际走过的路完整梳理一遍，重点讲清楚TCL脚本生成工程的原理、具体步骤和排错方法，给正在被这个流程折磨的朋友一个能直接照着做的参考。
1. 动手之前，先把AD9361 HDL工程的底摸清
1.1 AD9361 HDL工程到底是什么
AD9361是ADI公司一颗非常经典的射频收发器，工作频率范围能做到70 MHz到6 GHz，带宽从200 kHz到56 MHz可调，内部集成了12位ADC/DAC、可配置的滤波器、自动增益控制等模块。但注意，AD9361本身只是一颗模拟前端加数据转换器，它不包含任何数字基带处理逻辑。想让FPGA和它配合工作，你得自己负责所有数字接口逻辑：收发数据采样、SPI配置、时钟使能、DMA搬运等等。
ADI官方为了降低门槛，在GitHub上维护了一套开源HDL参考设计，也就是我们常说的ADI HDL仓库。这套设计里已经写好了与AD9361对接的AXI接口IP核，比如axi_ad9361、util_pack、axi_dmac这些模块，还针对自家评估板做好了板级约束、Block Design和完整的构建脚本。所谓的“用TCL脚本生成HDL工程”，核心就是把这套参考设计在Vivado里实例化出来，生成一个可以直接综合、实现、导出比特流的Vivado工程。
很多人第一次接触时会犯一个认知上的错误：以为用TCL脚本生成就只是自动创建一个空工程。其实不是，它会帮你把整个FPGA工程搭好，包括Zynq处理器系统、AXI互联、DMA控制器、AD9361接口IP、引脚约束、时序约束，以及顶层仿真文件。生成完的工程打开就能看到完整的Block Design，直接可以跑综合。
1.2 为什么用TCL脚本而不是手点GUI
这个问题我一开始也不理解，Vivado GUI里明明可以手动创建工程、添加IP、连线，为什么非要用脚本？后来在实际维护项目时才发现，手动建工程方式有致命短板。
手动方式最大的问题是不可重复。假如今天你在GUI里点击了二十个选项才配好一个IP，到了明天想在新版本工程里复现，就得重新点一遍，过程里稍不留神就会漏一个选项，而且你很难向同事解释这个工程到底是怎么搭出来的。TCL脚本则是把整个流程固化成了文本，入库、评审、追溯都非常方便。说白了，脚本就是工程设计的“源代码”，Vivado工程本身反而是“编译产物”。
还有一个非常实际的好处：批量修改。比如你手上有三块不同的载板，主芯片相同但接口引脚不同，脚本只需要改一两处板级参数，然后循环执行就能生成三个工程。手动方式下，改完一个再克隆另一个，操作繁琐且容易出错。TCL脚本配合Makefile还能做到一键全流程，从工程生成、综合、实现到导出XSA，全自动跑完。
1.3 版本匹配是绕不开的第一个坑
当我准备跑ADI的TCL脚本时，遇到的第一个问题不是脚本本身报错，而是版本对不上。ADI HDL仓库对Vivado版本非常敏感，不同时间点的仓库分支对应不同版本的Vivado。官方在仓库里维护了类似hdl_2019_r1、hdl_2020_r2、hdl_2021_r1这样的发布分支，每个分支对应一个主流的Vivado版本。
如果你用最新的master分支去配老版本的Vivado，大概率会在IP生成或者综合阶段报出一堆看不懂的错误，因为仓库里的IP版本和工具链内置的IP版本对不上。反过来，你用了很老的发布分支，却拿最新的Vivado去打开，同样会碰到IP升级、约束弃用、命令变更这些兼容性问题。
我个人的建议是严格按照ADI官方Wiki里给出的版本对应表来选择仓库分支。比如用Vivado 2019.1，就用hdl_2019_r1分支；用Vivado 2021.1，就用hdl_2021_r1分支。同一分支内部的代码和工具链是经过验证的，踩坑概率最小。强行用新版本Vivado配老分支不是不行，但你要做好后续手动修改一堆TCL脚本和IP配置的打算，新手不建议这么做。
2. 环境准备：工具链、仓库和子模块
2.1 必备的软件清单
在开始跑TCL脚本之前，先把环境准备好。按我这次的实践，至少需要以下几样东西。
第一是Vivado本身。AD9361参考设计大部分是基于Zynq-7000或者7系列FPGA，用Vivado Standard版就够了，不需要Vivado HLx Enterprise。安装时建议把安装路径放到纯英文目录下，避免后面脚本路径出问题。
第二是Git。这个必须装，而且要装好。ADI HDL仓库通过Git管理，里面还有大量子模块，没有Git你连完整代码都拿不到。Windows环境下推荐Git for Windows，安装时选上“Git Bash”组件，后面有些操作在Git Bash里执行比在CMD里顺手。
第三是Python，虽然不是跑TCL脚本的直接依赖，但ADI仓库里一些辅助工具、驱动脚本会用到Python。装一个Python 3.8以上的版本放着不会错，记得勾选“Add Python to PATH”。
第四是文本编辑器，推荐Visual Studio Code。因为你需要经常看TCL脚本和Makefile，用VSCode打开仓库目录，检索定义、全局搜索都很方便，遇到编码问题也比记事本可控。
提示：TCL脚本对路径中的中文和空格很敏感。如果你之前习惯把工程放在“D:\我的工程\”这类路径下，这次最好改成“D:\hdl”这样的纯英文短路径，能省掉很多怪问题。
2.2 克隆HDL仓库并拉取子模块
ADI HDL仓库的完整地址是https://github.com/analogdevicesinc/hdl。克隆的时候最推荐带--recursive参数，这样会同时拉取子模块。
git clone --recursive https://github.com/analogdevicesinc/hdl.git如果你已经克隆了但忘了带--recursive，别慌，进到仓库目录里执行下面这条就能补拉：
git submodule update --init --recursive这个仓库体积不小，子模块也很多，第一次拉取可能需要一段时间。拉完之后建议检查一下子模块是否都完整，最简单的办法是看library目录下有没有对应模块的实际文件。如果某个子模块目录是空的，后续脚本在source IP定义时就会报文件找不到。
还有一个必须要执行的步骤是切换分支。如果不确定要用哪个分支，先看一下当前在哪个分支上：
git branch -a然后切换到和Vivado版本匹配的分支。例如：
git checkout hdl_2019_r1 git submodule update --recursive注意，切换分支之后必须再执行一次子模块更新，因为不同分支的子模块版本也不一样。这个顺序不能反，否则代码和子模块版本可能会出现错位。
2.3 第一次认识工程目录与关键脚本
拿到仓库后，先别急着跑，花几分钟把目录结构认一遍。这样后续遇到错误时，你至少知道去哪里找原因。
仓库根目录下有library、projects、scripts等关键目录。library目录放的是所有可复用的IP核源文件和脚本，比如axi_ad9361、axi_dmac这些都在里面。projects目录则按板卡名组织，每个工程一个子目录。一个典型的AD9361参考设计工程在projects/fmcomms2下，里面会有Makefile、system_project.tcl、system_top.v这样的文件。
system_project.tcl是生成工程的主要入口。它做的事情可以大致概括为：导入公共脚本、创建Vivado工程、设置FPGA型号、添加源文件、生成Block Design、添加约束。Makefile则是外围封装，它调用Vivado批处理模式去执行TCL脚本，好处是可以用make一条命令完成整个构建流程。
记住一点：system_project.tcl里的路径都是相对于脚本所在目录的。这意味着你必须先cd到对应的工程目录，再执行脚本，千万不能从别的目录直接来个绝对路径调用，否则脚本内部引用的相对路径就会全部失效。
2.4 License和Vivado安装的常见前置条件
如果之前没装过Vivado，这里也提醒一下。License文件如果还没有，先去Xilinx官网申请一个免费的Standard版License，或者用本地License文件。批处理模式下License不对，经常会报“No license available for IP”之类的问题，而且这个报错往往在跑到一半才出现，尤其消耗耐心。
Vivado安装时组件可以只选需要的，比如“Synthesis”、“Implementation”、“Vivado High-Level Synthesis”这些核心工具，以及目标器件对应的支持包。AD9361参考设计大多用到Zynq-7000系列，对应的器件支持包一定记得勾上。如果没装器件包，TCL脚本在设置part型号时就会报错，根本走不到生成工程那一步。
另外还有一个容易被忽略的问题：如果你安装Vivado时使用了非默认安装路径，命令行下可能找不到vivado这个命令。最简单的解决方式是打开Vivado自带的“Vivado Tcl Shell”，在里面执行脚本，因为环境变量已经自动配置好了。或者也可以手动把Vivado的bin目录加到PATH里。
3. 用TCL脚本生成HDL工程的完整过程
3.1 选择正确的工程目标
AD9361对应的参考设计工程不止一个。常见的有fmcomms2、fmcomms4、fmcomms5，还有针对ADRV9361系列板卡的工程目录。每个工程的硬件设计不同，比如FMCOMMS2评估板使用AD9361单芯片，FMCOMMS4是AD9364，FMCOMMS5是双AD9361。你手里是哪块板子，就进哪个目录。
选目录时一定要核对载板型号。我有一次用错了工程，把FMCOMMS4的工程跑在FMCOMMS2的载板上，直到烧进去跑数据才发现接口定义不一样。这种错误在FPGA上最坑，因为综合能通过、能出比特流，表面上看一切正常，实际跑起来数据全是乱的。
选定目录后，建议先读一遍该目录下的README.md或Makefile，里面通常会写明支持的板卡型号、Vivado版本、以及构建命令。ADI这些工程文档写得很全，按照文档来比你猜命令要快得多。
3.2 命令行批处理模式执行TCL
在工程目录下执行构建。以fmcomms2工程为例，最直接的方式是运行make：
cd projects/fmcomms2 make如果你没有装make工具，或者你想看得清楚一点，也可以直接调用Vivado批处理模式：
vivado -mode batch -source system_project.tcl这条命令的意思是让Vivado在无图形界面的批处理模式下执行system_project.tcl脚本。批处理模式比GUI模式稳定，因为它不会弹出一堆窗口打断脚本，出问题时日志也更干净。日志会输出到终端，同时Vivado也会把运行信息写到vivado.log文件里，排错时重点看这个文件。
脚本执行时间取决于电脑性能和工程复杂度。我的机器上跑一个fmcomms2工程，从创建到完成大概需要十到二十分钟。如果你看到终端长时间没有输出，先别急着杀进程，有可能是在综合或者生成IP。可以通过任务管理器看Vivado的CPU占用，如果还在跳动，就说明还在跑。
注意：批处理模式下，如果脚本里没有显式调用
exit命令，Vivado跑完后会自动退出。有时候你想在脚本跑完后保留Vivado窗口检查内存状态，可以用vivado -mode tcl进入交互模式再source脚本，而不是用batch模式。
3.3 工程生成时到底发生了什么
很多人在跑脚本时只知道等，不知道每一步在干什么。其实TCL脚本生成工程的流程非常清晰，搞懂它，你以后自定义工程就有方向了。
脚本第一步是导入公共函数，比如adi_project.tcl、adi_board.tcl这些文件。这些公共脚本封装了创建工程、添加IP、创建Block Design的通用操作。第二步是根据板卡类型设置工程属性，包括FPGA型号、目标语言、默认约束文件等。第三步是创建Vivado工程并添加源文件，顶层HDL、IP核文件、约束文件都在这一步加入。第四步是在创建的Block Design中例化处理器系统、AD9361接口IP、DMA等模块，并建立连接。第五步是生成约束文件并运行综合布线。
有一个值得注意的点：脚本里生成的Block Design，里面的关键参数是从顶层TCL变量和板级配置文件中读取的。比如DMA的突发长度、接收FIFO深度、数据接口是LVDS还是CMOS模式，这些参数都能在脚本里看到对应的set_property或adi_project_params之类的调用。修改这些参数后重新生成工程，就会得到不同资源配置的版本。
生成成功后，工作目录下会出现很多新文件。最关键的是fmcomms2.xpr，这就是Vivado工程文件，可以用Vivado GUI直接打开。另外还会生成fmcomms2.srcs、fmcomms2.ip_user_files、fmcomms2.runs等目录，分别存放源文件、IP用户文件和运行结果。如果脚本执行到一半失败，工程目录可能没创建完整，这时重新跑脚本前最好把残留的工程文件删除干净，否则可能因为状态不一致而报一些莫名其妙的错误。
3.4 从生成到综合实现：验证工程能否跑通
TCL脚本生成工程不等于万事大吉，至少还要跑一次综合和实现，才能确认整个工程真的能用来烧板。打开生成的工程后，最简单的验证方式是在GUI里依次点击“Generate Bitstream”，或者继续用批处理命令：
vivado -mode batch -source scripts/run_bitstream.tcl如果你用的是make流程，ADI的Makefile里一般已经包含从生成工程到出比特流的完整目标，执行make之后如果没报错，会在fmcomms2.runs/impl_1/下生成比特流文件。
我第一次跑完综合后看到一堆时序警告，心里直打鼓，后来发现这些警告大多来自AD9361的接口时序约束和默认的I/O延迟设置，在参考设计里属于正常现象。只要没有红色的时序失败（Timing Failed）条目，基本可以认为工程状态正常。
跑完综合后推荐做一件事：打开Block Design，用“Validate Design”功能检查一下连接是否正确。虽然TCL脚本已经自动连接了模块，但某些手动修改过的工程可能存在未连接端口，Validate会直接报错。这个检查做一遍，能避免后面导出硬件平台时出问题。
3.5 修改AD9361配置参数再重新生成
TCL脚本最大的优势就在于参数化。比如说，你想把AD9361与FPGA之间的数据接口从CMOS模式改成LVDS模式，或者调整某些DMA缓冲深度，这些都可以通过修改工程级的TCL参数实现。
具体怎么改，每个工程稍有差异，你需要先找到工程目录下定义这些变量的地方。通常在system_project.tcl或公共板级文件里会有一堆set ADC_DMA_ADDR_WIDTH、set DAC_DMA_ADDR_WIDTH、set FPGA_DATA_WIDTH之类的变量。你可以搜关键词ad9361，看它附近有哪些参数。修改后重新执行构建脚本，对比新生成的Block Design，就会发现对应IP的配置已经发生变化。
不过这里有个大原则：不是所有参数都能随便改。AD9361接口模式由芯片的SPI配置和FPGA侧的引脚连接共同决定，硬件上如果走的是CMOS模式布线，你光把FPGA侧改成LVDS，板子上信号完全对不上，跑起来肯定一塌糊涂。所以改参数之前，先确认你的硬件设计到底支持哪些模式。TCL脚本帮你生成的是“符合工程默认硬件配置”的设计，硬件不支持的参数强改没有意义。
4. 常见问题与实战排错
4.1 IP版本不一致导致的升级弹窗
用TCL脚本生成工程时，最频繁遇到的问题就是IP版本升级。Vivado每次大版本升级，自带的IP核版本号都会变。ADI仓库的分支虽然对应某个Vivado版本，但不同时间点拉下来的子模块，IP版本可能和当前Vivado内置的IP版本存在细微差异。
常见现象是脚本执行过程中出现类似“IP must be upgraded”的CRITICAL WARNING。如果是在批处理模式下，Vivado可能不会弹窗，而是直接生成一个与当前版本不匹配的IP，后面综合时就会报错。解决方法很简单，在工程打开后手动执行IP升级：
upgrade_ip [get_ips]或者在TCL脚本里找到生成IP之后、综合之前的位置，加一条upgrade_ip命令。执行完之后再看看report_ip_status的结果，确保所有IP状态都是“Up-to-date”。
提示：升级IP有可能会修改IP内置配置，导致行为变化。如果是老工程迁移，升级前最好对比一下IP版本变更记录，避免上了板才发现时序行为不一样。
4.2 路径、环境变量和跨平台坑
路径问题是我这次踩得最多的坑。Windows环境下最容易犯两个错误。
第一个错误是路径里带空格。TCL的sourc命令遇到带空格的路径会拆分字符串，导致找不到文件。解决办法是用花括号包裹路径，或者干脆把仓库放到没有空格的纯英文路径下。
第二个错误是路径分隔符。Vivado TCL环境继承了TCL的语法，路径分隔符统一用正斜杠/。从Windows资源管理器复制路径是反斜杠\，在TCL里会被当成转义字符处理。所以手写source路径时，务必把反斜杠改成正斜杠。
还有一个跨平台问题：在Linux上使用源码克隆时，文件权限、子模块符号链接的解析方式和Windows不一样。如果你在Windows上用Git Bash克隆，又在Windows的Vivado里执行脚本，通常没问题；但如果你把整个仓库从Windows拷贝到Linux，或者反过来，经常会出现exec: No such file or directory一类的错误。解决办法是别跨平台拷贝，直接在目标平台上重新克隆一次。
4.3 仿真模型分辨率错误与卡死
生成工程后如果想跑行为仿真，可能会遇到某种“模块未定义”的错误。比如报Module 'axi_ad9361' not found，这通常是仿真模型没有正确生成或没有添加到仿真源文件列表里。
大多数情况下，解决方法是先重新生成Block Design的仿真模型：
generate_target simulation [get_files fmcomms2.bd]然后重新启动仿真。如果依然报错，检查一下fmcomms2.srcs/sources_1/bd/fmcomms2/sim目录下是否生成了对应的sim_netlist.v文件。没有的话，说明IP核的仿真模型生成被跳过了，需要在Vivado的IP Catalog里手动重新Generate Output Products。
还有一种神似“卡死”的情况：仿真启动后波形窗口一直空白，进度条不动。这往往不是真的死机，而是仿真时间太长，或者设计中存在巨大的异步FIFO初始化过程。此时可以适当增加仿真时间步长，或者先跑一个小规模的顶层测试，别一上来就整个AD9361数据通路都仿真。
4.4 生成硬件平台后与Vitis/SDK协同
使用Zynq平台时，最终肯定要把硬件信息导出给Vitis或老版SDK做嵌入式软件开发。工程综合实现并生成比特流后，需要导出XSA文件。
最简单的导出命令是：
write_hw_platform -include_bit -force fmcomms2.xsa注意-include_bit参数会把比特流打包进XSA，这样Vitis里直接就能加载FPGA配置。如果漏了这个参数，到Vitis里调试时会发现下载程序后FPGA没有配置，外设全部不可用。
导出XSA之前，还要确保Block Design已经生成了正确的硬件描述。最好先执行generate_target all，把所有输出产物刷新一遍再导出。否则可能报No hardware definition found，而且这个错误在GUI里还不明显，等你到Vitis里导入时才暴露。
还有一点要特别注意：XSA文件只能由与之版本匹配的Vitis或SDK打开。比如你用Vivado 2019.1生成的XSA，必须用2019.1版本的SDK。用2020.2的Vitis去打开就会直接拒绝导入。版本匹配不仅是Vivado和HDL仓库之间的事，还一直延伸到嵌入式工具链。
4.5 快速定位问题的检查清单
遇到问题时最重要的不是盲目重试，而是按照顺序排查。我把常用检查项整理成一个清单，基本能覆盖大部分TCL脚本生成工程的问题。
- 仓库分支和Vivado版本是否匹配。不匹配先换分支。
- 子模块是否完整。缺子模块会有一堆“file does not exist”。
- 路径是否纯英文、无空格、正斜杠。
- 是否在正确的工程目录下执行脚本。当前目录必须包含
system_project.tcl。 - License是否有效。IP生成时报license错误就检查这里。
- Vivado版本与工程生成的目标版本是否一致。
- 工程目录是否有残留。有残留就删干净再重新生成。
- 查看
vivado.log中第一条报错信息。往往后面的连锁报错都是第一条引起的。
这八个检查项覆盖了我遇到过的绝大部分问题。如果按照这个清单逐项排查之后仍然不行，那就把vivado.log完整保存下来，去ADI HDL的GitHub issues里搜索，大概率能找到类似问题。
5. 一些个人经验和后续扩展思路
5.1 建议的工作流：先脚本后GUI
经过一次次折腾，我逐渐形成了自己的固定工作流。一开始我不信任TCL脚本，总想用GUI确认每一步，后来发现这样反而容易出问题。现在我的做法是：先用脚本批处理方式生成工程，然后直接在文本里检查TCL参数，接着用脚本跑综合实现，最后才打开GUI查看Block Design和时序报告。
这样做的最大好处是高效。GUI交互看起来很直观，但本质上每一步操作都要等待响应，效率太低。而且批处理模式下日志完整输出，问题定位比在GUI里翻窗口方便得多。等脚本流程完全跑通后，再打开GUI做细粒度验证，就非常从容了。
5.2 后续可以怎么改：自定义载板、自定义约束
TCL脚本不只是用来跑官方板卡的，它完全可以改造成你自己的载板工程。最常见的方式是把ADI某个官方工程目录复制一份，然后修改工程名、板级约束、引脚分配和器件型号。
复制后需要改的地方包括：system_project.tcl里定义的工程名称和FPGA器件型号，system_top.v里的顶层端口连接，以及约束文件里的引脚和电压标准。ADI的adi_board.tcl封装了大量板级初始化逻辑，如果你的板子没有特殊初始化需求，可以直接沿用官方的板级配置，只需要替换引脚约束。
我自己改过一个自定义载板，过程其实没有想象中复杂。核心思路是：保留ADI的IP和Block Design逻辑，把板级相关部分全部替换成自己的硬件设计。关键是列好一张接口映射表，把AD9361的每一个引脚对到FPGA的bank和引脚上，再写进XDC约束文件。一旦这个映射表没错，工程生成后大概率能直接跑通。
5.3 最后的个人体会
从“手动建工程”转向“TCL脚本生成工程”，是一个思维方式的转变。刚开始会觉得脚本晦涩、报错看不懂，但它带来的可重复性和自动化程度，是GUI操作完全无法比的。尤其是AD9361这类复杂的混合信号工程，工程配置项非常多，一旦做到参数化和脚本化，后续维护就变成改文本、跑脚本、看日志，清爽很多。
最后再分享一个小技巧：如果你确定自己会在同一个工程上反复改参数、反复生成，建议在Makefile或者自己写的批处理脚本里把整个流程固化下来，包括清理旧工程、拉取子模块、切换分支、执行TCL、导出XSA这些步骤。这样以后不管过多久回来，只要一条命令就能恢复完整的开发环境，省下的时间足够你多调几个AD9361的滤波参数。
