Vivado Command Line Simulation Tutorial

The Vivado design suite has a professional logic simulation tool that you can use to simulate the behavior of your SystemVerilog HDL files. HDL Simulation tools like this are used by professional engineers to simulate very complex and large digital design files. Your ability to use simulation tools effectively is key to successfully designing digital circuits.

This tutorial will guide you through how to set up and start the Vivado simulation tool in the command line. Other tutorials will provide more information on how to interact with the simulation tool. This tutorial will demonstrate this process using the binary_adder.sv design from Lab 2.

Analyze HDL

The first step in the simulation process is to analyze each of the SystemVerilog files in your project. HDL ‘analysis’ is very similar to compiling a C/C++ file. For a C/C++ file, the compiler reads the file, checks for syntax errors, and creates an .o object file for use later by the linker. The HDL analysis process reads the SystemVerilog file, checks for syntax errors, and creates an intermediate file that is used later by the simulator. You will need to analyze each of the SystemVerilog files in your project before you can simulate them.

The command line executable you will use for HDL analysis is xvlog. Execute the following command to analyze the binary_adder.sv file:

% xvlog binary_adder.sv -sv --nolog
INFO: [VRFC 10-2263] Analyzing SystemVerilog file "../binary_adder.sv" into library work
INFO: [VRFC 10-311] analyzing module binary_adder

If there are no syntax errors in your SystemVerilog file, you will have successfully analyzed this file. A new directory, xsim.dir, will be created that contains the intermediate files needed for simulation.

If multiple files needed to be analyzed then each file would be listed in the command line call to xvlog. Multiple files can be provided to the xvlog command line call if you would like to analyze them with one command.

Elaborate Top-Level Module

The second step in the simulation process is to ‘elaborate’ the top-level module of your design. Most designs involve multiple HDL files that are interconnected. The elaboration step integrates all the HDL files and resolves all references to create a single design that can be simulated. The ‘elaboration’ process is similar to the linking stage in C/C++.

The command line executable you will use for HDL analysis is xelab. Execute the following command to elaborate the binary_adder.sv design:

% xelab binary_adder  -debug typical  --nolog

The arguments for this command are as follows:

  • ‘binary_adder’ is the name of the top-level module in the design.
  • ‘-debug typical’ enables the debug mode for the simulation
  • ’–nolog’ suppresses the creation of a log file.

In this example, there is only one module in the design, so the top-level module is the same as the module name. In other designs in which there are more than one module, you would need to specify the top-level module name.

This command will update files within the xsim.dir directory that was created during the analyze step.

Run Simulation Tool

Once your design has been successfully elaborated, you are ready to run the simulation tool. The HDL simulation tool is like a debugger that allows you to observe the behavior of your circuit when applied with specific inputs. The executable for simulation is xsim. For this tutorial we will be running the executable in ‘command-line’ mode. An additional tutorial for GUI mode will be provided later.

Logic simulation can operate in ‘interactive’ mode or ‘batch’ mode. For ‘interactive’ simulation, you are able to interactively set inputs, further time in the simulation, and observe the outputs. Interactive simulation is useful for debugging early in your design process when you may have a number of errors and need to quickly iterate on your design. In ‘batch’ simulation, you run the complete simulation with a batch file or testbench module to test your module against a variety of input conditions. Your laboratory assignments will run your simulations in batch mode during the passoff process, but you will likely run them in interactive mode during the debugging process.

The simulator operates with a shell using the ‘Tcl’ (pronounced ‘tickle’) programming language. You will need to use several Tcl commands and create simple Tcl scripts to perform your logic simulations.

Commands for Interactive Simulation

In interactive simulation you will be manually applying values to the circuit inputs, advancing the simulation time, and observing the outputs. The following command line executable is used to start the simulator in interactive mode:

% xsim binary_adder --nolog

The first argument is the simulation ‘set’ specified in the elaborate command. The --nolog option suppresses the creation of a log file.

Once you have the simulation shell, enter each of the commands described below:

1. Determine the value of the O output by typing the get_value command:

xsim% get_value -radix bin O

The -radix bin command option will cause the output to be printed in binary rather than the default decimal. Notice that the value of the ‘O’ outputs is xxx indicating that the value is unknown. The unknown value is due to the fact that the switches have not been set to a specific value within the simulation.

2. Set the value of the A inputs by typing the set_value command:

xsim% set_value A -radix bin 00

This command will set both bits of ‘A’ to 0. Note the use of the -radix bin command option to indicate that the input is specified in binary. Other radices are also possible including hex, dec, oct, unsigned, and ascii.

3. Advance the simulation runtime

Once the input has been set, you need to advance the simulation time of the simulator so the inputs can propagate through the gates (changes to inputs do not happen immediately and require simulation time). The following command will advance the simulation time of the simulator by 10 ns:

xsim% run 10 ns

You can determine the current simulation time of the simulator by running the current_time command.

3. Query the LED outputs

Now that the simulator has advanced in time, query the value of the ‘led’ outputs to make sure they have changed.

xsim% get_value -radix bin O

4. Apply different switch inputs

Apply a variety of inputs to the switches and query the LED outputs to convince yourself that the circuit properly performs addition.

Other Tcl Simulation Commands

There are a number of other simulation commands you may find useful when simulating in Vivado:

  • quit or exit: Quit the simulator
  • restart: Restart the simulator at time zero and remove all set input values

Simulation Script

While interactive simulation is often necessary for early debugging, it is helpful to create Tcl simulation scripts that perform multiple Tcl commands at once. These simulation scripts can be executed by running the source command.

The following is a simple example of a simple Tcl script that can be used to simulate the binary_adder design with multiple commands:

# Script to simulate the binary_adder design (Tcl uses '#' for comments)
run 10 ns
set_value A -radix bin 00
set_value B -radix bin 00
run 10 ns
get_value -radix bin O
run 10 ns
set_value A -radix bin 11
set_value B -radix bin 01
run 10 ns
get_value -radix bin O

If this script is saved in a file named sim.tcl, the following command will execute all of the script commands at once:

xsim% source sim.tcl

Batch Mode Simulation

You can run a complete simulation from a single executable by running the simulator in ‘batch’ mode. This is often done after a module has been verified when small changes are made to make sure nothing has changed. A batch simulation can be run from the command line using the following command:

% xsim binary_adder -tclbatch sim.tcl -log sim_adder.log

This command will run the simulator with the sim.tcl script and log the output to the sim_adder.log file.