APS/Vivado Basics/04. Simulation.md

# How to Run a Simulation in Vivado

Simulation is one form of modeling. Modeling is used to verify the behavior of a designed device. To do this, test stimuli are applied to the module inputs and the results are read from its outputs. In parallel, the same test stimuli are also applied to a reference model of the device. The model's output is compared with the output of the design under test, and any discrepancy is reported as an error.

Generating test stimuli, applying them to the device under verification and the reference model, comparing results, and logging errors — all of this is handled by the verification environment, referred to in these lab assignments as a "testbench". Testbenches are non-synthesizable modules and therefore must not be placed in the `Design Sources` folder; instead, the `Simulation Sources` folder is used for them (see ["Project Manager"](03.%20Project%20manager.md)).

A separate testbench is provided in the repository for each module to be verified. Before launching a simulation, make sure that the testbench for the module you intend to verify is selected as the top-level module in the `Simulation Sources` folder.

There are several ways to launch a simulation; two of them are described here:

1. In the left panel, under the `SIMULATION` section, click `Run Simulation` → `Run Behavioral Simulation`.

![../.pic/Vivado%20Basics/04.%20Simulation/fig_01.png](../.pic/Vivado%20Basics/04.%20Simulation/fig_01.png)

_Figure 1. Launching a simulation via the `SIMULATION` tab of the `Flow Navigator`._

2. In the project hierarchy, right-click the `sim_1` folder and select `Run Simulation` → `Run Behavioral Simulation`.

![../.pic/Vivado%20Basics/04.%20Simulation/fig_02.png](../.pic/Vivado%20Basics/04.%20Simulation/fig_02.png)

_Figure 2. Launching a simulation via the context menu of the `sim_1` folder in `Simulation Sources`._

After the simulation is launched, a specified amount of simulation time will be modeled — this duration is set in the project settings (we set it to one second when creating the project) — after which the simulation pauses. The simulation can also be stopped early by the testbench itself.

## Simulation Windows

After the simulation is launched, the simulation window shown in _Fig. 3_ will open in the main area of the Vivado window.

![../.pic/Vivado%20Basics/04.%20Simulation/fig_03.png](../.pic/Vivado%20Basics/04.%20Simulation/fig_03.png)

_Figure 3. Simulation window._

This window consists of four sub-windows:

1. A window with the `Scope` and `Sources` tabs;
2. A window with the `Objects` and `Protocol Instances` tabs;
3. The editor window with open files and a waveform viewer (which is also represented as a file);
4. A window with the `Tcl Console`, `Messages`, and `Log` tabs.

## The Scope and Sources Window

The `Sources` tab is the same tab used when adding and describing source files, and is described in detail in the chapter "[Project Manager](./03.%20Project%20manager.md)".

The `Scope` tab displays the simulation scope. The top level consists of the top-level module from `Simulation Sources` and the `glbl` library, which can be ignored in this course. Expanding the top-level module reveals a module hierarchy similar to the one in `Simulation Sources`. Selecting a specific module in the `Scope` tab allows you to add it to the waveform viewer — either by dragging it into the signal area or by right-clicking it and selecting `Add to Wave Window`. In this case, the module's inputs, outputs, and internal signals will all be added to the waveform. In addition, selecting a module in the `Scope` tab updates the content displayed in the `Objects` tab.

The `Objects` tab lists all objects contained in the module selected in the `Scope` tab: its inputs and outputs, internal wires and registers, module parameters, and so on. This tab can be used to add individual objects of the selected module to the waveform.

## Simulation Toolbar

After the simulation is launched, the toolbar at the top of the Vivado window changes. The buttons shown in _Fig. 3_ are:

1. Restart simulation (keyboard shortcut `Ctrl+Shift+F5`);
2. Run simulation until stopped by the testbench or manually (keyboard shortcut `F3`);
3. Run simulation for the time interval specified to the right of the button (keyboard shortcut `Shift+F2`);
4. Relaunch simulation (no default keyboard shortcut, but one can be assigned in the settings);
5. Close simulation.

The difference between restarting and relaunching the simulation is as follows. When the simulation is restarted, the simulated values of all signals added to the waveform are cleared (the signals themselves remain), and the simulation time is reset to zero (i.e., the simulation starts over). This may be necessary during debugging, or when you have added new signals to the waveform in the middle of a simulation and want to see their behavior from the beginning. Restarting does not recompile the source files, even if their contents have been changed.

Relaunching the simulation is similar to closing and reopening it. If source files have been changed, they will be recompiled. Note that Vivado primarily detects only changes made through its own editor. If files were modified externally (this is especially relevant for `mem` files, which start being used from the fourth lab assignment), Vivado may not detect the new changes. If the simulation was previously launched and Vivado has not detected any changes in the files since then, the sources are not recompiled and the simulation runs using the previously compiled objects. If changes were made externally but Vivado did not detect them, you can clear the previous build by right-clicking `Simulation` in the `Flow Navigator` and selecting `Reset Behavioral Simulation` (see _Fig. 4_).

![../.pic/Vivado%20Basics/04.%20Simulation/fig_04.png](../.pic/Vivado%20Basics/04.%20Simulation/fig_04.png)

_Figure 4. Resetting simulation files._

Therefore, if you have added signals to the waveform and want to see their behavior from time zero, or if you want to clear the message log and see only the messages up to a certain point (i.e., perform any action that does not involve recompiling source files), it makes sense to restart the simulation and run it again.

If you have modified the source code of a module and want to simulate the updated code, you can close the simulation and relaunch it using the same methods as before, or relaunch it using button `4` shown in _Fig. 3_.

> If you have changed the top-level module in `Simulation Sources`, you must close the current simulation first. Without doing so, a new simulation cannot start and will produce the error "boost filesystem remove: The process cannot access the file". More information about this error can be found in the "[List of Common Vivado Errors](../Other/FAQ.md)".

More information about debugging and working with the waveform viewer is provided in the chapter "[Guide to Finding Functional Errors](05.%20Bug%20hunting.md)".