Trace Report - 2021.2 English

Versal ACAP AI Engine Programming Environment User Guide (UG1076)

Document ID
UG1076
ft:locale
English (United States)
Release Date
2021-12-17
Version
2021.2 English

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

The first use model applies to standalone x86 simulation without external test bench and with --stop-on-deadlock enabled. 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. In this second simulation, 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. This option is also a good choice if your simulation does not terminate (deadlock or segmentation fault) and you do not want to specify --timeout=secs or --stop-on-deadlock

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.