CVPAV(1)CVPAV(1)NAMEcvpav - present the information about an MP Fortran program from its
MIPSpro 7.2 or higher analysis files
SYNOPSIScvpav [-e executable] [-f file.f [-anl analysis]] [-F fileset] [-ro
{True|False}] [-scheme schemeName]
DESCRIPTIONcvpav 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)
Page 1
CVPAV(1)CVPAV(1)-scheme schemeName
specifies which color scheme should be used for cvpav.
X RESOURCEScvpav 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.
Page 2
CVPAV(1)CVPAV(1)USER INTERFACEcvpav 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
Page 3
CVPAV(1)CVPAV(1)
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
Page 4
CVPAV(1)CVPAV(1)
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
Page 5
CVPAV(1)CVPAV(1)
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.
Page 6
CVPAV(1)CVPAV(1)
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
Page 7
CVPAV(1)CVPAV(1)
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 ALSOcvd(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
