极客工场

Appearance

共 2,243 字预计阅读约 7 分钟

Vivado 命令行批处理仿真：xvlog、xelab、xsim -R 无 GUI 全流程 ​

更新时间：2026-10-22。面向想把仿真从「点 Run Simulation」搬到脚本里的同学——CI 回归、Makefile 流、远程服务器调试，都依赖无 GUI 的批处理仿真。本文用一个 4 位计数器工程在 Vivado 2017.4 上真跑了一遍 xvlog → xelab → xsim -R 三连：全程不开 GUI，三步合计约 6 秒，TEST PASS 干净退出。三连里每一步的报错排查分别见 XSim 找不到设计单元 与 XSIM 43-4099 模块缺 timescale，本文聚焦「把流程跑顺」本身。

本文要回答的问题 ​

  1. 无 GUI 批处理仿真的最小命令序列是什么？
  2. 三步各自的输入输出是什么，数据怎么流动？
  3. 脚本怎么写才能「一步失败立刻停、失败能定位」？
  4. 6 秒跑完的三连，时间分别花在哪？

一、为什么要离开 GUI ​

GUI 工程里点「Run Simulation」很爽，但有三类场景它进不去：CI 服务器没有桌面环境；Makefile/脚本流里每一步都要能判退出码；远程 SSH 到一台没装 X 的机器。批处理仿真的本质，是把 GUI 帮你按序点掉的三步——编译、细化、运行——还原成三条命令，自己掌控顺序、参数和失败处理。

这三条命令在 Windows 是 xvlog.bat / xelab.bat / xsim.bat（Linux 下去掉 .bat），它们就在 Vivado 安装目录的 bin/ 下，不需要启动 Vivado 主程序。本文的实验工程是最小配置：DUT 一个 4 位异步复位计数器 counter4，TB 产生 10ns 时钟、跑 20 拍后自检并 $finish。

二、最小三连：每条命令管什么 ​

Vivado 命令行批处理仿真三连：编译入库、生成快照、跑完即退

读这张流程卡抓一条主线：每步只对自己上一步的产出负责。xvlog counter4.v tb_counter4.v 把两个源文件分析进 xsim.dir/work 库；xelab -debug typical tb_counter4 -s sim_du 从库里取出顶层 tb_counter4，解析整棵实例树，生成名为 sim_du 的快照；xsim sim_du -R 加载快照跑到底自动退出。这里 -debug typical 是调试友好档（保留波形所需信息），-s 给快照起名，-R 是 run-all 即「跑完就退」——批处理场景的灵魂参数，没有它 xsim 会停在交互提示符等你敲命令。

三步的分工细节与「错一步会怎样」，在 XSim 找不到设计单元 里用两类真实报错讲过；本文不重复，只给结论：xvlog 过不代表 xelab 能成，xelab 过不代表你传对了快照名。

三、真实跑一遍：6 秒全绿 ​

本次实验把三条命令写进一个 run.bat，在 Windows 节点用 PowerShell 计时整体执行，关键输出摘录（完整日志见文末实验环境）：

run.bat 批处理三连：TEST PASS，全程约 6 秒

读这张终端卡按时间顺序抓五个证据点：

  1. INFO: [VRFC 10-311] analyzing module counter4 / tb_counter4——xvlog 把两个模块收进 work 库；
  2. Time Resolution for simulation is 1ps + Built simulation snapshot sim_du——xelab 细化成功，快照落盘；
  3. run -all 之后 $monitor 逐拍打印：0 ns: rst_n=0 count=0 (0x0) 起步，25ns 释放复位后 count 每 10ns 加一，到 0xf 回卷；
  4. TEST PASS: counter wrapped, final count=0x4 + $finish called at time : 225 ns——TB 自检通过、干净收尾；
  5. 日志最后两行：run.bat exit=0、elapsed_sec=6——整个三连从编译到跑完只用了约 6 秒。

6 秒这个数的分布大致是：xvlog 约 1 秒（两个文件），xelab 约 2-3 秒（启动最重），xsim 约 1-2 秒。对小工程来说瓶颈是进程启动开销，不是仿真本身——这也是 CI 里应该「一个快照跑多个激励」而不是每测一条重开三连的原因。

编译与细化段的原始输出（termshot 只截了仿真段，这里是日志开头的完整前两步）：

exp-log
INFO: [VRFC 10-2263] Analyzing Verilog file "C:/eda-lab/batch-sim/counter4.v" into library work
INFO: [VRFC 10-311] analyzing module counter4
INFO: [VRFC 10-2263] Analyzing Verilog file "C:/eda-lab/batch-sim/tb_counter4.v" into library work
INFO: [VRFC 10-311] analyzing module tb_counter4
Vivado Simulator 2017.4
Running: D:/Xilinx/Vivado/2017.4/bin/unwrapped/win64.o/xelab.exe -debug typical tb_counter4 -s sim_du 
Multi-threading is on. Using 14 slave threads.
Starting static elaboration
Completed static elaboration
Starting simulation data flow analysis
Completed simulation data flow analysis
Time Resolution for simulation is 1ps
Compiling module work.counter4

四、数据在三步之间怎么流动 ​

fpga/intermediate/vivado-cli-batch-sim.md D2 示意图

读这张图注意：work 库和快照都是文件系统里的真实目录，不是内存状态——所以你可以删掉 xsim.dir 重来，也可以只重跑 xsim 复用旧快照；这也意味着换了工作目录后相对路径会找不到快照（43-3225 篇 排查表里有这条）。右边两个出口对应两种证据形态：文本证据（$monitor/$display，默认就有）和波形证据（需要额外 tcl 命令挂接，方法见 XSim 批处理 dump VCD 离线看波形）。

五、脚本写法：能定位、不掩饰 ​

实验用的 run.bat 核心逻辑（Windows cmd 语法，完整文件见公开仓）：

bat
@echo off
set VIVADO_BIN=D:\Xilinx\Vivado\2017.4\bin
set TOP=tb_counter4
set SNAP=sim_du

call %VIVADO_BIN%\xvlog.bat counter4.v tb_counter4.v
if %ERRORLEVEL% neq 0 exit /b %ERRORLEVEL%
call %VIVADO_BIN%\xelab.bat -debug typical %TOP% -s %SNAP%
if %ERRORLEVEL% neq 0 exit /b %ERRORLEVEL%
call %VIVADO_BIN%\xsim.bat %SNAP% -R
exit /b %ERRORLEVEL%

三个要点，都是血泪经验。其一，每步判退出码、非零立即 exit：不判的话 xvlog 挂了 xelab 接着跑，最后报错的位置离根因十万八千里；43-4099 和 43-3225 的实际损失大半来自「报错被后续命令刷出屏幕」。其二，顶层名和快照名用变量贯通：三处引用同一个 %TOP% / %SNAP%，杜绝手抄偏差——名字不一致是快照缺失报错的头号原因。其三，call 不能省：bat 里直接调另一个 bat 不 return，后续命令根本不会执行。

Linux 下同一套逻辑写成 shell，把 %ERRORLEVEL% 换成 $?、或直接 set -e 一把梭；命令名去掉 .bat 后缀即可，参数完全一致。

六、三条命令的常用选项速查 ​

批处理脚本写顺手后，下表这些选项覆盖九成日常需求（完整清单用 xvlog -h / xelab -h / xsim -h 查）：

命令选项作用
xvlog--sv按 SystemVerilog 语法分析（.sv 文件必加）
xvlog-d 宏名定义编译宏，等价于源码里的 define
xvlog-i 目录加 include 搜索路径
xelab-debug typical保留调试所需信息（波形/层级可见），批处理默认推荐
xelab-debug off全优化，回归跑速度最快但看不到波形
xelab-s 快照名给快照起名，xsim 按这个名字加载
xelab-top 模块名显式指定顶层（位置参数也可，脚本里显式更不易错）
xsim-Rrun all 跑完自动退出，批处理灵魂参数
xsim-gui开图形界面调波形，与 -R 二选一
xsim-tclbatch 脚本启动后执行 tcl（挂波形/dump VCD 用）
xsim-wdb 文件指定波形数据库文件名

两个容易踩的点：其一，--sv 漏加时 .sv 文件里的 logic、always_ff 会报一堆语法错，误判成「代码坏了」；其二，-debug off 与 -debug typical 生成的快照不通用——想用波形就必须在 xelab 阶段决定，事后补不了。

七、批处理与 GUI 的分工 ​

场景推荐方式理由
CI 回归 / 每晚跑全量用例xsim -R 批处理无桌面依赖、退出码即结论、可并行
远程 SSH 服务器调试批处理 + dump VCD没图形环境，波形离线看（见 VCD 离线篇）
交互式调时序、翻波形xsim -gui波形窗缩放、加信号、断点都靠 GUI
快速验证一个小改动批处理6 秒出结果，比开 Vivado 快一个数量级

两条路线共享同一个 xelab 快照：白天用 GUI 调，晚上 CI 用 -R 回归，互不干扰。调波形类需求里有个常见坑要提醒：XSim 的 tcl 里没有 ModelSim 的 wave 命令，批处理挂波形要写 add_wave，写错会把进程挂死在 xsim% 提示符——这个坑的完整排错过程见 XSim 报 invalid command name wave。

实验环境 ​

  • 机器/系统：Windows 10 工作站（Vivado 2017.4 实机）
  • 工具版本：Vivado Simulator 2017.4（xvlog.bat / xelab.bat / xsim.bat，D:\Xilinx\Vivado\2017.4）
  • 日期：2026-10-22
  • 完整命令：cmd /c run.bat（内部依次执行 xvlog.bat counter4.v tb_counter4.v、xelab.bat -debug typical tb_counter4 -s sim_du、xsim.bat sim_du -R），PowerShell Stopwatch 整体计时

代码获取：本实验完整代码（counter4.v、tb_counter4.v、run.bat）见公开仓库 derekzhuo/geek-doc.cn 的 experiments/vivado-cli-batch-sim/。把 run.bat 里的 Vivado 路径改成本机安装目录即可复现。

这一篇在知识体系里的位置 ​

本篇是 FPGA 中级 工具链主线的一环：入门侧的仿真基础见 Testbench 与仿真 与 仿真波形怎么看；三连流程的两条高频报错各有专篇——XSIM 43-3225 找不到设计单元、XSIM 43-4099 模块缺 timescale；跑通之后想把波形搬到无 GUI 环境看，接 XSim 批处理 dump VCD 离线看波形；仿真通过、进入综合阶段后的资源报告解读见 Vivado 利用率报告怎么读。

一句话总结 ​

Vivado 无 GUI 批处理仿真就是 xvlog 编译入库 → xelab 生成快照 → xsim -R 跑完即退 三条命令，真实工程全程约 6 秒；脚本侧记住三件事——每步判退出码、顶层名与快照名用变量贯通、bat 里调 bat 必须 call——就能把 GUI 点鼠标的流程完整搬进 CI 和 Makefile，失败定位也精确到具体哪一步。