.\" @(#)loopreport.1 1.2 96/08/30 SMI; .\" Copyright 30 August 1996 Sun Microsystems, Inc. All Rights Reserved. .TH loopreport 1 "03/27/00" .SH NAME loopreport \- print loop timing data to stdout .SH SYNOPSIS .LP .B looptool [ .B \-p .IB path "] [" image-file "] [" timing-file ] .br .sp .B loopreport [ .B \-p .IR path ] .RI [ "image-file" "] [" "timing-file" ] .SH DESCRIPTION .LP .B looptool and .B loopreport produce summaries of loop performance. Compile your f77, f90 or C source files with .BR \-Zlp , run the resulting executable and invoke either .B looptool or .B loopreport. .B looptool is the graphical user interface. .B loopreport is the command line interface, and it writes the summary of loop performance to stdout. .SH NOTE .LP Sun WorkShop Version 6 is the last release that will contain .B loopreport and .B looptool. In later releases their functionality will be incorporated into the Sampling Analyzer. .SH OPTIONS .TP .BI "\-p " Search .I path first for loop timing files. .TP .B "\-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. .SH USAGE The first step is to instrument your program. Compile with the switches .B \-xO3 or .BR \-xO4 , .BR \-xparallel , and .BR -Zlp . If you do not specify either .B -O3 or .BR -O4 , the driver adds .B -O3 to your compile line. If you do not specify .BR -parallel , the .B f77 driver adds .B \-xdepend to your compile line. .LP The .B \-Zlp switch takes an optional argument, .IR n, which instructs the compiler not to instrument loops with a nesting level greater than .I n. By default, all loops are instrumented. If you specify .BR \-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. .LP 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 .I programname.looptimes by default. If you set the environment variable LVPATH, then the timing file is put in the directory LVPATH and named .I pid.programname, where .I pid is the process id, and .I programname is the name of your executable. .LP The third step is to run one of the postprocessors, .B looptool or .B loopreport. If you invoke .B 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 .I vgam is displayed. .LP Both .B looptool and .B 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 .I programname.looptimes. However, if you use the command line option .B \-p .I path then the directory named .I path is searched first for timing files. Next, if the environment variable .SB LVPATH is set, the directory named by .SB LVPATH is searched. Finally, the current working directory is searched for timing files. .LP .B 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. .TP 10 For example, some loop characteristics are .br \(bu loop's beginning source line number .br \(bu loop's nest level .br \(bu is loop parallel or serial? .br \(bu loop contains an MT-unsafe call .br \(bu compiler generated two versions of code for this loop, parallel and serial .br \(bu a variable in the loop caused a data dependence .br \(bu loop is unprofitable to parallelize .br \(bu two or more loops were fused or interchanged (and thus source line numbers may not match runtime data exactly) .br \(bu loop was parallelized because the explicit parallelization pragma was used .br \(bu loop has multiple exits, and therefore timing data may be suspect .br \(bu loops contains I/O .br \(bu loop has backward flow of control .LP Check the manual for the version of Fortran or C you are using to compile your program to make sure that the .B \-Zlp switch is recognized by the compiler. .SH ENVIRONMENT .TP 10 .SB LVPATH If the environment variable .SB LVPATH contains a value, then an instrumented executable will place its loop timing data in that directory, in a file named .I pid.programname. pid is the process id, and .I programname is the value stored in argv[0], minus any path prefixes. .B looptool and .B 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. .TP 10 .SB LD_LIBRARY_PATH If .B 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: .nf .B "% " "setenv LD_LIBRARY_PATH"\fI/local-motif-path\fB: $LD_LIBRARY_PATH .fi .TP 10 .SB 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: .nf .RB "% " "setenv PARALLEL 2" .fi .SH EXAMPLES .nf .BI " % f77 -xO4 -xparallel -Zlp prog.f -o foo" " (instrument foo)" .BI " % foo" " (run foo)" .BI " % looptool foo" " (run looptool)" .BI " % loopreport foo > foo.loopreport" " (create report)" .fi .SH FILES .TP 25 .B programname Instrumented binary .TP .B liblv.a Library that contains loop timing functions; an instrumented executable links with liblv.a. .TP .BI programname .B.looptimes The text file that is silently created by an instrumented executable when it finishes running. It contains the loop timing data. .TP .B loopreport Executable that prints a summary of loop performance data to stdout. .TP .B looptool Executable that displays loop data graphically. .SH SEE ALSO .B f77(1) .br .B f90(1) .br .B cc(1) .br .IR "Analyzing Program Performance With Sun WorkShop" . .br .SH DIAGNOSTICS .LP 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. .SH BUGS .LP 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. .LP 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 \(em this is expected behavior! \(em but it can be misleading.