Command
Line
Interface
Specification
Version 2.1 Release
August 9, 2014
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 MRNet
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.
- The commands are not case sensitive. So,
expcreate
and expCreate are treated exactly the same.
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|SpeedShop Command Information
Sections
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.
Online Mode of Operation: 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
Online Mode of Operation: 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
Online Mode of Operation: 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
