Verifying Code with C Simulation

Vitis High-Level Synthesis User Guide (UG1399)

Document ID
English (United States)
Release Date
2021.2 English

Verification in the Vitis HLS flow can be separated into two distinct processes.

  • Pre-synthesis validation that the C program correctly implements the required functionality.
  • Post-synthesis verification that the generated RTL code performs as expected.

Both processes are referred to as simulation: C simulation and C/RTL co-simulation.

Before synthesis, the function to be synthesized should be validated with a test bench using C simulation. A C test bench includes a main() top-level function, that calls the function to be synthesized by the Vitis HLS project. The test bench can also include other functions. An ideal test bench has the following features:

  • The test bench is self-checking, and validates that the results from the function to be synthesized are correct.
  • If the results are correct the test bench returns a value of 0 to main(). Otherwise, the test bench should return any non-zero value.

In the Vitis HLS GUI, clicking the Run C Simulation toolbar button opens the C Simulation Dialog box, as shown in the following figure:

Figure 1. C Simulation Dialog Box

The options for the C Simulation Dialog box include the following:

Launch Debugger
This compiles the C code and automatically opens the Debug perspective. From within the Debug perspective, the Synthesis perspective button (top left) can be used to return the windows to the Synthesis perspective.
Build Only
Compiles the source code and test bench, but does not run simulation. This option can be used to test the compilation process and resolve any issues with the build prior to running simulation. It generates a csim.exe file that can be used to launch simulation from a command shell.
Clean Build
Remove any existing executable and object files from the project before compiling the code.
Optimizing Compile
By default the design is compiled with debug information enabled, allowing the compilation to be analyzed and debugged. The Optimizing Compile option uses a higher level of optimization effort when compiling the design, but does not add information required by the debugger. This increases the compile time but should reduce the simulation runtime.
Tip: The Launch Debugger and Optimizing Compile options are mutually exclusive. Selecting one in the C Simulation Dialog box disables the other.
Enable Pre-Synthesis Control Flow Viewer
Generates the Pre-synthesis Control Flow report as described in Pre-Synthesis Control Flow.
Input Arguments
Specify any inputs required by your test bench main() function.
Do not show this dialog box again
Lets you disable the display of the C Simulation Dialog box.
Tip: You can re-enable the display of the C Simulation Dialog box by selecting Project > Project Settings and selecting the Simulation settings.
After clicking OK in the dialog box, the C code is compiled and the C simulation is run. As the simulation runs, the console displays any printf statements from the test bench, or hls::print statements from the kernel or IP. When the simulation completes successfully, the following message is also returned to the console:
INFO: [SIM 211-1] CSim done with 0 errors.
INFO: [SIM 211-3] *************** CSIM finish ***************
Finished C simulation.
When the simulation fails, an error is returned:
@E Simulation failed: Function 'main' returns nonzero value '1'.
ERROR: [SIM 211-100] 'csim_design' failed: nonzero return value.
INFO: [SIM 211-3] *************** CSIM finish ***************

If you select the Launch Debugger option, the tool automatically switches to the Debug layout view as shown in the following figure. The simulation is started, but lets you step through the code to observe and debug the function. This is a full featured debug environment: you can step into and over code, specify breakpoints, and observe and set the value of variables in the code.

Figure 2. C Debug Environment
Tip: You can return to the Synthesis layout view by selecting the Window > Synthesis.