looptool(1)
NAME
looptool − graphically display loop timing data
SYNOPSIS
looptool [ −p path] [image-file] [timing-file]
loopreport [ −p path] [image-file] [timing-file]
DESCRIPTION
looptool and loopreport produce summaries of loop performance. Compile your f77, f90 or C source files with −Zlp, run the resulting executable and invoke either looptool or loopreport. looptool is the graphical user interface. loopreport is the command line interface, and it writes the summary of loop performance to stdout.
OPTIONS
−p Search path first for loop timing files.
−x Disable usage tracking. Usage tracking is on by default in early access releases. Usage tracking means that when you use the tool, an email message is sent to the developer.
USAGE
The first step is to instrument your program. Compile with the switches −xO3 or −xO4, −xparallel, and -Zlp. If you do not specify either -O3 or -O4, the driver adds -O3 to your compile line. If you do not specify -parallel, the f77 driver adds −xdepend to your compile line.
The −Zlp switch takes an optional argument, n, which instructs the compiler not to instrument loops with a nesting level greater than n. By default, all loops are instrumented. If you specify −Zlp=2, then only the outer two levels of loops are instrumented. This option is provided in case the overhead of instrumenting all loops seems unacceptably high.
The second step is to run the instrumented executable. The instrumented executable silently creates a timing file when it finishes running. The name of the timing file is programname.looptimes by default. If you set the environment variable LVPATH, then the timing file is put in the directory LVPATH and named pid.programname, where pid is the process id, and programname is the name of your executable.
The third step is to run one of the postprocessors, looptool or loopreport. If you invoke looptool without giving it the name of a program, then by default the GUI prompts you with a pop-up window for a program name. If you invoke looptool or loopreport without specifying an executable, the default file fft is displayed.
Both looptool and loopreport read two files: the instrumented executable and its associated timing file. Typically, the timing file resides in the same directory as the executable, and is named programname.looptimes. However, if you use the command line option −p path then the directory named path is searched first for timing files. Next, if the environment variable LVPATH is set, the directory named by LVPATH is searched. Finally, the current working directory is searched for timing files.
looptool represents loop timing data in bar charts. Clicking on a loop’s representation with the first mouse button brings up that loop’s source code in an editor window. Loop characteristics, such as which transformations were applied to the loop, are shown as part of the source code display.
For example, some loop characteristics are
• loop’s beginning source line number
• loop’s nest level
• is loop parallel or serial?
• loop contains an MT-unsafe call
• compiler generated two versions of code for this loop, parallel and serial
• a variable in the loop caused a data dependence
• loop is unprofitable to parallelize
• two or more loops were fused or interchanged (and thus source line numbers may not match runtime data exactly)
• loop was parallelized because the explicit parallelization pragma was used
• loop has multiple exits, and therefore timing data may be suspect
• loops contains I/O
• loop has backward flow of control
Check the manual for the version of Fortran or C you are using to compile your program to make sure that the −Zlp switch is recognized by the compiler.
ENVIRONMENT
LVPATH If the environment variable LVPATH contains a value, then an instrumented executable will place its loop timing data in that directory, in a file named pid.programname. pid is the process id, and programname is the value stored in argv[0], minus any path prefixes. looptool and loopreport search directories for timing files in this order: first, a directory specified with −p on the command line; second, a directory named by LVPATH; finally, the current working directory.
LD_LIBRARY_PATH
If looptool cannot find the Motif library when it starts up (libxm.so) then set this variable to include a path with an appropriate Motif library such as:
% setenv LD_LIBRARY_PATH /local-motif-path: $LD_LIBRARY_PATH
PARALLEL
This variable should be set to the number of processors on your machine, before you compile. For example, if your machine has two processors:
% setenv PARALLEL 2
EXAMPLES
% f77 -xO4 -xparallel -Zlp prog.f -o foo (instrument foo)
% foo (run foo)
% looptool foo (run looptool)
% loopreport foo > foo.loopreport (create report)
FILES
programname Instrumented binary
liblv.a Library that contains loop timing functions; an instrumented executable links with liblv.a.
programname The text file that is silently created by an instrumented executable when it finishes running. It contains the loop timing data.
loopreport Executable that prints a summary of loop performance data to stdout.
looptool Executable that displays loop data graphically.
SEE ALSO
f77(1)
cc(1)
Sun WorkShop: Beyond the Basics.
DIAGNOSTICS
The diagnostics produced by looptool and loopreport are intended to be self-explanatory. Occasional messages may be produced by system calls if a selected file cannot be opened.
BUGS
The loop line numbers and nesting levels may be incorrect. This information is derived by the compiler during its optimization phase, and may not exactly match the source line numbering and source nesting.
Loop times are measured as wallclock elapsed time. If a loop is parallelized, it is credited with the elapsed time for all of the instances of the loop. Thus, inner parallelized loops may sometimes be credited with more elapsed runtime than the outer loop that encompasses the parallelized loop. This is not a bug — this is expected behavior! — but it can be misleading.
SunOS 3.0.1 — Last change: 30 August 1996