pixie(1) General Commands Manual pixie(1)
NAME
pixie - Instruction-counting profiler for optimization and coverage-analysis
SYNOPSIS
pixie [-pthread] [-fork] [-heapbase addr] [-sigdump signal] [-E proc]... [-quiet] [-v] [-output file] [-dirname path] [-pids] [-threads]
[-all] [-excobj lib]... [-incobj lib]... [-Lpath]... [-run | -display | prof-option...] program [argument...]
The first few options above may be essential for the correct execution of the program. See the start of the OPTIONS section below for
details, and specify any that are necessary.
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 major release.
DESCRIPTION
The pixie command creates an instrumented version of a program (program.pixie) that produces a profile of the number of times each instruc-
tion 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.
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
procedure names, and file names are unavailable. Inlined procedures are always profiled as part of their callers, so test-coverage analy-
sis 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
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 con-
taining 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. Specify -fork if the program or any of its libraries calls fork(2). The -fork
option ensures that forked multi-threaded programs are profiled in a thread-safe way, and it produces separate profiling data files for the
forked subprocesses, including the process-id in their filenames as if -pids was specified. Failure to use -fork might lead to deadlock in
the forked child processes. This option is usually not needed if the sub-processes call exec(2).
For compatibility with earlier releases, a default level of fork support 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 recom-
mended. 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 nor-
mally, 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.
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.
Shared-Library Profiling Options
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
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 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. Gen-
erates 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. Esti-
mates 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
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
EXAMPLES
The pixie command can be used to instrument an executable program, run the instrumented executable, and store the resulting profiling
information 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
shared libraries, a similar technique that records the profile in a separate feedback file can be used. For example: cc -o libexam-
ple.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
exerciser.Counts cc -cord -feedback libexample.fb -o libexample.so -shared
-g1 -O3 lib*.c
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
NOTES
When shared libraries are profiled (or when -fork or -pthread is specified for a program that was linked -call_shared), pixie places
instrumented versions of the selected shared libraries in the working directory, so the LD_LIBRARY_PATH environment variable is defined by
pixie to tell the loader where to find the instrumented libraries.
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 for-
mat, 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.
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 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.
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
Commands: atom(1), cc(1), dxprof(1), hiprof(1), kill(1), ld(1), pdtostd(1), prof(1), prof_intro(1), uprofile(1). (dxprof is available as
an option.)
Others: fork(2), pthread(3)
Programmer's Guide
pixie(1)