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:
-
--traceto get a full trace report at the end of the simulation. -
--trace-printto 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.txtuses 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.