xinstrument(1)
NAME
xinstrument - AIMS source code instrumentor with X interface
SYNOPSIS
xinstrument [ options ]
DESCRIPTION
xinstrument serves as a graphical front-end to a number of
source-code instrumentors supported by AIMS (see
batch_inst(1)). All of the operations in xinstrument can be
reduced to manipulations of two basic data data structures:
an application database, and a construct profile.
The application database encapsulates information about the
static structure of the modules in the application. This
information is included in trace files generated by execut-
ing instrumented application programs, and used by trace-
analysis tools - such as VK(1) - to bind events in trace
records to their respective source-code constructs.
The construct profile is a table of flags, one for each con-
struct in the application database. Xinstrument provides
several ways to manipulate this profile. The profile is
used either by the instrumentor to select the constructs to
be instrumented and/or by the monitor to select the instru-
mented constructs to be traced. Only those constructs whose
flag is true in the profile will be instrumented/traced. In
other words, xinstrument can be used to modify the profile
even after the instrumented code has been compiled, specify-
ing that only a subset of the instrumented constructs should
fire at run time.
There are three sections in the top-level window of xinstru-
ment. They are, in order of appearence, the menu bar, the
module table, and the instrument button. On-line help for
most windows in xinstrument can be displayed by pressing the
MOTIF help key (usually F1).
The module table shows a list of all the modules in the
application database. Modules can be loaded into the appli-
cation database either using command-line options (see
below) or by selecting the Load Module option from the File
menu. Modules can be selected from the Load Module(s) menu
by dragging or clicking the left mouse button in the Files
section, and deselected by dragging or clicking the left
mouse button while simultaneously pressing the CTRL key.
When loading or instrumenting modules, it is imperative that
the correct platform be chosen. Currently, there is no
mechanism for automatically determining the platform for
which a given module is intended. The user can select the
appropriate platform for the modules selected in the Files
section by clicking the left mouse button on the Platform
button of the Load Module(s) menu. The default platform can
be specified on the command line.
Double-clicking on a module with the left mouse button
causes the structure of that module to be displayed in a
window. This window shows the module as a tree of con-
structs. Nodes that represent instrumentable constructs
appear as buttons. Items can be selected/deselected from
the construct profile either individually or by groups using
the menu selections at the top of the window. Also, the
user can control which constructs are displayed. Constructs
of a certain type can be displayed (or hidden from view) by
using the view (or unview) menus. Likewise, constructs in a
given subtree can be displayed or hidden, selected or
deselected. See on-line help for more details.
The user can select any number of the entries in the module
table for global operations (e.g. instrument selected
modules, or alter the profile for selected modules).
Prior to parsing each file, it may be necessary to pass the
source code through the preprocessor (as done for C pro-
grams). In such cases it may be necessary to specify what
switches (e.g. -D options for defining macros) need to be
passed. This can be done by clicking on the ``Set Prepro-
cessor Options..'' in the Adanced Options menu or by speci-
fying the shell variable:
AIMS_PP_OPTIONS
The final section of the top-level window is the instrument
button; when it is pressed, xinstrument sends all the files
selected in the module table to the appropriate instrumentor
(as specified by the platform-selection button; see
batch_inst(1) ). Should an error occur during instrumenta-
tion, the user will be notified via a dialog box, but the
text of the error will appear in the shell from which xin-
strument was initiated.
OPTIONS
Below is a list of the command-line options accepted by xin-
strument. Most of these options can also be modified
interactively via the menu bar in the main window.
-adb path
Specify an application database to be loaded. This
option is used for subsequent instrumentation of an
already instrumented application. When the Instrument
button is pressed, a file is created in the output
directory to hold the application database for
inclusion into the trace file.
-oadb path
Specify the name of the file the application database
should be written to when the Instrument button is
pressed. This file is always written into the output
directory. By default, the name of this file is
APPL_DB.
-output path
Specify the directory into which the instrumented
modules should be written. Default is ./inst.
-origin path
Specify the full pathname for the root directory of the
source tree. Default is the current working directory.
-overwrite
This switch overrides a safeguard to keep users from
overwritting an existing application-database file.
The monitor determines which constructs are instru-
mented by examining the application database. If the
database were overwritten, it might not instrument the
proper constructs. False information would be conveyed
to the analysis tools which, in turn, would not display
full information about these constructs.
-verbose
Print each file's name as it is instrumented.
-pp_options switches
Switches passed to the preprocessor for source files.
Settable from the Options menu in the main window.
-platform platform
Select a target platform on which the instrumented code
will be executed. This option can be used several
times on the command line interspersed between the
filenames. Possible values for platform are:
f77-pvm
A FORTRAN77 program using PVM message passing;
f77-mpi
A FORTRAN77 program using MPI message passing;
c-pvm
A C program using PVM message passing;
c-pvm
A C program using MPI message passing.
-help
Print helpful information about command-line options.
In addition, since xinstrument uses the X toolkit command-
line-processing utilities, the user may pass the standard
X-application options (e.g. -fg, -bg, -bw, -xrm). Several
options are also settable via the .Xdefaults file. See AIMS
user's manual for details.
ENVIRONMENT VARIABLES
AIMS_PP_OPTIONS
SEE ALSO
AIMS(1), batch_inst(1), , tally(1), VK(1),
MONITOR(3), MONITOR(5)
The AIMS Reference Manual
AIMS Release 3.7 Last change: 2 July 1997