pixie(1)
pixie - add profiling code to an executable file
As shipped in IRIX 6.5.19. Unchanged since IRIX 6.5.
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 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; 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 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. -[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]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. 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).