pixie - Instruction-counting profiler for optimization and coverage-
pixie [-pthread | -threads] [pixie-option...] [prof-option...] program
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]
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 pro-
gram 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
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 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.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 pro-
cedures, 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-
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.
Some or all of these options may be needed to prevent the instrumented pro-
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.
Specify -fork if the program calls any variant of fork(2). It is not
usually needed if the subprocesses also call any variant of exec(2).
The -fork option ensures that forked multi-threaded programs are pro-
filed in a thread-safe way, and it produces separate profiling data
files for the forked subprocesses, including the process id in their
file names as if -pids was specified. Failure to use -fork might lead
to deadlock in the forked child processes.
For compatibility with earlier releases, a default level of fork sup-
port is provided if the executable is non-shared or if libc.so is
instrumented. However, this approach can lead to deadlock and will be
retired in a future release, so specifying -fork is recommended.
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 -sig-
dump TERM. Chose a signal that the program does not use for another
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.
File Generating Options
Prevents informational and progress messages from being printed.
-v Prints the command lines used to instrument the program and to execute
the instrumented program.
Names the instrumented program file instead of the default
Specifies the directory to which the instrumented program writes the
profiling data file(s) for each test run. The default is the current
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 syn-
Shared-Library Profiling Options
Profiles all the shared libraries in addition to the program's execut-
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
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
Executes the instrumented program, even if no arguments are specified.
By default, the program is just instrumented for later execution.
Prints the tool's version number.
Executes the instrumented program, and runs prof with default options
on the resulting .Counts file(s).
Executes the instrumented program, and runs prof on the resulting
.Counts file(s). The following prof options are supported:
Reports the profile as an annotated disassembly.
Excludes procedure proc from the profile, but totals all pro-
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 .Counts files into file.
Prints each procedure's starting line number.
Includes only procedure proc in the profile, but totals all pro-
Includes only procedure proc in the profile and in the total.
Profiles the instructions executed in each procedure and the calls
-quit n [[cum]%]
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 profil-
ing information, for use in future cc -feedback program command(s).
Reports procedures that were never called.
This syntax (option names and options after program name) is recognized
only if no other options and no program arguments are specified, for compa-
tibility 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:
Specifies the name of the basic block counts file. Default:
[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:
Specifies the name of the instrumented program. The default is to
remove any leading directory names from program and append .pixie.
1. The pixie command can be used to instrument an executable program, run
the instrumented executable, and store the resulting profiling infor-
mation in the original executable. This process provides profile-
directed feedback for the optimization phases of future compiling and
linking. For example:
cc -non_shared -o program -feedback program -O3 *.c
pixie -update program
cc -non_shared -o program -feedback program -om -O3 *.c
Forshared libraries, a similar technique that records the profile in a
separate feedback file can be used. For example:
cc -o libexample.so -shared -g1 -O3 lib*.c
cc -o exerciser -O3 exerciser.c -L. -lexample
pixie -L. -incobj libexample.so -run exerciser
prof -pixie -feedback libexample.fb libexample.so \
cc -cord -feedback libexample.fb -o libexample.so -shared \
-g1 -O3 lib*.c
2. 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 cov-
erage 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
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 Ver-
sion 4.0. To convert the data files to the industry-standard format, use
the pdtostd command, at the expense of losing profiles for shared
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.
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 instruc-
tions, 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 pro-
grams executing on multiple processors that have different cycle speeds.
The hiprof, uprofile, and cc -p/-pg profilers provide better CPU-time pro-
The procedures in system libraries that are used by the POSIX threads pack-
age 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 .Addrs and .Counts 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
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.)