Man Page er_print.1
NAME
er_print - print an ASCII report from Forte(TM) Developer
(Sun WorkShop(TM)) performance experiments
SYNOPSIS
er_print [ -script script | -command | - ] exper_1 ... exper_n
AVAILABILITY
Part of Forte C, Forte C++, and Forte for High Performance
Computing.
DESCRIPTION
er_print is a utility that generates an ASCII version of the
various displays supported by the Performance Analyzer. The
output is displayed on the standard output. Experiment
files exper_1 ... exper_n are generated using the Sampling
Collector from the Sun WorkShop Debugging window, the col-
lect command, or the dbx collector command. The input argu-
ments to er_print can be either experiment names or experi-
ment group names. An experiment group is defined by a file
that contains the names of the experiments in the group.
Based on the data collected, various metrics of performance
can be computed for functions, callers and callees, source
files, and disassembly listings. The data collected and
metrics generated are described in collector(1). The graph-
ical displays available are described in analyzer(1).
OPTIONS
- Enter interactive mode to read er_print com-
mands from the terminal.
-script script
Read er_print commands from the file script,
which contains one command per line. If the
-script argument is not present, er_print
reads its commands from the terminal or from
the command line.
-command Process the given command.
Multiple options can appear on the command line, and they
are processed in the order they appear. Scripts, - argu-
ments and explicit commands can be mixed in any order. If
no command or script arguments are supplied, er_print enters
interactive mode to read commands from the terminal.
COMMANDS
The commands accepted by er_print are listed below. Any
command can be abbreviated by a shorter string, as long as
the command is unambiguous.
Commands Controlling the Function List
functions
Write the function list with the current set of
metrics.
metrics metric_list
Set the function list metrics. metric_list is a list
of metric keywords separated by colons. Each keyword
is of the form <type><visibility><metric-name>. If the
metric "name" is not in the list, it is appended to it.
<type> can be either "i" for inclusive or "e" for
exclusive. The combinations "ie" and "ei" are expanded:
for example "ie<visibility><metric-name>" is expanded
to "i<visibility><metric-name>:e<visibility><metric-
name>"
<visibility> can be any combination of "." (to show the
metric as a time), "%" (to show it as a percentage),
and "+" (to show it as a count). If the metric can
only be shown as a time or only as a count, "." and "+"
have the same meaning. For hardware counter profiling
experiments, where the counter counts in cycles, the
metric is normally shown as a time ("."); it can be
shown as a count using "+" in its <visibility> field.
The order of appearance of time, percent, and count is
fixed: it is not affected by the order of the charac-
ters in the <visibility> setting.
For example:
metrics i.%user:e.%user
means show inclusive user time and percentage, and
exclusive user time and percentage, in that order.
The default metrics setting is taken from .rc files, as
described under DEFAULTS, below. The current metrics
setting and a list of all metrics available from the
given experiment(s) is printed in response to the
metric_list command, described below.
If a metrics command has an error in it, it is ignored
with a warning, and the previous settings remain in
effect.
metrics default
Restores the default settings for the data recorded.
sort metric_name
Sort the function list by the given metric. For
example:
sort i.user
means to sort by inclusive user time.
fsummary
Loop over the functions, and write the summary metrics
panel for each.
objects
Loop over the load objects, and write each out with the
current metrics.
osummary
Loop over the load objects, and write the summary
metrics panel for each.
Commands Controlling the Callers-Callees List
callers-callees
Loop over the functions, as currently sorted, and write
the callers-callees panel for each, using the last
cmetrics spec.
cmetrics metric_list
Set the caller-callee metrics. The metric_list is
defined in the metrics section, with the addition of
the <type> "a" for attributed.
By default, the caller-callee metrics are set to match
the function list metrics at the time the caller-callee
command is processed, and the attributed metrics are
prepended to all the visible metrics in the function
list.
csort metric_list
Sort the callers and callees within the callers-callees
report for each function by the given metric. The
callers-callees report as a whole is sorted as speci-
fied for the function list. The csort metric must be
either an attributed metric, or the address or name. By
default, it is the attributed metric corresponding to
the function list sort metric at the time the callers-
callees command is processed.
Commands Controlling Source and Disassembly Listings
source { file | function } [N]
Write annotated source of the given file, or of the
file containing the given function. The optional
parameter N is needed for those cases where the file or
function name is ambiguous; in that case the Nth pos-
sible choice is used (with the numbering starting from
1). When an ambiguous name is given without a numeric
specifier, a list of the possible names is written,
without producing the annotated source for any of them.
In all cases, the list of names is of object modules.
If the originally supplied name was recognized as a
function, the name of the function is appended to the
object file name. In addition, the number that could
be used for input as the option N argument is printed.
If there is more than one possibility, and the N sup-
plied is not within the possible range, an error is
reported; if there is only one possibility, any such
error is ignored. Note that, when -source is used on
the command line, the parameter N is not optional, but
must be specified. If it would not be needed, it is
ignored.
The source listing has any selected compiler commentary
interleaved within it. Lines with metrics that are
equal to or exceed a threshold percentage of the max-
imum for that metric within the file have the string
"##" prepended to them, to make it easier to find the
important lines. The threshold and the classes of com-
mentary shown are governed by the preferences setting
for source compiler commentary, scc.
er_print looks for the file containing the selected
function under the absolute pathname as recorded in the
executable. If it is not there, it tries to find a
file of the same basename in the current working direc-
tory, and use it. If you have moved the sources, or
the experiment was recorded in a different file system,
you can put a symbolic link from the current directory
to the real source location in order to see the anno-
tated source.
src { file | function } [N]
Same as source.
disasm { file | function } [N]
Write annotated disassembly of the given file, or of
the file containing the given function. Ambiguities
are resolved in the same way as for the source command.
The disassembly listing has the source and any selected
compiler commentary interleaved within it, if these are
available. Lines with metrics that are equal to or
exceed a threshold percentage of the maximum for that
metric within the file have the string "##" prepended
to them, to make it easier to find the important lines.
The threshold and the classes of commentary shown are
governed by the preferences setting for disassembly
compiler commentary, dcc.
er_print looks for the source file for the specified
disassembly as described for the source command, and
interleaves the source with the disassembly. If the
source file can not be found, the disassembly is shown
without the source and without the compiler commetary.
scc class_list
Specify which classes of compiler commentary are shown
with annotated source. class_list is a colon separated
list of classes. Each of the classes refers to specific
types of messages. The allowed classes are:
b[asic] -- show basic messages from all classes
v[ersion] -- show version messages
w[arn] -- show warning messages
pa[rallel] -- show parallelization messages
q[uery] -- show questions from the compiler
l[oop] -- show loop transformation messages
pi[pe] -- show pipelining messages
i[nline] -- show inlining messages
m[emops] -- show messages about memory operations
f[e] -- show front-end messages
c[g] -- show code generator messages
all -- show all messages
none -- do not show messages
The classes "all" and "none" cannot be used with other
classes.
In addition, the threshold for flagging important lines
can be included in the list with any of the classes.
t[hreshold]=nn
A line is flagged as important if it has a metric value
which is greater than nn percent of the largest value
of that metric on any line in the file. The default
value of nn is 75.
For example:
scc l:pi:t=50
means show loop transformation messages and pipelining
messages, and set the threshold to 50 percent.
If no scc command is given, the default class shown is
"basic". If class_list is not specified, compiler com-
mentary is turned off. The scc command is normally
used only in a .er.rc file.
dcc class_list
Specify which classes of compiler commentary are shown
with annotated disassembly. The class_list specifica-
tion for this command can include any of the scc
classes and the following additional class:
h[ex]
which means show the hexadecimal representation of each
instruction. The same defaults apply as for the scc
command. This command is normally used only in a
.er.rc file.
Commands Listing Experiments, Samples, Threads, and LWPs
exp_list
Display the list of existing experiments. Each experi-
ment is listed with an index, which can be used to
select samples, threads, or LWP's.
sample_list
Display the list of samples processed during the
experiments(s).
lwp_list
Display the list of LWP's processed during the
experiment(s).
thread_list
Display the list of threads processed during the
experiment(s).
Commands Controlling Selectivity: Experiments, Samples,
Threads, and LWPs
sample_select sample_list
sample_list is a sample list, as described below.
lwp_select lwp_list
lwp_list is a LWP list, as described below.
thread_select thread_list
thread_list is a thread list, as described below.
Each of the lists above can be a single number, a range of
numbers (n-m), a comma-separated list of numbers and ranges,
or the explicit string "all". Each list can optionally be
preceeded by an experiment list with a similar format,
separated from the list by a colon (:). Multiple lists can
be concatenated, separated by a plus sign. Lists must not
contain spaces. If no experiment list is included, the list
applies to all experiments.
The experiment selection from any of the select commands is
applied to all three select targets -- threads, LWPs and
samples. For each experiment, if a selection of threads,
LWPs or samples exists, it is retained; if it does not exist
it is set to "all". Selections for experiments not in the
experiment list are turned off.
Some examples:
thread_select 1
selects thread 1 from all experiments.
thread_select all:1
selects thread 1 from all experiments.
thread_select all:1,3,5
selects threads 1, 3, and 5 from all experiments.
thread_select 1,2:all
selects all threads from experiments 1 and 2, as listed
by exp_list.
thread_select 1:1+2:2
selects thread 1 from experiment 1 and thread 2 from
experiment 2.
Commands Controlling Load-object Selectivity
object_list
List the names of available load-object lists.
object_select object1,object2,...
Set the list of active load objects. The names of the
objects can be either full pathnames or the basename.
If the name contains a comma character, it should be
surrounded by double quotes.
Commands Controlling Metrics
metric_list
Display the currently selected function list metrics
and a list of metrics and keyword names that can be
used to reference them in other commands, such as sort.
Some keywords differentiate between metrics specified
as a number (e.total) or as a percentage (e%total).
For hardware counter experiments, where the particular
counter measures any type of cycles, the metric can
also be specified as a time (e.cycles), a percentage
(e%cycles), or a value (e+cycles). The available
metrics depend on the data collected. See the collec-
tor(1) man page.
cmetric_list
Display the currently selected caller-callee metrics
and a list of metrics and keyword names for the
callers-callees report. The list is displayed in the
same way as the metric_list output, except that attri-
buted metrics appear as well.
Commands Controlling the Output
outfile filename
Close any open output file, and open filename for sub-
sequent output. If filename is a dash (-), output is
written to stdout.
limit n
Limit any output to the first n entries of the report,
where n is an unsigned integer.
name { long | short }
Use long or short form of C++ function names.
Miscellaneous Commands
address_space [ experiment-id ]
Write the address space data for the specified experi-
ment. If experiment-id is omitted, the first experi-
ment is selected.
overview [ experiment-id ]
Write the sample list for the specified experiment,
with data for each sample. If experiment-id is omit-
ted, the first experiment is selected.
statistics [ experiment-id ]
Write the execution statistics data for the specified
experiment, aggregating data over the current sample
set. If experiment-id is omitted, the first experiment
is selected.
mapfile load-object mapfilename
Write the map file for the given load object to map-
filename. If mapfilename is dash (-), write the map
file to stdout. The mapfile produced is ordered by
whatever metric is currently set to sort the function
list.
header [ experiment-id ]
Write descriptive information about the specified
experiment. If experiment-id is omitted, the first
experiment is selected.
script script
Process commands from the named script.
help Print help information.
quit Exit interactive mode. If used in a script, no more
commands from that script are processed.
{ Version | version }
Print the current release version.
# ...
Comment line; used in scripts or a .er.rc file.
DEFAULTS
er_print processes a .er.rc file in the current directory,
if present; a .er.rc file in the user's home directory, if
present; and a system-wide er.rc file. Directives from the
files take precedence in the order given above.
These files can contain scc and dcc commands, as described
above. They can also contain the following commands, which
may not appear on the command line or in scripts:
dmetrics metric_list
Specifies the default order and visibility of metrics.
Multiple dmetrics commands can be given in any er.rc
file, and are concatenated. dmetrics from the various
files are concatenated in the order: current directory,
user's home directory, and system.
The metric_list is described under the metrics command
above with the following additions:
The <visibility> can be "!" which means that no version
of the metric is visible. This allows the user to
specify the order of a metric without making it visi-
ble.
Two generic metric names can be specified. "hwc" means
any hardware counter metric, and "any" means any metric
at all.
For all metrics computed from the experiments which
have been loaded, the concatenated list of all dmetrics
is scanned for a match. The first matching entry
determines both the visibility and the ordering of the
metrics on screen and in the metric chooser.
dsort metric_list
Specifies the metric to be used by default for sorting
the function list. In determining the metric to use
for sorting, the dsort specification is scanned, and
the first metric in the metric chooser that matches
will be used for sorting. If the entry in the dsort
metric_list has a <visibility> of "!", the first metric
whose name matches is used, whether it is visible or
not; if any other setting of <visibility> is used, the
first visible metric whose name matches is used. Like
dmetrics, dsort specifications from the various er.rc
files will be concatenated in the order: current direc-
tory, user's home directory, and system.
gdemangle library.so
Set the path to the shared object that supports an API
to demangle C++ function names for other C++ compilers.
The shared object must export the C function,
cplus_demangle(), conforming to the standard GNU
libiberty.so interface. The tools will first try to
open the library specified by the gdemangle directive.
If that fails, or no directive is given, they will try
to open libiberty.so, assuming that LD_LIBRARY_PATH is
set to find it. If that fails, they will try to open
/usr/local/lib/libiberty.so. If that fails, C++ func-
tion names for other C++ compilers will not be deman-
gled.
SEE ALSO
analyzer(1), collect(1), collector(1), dbx(1),
er_archive(1), er_cp(1), er_export(1), er_mv(1), er_rm(1),
er_src(1), workshop(1), libcollector(3), and
Analyzing Program Performance With Sun WorkShop.