Trace Report - 2025.2 English - UG1076

You can use Trace capability to debug simulation hangs without the need for instrumenting kernel code or using gdb. Trace capability is not available with an external test bench. There are two use models.

The first use model applies to standalone x86 simulation without an external test bench. If the x86 simulator detects deadlock, it prints a message indicating that the design is in deadlock and terminates the simulation. The simulator suggests to rerun the simulation with the trace option enabled.

When you re-run the simulation with the trace option enabled, the simulator produces a textual report on the events that occurred during the simulation. Study this report to help 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 complex.

The second use model applies to simulations where the --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 trace report 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. Trace reports include the following recorded events:

• The start of a kernel iteration
• The end of a kernel iteration
• The start of a stream stall. (That is, 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 (That is, the point where a read from a stream port that initially blocked, finally returns.)
• The start of a lock stall. (That is, the start of an attempt to acquire a window port where the lock is initially not available.)
• The end of a lock stall. (That is, 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 legible as the file generated by --trace. To quickly check the simulation state, 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.