NOTE: This part of the manual is relevant only if you are using the classic userspace-only version of PTLsim. If you are looking for the full system SMP/SMT version, PTLsim/X, please skip this entire part and read Part III instead.
Prerequisites:
PTLsim invocation is very simple: after compiling the simulator and making sure the ptlsim executable is in your path, simply run:
ptlsim full-path-to-executable arguments...PTLsim reads configuration options for running various user programs by looking for a configuration file named /home/username/.ptlsim/path/to/program/executablename.conf. To set options for each program, you'll need to create a directory of the form /home/username/.ptlsim and make sub-directories under it corresponding to the full path to the program. For example, to configure /bin/ls you'll need to run "mkdir /home/username/.ptlsim/bin'' and then edit "/home/username/.ptlsim/bin/ls.conf" with the appropriate options. For example, try putting the following in ls.conf as described:
-logfile ptlsim.log -loglevel 9 -stats ls.stats -stopinsns 10000Then run:
ptlsim /bin/ls -laPTLsim should display its system information banner, then the output of simulating the directory listing. With the options above, PTLsim will simulate /bin/ls starting at the first x86 instruction in the dynamic linker's entry point, run until 10000 x86 instructions have been committed, and will then switch back to native mode (i.e. the user code will run directly on the real processor) until the program exits. During this time, it will compile an extensive log of the state of every micro-operation executed by the processor and will save it to ``ptlsim.log'' in the current directory. It will also create ``ls.stats'', a binary file containing snapshots of PTLsim's internal performance counters. The ptlstats program (Chapter 8) can be used to print and analyze these statistics by running ``ptlstats ls.stats''.
PTLsim supports a variety of options in the configuration file of each program; you can run ``ptlsim'' without arguments to get a full list of these options. The following sections only list the most useful options, rather than every possible option.
The configuration file can also contain comments (starting with ``#'' at any point on a line) and blank lines; the first non-comment line is used as the active configuration.
PTLsim supports multiple models of various microprocessor cores; the ``-core corename'' option can be used to choose a specific core. The default core is ``ooo'', the dynamically scheduled out of order superscalar core described in great detail in Part IV. PTLsim also comes with a simple sequential in-order core, ``seq''. It is most useful for debugging decoding and microcode issues rather than actual performance profiling.
PTLsim can log all simulation events to a log file, or can be instructed to log only a subset of these events, starting and stopping at various points:
Specifies the file to which log messages will be written.
Selects a subset of the events that will be logged:
Starts logging only after cycle cycles have elapsed from the start of the simulation.
Starts logging only after the first time the instruction at rip is decoded or executed. This is mutually exclusive with -startlog.
PTLsim also maintains an event log ring buffer. Every time the core takes some action (for instance, dispatching an instruction, executing a store, committing a result or annulling each uop after an exception), it writes that event to a circular buffer that contains (by default) the last 32768 events in chronological order (oldest to newest). This is extremely useful for debugging in cases where you want to ``look backwards in time'' from the point where a specific but unknown ``bad'' event occurred, but cannot leave logging at e.g. ``-loglevel 99'' enabled all the time (because it is far too slow and space consuming).
The event log ring buffer must be enabled via the -ringbuf option. This is disabled by default since it exacts a 25-40% performance overhead (but this is much better than the 10000%+ overhead of full logging).
PTLsim will always print the ring buffer to the log file whenever:
Normally PTLsim starts in simulation mode at the first instruction in the target program (or the Linux dynamic linker, assuming the program is dynamically linked). It may be desirable to skip time-consuming initialization parts of the program, using one of two methods.
The -startrip rip option places a breakpoint at rip, then immediately switches to native mode until that breakpoint is hit, at which point PTLsim begins simulation.
Alternatively, if the source code to the program is available, it may be recompiled with call(s) to a special function, ptlcall_switch_to_sim(), provided in ptlcalls.h. PTLsim is then started with the -trigger option, which switches it to native mode until the first call to the ptlcall_switch_to_sim() function, at which point simulation begins. This function, and other special code that can be used within the target program, is described in Section 9.1.
By default, PTLsim continues executing in simulation mode until the target program exits on its own. However, typically programs are profiled for a fixed number of committed x86 instructions, or until a specific point is reached, so as to ensure an identical span of instructions is executed on every trial, without waiting for the entire program to finish. The following options support this behavior:
The node is at the root of the statistics tree (typically this only applies to the PTLsimStats structure itself)
PTLsim supports the collection of a wide variety of statistics and counters as it simulates your code, and can make regular or triggered snapshots of the counters. Chapter 8 describes this support, while Section 8.1.3 documents the configuration options associated with statistics collection, including -stats, -snapshot-cycles, -snapshot-now.