Running C Simulation - 2023.2 English

Vitis High-Level Synthesis User Guide (UG1399)

Document ID
UG1399
Release Date
2023-12-18
Version
2023.2 English

Verification of the HLS component can be separated into distinct processes that occur before and after high-level synthesis. These processes include C Simulation and Code Analysis to validate the C/C++ source code prior to high-level synthesis; and C/RTL Co-simulation to validate the generated RTL design.

Running C simulation on the HLS component requires a test bench as described in Writing a Test Bench. 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. Prior to running simulation though, you must configure the HLS component to support simulation. C Simulation can be run by itself or with the Code Analyzer enabled. By itself, C Simulation validates the logic of the source code using a test bench and provided data. With Code Analyzer the simulation to validate the algorithm is still completed, but a deeper analysis of the source code and prospective performance of the design is also performed. Code Analyzer lets you visualize the potential for task level parallelism, estimate the potential performance of the design, and understand the architectural changes needed to improve the performance of the design.

Loading Test Bench Files

Like C synthesis, the source files required for simulation can be loaded at the time the HLS component is created. However, you can skip that step at creation and add the test bench files prior to running simulation. It is also possible to change or add to the files used for simulation. This is done in the Testbench sources section of the Config Editor.

Figure 1. HLS Component Testbench Sources

The Testbench sources displays currently added test bench files, and lets you edit, or delete current files, add new files, and add or modify CFLAGS for the test bench.

  • Add item: Select this command to add new test bench files to the HLS component. This opens a File Browser, and lets you navigate to and select the files to add.
  • Add CFLAGS: You can add compilation flags (CFLAGS) to be applied to all source files, or to be added to specific source files. As shown in the figure above, simply add the flags to the appropriate text entry box for Flags common to all files. To add flags for specific source files, select the source file and select Edit item to add the flags, or modify the file name and path.
These selections result in the following config file entries:
[HLS]
tb.file=../../src/in.dat
tb.file=../../src/out.golden.dat
tb.file=../../src/dct_test.cpp
tb.cflags=<cflag>
tb.file_cflags=../../src/dct_test.cpp,<cflag>

Configure the Simulator

You can configure the C simulator prior to running simulation using the C Simulation section of the Config Editor, as shown below.

Figure 2. HLS Component Simulation Settings

These configuration commands let you specify how the simulation should run. The configuration options include:

O
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.
argv
Specify any inputs required by your test bench main() function.
clean
Remove any existing executable and object files from the project before compiling the code.
code_analyzer
Enable the Code Analyzer tool as described in Using Code Analyzer.
ldflags
Specifies the options passed to the linker for simulation. This option is typically used to pass include path information or library information for the C/C++ test bench.
mflags
Provides for options to be passed to the compiler for C simulation. This is typically used to speed up compilation.
setup
When this option is specified, the simulation binary will be created in the csim directory of the current HLS component, but simulation will not be executed. Simulation can be launched later from the compiled executable. The default is false, and simulation is run after setup is complete.
These selections result in the following config file entries as an example:
[HLS]
csim.clean=true
csim.O=true
csim.code_analyzer=0
csim.argv=arg1 arg2

Run Simulation

To run simulation make sure the HLS component is active in the Flow Navigator, or select it from the Component menu to make it the active component in the tool. When the HLS component is the active component, the Flow Navigator enables running C Synthesis, C Simulation, C/RTL Co-simulation, Packaging, and Implementation to build and analyze the HLS component. To simulate the HLS component select Run beneath the C SIMULATION heading in the Flow Navigator.

Tip: You can also select the Debug command from the Flow Navigator to launch the debug process as described in Debugging the HLS Component.

You can track the progress of simulation in the Output window. The transcript for the synthesis run will have the top function name as <component-name>::c_simulation as shown below.

Figure 3. HLS Component Running Simulation
Tip: The simulation run in the Vitis IDE uses the vitis-run --mode hls --csim command as described in vitis, v++, and vitis-run Commands.

Results of C Simulation

After clicking OK in the dialog box, the C/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 ***************

When the simulation is complete a Summary report is generated which shows the simulation command and the time stamp of the run. You can view the Summary report and simulation log file by selecting them freom the Report heading, or by viewing them in the Analysis view. If Code Analyzer was also run there will be a report for that as well.