X86 Simulation Debug Walkthrough - 2024.1 English

Vitis Tutorials: AI Engine

Document ID
Release Date
2024.1 English

X86 Simulation Debug Walkthrough


The x86simulator supports faster simulation to help verify the kernel’s functionalities. It applies systemC model instead of the register transfer level (RTL) model to achieve faster build and runtime. The hardware constraints, such as heap/stack sizes and program memory size, are not verified in the software emulator.

Before starting this tutorial:


Build and Simulate in the Vitis IDE Demonstrates how to use the Vitis IDE to build and simulate an AI Engine design.
Debug Using printf() Demonstrates how to add formatted `printf()` to print debug messages.
Debug Using printf() with Vector Datatypes Demonstrates how to print vector output data value via `printf()`.
Debug Using the Vitis IDE Debugger Demonstrates how to use the Vitis IDE debugger to debug an AI Engine design.
x86simulator Options for Debugging Demonstrates how to use the x86simulator options file for debugging.
Data Dump Demonstrates how to use the data dump feature with a practical scenario.
Deadlock Detection Demonstrates how to debug deadlock scenarios in an x86simulation.
Trace Report in a File Demonstrates how to visualize the trace report in a file.
Trace Report in the Output Console Demonstrates how to visualize the trace report in the output console during runtime.
Memory Access Violation and Valgrind Support Demonstrates how to debug a memory access violations in an AI Engine design using Valgrind support.
Using the GDB Debugger in Command Line Demonstrates about debugging in command line using the GNU debugger (GDB).
x86simulation on the Command Line Demonstrates how to run an x86simulation on the command line.
x86simulation with GDB Demonstrates how to use the GDB during x86simulation.
x86simulator Using the GDB Server Demonstrates how to use a GDB server to debug the design.

Section 1

Build and Simulate in the Vitis IDE

  1. Once the Vitis IDE is opened and the system project is created manually, select the AI Engine Component from the left-side pane, and expand to locate and select the aiecompiler.cfg file to open the compiler configuration settings.

  2. Select the Module-Specific settings and click Add item under the Pre-processor setting. build settings

  3. Add -O0 to the Pre-processor option. This improves the debug visibility.

  4. Now, in the Flow navigator window, select the Build option under X86 SIMULATION. This builds the AI Engine component for x86simulation target. Once the build completes, you see the Compilation Complete and Build Finished Successfully messages in the console. Also a green tick mark as highlighted below.

  5. In the Flow navigator window, under X86SIMULATION, select the Run option. If there is no existing launch configuration, you need to create one by clicking on Create Configuration -> New Launch Configuration -> x86sim. Create_Configuration

  6. You can change the Launch Config Name and click Run button to start simulation for x86simulation target. When the simulation complete, you see the following output in the console. simulator output

Section 2

Debug Using printf()

The simplest form of tracing is to use a formatted printf() statement in the code for printing debug messages. Visual inspection of intermediate values and addresses can help you understand the progress of program execution. You can add printf() statements to your code to be processed during x86 simulation, and remove them or comment them out for hardware builds. To help identify which kernel is printing which line, the X86SIM_KERNEL_NAME macro can be useful.

This section talks about adding a printf() statement in the source code, compile and run x86simulator, and check the output in the console.

  1. From the Vitis IDE, browse to the [AI Engine] component and expand Sourceskernelsclick on peak_detect.cc.

  2. Add #include <adf/x86sim/x86simDebug.h> at the beginning of the source file and printf("%s: %s, %d\n", __FUNCTION__, X86SIM_KERNEL_NAME, __LINE__); after for the loop.

  3. To compile the project, select the Build option under X86 SIMULATION in FLOW navigator.

  4. To run the project, select the Run option under X86SIMULATION in Flow navigator.

  5. The expected result is as follows. printf support

  6. Remove the added printf statement from the peak_detect.cc file to use it for other features.

Section 3

Debug Using printf with Vector Datatypes

The x86simulator supports printing vector output data value via printf(). This section talks about visualizing vector values using the x86simulator.

  1. Add the following lines in the peak_detect.cc.

    int32_t* print_ptr = (int32_t*)&v_in;
    for(int pp=0;pp<16;pp++)
       printf("Iteration-%d -> Vector-%d -> value = %d\n",i,pp,print_ptr[pp]);
  2. Recompile the project either by hitting the build option in the Flow navigator.

  3. Run the x86simulation, and observe the following printf statements in the console.