 |
Index for
Section 1 |
|
 |
Alphabetical
listing for P |
|
 |
Bottom of
page |
|
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]
To use the atom -tool pixie interface, see pixie(5). Note that pixie(5)
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
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.
OPERANDS
program
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.
argument
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 containing spaces, *, and
so on must be quoted.
Essential Options
Some or all of these options may be needed to prevent the instrumented
program malfunctioning:
-pthread
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.
-fork
Specify -fork if the program was linked -call_shared and it or any of
its libraries calls fork(2). This option is implied if libc.so is
selected for instrumentation. 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,
appending the process-id as if -pids was specified.
-heapbase addr
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.
-sigdump signal
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.
-E proc
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
-quiet
Prevents informational and progress messages from being printed.
-v Prints the command lines used to instrument the program and to execute
the instrumented program.
-output file
Names the instrumented program file instead of the default
program.pixie.
-dirname path
Specifies the directory to which the instrumented program writes the
profiling data file(s) for each test run. The default is the current
directory.
-pids
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.
-threads
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.
Shared-Library Profiling Options
-all
Profiles all the shared libraries in addition to the program's
executable.
-excobj lib
If -all was specified, does not profile the shared library lib. Can be
repeated, to exclude multiple libraries.
-incobj lib
Profiles the shared library lib. Can be repeated to include multiple
libraries.
-Lpath
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
-run
Executes the instrumented program, even if no arguments are specified.
By default, the program is just instrumented for later execution.
-display|prof-option...
Executes the instrumented program, and runs prof on the resulting
.Counts file(s). The following prof options are supported:
-asm
Reports the profile as an annotated disassembly.
-exclude proc
Excludes procedure proc from the profile, but totals all
procedures.
-feedback file
Generates file for cc -feedback optimization.
-heavy
Reports the lines that executed the most instructions.
-invocations
Reports the callers of each procedure executed.
-lines
Reports the profile per source line within each procedure.
-merge file
Merges all .Counts files into file.
-numbers
Prints each procedure's starting line number.
-only proc
Includes only procedure proc in the profile, but totals all
procedures.
-Only proc
Includes only procedure proc in the profile and in the total.
-procedures
Profiles the instructions executed in each procedure and the calls
to procedures.
-quit n [[cum]%]
Truncates the report after n lines or after (cumulative) n percent
of the whole.
-testcoverage
Reports lines that were not executed.
-totals
Profiles the whole executable and any shared libraries.
-truecycles n
Estimates cycles, assuming cached memory (n=0-2).
-update
Updates the original program executable (program) with the
profiling information, for use in future cc -feedback program
command(s).
-zero
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:
-[no]quiet
[Permits] or suppresses messages summarizing the binary-to-binary
translation process. Default: -noquiet.
-bbaddrs name
Specifies the name of the basic block addresses file. Default:
program.Addrs.
-bbcounts name
Specifies the name of the basic block counts file. Default:
program.Counts.
-[no]pids
[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.
-o file
Specifies the name of the instrumented program. The default is to
remove any leading directory names from program and append .pixie.
EXAMPLES
1. 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 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 \
exerciser.Counts
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
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 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.
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 .Addrs and .Counts files
are each several percent of the size of the program's text segment.
FILES
program.pixie
Instrumented version of program produced by pixie
program.Addrs
Instruction-addresses file (for prof and optimizers) produced by pixie
program.Counts[.pid][.sequence]
Instruction-counts file produced by program.pixie
lib*.so.pixie*
Instrumented shared libraries produced by pixie
.pixie.pid
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), pixie(5)
Programmer's Guide
|
Index for
Section 1 |
|
|
Alphabetical
listing for P |
|
 |
Top of
page |
|