qpt2(1) UNIX Programmer's Manual qpt2(1) NAME qpt2 - Quick Program Profiler and Tracer SYNTAX qpt [-a file -f file -fc -O -o file -q -s -t -v] a.out DESCRIPTION qpt2 is an exact and efficient profiler profiler and program tracing system. It rewrites (instruments) a program's exe- cutable file (a.out) by either inserting code to record the execution frequency of every basic block (straight-line sequence of instructions) or control-flow edge or by insert- ing code to trace every instruction and data reference. From the counts, another program qpt2_stats can calculate the execution cost of the procedures in the program. Unlike the Unix tools prof and gprof, qpt2 records exact execution frequency, not a statistical sample. qpt2 operates in two profiling modes. In ``slow'' mode, it places a counter in each basic block in a programin the same manner as the MIPS tool pixie. In ``quick'' mode, qpt2 places counters on an infrequently-executed subset of the edges in a program's control-flow graph. This placement can reduce the cost of profiling up to 3-4 times. The quick algorithm requires more program analysis and consequently slows qpt2 and qpt2_stats. The additional cost to instru- ment a program and report the results, however, is quickly gained back when profiling long-running programs. When tracing a program, qpt2 also produces a trace regenera- tion program that reads the highly compressed trace file and produces a full program trace. The regeneration program is C code that is put into files named: a.out_sma0.c, a.out_sma1.c, etc. The regeneration program can also pro- duce traces of loop executions, function entry and exit, block entry, line numbers, memory allocation and dealloca- tion, and non-local goto's. The default is to produce a complete address (instruction and data) trace. Look at the definitions at the start of each regeneration file for details. The interface to the regeneration program is: qpt_recreate(file, event_function) This function return a non-zero value if the recreation com- pleted or prints an error message and returns zero if the process failed. file is the name of the file containing the trace. "-" means read from standard input. event_function is a function that is passed the addresses from the full trace. Its interface is: Printed 6/2/95 1 qpt2(1) UNIX Programmer's Manual qpt2(1) event_function (type, addr, v1, v2) type is the type of event (instruction execution, memory read, memory write, etc.). See the file qpt_events.h for a complete list of event types. addr is the memory address of the reference. v1 and v2 are auxiliary data passed to the regeneration routine. OPTIONS qpt2 has only a few real options: -s Profile the program in slow mode, with a counter in each basic block. -q Profile the program in quick mode by placing the counters more intelligently (this is the default). -t Trace a program (the default is to profile). -fc Trace a program and trace its child process after a fork system call. Note that a vfork system call cannot be traced. -v Print out interesting statistics about the pro- gram. -O# Inform qpt2 that the program was compiled at optimization level -O#, where # is a small integer that defaults to 2. The rest of the options specify the names of the input and output files: -a file Write the instrumented executable file to a file called ``file''. The default name is formed by appending ``.qpt'' to the name of the executable file, so ``myprog'' is rewritten to ``myprog.qpt''. -o file Arrange for the instrumented program to write its counters or trace to a file named ``file''. The default is to write profiling information to a file whose name is formed by appending ``.QCounts'' to the name of the executable file, so the counts for ``myprog'' are written to ``myprog.QCounts''. The default for a trace is to append ``.QTrace'' to the executable file name, for example: ``myprog.QTrace''. A program trace can also be send to the standard output or stan- dard error file descriptors by specifying the names ``stdout'' or ``stderr'', respectively. In addition, a trace can be written to file Printed 6/2/95 2 qpt2(1) UNIX Programmer's Manual qpt2(1) descriptor n by specifying the file name as: ``+n''. For example, to have a trace program write to file descriptor 19: qpt2 -t -o +19 myprog -f file Read in a feedback file called ``file'' produced by qpt2_stats and use it to place the counters in infrequently executed locations. The feedback file is created by profiling the program and can reduce the cost of quick profiling by up to 35%. a.out is the executable file to be instrumented. EXAMPLE In the following example, the program myprog is profiled while running on a small input data set. The profile is used to build a feedback file, which is used to profile the program again. qpt2 -q myprog myprog.qpt small_input qpt2_stats -Wfb myprog qpt2 -q -fb myprog myprog.qpt2 very_large_input qpt2_stats -q -fb myprog In the following example, the program myprog is traced and the trace regeneration routine is linked with a small driver routine that prints out the trace. qpt2 -t myprog cc -o adtr adtr.c myprog_sma*.c myprog.qpt adtr myprog.QTrace DRIVERS qpt2 comes with two driver routines. adtr.c is a general- purpose driver that performs a small amount of sanity check- ing on the address in the trace and writes all events in a readable format. din.c writes address traces in the format expected by Mark Hill's dineroIII cache simulator. BUGS Quick profiling may produce incorrect counts in programs that execute interprocedural jumps. setjmp/longjmp are interprocedural jumps. These jumps also occur in handwrit- ten code. Printed 6/2/95 3 qpt2(1) UNIX Programmer's Manual qpt2(1) Some compilers put data into the text segment. qpt2 tries very hard to separate the program from its data. If it fails, so does the program. SEE ALSO qpt2_stats(1), prof(1), gprof(1), pixie(1) Thomas Ball and James Larus, ``Optimally Profiling and Trac- ing Programs,'' ACM Transactions on Programming Languages and Systems (TOPLAS), pp. 1319--1360, July 1994. James Larus, ``Abstract Execution: A Technique for Effi- ciently Tracing Programs,'' Software -- Practice Experi- ence, Vol. 20, No. 12, pp. 1241--1258, December 1990. AUTHOR James R. Larus (larus@cs.wisc.edu), Computer Sciences Department, University of Wisconsin-Madison. Printed 6/2/95 4