 |
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 | -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 -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.
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
(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.Programs that are stripped or are optimized by spike or cc -om
are not supported.
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
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.
-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.
Profiling Statistics Options
-stats dstride | icount
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 .Counts 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
-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.If -sigdump is needed,
-pthread is recommended instead of -threads, to avoid possible
synchronization problems.
-lite
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
-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
-version
Prints the tool's version number.
-run
Executes the instrumented program, even if no arguments are specified.
By default, the program is just instrumented for later execution.
-display
Executes the instrumented program, and runs prof with default options
on the resulting .Counts file(s).
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 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.
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
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.
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 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 .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.instrumented-executable
Instrumented shared libraries produced by pixie
.pixie.pid
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
|
Index for
Section 1 |
|
|
Alphabetical
listing for P |
|
 |
Top of
page |
|