CVPAV(1) CVPAV(1) NAME cvpav - present the information about an MP Fortran program from its MIPSpro 7.2 or higher analysis files SYNOPSIS cvpav [-e executable] [-f file.f [-anl analysis]] [-F fileset] [-ro {True|False}] [-scheme schemeName] DESCRIPTION cvpav reads the analysis file(s) generated by MIPSpro 7.2 or higher, for the files in a fileset, and displays information about the loops in the files in a window. It allows the user to select any loop, request changes governing that loop, and then install those changes in the source. The analysis file is generated by MIPSpro 7.2 or higher, which is a prerequisite for WorkShop Pro MPF. The analysis file contains the information currently shown on MIPSpro 7.2 or higher, listing file (*.l), and some additional information. cvpav takes that information, and applies some heuristics to present it in a more comprehensible form with a graphical user interface. MIPSpro 7.2 or higher, may be invoked with the -pfa keep flag on the f77 command; the keep flag should always be used; otherwise the analysis file is not written, and cvpav can not be used. COMMAND-LINE OPTIONS cvpav accepts the following command-line options: -e executable specifies a single executable file name as input; the fileset will consist of all the Fortran source files that went into building it. cvpav must always be invoked with the -e flag if it is to be used with the WorkShop Performance Analyzer, to examine performance data recorded for the executable. -f filename.f specifies a single Fortran source file name. -anl analysis specifies the analysis file, if not the default, corresponding to the Fortran file given by the -f filename.f argument. This argument is not normally needed. -F fileset specifies a single text file name as input; the fileset will consist of the Fortran files whose names appear in the input file. Each file name should be on a single line. -ro {True|False} specifies whether cvpav will be able to modify the source files in the fileset (-ro False) or not (-ro True) -scheme schemeName specifies which color scheme should be used for cvpav. X RESOURCES cvpav uses many resources to control its user interface, most of which should not be changed by the user. Those that a user might want to change are: cvpav*readOnly is a Boolean used to determine whether (False) or not (True) cvpav will allow the user to modify the files in its fileset. It defaults to False. cvpav*gDiff is a Boolean used to determine whether (True) or not (False) cvpav will automatically run gdiff to show changes in a source file when it is modified. It defaults to False, so that no gdiff appears. cvpav*runUserEdit is a Boolean used to determine whether (True) or not (False) cvpav will run the userEdit editor command after running the sed script. It defaults to False, so that no editor will be run; rather the new file will be built immediately. cvpav*editorCommand is a string used as a command for a user to edit the file after sed and gdiff have been run on it. It defaults to the following: cvpav*editorCommand: xwsh -e vi %d You may put an alternative command in your .Xdefaults file. The command string should invoke a window shell. If it contains a ``%s'', the filename will replace the ``%s''; if not, the filename will be appended. The command may also contain a ``%d'' which will be replaced by a 1, to position the file at the top line. cvpav*scheme specifies the color and font scheme to be used for cvpav. cvpav*useSmallFonts specifies that small fonts are to be used for cvpav in order to better use screen real-estate. It defaults to False. cvpav*anlFileSuffix specifies the suffix used to construct an analysis file name from the corresponding source file. It defaults to .anl corresponding to MIPSpro 7.2 or higher, normal output. cvpav*trsrcFileSuffix specifies the suffix used to construct the name of the transformed source from the corresponding source file. It defaults to .m corresponding to MIPSpro 7.2 or higher, normal output. USER INTERFACE cvpav initially comes up with a menu bar, a status area, a list pane, a control region, and a Loop Information Pane. MENU BAR The ``Admin'' menu has entries to save the current data as a text file, to Generate a trap file for use by the WorkShop Performance Analyzer, to iconify or raise the windows of the Parallel Analyzer View, or to exit the tool, or to bring up the Icon Legend. It also has a ``Launch Tool'' submenu that will launch the other WorkShop tools, and a ``Project'' menu that will raise or iconify all windows in all tools within the project, remap paths to find source and analysis files, or exit all tools in the project. The ``Views'' menu allows the user to bring up the auxiliary Views. These are the Transformed Loops View, the Subroutine and File View, and the MIPSpro 7.2 or higher, Analysis Parameters View. The ``Fileset'' menu allows the user to add files to or delete files from the fileset. It also contains an entry to rescan all the files. The ``Operations'' menu is used to undo changes to a single loop, or to undo all changes, and to insert new assertions or directives. The ``Configuration'' menu is used to give the user a choice between using OpenMP constructs and directives or old PCF style of constructs and directives. The ``Update'' menu is used to take any changes the user has requested, generate a sed script for them, and run that script on a single file, or on all files in the fileset. It also has two toggles that can be used to control whether or not a gdiff is run to show the changes as made, and whether or not a user editor is invoked after the changes are made, but before the rebuild is started. The default settings for the toggles are taken from the corresponding resources. The ``Help'' menu is used to access on-line help for cvpav. THE STATUS AREA The status area is used to inform the user of the current status of the program, as well as to describe any performance experiment that is in the current project. THE LOOP LIST The upper subpane in the main window is the Loop List. It contains a scrolled list of all the loops in the files belonging to the fileset, with information about the nesting level, and description of each loop. Each loop has an icon next to it which indicates whether the loop is parallel, serial, serial within a parallel loop, optimized away, fused with another loop, or unparallelizable. In addition, a check mark appears next to any loop that has been displayed in the Loop Information Pane (see below), and a plus sign next to the check mark if the user has requested any changes to that loop. The icons are colored differently to show parallel loops, unparallelizable loops, and the various kinds of serial loops. The colors used will match the loop annotation brackets that appear on the two SourceViews that may be brought up. A loop may be selected by double-clicking on the line in the Loop List showing that loop. The ``Next'' and ``Previous'' buttons may be used to step forwards and backwards through the list. If no loop is selected, the ``Next'' and ``Previous'' buttons will select the first loop on the list. A loop may also be selected by clicking in the loop annotation canvas in either SourceView. THE CONTROL AREA The control area contains a search field to find a loop based on any string appearing in its line, sorting and filtering controls, and a row of buttons. The search field is in the upper left of the control area. The sort menu is in the middle left of the control area. It allows sorting in the order the loops appear in the source, or if a Performance Analyzer is part of the current session, in order of performance cost. If the Performance Analyzer is not part of the session, the menu entry for sorting by performance cost will be disabled. Two filtering controls can be used to prune the list. One filters the list according to the type (parallelized, unparallelizable, serial, OpenMP constructs, or modified) of the loops, and the other filters on the basis of either the function (subroutine) or file from which the loop comes. A text area for entering the name of a function or file will appear above the menu when one of the filtering menu entries is selected. Double clicking on a function or file line in the Subroutines and Files View (see below) will select that function or file, and, if the filtering is enabled, will reload the list. Both types of filters may be used simultaneously. If a previously selected loop is in the list after changing the filtering, it will remain selected; if not, no loop will be selected. At the bottom of the control area are buttons to bring up the source for the loop, to bring up the transformed source for the loops derived from that loop, and to step to the next or previous loop. THE LOOP INFORMATION PANE The lower subpane of the main window is the Loop Information Pane. It shows detailed information for whatever loop is currently selected from the Loop List; if no loop is selected, it contains a single line to that effect. The Loop Information Pane shows the loop identification information, and the parallelization status for the loop, with a menu that allows the user to insert directives controlling the parallelization of the loop. Similarly there is a menu for controlling the MP-scheduling of a parallel loop, and a filed for the chunk size to be used; these controls are not meaningful for a non-parallel loop. The pane also shows any assertions or directives controlling the selected loop, and, where applicable, a menu allowing the user to keep or delete them. (Those assertions and directives that control parallelization of the loop do not have menus, as they are handled by the parallelization status menu; For loops that can not be parallelized, it shows the reasons MIPSpro 7.2 or higher, can not parallelize it. The changes will not actually be installed in the source until the update of the file containing that loop is requested using the ``Update'' menu. Some of the lines appearing in the Loop Information Pane have small buttons containing a light-bulb icon next to them. A left mouse click on any of those buttons will bring up and highlight the source for that loop, marking the line(s) or names that apply to the particular line of information selected. For names of variables or functions, the highlighting is applied only within the loop that has been selected, rather than within the entire file. Highlighting variable or function names is done as a token highlight; it will attempt to use FORTRAN rules to determine whether an instance of the named variable is really a reference to the variable or if it is a string that coincidentally matches. It will miss some matches, where, for example, the user has inserted spaces in the middle of the name, or uses a letter in column 6 to indicate a continuation line and no space between it and the variable reference. The WorkShop 2.0/Static Analyzer can be used for a semantically correct search and highlight, since it is based on information output by the FORTRAN compiler. Once all changes for a particular file have been made, the ``Update'' menu can be used to install those changes in the source. When invoked, the file will be moved to a backup file, and a sed script will be written and run to install the changes. If requested, gdiff will be run to show the changes and/or an editor will be invoked to allow additional user changes. After the exit from gdiff and/or the editor, the WorkShop Build Analyzer will be invoked to start a rebuild from the modified sources. It depends on the existence of a Makefile for that purpose. If one exists, and is properly set up, hit the ``Build'' button on the Build Analyzer, and the rebuild will be started. When it completes, it will tell cvpav, which will automatically rescan the file. If no Makefile exists, the Build Analyzer will report the error, and cvpav will post an error asking that cvMIPSpro 7.2 or higher, be run by hand, and that the user then invoke ``Rescan All Files'' from the ``Fileset'' menu. If cvpav is brought up on a program whose analysis file was written by an earlier version of MIPSpro 7.2 or higher, it will post a warning saying the version string was from an older version. Although it will still work, you should rebuild the analysis file with the latest version. THE PARALLELIZATION ICON LEGEND The Icon Legend is brought up from the ``Admin'' menu. It shows each of the icons that are used to describe the parallelization state of any loop in the Loop List, the Loop Information Pane, and the Transformed Loops View, and gives their meaning. It also shows the icons used to describe the read/write status of each of the variables in the loop shown in the Custom DOACROSS Dialog, along with their meanings. Finally, it also shows the icons used in the Subroutines and Files view. THE ORIGINAL AND TRANSFORMED SOURCEVIEWS There are two SourceViews that may be brought up on a loop, one to show the original source, and one to show the source as transformed by MIPSpro 7.2 or higher. They are brought up with buttons at the bottom of the control panel of the main window. When either SourceView is brought up, it will be annotated with loop information, appearing as brackets indicating the range of a loop. The brackets are coded to match the colors of the icons describing the parallelization state of the loop. Clicking the mouse on a bracket will select that loop, either original or transformed, and cause all the other windows to update to reflect the selection. Clicking outside the outer bracket will select the outermost loop; clicking inside the inner bracket will select the innermost loop. Clicking on a line that is not within any loop will be ignored. The Transformed SourceView also will have a vertical bar in the same color as the highlighting of an original loop in the Original SourceView next to each loop in the transformed source that is derived from the selected original loop. If the project also includes a Performance Tool, the SourceViews will additionally be annotated with line-level performance information. For any particular file, only one of the two SourceViews will get performance annotations (the SourceView corresponding to the file that has its line number information in the symbol table). THE TRANSFORMED LOOPS VIEW The Transformed Loops View is brought up from the ``Views'' menu. It lists all the loops into which the selected original source loop was transformed. The first line of description of each loop gives that loop's transformed-ID (an integer). It also has a highlight button which is sensitive to a left-mouse click, and which will show the original source of the program, highlighting those lines that went into the transformed loop. Other lines show messages associated with the transformed loop. Those lines that have highlight buttons are sensitive to left-mouse clicks; clicking on them will mark the relevant source lines. When writing the transformed source, MIPSpro 7.2 or higher, will insert lines bracketing each transformed loop; these lines are of the form: CSGI$ start nnn CSGI$ end nnn where nnn is the transformed-ID of the loop. If the transformed source is being shown, when any of the lines listing a transformed loop in this window is clicked, its source view will highlight all the lines between the start and end lines for that loop, mark their position in the scrollbar, and scroll to the start line. It will also highlight all lines in the original SourceView that went into the selected Transformed Loop. THE SUBROUTINES AND FILES VIEW The Subroutines and Files View is brought up from the ``Views'' menu. It consists of a scrolled list of all the files in the fileset, and the functions contained in each. For a file, the view lists the status of that file, and the date at which the source was last modified. Files that were not scanned will get an icon with an international ``not'' sign; those which were scanned with no errors will get a check mark. If the user has requested changes in any of the loops within the file, a plus sign appears next to the check for the file. For a subroutine, the view shows if there were any syntax errors in it, and it shows the source lines for the function. Functions with syntax errors will get an icon with an international ``not'' sign; those with no errors will get a check mark. Double clicking on a line in this view will select the file or subroutine which it describes, and, if file or subroutine filtering is enabled, will reload the list of loops. THE CUSTOM DOACROSS DIALOG The Custom ``DOACROSS''/``OMP PARALLEL DO'' Dialog is brought up by selecting ``DOACROSS...'' from the loop status menu in the Loop Information Pane. It shows all variables within the loop, with a menu used to select whether they should be treated as local, shared, last- local, or as a reduction variable. Each variable has a highlight button next to it, which can be used to highlight uses of the variable within the loop. Each also has an icon next to it indicating whether the variable is read, written, or both. The DOACROSS Dialog also has a menu for setting the MP scheduling and a text field for entering a chunk size. It also has text fields for affinity, onto, and nest; these are new directives that are supported by MIPSpro 7.2 or higher. It also has a text-entry field to optionally enter an expression that will determine at run-time whether the loop should be run in serial or parallel. When the user is finished composing the custom DOACROSS for a loop, he or she must hit either ``Apply'' to make the changes take, or ``Cancel'' to undo them. The changes will not actually be installed in the source until the update of the file containing that loop is requested using the ``Update'' menu. If the user attempts to switch to a different loop (or perform any manipulation of the fileset or filtering or attempt to exit) with the Custom DOACROSS Dialog up, the program will post a warning asking the user to hit either Apply or Cancel first. THE CUSTOM OMP PARALLEL DO DIALOG The Custom OMP PARALLEL DO Dialog is brought up by selecting ``OMP PARALLEL DO..'' from the loop status menu in the Loop Information Pane. It shows all variables within the loop, with a menu used to select whether they should be treated as local, shared, last-local, or as a reduction variable. Each variable has a highlight button next to it, which can be used to highlight uses of the variable within the loop. Each also has an icon next to it indicating whether the variable is read, written, or both. The OMP PARALLEL DO Dialog also has a menu for setting the MP scheduling and a text field for entering a chunk size. It also has text fields for local, shared, default, firstlocal, lastlocal, copyin, reduction, affinity, onto, and nest; these are new directives that are supported by MIPSpro 7.2.1. It also has a text-entry field to optionally enter an expression that will determine at run-time whether the loop should be run in serial or parallel. When the user is finished composing the custom OMP PARALLEL DO for a loop, he or she must hit either ``Apply'' to make the changes take, or ``Cancel'' to undo them. The changes will not actually be installed in the source until the update of the file containing that loop is requested using the ``Update'' menu. If the user attempts to switch to a different loop (or perform any manipulation of the fileset or filtering or attempt to exit) with the Custom OMP PARALLEL DO dialog up, the program will post a warning asking the user to hit either Apply or Cancel first. If the source file can not be written, or if the read-only flag is supplied as True on the command line or as an X resource, none of the control menus will be operative. Also, if a particular loop comes from an included source file, rather than a file explicitly named in the fileset, it will be treated as read-only, as the program can not tell what effects changing one instance of an included file might have on other instances of it. Environment Variables You can turn off Software Pipelining messages by setting MPF_TESTING environment variable setenv MPF_TESTING SEE ALSO cvd(1), cvperf(1), cvbuild(1), gdiff(1), sed(1) BUGS The detailed list of known problems is given in the release notes chapter 3; please examine it there. Page 8