Trace Report - 2023.1 English

AI Engine Tools and Flows User Guide (UG1076)

Document ID
UG1076
Release Date
2023-06-23
Version
2023.1 English

Trace capability is used for debugging simulation hangs without the need for instrumenting kernel code or using gdb. Trace capability is not available with external test bench. There are two use models.

The first use model applies to standalone x86 simulation without external test bench. At the time that the x86 simulator detects deadlock, it prints a message indicating that the design is deadlocked and the simulation will be terminated and suggests to rerun the simulation with the trace option enabled. When you re-run the simulation again and the trace option is enabled, the simulator produces a textual report on the events that occurred during the simulation. Studying this report can help you identify the root cause of the deadlock. The root cause can be as simple as insufficient input data in a data file of the simulation platform, or it can be more involved.

A second use model applies to simulations where --trace and --timeout=secs options are enabled. After the timeout expires, the simulator terminates and produces the trace report. As in the first use model, analysis of the trace report can help identify the root cause of the deadlock.

The following options are available:

  • --trace to get a full trace report at the end of the simulation.
  • --trace-print to get output displayed on the console while the simulation is running.

Trace Report Content

The trace report shows the sequence of events that occurred during the simulation of your design in the x86 simulator. The name of the generated file is x86simulator_output/trace/x86sim_event_trace.data.txt. The kind of events that are recorded include:

  • The start of a kernel iteration
  • The end of a kernel iteration
  • The start of a stream stall, i.e., the start of a read from a stream port of a kernel that blocks because of lack of data
  • The end of a stream stall, i.e., the point where a read from a stream port that initially blocked, finally returns
  • The start of a lock stall, i.e., the start of an attempt to acquire a window port where the lock is initially not available
  • The end of a lock stall, i.e., the point in time where an attempt to acquire a window port that initially blocked, finally returns

Output of --trace-print versus --trace

The output of --trace-print is not as polished as the file generated by --trace. If you want to quickly see what is going on in the simulation, or if you are planning to terminate the simulation via CTRL-C instead of --timeout=secs, use --trace-print.

The columns of the output of --trace-print contain the following information:

  • Timestamp: It is the same as in x86sim_event_trace.data.txt.
  • Internal name of the kernel (x86sim_event_trace.data.txt uses the user name).
  • Event type.
  • Numeric value whose meaning depends on the event type: It encodes the port that you are waiting on for a lock or stream stall. It encodes the iteration number of a start of an iteration event.