pixie(1)pixie(1)NAMEpixie - Instruction-counting profiler for optimization and coverage-
analysis
SYNOPSISpixie [-pthread | -threads] [pixie-option...] [prof-option...] program
[argument...]
pixie-stats dstride [pixie-option...] program [argument...]
See the start of the OPTIONS section below for details of pixie options
that may be essential for the correct execution of the program.
Alternatively, for compatibility with earlier Tru64 UNIX releases:
pixie program [-[no]quiet] [-bbaddrs name] [-bbcounts name] [-[no]pids]
[-o file]
The atom -toolpixie interface is still available, for compatibility
with earlier releases. However, it is now undocumented, and it will be
retired in a future release.
DESCRIPTION
See prof_intro(1) for an introduction to the application performance
tuning tools provided with Tru64 UNIX.
The pixie command creates an instrumented version of a program (pro‐
gram.pixie) that produces a profile of the number of times each
instruction was executed during a test run of the instrumented program.
If you specify program arguments (argument...) or -run, the instru‐
mented program is executed too.
If you specify -display or any of the prof-options, the pixie command
runs the instrumented program and then runs the prof tool (with any
specified prof-options) to display the profile or to save it in a
choice of output file formats.
If you omit the program name, a usage message is printed.
OPERANDS
File name of a fully linked call-shared or nonshared executable to be
profiled. This program should be compiled with the -g or -gn option
(n>=1) to obtain more complete profiling information. If the default
symbol table level (-g0) is used, line number information, static pro‐
cedure names, and file names are unavailable. Inlined procedures are
always profiled as part of their callers, so test-coverage analysis and
procedure-call profiles may be more useful if inlining is disabled.Pro‐
grams that are stripped or are optimized by spike or cc -om are not
supported. An argument needed by the instrumented program to execute
the procedures, lines, and instructions of interest. Multiple arguments
can be specified. They imply -run if any are specified, and they can be
replaced by -run if they are not otherwise needed.
OPTIONS
Options can be abbreviated to three characters, except the prof-
options, which can be abbreviated (usually to one character) as in a
prof command. For example, -qui is interpreted as -quiet and -exc is
-excobj, but -q is -quit and -e is -exclude. (See the -display option
for the supported prof-options.)
For options that specify a procedure name (proc), C++ procedures can
omit the argument type list, though this will match all overloaded pro‐
cedures with that name. To select a specific procedure, specify the
full symbol name (as printed by the nm command). Symbol names contain‐
ing spaces, *, and so on must be quoted.
Essential Options
Some or all of these options may be needed to prevent the instrumented
program malfunctioning: Specify -pthread if the program or any of its
libraries calls pthread_create(3)--for example if it was compiled with
either the -pthread option or the -threads compatibility option. This
will make the collection of profile data thread-safe. The -fork option
is maintained for compatibility with earlier releases. By default,
pixie now profiles subprocesses that do not call exec(2), and produces
separate profiling data files for the forked subprocesses, including
the process id in their file names as if -pids was specified. By
default the pixie code running in the program's process allocates mem‐
ory for its own use at address 38000000000. If the program needs to use
memory between 38000000000 and 3ff00000000, specify the hexadecimal
address that the pixie code should use. Specify -sigdump to force the
instrumented program to write the current profile data to its file(s)
on receipt of the named signal. By default, the program writes the
profiling data file(s) only when the process terminates, but some pro‐
cesses never terminate normally, so this option lets you generate the
file(s) on demand. After a file is written, the instruction-counts of
the profile are all set to zero, so by sending two signals, any inter‐
val of a test run can be profiled, with the second signal's file(s)
overwriting the first. For example, to use the default kill pid command
to signal the program, specify -sigdump TERM. Chose a signal that the
program does not use for another purpose. Does not instrument the pro‐
cedure proc, and excludes its instruction execution count from the
total for the program--for example, to exclude uninteresting procedures
or procedures (such as non-standard assembly code) that instrumentation
would interfere with. If you tell pixie to display the profile, prof's
-Exclude option is implied.
Profiling Statistics Options
By default, pixie profiles the program as if -stats icount is speci‐
fied; that is, it counts how many times each instruction is executed.
The alternative -stats dstride option analyzes the program's
data access patterns, so that the resulting file can be used by
spike(1) to drive data prefetch optimizations. Only the -lite,
-heapbase, -v, -output, -version, and -run options can be used
with this kind of profiling.
File Generating Options
Prevents informational and progress messages from being printed.
Prints the command lines used to instrument the program and to execute
the instrumented program. Names the instrumented program file instead
of the default program.pixie. Specifies the directory to which the
instrumented program writes the profiling data file(s) for each test
run. The default is the current directory. Adds the process-id of the
instrumented program's test run to the name of the profiling data file
produced (that is, program.Counts.pid). By default, the file is named
program.Counts. When profiling a threaded program, specify -threads to
produce a separate profile for each pthread in the program. The files
are named program.Counts[.pid].sequence, where sequence is the thread
sequence number assigned by pthread_create(3). The -threads option
implies the -pthread option for thread-safe profiling.If -sigdump is
needed, -pthread is recommended instead of -threads, to avoid possible
synchronization problems. Modifies the -stats dstride option to pro‐
file faster but potentially less accurately. It may help programs that
cannot tolerate being slowed down by the profiling code, but it may
also reduce the amount of profile-directed optimization that is possi‐
ble.
Shared-Library Profiling Options
Profiles all the shared libraries in addition to the program's exe‐
cutable. If -all was specified, does not profile the shared library
lib. Can be repeated, to exclude multiple libraries. Profiles the
shared library lib. Can be repeated to include multiple libraries.
Searches for shared-libraries in the named directory before searching
the default directories. Can be repeated to make a search path. Use the
same options that were used when linking the program with ld.
Execution Control Options
Prints the tool's version number. Executes the instrumented program,
even if no arguments are specified. By default, the program is just
instrumented for later execution. Executes the instrumented program,
and runs prof with default options on the resulting file(s). Executes
the instrumented program, and runs prof on the resulting file(s). The
following prof options are supported: Reports the profile as an anno‐
tated disassembly. Excludes procedure proc from the profile, but
totals all procedures. Generates file for cc -feedback optimization.
Reports the lines that executed the most instructions. Reports the
callers of each procedure executed. Reports the profile per source
line within each procedure. Merges all files into file. Prints each
procedure's starting line number. Includes only procedure proc in the
profile, but totals all procedures. Includes only procedure proc in
the profile and in the total. Profiles the instructions executed in
each procedure and the calls to procedures. Truncates the report after
n lines or after (cumulative) n percent of the whole. Reports lines
that were not executed. Profiles the whole executable and any shared
libraries. Estimates cycles, assuming cached memory (n=0-2). Updates
the original program executable (program) with the profiling informa‐
tion, for use in future cc -feedback program command(s). Reports pro‐
cedures that were never called.
Compatibility Options
This syntax (option names and options after program name) is recognized
only if no other options and no program arguments are specified, for
compatibility with DIGITAL UNIX V3 and V4 systems: [Permits] or sup‐
presses messages summarizing the binary-to-binary translation process.
Default: -noquiet. Specifies the name of the basic block addresses
file. Default: program.Addrs. Specifies the name of the basic block
counts file. Default: program.Counts. [Disables] or enables the addi‐
tion of the process-id number to the filename of the basic block counts
file. This is useful for collecting data for multiple invocations of
the instrumented program. Default: -nopids. Specifies the name of the
instrumented program. The default is to remove any leading directory
names from program and append
EXAMPLES
The pixie command can be used to instrument an executable program, run
the instrumented executable, and store the resulting profiling informa‐
tion in a feedback file. This process provides profile-directed feed‐
back for the optimization phases of future compiling and linking. For
example: cc -o program -O3 *.c pixie-run program spike -fb program
program
See prof_intro(1) for additional techniques. The profile pro‐
duced by the pixie command can also be used to verify that the
test data has exercised all the code-paths that need to be most
heavily optimized or tested. For example, to check the test cov‐
erage for all the code in a multi-threaded program: cc -g1
-pthread -L. -o program *.c -lapp1-lapp2pixie-pthread-L.
-all -t program
NOTES
If pixie finds any previously instrumented shared libraries in the
working directory, it will reuse them if they meet current require‐
ments, to reduce re-instrumentation costs.
The prof command can also print various reports showing how many times
each instruction, source-line, or procedure was executed, but the cc
-p, cc -pg, hiprof, or uprofile commands can produce more accurate per‐
formance profiles because they reflect the effects of memory-access
delays.
The format of the data files produced by pixie changed in DIGITAL UNIX
Version 4.0. To convert the data files to the industry-standard format,
use the pdtostd command, at the expense of losing profiles for shared
libraries.
Temporary instrumentation files are created in /tmp. Set the TMPDIR
environment variable to a different directory to create the files else‐
where, for example in a disk partition with more space.
RESTRICTIONS
Although the displayed profiles indicate units of cycles, they are not
the actual number of cycles used by the program, because they assume
perfect memory access (for example, zero cache misses and access time).
By default, the units are counts of instructions executed. With the
-truecycles 0|1|2 option, they reflect the number of cycles needed by
the particular instructions, but still assuming perfect memory.
The total time in seconds that prof reports is inaccurate, because mem‐
ory access delays are not included and because pixie cannot account for
programs executing on multiple processors that have different cycle
speeds. The hiprof, uprofile, and cc -p/-pg profilers provide better
CPU-time profiles.
The procedures in system libraries that are used by the POSIX threads
package are not profiled in multi-threaded programs.
Approximate performance estimates are as follows but will vary accord‐
ing to the application and the machine's CPU count, type, and clock
rate. The pixie instrumentation takes ~2s per Mb of program file on a
500-MHz EV6 (21264) Alpha system, using ~10 Mb of memory plus another
~15 Mb per Mb of the largest file. The instrumented files are ~2.5
times the size of the originals, plus ~0.5 Mb of pixie code. Non-
threaded programs run ~10 times slower; threaded programs may run ~20
times slower, or ~100 times slower with per-thread profiling. The
sizes of the pixie and files are each several percent of the size of
the program's text segment.
FILES
Instrumented version of program produced by pixie Instruction-addresses
file (for prof and optimizers) produced by pixie Instruction-counts
file produced by program.pixie Instrumented shared libraries produced
by pixie Temporary file created and deleted in the current and -dirname
path directories.
SEE ALSO
Introduction: prof_intro(1)atom(1), cc(1), dxprof(1), fork(2), hiprof(1), kill(1), ld(1),
pdtostd(1), prof(1), pthread(3), uprofile(1). (dxprof is available as
an option.)
Programmer's Guide
pixie(1)
