Command
Line Interface Specification
Developer Beta Version : November 13,
2005
Table of Contents
Open|SpeedShop
Command Line Definitions
Definitions of Important
Terms
- Experiment: A set of collectors and
executables
bound together to generate performance metrics..
- Collector: Portion of the tool containing logic
that is
responsible for the gathering of the performance metric.
- Metric: The entity, which the collector/experiment
is gathering.
A time, occurrence counter, or other entity, which reflects in some way
on the applications performance and is gathered by a performance
experiment (by the collector).
- Focused experiment: The experiment that is in
current
active context. The last created experiment is usually the
default or focused experiment, however, the expFocus command
will set the
experiment specified in the expFocus
command to be the focused or default experiment.
- Framework: The set of API functions that
allows the user
interface to manage the creation and viewing of performance
experiments. It is the interface between the user interface
and the DPCL and Dyninst components.
Assumptions used in
the Definition of the Commands
- There is a focused (default) experiment id
available to subsequent commands.
- Our tool will not change the focus of
the tool
on an experiment.
It can only be changed or set initially by the user. The one exception
to this is when the experiment is created via the expCreate
command the focus is set to this experiment.
- The user can change the focus at anytime via the expFocus command.
- Commands with no explicit experiment id refer to the currently
focused experiment, e.g. the default experiment.
- There is no experiment context (default) until expCreate command
is successfully completed.
- expCreate with no
application/collector defines an experiment and
returns and experiment id. Collectors/precanned experiments can be
added later. More application
objects can also be added after the expCreate
command is completed.
Invocation of Open|SpeedShop
The openss command supports several
arguments.
It is possible to define an initial experiment and to pipe in a file of
commands
that will be read. Arguments on the command line are processed first,
to
define
any initial experiment; a piped in file is then read and comands in it
are processed;
if any interactive windows are requested, they are then opened and can
provide
additional commands to the Open|SS performance analysis tool.
The Open|SS Commands
The basic functionality of the commands.
The detail meaning of each command.
The details of each command's sub-field.
A simple list of command with their syntax.
Example scenarios that
show command usage and
tool design flow
First the simple command list is presented, then a
more detailed commentary with the commands is presented. Finally, an
"under the hood" commentary is included with the commands to give the
overall actions of the various parts of the Open|SpeedShop tool.
Example 1
This simple scenario will build an experiment that
to run a.out and gather pc sampling information.
It will then run the experiment,
pause the experiment, change an argument to the
experiment, continue the experiment, and finally display the results
of the experiment.
Details of Example 1
Example 2
This simple scenario
will intermingle the creation of experiments and loading of executables
on host1, create several experiments for all executables and start the
experiment running.
Details of Example 2
Example 3
This more complex scenario
will insert and remove instrumentation at various times during
execution
of a program running on several hosts.
Details of Example 3
