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 html 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 grafts its runtime code into the executable by invoking ld on an archive library (pixie.a, pixie_32.a, or pixie_64.a) appropriate to the architecture of the program being pixified, and then installing the code relocated by ld into the executable. The directory containing these three libraries is searched for first as PIXIE_LIBRARY_PATH, if that environment variable is set, then as $(_RLD_ROOT)/usr/lib/pixie, if the _RLD_ROOT environment variable is set, and finally under /usr/lib/pixie/. If it is not found, pixie will fail.

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, (provided it terminates normally or via a call to exit(2)). If is to be terminated with a signal such as SIGINT, the program will need to have used a signal handler and leave the program through exit(2).

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), sprocsp(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 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.

-pixie_file <name>

Specify the name of the pixiefied executable. Default: append ".pixie" (or an explicit suffix, as set by -suffix) to the original name.

-counts_file <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; 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 causes a ".pix32" extension to be used.

-dso32

Treat executable as a n32 DSO. Performs a search of standard n32 library directories, and causes a ".pixn32" extension to be used.

-dso64

Treat executable as a n64 DSO. Performs a search of standard n64 library directories, 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]idtrace

[Disable] or enable tracing of both instruction and data memory references. Default: -noidtrace

-[no]itrace

[Disable] or enable tracing of instruction memory references. Default: -noitrace -idtrace_file number Specify a UNIX file descriptor number for the trace output file. Default: 19

OBSOLESCENT OPTIONS

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.

-[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]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. Default: -nopids

-[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]call_counts

[Disable] or enable collecting function invocation counts. This is used in conjunction with prof -gprof. Default: -call_counts

-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.

The -itrace and -idtrace options are supported for only 32 bit nonshared executables in the current release. The output generated by these options is not used by any existing released tools.

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).