Sanitizers During C Simulation - 2024.1 English

Vitis High-Level Synthesis User Guide (UG1399)

Document ID
UG1399
Release Date
2024-05-30
Version
2024.1 English

A new feature is now available in C simulation: sanitizers. Sanitizers help identify undefined behaviors in the code (test bench and design). Undefined behaviors occur when the code is correct but is specified in the C/C++ language specifications to have unpredictable effects. If the design code can trigger undefined behaviors, the computation performed by the synthesized hardware is likely to be incorrect. Examples of undefined behaviors in C/C++ include integer overflows or array access out of bounds.

Vitis HLS ships two sanitizers to identify undefined behaviors in HLS components.

  • The "address sanitizers" identifies undefined memory accesses when C simulation runs.
  • The "undefined-behavior sanitizers" identifies other non address-related undefined behaviors during C simulation.

Both sanitizers can be enabled prior to running C simulation in the HLS project options using the GUI (need screenshot) or using the Tcl commands `config_csim -sanitize_address=true` and `config_csim -sanitize_undefined=true`.

In some cases, sanitizers will produce in the console a stack trace pointing at where the problem occur. It can resemble the following example:

AddressSanitizer:DEADLYSIGNAL
 =================================================================
 ==44041==ERROR: AddressSanitizer: SEGV on unknown address 0x0000000000c0 (pc 0x7ff6d5c4c284 bp 0x7ffeccaa1d80 sp 0x7ffeccaa1aa0 T0)
 ==44041==The signal is caused by a READ memory access.
 ==44041==Hint: address points to the zero page.
     #0 0x7ff6d5c4c284 in _IO_vfscanf (/lib64/libc.so.6+0x59284) (BuildId: 398944d32cf16a67af51067a326e6c0cc14f90ed)
     #1 0x274110 in __interceptor_vfscanf /path/compiler-rt/lib/asan/../sanitizer_common/sanitizer_common_interceptors.inc:1523:1
     #2 0x274110 in fscanf /path/compiler-rt/lib/asan/../sanitizer_common/sanitizer_common_interceptors.inc:1541:1
     #3 0x313c74 in main /project/hls/csim/build/../../../testbench.cpp:36:3
     #4 0x7ff6d5c15504 in __libc_start_main (/lib64/libc.so.6+0x22504) (BuildId: 398944d32cf16a67af51067a326e6c0cc14f90ed)
     #5 0x253198 in _start (/project/hls/csim/build/csim.exe+0x253198)
 
 AddressSanitizer can not provide additional info.
 SUMMARY: AddressSanitizer: SEGV (/lib64/libc.so.6+0x59284) (BuildId: 398944d32cf16a67af51067a326e6c0cc14f90ed) in _IO_vfscanf
 ==44041==ABORTING

In the example the lines preceded by # and a number indicate a stack entry from 0 (deepest level of function calls) to the last entry in the list (initial function call in your application). Usually, the problem is related to the deepest function call that occurred in the HLS project when the error happened. To find the problematic source code line, you can go down the trace starting from #0 and identifying the first line of code which belongs to your design or test bench. In this example, a segmentation fault happened when executing the line 36 of the test bench file (entry #3 in the stack trace) and should be checked.