Skip to content

Automated XSim runs

Your Vivado installation includes three command-line simulator stages:

Command Role
xvhdl Analyze VHDL into a library
xelab Elaborate and create a simulation snapshot
xsim Run or debug the snapshot

Minimal commands

D:\FPGA\2026.1\Vivado\bin\xvhdl.bat -2008 src\design.vhd
D:\FPGA\2026.1\Vivado\bin\xvhdl.bat -2008 tb\tb_design.vhd
D:\FPGA\2026.1\Vivado\bin\xelab.bat work.tb_design -s tb_design_sim
D:\FPGA\2026.1\Vivado\bin\xsim.bat tb_design_sim -R

-R runs the simulation after loading the snapshot. The testbench should stop itself with std.env.finish.

Why use a script?

A script guarantees:

  • Correct source order.
  • VHDL-2008 enabled every time.
  • Correct top and generics.
  • Immediate stop on compile/elaboration failure.
  • Non-interactive repeatability.
  • One command for every regression.

PowerShell runner pattern

$ErrorActionPreference = "Stop"

$VivadoRoot = "D:\FPGA\2026.1\Vivado"
$Xvhdl = Join-Path $VivadoRoot "bin\xvhdl.bat"
$Xelab = Join-Path $VivadoRoot "bin\xelab.bat"
$Xsim  = Join-Path $VivadoRoot "bin\xsim.bat"

& $Xvhdl -2008 "src\design.vhd"
if ($LASTEXITCODE -ne 0) { throw "Design compilation failed" }

& $Xvhdl -2008 "tb\tb_design.vhd"
if ($LASTEXITCODE -ne 0) { throw "Testbench compilation failed" }

& $Xelab "work.tb_design" -s "tb_design_sim"
if ($LASTEXITCODE -ne 0) { throw "Elaboration failed" }

& $Xsim "tb_design_sim" -R
if ($LASTEXITCODE -ne 0) { throw "Simulation failed" }

Always inspect and propagate $LASTEXITCODE. PowerShell does not automatically convert every native-program failure into an exception.

Run the included tests

cd C:\Users\yanis\Documents\Bibliotheque-VHDL-Basys3\examples\adder

# Both tests
powershell -ExecutionPolicy Bypass -File .\sim\run-tests.ps1

# Only exhaustive
powershell -ExecutionPolicy Bypass -File .\sim\run-tests.ps1 -Test exhaustive

# Only file-driven
powershell -ExecutionPolicy Bypass -File .\sim\run-tests.ps1 -Test file

The script compiles once, elaborates each test, and fails the command if any stage fails.

Project files for larger source sets

XSim project files can list sources and language version:

vhdl2008 work "../src/package.vhd"
vhdl2008 work "../src/design.vhd"
vhdl2008 work "../tb/tb_design.vhd"

Then compile according to the options supported by your installed XSim version. Keep package/dependency order explicit.

Generics from the command line

Elaboration can override top-level generics:

xelab.bat work.tb_design -s tb_sim -generic_top "WIDTH=16"

For string/file generics, quote carefully and prefer normalized absolute paths. Validate the exact form with xelab -help for the installed Vivado release.

Regression directory

Let the simulator create generated data under a disposable build directory:

sim/
├── run-tests.ps1
└── build/          # generated logs, snapshots, wave database

Ignore build, .Xil, xsim.dir, .jou, and .wdb in Git.

Failure behavior

Your runner should fail for:

  • Tool not found.
  • Compile or elaboration error.
  • Assertion at the configured stop severity.
  • Simulator crash or non-zero exit code.
  • Watchdog timeout.
  • No tests discovered/executed.

Some simulators/configurations may print an assertion error without returning the exit status you expect. Verify failure propagation once by deliberately changing an expected result, then restore it.

Debug a failed automated test

  1. Re-run only the failing test.
  2. Preserve the seed/vector index.
  3. Add the relevant signals to a waveform configuration.
  4. Run XSim in GUI mode on the existing snapshot:
xsim.bat tb_design_sim -gui
  1. Find the first mismatch, not the last cascade.
  2. Convert the bug into a permanent directed test.

Continuous integration

The same script can run in CI on a machine with a compatible Vivado license/install. Useful outputs:

  • Simulator log.
  • Test count.
  • Failing vector and seed.
  • Optional JUnit XML from a wrapper/framework.
  • Timing and DRC reports for full FPGA builds.

Start locally with one command. CI is just another machine running that trusted command.