PIXIE(1) PIXIE(1)
NAME
pixie - add profiling code to an executable file
SYNOPSIS
pixie file [ options ]
DESCRIPTION
pixie is an object instrumentation tool that can be used to measure code
execution frequency in a program for performance analysis. pixie reads
an executable program, partitions it into basic blocks, and writes an
equivalent program containing additional code that counts the execution
of each basic block. (A basic block is a region of the program that can
be entered only at the beginning and exited only at the end).
Other options allow producing an uninstrumented copy of the executable,
with map and graph sections added, and producing an instrumented
executable for just counting function calls (arcs).
pixie is normally invoked from the SpeedShop ssrun(1) command; when it is
so invoked, the SpeedShop runtime will be inserted into the program, and,
when the program is run, it will generate a SpeedShop experiment file
with the appropriate count data. Data will be generated if the process
exits normally, or received a fatal signal, unless the user has installed
his or her own handler for that signal. If the process invokes any of
the various dlopen() calls, the DSO requested will be automatically
instrumented, and the instrumented version added to the process.
prof(1) can analyze these files and produce a listing of profiling data.
See its man pages for more details.
elfdump(1) can be used to dump out the contents of the various sections
added to an executable by pixie.
pixie(1) adds its runtime DSO(5) to the liblist of the executable. The
normal rules rld(1) uses for LD_LIBRARY_PATH, _RLD_ROOT, and their abi
variants apply to locating the pixie runtime dso libpixrt.so.
DIRECT INVOCATION OF PIXIE
pixie may also be directly invoked by a user, in which case the SpeedShop
runtime is not inserted. When the instrumented program is run, it will
generate a file containing the basic block counts. The pixified
executable will creat a counts file in the event of fatal signals as long
as the executable does not override the signal handlers set up by the
pixie(1) runtime.
The name of the output .Counts file is that of the original program with
any leading directory names removed and ".Counts" appended. If the
program during runtime executes calls to sproc(2) , sprocspc(2) or
fork(2) then multiple ".Counts" files will be generated, one for each
process in the share group. In this case, each ".Counts" file will
additionally have the process id appended to the name. If the process
invokes any of the various dlopen() calls, the DSO requested will NOT be
Page 1
PIXIE(1) PIXIE(1)
automatically instrumented; it is the user's responsibility to pre-
instrument all such DSOs. When instrumenting DSO's it is necessary to
use one of the following switches: -dso, -dso32, -dso64, depending on
whether the DSO is o32, n32, or n64 respectively.
prof(1) can analyze these .Counts files and produce a listing of
profiling data. If the ".Counts" file has a process id number appended
to it, you will need to give prof the full name including the suffix. See
the prof man pages for more details.
OPTIONS
pixie is normally invoked by the ssrun(1) command, and not directly
invoked by a user. It recognizes the following arguments:
-copy
Produce a copy of the target with function list (map) and arc list
(graph) sections, but no instrumentation.
-fcncounts
Produce an instrumented executable that counts function calls and
arc calls, but not basic-block- or branch-counts.
-addlibs lib1.so:lib2.so:...libN.so
Specify one or more DSOs that should be add to the library list of
the executable (if they are not already explicitly there).
Default: no libraries are added.
-pixiefile <name>
Specify the name of the pixiefied executable.
Default: append ".pixie" (or an explicit suffix, as set by -suffix)
to the original name.
-countsfile <name>
Specify the name to be used for the output .Counts file.
Default: append ".Counts" to the original program name.
-suffix <.suffix>
Specify the suffix to be appended to the pixified executable and
DSO.
Default: For an a.out, append ".pixie" (although ssrun(1) always
explicitly sets the suffix). For DSOs, the default suffix depends
on the build architecture of the DSO; for o32 it is ".pix32", for
n32, it is ".pixn32", and for n64 it is ".pix64".
-dso
Treat executable as a o32 DSO.
Performs a search of standard o32 library directories (and
LD_LIBRARY_PATH), and causes a ".pix32" extension to be used.
-dso32
Treat executable as a n32 DSO.
Performs a search of standard n32 library directories (and
Page 2
PIXIE(1) PIXIE(1)
LD_LIBRARYN32_PATH), and causes a ".pixn32" extension to be used.
-dso64
Treat executable as a n64 DSO.
Performs a search of standard n64 library directories (and
LD_LIBRARY64_PATH), and causes a ".pix64" extension to be used.
-directory directory_name
Specify a directory for writing the output file(s).
Default: Current directory, "./".
-[no]autopixie
[Prevents] or permits a recursive instrumenting with pixie of all
dynamic shared libraries used by the input file during runtime.
pixie keeps the timestamp and checksum from the original executable.
Before automatically instrumenting a shared library pixie will check
any <lib>.pixie that it finds matching the <lib> it is to instrument
and sees if the fields match. If so they will not be re-
instrumented. This option is not useful if the input file is non-
shared. All DSO's used by the executable must to be instrumented in
order for it to work correctly.
Default: -autopixie for an executable; -noautopixie for a DSO.
-[no]verbose
[Prevents] or permits messages summarizing the binary-to-binary
translation process.
Default: -noverbose
-[no]longbranch
When pixie instruments the user program, some transformations can
push a branch offset beyond its legal range and pixie will generate
warnings about branch offsets being out of range. The -longbranch
option will cause pixie to transform these instructions into jumps.
Default: -nolongbranch
-[no]pids
This option tells pixie to append the process id number on the end
of the ``.Counts'' name. This is useful if you want to run the
program instrumented with pixie through a variety of tests before
generating the statistics with prof. This option is only needed for
the main program. It will be transferred automatically to the
instrumented DSO's during runtime. The -nopids options will always
be overridden by a process that issues a fork(2) or sproc(2) system
call.
Default: -nopids
The following options are currently supported for compatibility reasons,
but are considered obsolescent, and will eventually be removed. If you
feel they are necessary for your work, please contact us.
Page 3
PIXIE(1) PIXIE(1)
-[no]liblist
[Prevents] or permits printing the names and paths of dynamic shared
libraries used by the input file during runtime. This uses the same
default search path strategy used by rld and prof. This list is
useful for building a dependency list for makefiles and shell
scripts. The name of the file is that of the original program with
any leading directory names removed and ".liblist" appended. While
pixie can not detect and pre-instrument any DSOs that the program
dynamically opens, the SpeedShop runtime does detect them, and will
cause them to be instrumented before proceeding with the dlopen.
Default: -noliblist
-[no]liblistonly
[Prevents] or permits printing the names and paths of dynamic shared
libraries used by the input file during runtime. This is the same as
-liblist except that in this case no other operations are performed.
Default: -noliblistonly
-[no]branchcounts
[Prevents] or permits insertion of extra counters to track whether
each branch instruction is taken or not taken. When this option is
used, prof understands the new information automatically and prints
more statistics.
The information produced:
branch to branch taken
branch to branch untaken
untaken conditional branches
taken conditional branches
taken conditional branches with bnop
untaken conditional branches with bnop
direction-predicted conditional branches with bnop
non-sequential fetches
taken branches per conditional branch
forward taken branches per conditional branch
forward untaken branches per conditional branch
backward taken branches per conditional branch
backward untaken branches per conditional branch
Default: -branchcounts.
-[no]table
[Disable] or enable dumping an ascii map of translations made by
pixie into the file <myprog>.table where <myprog> is the name of the
original object.
Default: -notable
-[no]callcounts
[Disable] or enable collecting function invocation counts. This is
used in conjunction with prof -gprof.
Default: -callcounts
Page 4
PIXIE(1) PIXIE(1)
-threeway hex number
Tell pixie not to transform code around threeway transfers. Such
code lies in libgl.so and exists only on machines which have VGX,GTX
and Reality Engine graphics boards. The number for the Reality
Engine is 0x3000 and the number for VGX and GTX is 0x6000.
Most applications are not affected by this, so it is recommended
this option not be used unless the graphics are obviously behaving
differently from the non-instrumented version. The erroneous
behavior most common is for the graphics to be completely black.
Since pixie currently uses a heuristic to find the threeway patterns
it can be fooled into thinking it has found a threeway transfer when
in fact it has not. Because of this, pixie does not pass the
-threeway flag automatically to the shared object and the user must
run pixie separately on libgl.so when using -threeway.
Default: no threeway support
-mips1
Use the MIPS1 instruction set (R2000, R3000) for output executable.
This option is only useful for translating a mips2 executable into a
mips1 executable. If the executable is mips3 or greater it will have
no affect.
Default: the architecture of the input executable will be
maintained.
SEE ALSO
prof(1), ssrun(1), speedshop(1)
NOTES
Some programs, e.g., uncompress and vi, will treat their arguments
differently when the name of the program is different. If you are
running the program manually, you may need to rename myprog.pixie to
myprog for example. If you are running the program with ssrun, the
program will think it was invoked with the original name.
When pixie reports the size of the old and new code, the numbers are
accurate in that the new code size reported is the size of the code pixie
will actually execute. However, the new code size does not count read-
only data (including a copy of the original text and another data block
the same size as the original text) put into the text section.
size(1) on the pixie output reports a much larger text size than pixie,
since size counts everything in the text segment as text.
Code instrumented by pixie is substantially larger than the original
code. Conditional branches that used to fit in the 16-bit branch
displacement field are specially handled and normally do not generate a
pixie error. In certain cases in which they cannot be handled, a warning
may be generated.
pixie(1) currently cannot handle stripped programs. pixie will give a
fatal error if it is invoked on a stripped executable.
Page 5
PIXIE(1) PIXIE(1)
pixie(1) sets the PIXIE_INIT bit of the processor-specific flags in the
ELF .dynamic section. This guarantees the pixie-inserted initialization
code of a dynamic shared libraries is executed before any other init
code. See ld(1).
Page 6