PIXIE(1)PIXIE(1) NAME pixie - Measures code execution frequency SYNOPSIS pixie [-addlibs lib.so[:lib.so ... :lib.so]] [-addlibs_file file] [-copy] [-counts_file file] [-directory dir] [-dso[32|64]] [-fcncounts] [-[no]autopixie] [-[no]longbranch] [-[no]pids] [-[no]verbose] [-pixie_file file] infile IMPLEMENTATION IRIX systems DESCRIPTION The pixie utility is a performance analysis tool that measures code execution frequency. pixie reads an executable program (infile), partitions it into basic blocks, and writes an equivalent program (infile.pixie) that contains additional code that counts the execution of each basic block. When infile.pixie is run, it generates a counts file (infile.Counts), which can be used as input to prof(1). The prof(1) utility can analyze the counts file and produce a listing of profiling data. A basic block is a program region that is entered only at the beginning and exited only at the end. If the executable file specified by infile contains any calls to dlopen(3), the Dynamic Shared Objects (DSOs) requested are not automatically instrumented. You must pre-instrument all such DSOs using -dso, -dso32, or -dso64. Typically, pixie is invoked from the SpeedShop ssrun(1) command, but it can also be invoked directly (for example, from the command line). pixie supports the following options: -addlibs lib.so[:lib.so ... :lib.so] Specifies DSOs on the command line to add to the library list of the executable file. By default, no libraries are added. -addlibs_file file Specifies DSOs in the named file to add to the library list of the executable file. Blank lines and lines starting with # are ignored. Specify one DSO per line. By default, libpixrt.so is always added; if pixie is running under SpeedShop, libss.so.pix* and libssrt.so.pix* are also added. -copy Produces a copy of the target with function list (map) and arc list (graph) sections but no instrumentation. -counts_file file Writes the counts file to file. The counts file is generated when the executable pixie file (infile.pixie, by default) is executed. By default, the name of the counts file is infile.Counts, which is the name of the original input file with leading directory names removed and .Counts appended. If infile calls sproc(2), sprocspc(2), or fork(2), multiple .Counts files are generated, one for each process in the shared group. In this case, the process id is appended to the name of each .Counts file. -directory dir Writes the output files to dir. By default, pixie writes output to the current directory: ./ . -dso[32|64] Specifies a particular DSO. If -dso is specified, pixie treats the executable file as if it were a DSO generated from a -32 compilation. When used, pixie searches the -32 library directories (and the LD_LIBRARY_PATH environment variable). If -dso32 is specified, pixie treats the executable file as if it were a DSO generated from a -n32 compilation. When used, pixie searches the -n32 library directories (and the LD_LIBRARYN32_PATH environment variable). If -dso64 is specified, pixie treats the executable file as if it were a DSO generated from a -64 compilation. When used, pixie searches the -64 library directories (and the LD_LIBRARY64_PATH environment variable). -fcncounts Produces an instrumented executable that counts invocations of functions and their call sites but not basic block counts or branch counts. -[no]autopixie Prevents or permits pixie to instrument recursively all dynamic shared libraries used by the input file during runtime. pixie keeps the timestamp and checksum from the original executable file. Before automatically instrumenting a shared library, pixie checks all lib.pixie files that it finds that match the lib it is to instrument. If the files match, they are not reinstrumented. This option is not useful if the input file is linked with the ld(1) command's -non_shared option. All DSOs used by the executable file must be instrumented in order for it to work correctly. The default is -autopixie for an executable file. The default is -noautopixie for a DSO. -[no]longbranch When pixie instruments the user program, some transformations can push a branch offset beyond its legal range. This causes pixie to generate warnings about branch offsets being out of range. The -longbranch option directs pixie to transform these instructions into jumps. The default is -nolongbranch. -[no]pids The pids options appends the process id number to the end of the counts file 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(1). If specified, the -nopids option is overridden by any process that issues a fork(2) or sproc(2) system call. The default is -nopids. -[no]verbose Suppresses or prints messages summarizing the binary-to- binary translation process. If printed, the messages are sent to stdout. The default is -noverbose. -pixie_file file Writes the executable pixie output file to file. By default, pixie writes the executable file to file.pixie, where file is the input file name (infile). infile The name of an executable binary file to be used as input to pixie. For example, a.out. ssrun(1) INVOCATION OF pixie(1) If pixie is invoked automatically by the ssrun(1) command, the SpeedShop runtime DSO is inserted into the program. When the program is executed, it generates a SpeedShop experiment file with the appropriate count data. Data are generated if the process exits normally or if it receives 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(3) calls, the DSO requested is automatically instrumented, and the instrumented version added to the process. You can use the elfdump(1) utility to dump out the contents of the various sections added to an executable by pixie. pixie adds its runtime DSO to the liblist of the executable file. The rules that rld(1) uses for LD_LIBRARY_PATH, _RLD_ROOT, and their Application Binary Interface (ABI) variants apply to locating the pixie runtime DSO libpixrt.so. If you are using rld.debug, you must specify the path to the pixified rld. By default, rld.pixie (instead of rld.debug.pixie) is loaded. The following environment variables can be used to specify the path to the pixified rld: PIXIE_RLD_PATH, PIXIE_RLDN32_PATH, and PIXIE_RLD64_PATH. EXAMPLES The following example shows how to generate a counts file and use it as input to prof(1): % f90 myprog.f % a.out % pixie a.out % a.out.pixie % prof a.out.Counts In this example, a.out.Counts could also have been used as input to the cvperf(1) command. FILES The following files are associated with pixie: File Type infile.Counts The file that contains execution information on infile's basic blocks. This file is suitable for further processing by prof(1) or cvperf(1). file.pixie A pixified executable or DSO. infile An executable output file created by the MIPSpro Fortran 90, FORTRAN 77, C, or C++ compilers. NOTES When pixie is invoked directly from the command line, the SpeedShop runtime DSO is not inserted. When the instrumented program (infile.pixie) is run, it generates infile.Counts, which contains the basic block counts. The .Counts file is created even if fatal signals are generated (as long as the executable file does not override the signal handlers set up by the pixie(1) runtime DSO). Some utilities, for example, uncompress(1) and vi(1), treat arguments differently when the name of the program is different. If you are running the program from the command line, you may need to rename myprog.pixie to myprog for example. If you are running the program with ssrun(1), the program assumes 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 that pixie actually executes. However, the new code size does not include 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. When the size(1) command is used on pixie output files, it reports a much larger text size than pixie because size(1) 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 handled specially and typically do not generate a pixie error. For cases in which they cannot be handled, a warning is generated, and you are instructed to use the -longbranch option. pixie does not work with stripped programs, and it generates a fatal error if it is invoked on a stripped executable file. pixie sets the PIXIE_INIT bit of the processor-specific flags in the ELF .dynamic section. This guarantees that initialization code for dynamic shared libraries is executed before any other initialization code. SEE ALSO elfdump(1), ld(1), prof(1), rld(1), size(1), speedshop(1), ssrun(1) fork(2), sproc(2), sprocspc(2) dlopen(3) dso(5)