pixie - Instruction-counting profiler for optimization and
coverage-analysis
pixie [-pthread | -threads] [pixie-option...] [profoption...]
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 -tool pixie interface is still available, for
compatibility with earlier releases. However, it is now
undocumented, and it will be retired in a future release.
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 (program.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 instrumented
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.
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 procedure
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.Programs 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 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 procedures with that name. To select
a specific procedure, specify the full symbol name (as
printed by the nm command). Symbol names containing
spaces, *, and so on must be quoted.
Essential Options [Toc] [Back]
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 memory 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 processes 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 interval 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 procedure 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 [Toc] [Back]
By default, pixie profiles the program as if -stats icount
is specified; 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 [Toc] [Back]
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 threadsafe
profiling.If -sigdump is needed, -pthread is recommended
instead of -threads, to avoid possible synchronization
problems. Modifies the -stats dstride option to profile
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 possible.
Shared-Library Profiling Options [Toc] [Back]
Profiles all the shared libraries in addition to the program's
executable. 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 [Toc] [Back]
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 annotated 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
information, for use in future cc -feedback program
command(s). Reports procedures that were never called.
Compatibility Options [Toc] [Back]
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 suppresses 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 addition 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
The pixie command can be used to instrument an executable
program, run the instrumented executable, and store the
resulting profiling information in a feedback file. This
process provides profile-directed feedback 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 produced 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
coverage for all the code in a multi-threaded program:
cc -g1 -pthread -L. -o program *.c -lapp1
-lapp2 pixie -pthread -L. -all -t program
If pixie finds any previously instrumented shared
libraries in the working directory, it will reuse them if
they meet current requirements, 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 performance 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 elsewhere, for example in a disk partition
with more space.
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 memory 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 according 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.
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.
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)
[ Back ] |
