NAME
er_print - print an ASCII report from one or more perfor-
mance experiments
SYNOPSIS
er_print [ - | -script script | -command | -V ] experiment-list
DESCRIPTION
er_print is a utility that generates a plain-text version of
the various displays supported by the Performance Analyzer.
The output is displayed on the standard output. Experiment
files are generated using the collect command, or the dbx
collector commands. The experiment-list can contain either
experiment names or experiment group names. An experiment
group is defined by a file that contains the names of the
experiments in the group. You can read experiments on des-
cendant processes either by referring to them explicitly or
by constructing an experiment group for them as described in
the collect(1) man page.
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 the collect(1) man page.
The graphical displays available are described in the
analyzer(1) man page.
OPTIONS
Option Meaning
- Enter interactive mode to read er_print com-
mands from the input terminal.
-script script Read er_print commands from the file script,
which contains one command per line.
-command Process the given command.
-V Display version information and exit.
The options are processed in the order they appear. Options
can be repeated. Scripts, - arguments and explicit commands
can be mixed in any order. If no command or script argu-
ments are supplied, er_print enters interactive mode to read
commands from the input terminal. Input from the input ter-
minal is terminated with the quit command.
Any line that ends in \ will have the \ character removed,
and the content of the next line appended before the line is
parsed. There is no limit (other than total memory) to how
many continuation lines you can use. Any arguments that
contain blanks must be surrounded by double quotes ("),
whether on the command line, or read from scripts, or read
from a .er.rc file.
After each command is processed, any error or warning mes-
sages arising from the processing are written. Summary
statistics on the processing can be printed with the
procstats command.
COMMANDS
The commands accepted by the er_print utility 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. The function list includes any load objects
whose functions are hidden with the object_select com-
mand.
metrics metric_spec
Set the function list metrics (the same metrics are
also used for source and disassembly, and for lines and
pcs). metric_spec is a list of metric keywords
separated by colons. For dynamic metrics, that is,
metrics based on measured data, each keyword is of the
form <flavor><visibility><metric-name>. For static
metrics, that is, metrics based on the static proper-
ties of the load objects in the experiments (name,
address, and size), each keyword is of the form
[<visibility>]<metric-name>, with the <visibility> set-
ting being optional.
<flavor> 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 be
shown only as a time or only as a count, "." and "+"
have the same meaning. For hardware counter profiling
experiments, and counters that count 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 static metrics,
"+", ".", and "%" all have the same meaning.
<visibility> can also be specified as a "!", meaning
turn off the metric. It is normally not used, but is
used in the dmetrics command (q.v.), used to set
default metrics to override the built-in visibility
defaults for each type of metric. The same metric may |
not appear multiple times in the metric_spec; if it |
does, it will be reported as an error. |
If the metric "name" is not in the list, it is appended
to it. A list of all the available <metric-name>
values for the experiments loaded can be obtained with
the metric_list command. See the collect(1) man page
for more information on metrics.
By default, use the metric setting based on the
dmetrics command, processed from .er.rc files, as
described under default-setting commands, below. If a
metrics command explicitly sets metric_spec to default,
restore the default settings appropriate to the data
recorded. When metrics are reset, the default sort
metric is set in the new list. If metric_spec is omit-
ted, print the current metrics setting.
In addition to setting the metrics for the function
list, etc., set cmetrics for caller-callees, set
data_metrics for data-derived output, and set
indxobj_metrics to match the metrics settings. See
those commands for further information.
If a metrics command has an error in it, or there are
no metrics in the specification corresponding to the
current data, ignore the command with a warning, and
keep the previous settings in effect.
sort metric_spec
Sort the function list by the given metric. The
metric_spec is described under metrics; it may be pre-
ceeded by a "-" sign, specifying reverse sort. For
example:
sort i.user
means to sort by inclusive user time. The <visibility>
in the metric name does not affect the sort order. If
more than one metric is named in the metric_spec, use
the first one that is visible. If none of the metrics
named are visible, ignore the command.
By default, use the metric sort setting based on the
dsort command, processed from .er.rc files, as
described under default-setting commands, below. If a
sort command explicitly sets metric_spec to default,
use the default settings.
If metric_spec is omitted, print the current sort
metric.
fsummary
Write the summary panel for each function in the func-
tion list, in the order specified by the current sort
metric. Include any load objects in the function list
whose functions are hidden with the object_select com-
mand.
fsingle function_name [N | ADDR]
Write the summary panel for the named function. The
optional parameter is needed for those cases where the
function name is ambiguous; see under the "source" com-
mand for more information.
Commands Controlling the Callers-Callees List
callers-callees
Write the callers-callees panel for each function,
using the last cmetrics specification, in the order
specified by the function sort metric (sort). Within
each caller-callee report, the callers and callees are
sorted by the caller-callee sort metrics (csort).
cmetrics metric_spec
Set the caller-callee metrics. The metric_spec is
defined in the metrics section, with the addition of
the <flavor> "a" for attributed.
By default, set the caller-callee metrics to match the
function list metrics whenever they are changed.
Caller-callee attributed metrics are inserted in front
of the corresponding exclusive and inclusive metrics,
with <visibility> corresponding to the logical or of
the <visibility> setting for those two. Static metric
settings are copied to the caller-callee metrics. If
the metric "name" is not in the list, it is appended to
it. A list of all the available <metric-name> values
for the experiments loaded can be obtained with the
cmetric_list command.
If metric_spec is omitted, print the current caller-
callee metrics setting. If a cmetrics command has an
error in it, ignore it with a warning, and keep the
previous settings in effect.
csingle function_name [N | ADDR]
Write the callers-callees panel for the named function.
The optional parameter is needed for those cases where
the function name is ambiguous; see under the "source"
command for more information.
csort metric_spec
Sort the callers and callees within the callers-callees
report for each function by the given metric. The
csort metric must be either an attributed metric, or a
static metric. If multiple metrics are specified, sort
by the first visible one that matches.
Whenever metrics are set, either explicitly or by
default, set the caller-callee sort metric based on the
function metrics: if sorting is by a dynamic metric,
either inclusive or exclusive, sort by the correspond-
ing attributed metric; if sorting is by a static
metric, sort by it.
If metric-spec is omitted, print the current callers-
callees sort metric.
Commands Controlling Leak and Allocation Lists
leaks
Write the list of leaks, sorted by size, along with the
call stack for each. Aggregate the entries in the leak
list by common call stack.
allocs
Write the list of allocations, sorted by size, along
with the call stack for each. Aggregate the entries in
the allocations list by common call stack.
Commands Controlling Source and Disassembly Listings
pcs Write a list of program counters (PCs) and their
metrics, ordered by the current sort metric. Include
lines in the list that show aggregated metrics for each
load object whose functions are hidden with the
object_select command.
psummary
Write the summary metrics panel for each PC in the PC
list, in the order specified by the current sort
metric.
lines
Write a list of source lines and their metrics, ordered
by the current sort metric. Include lines in the list
that show aggregated metrics for each function that
does not have line-number information, or whose source
file is unknown. Also include lines that show aggre-
gated metrics for each load object whose functions are
hidden with the object_select command.
lsummary
Write the summary metrics panel for each line in the
lines list, in the order specified by the current sort
metric. |
source { filename | function_name } [N | ADDR] ||
Write annotated source of the given object file, or of |
the object file containing the given function. If the |
name of the function is a that of a C++ function or a |
Java method, the demangled name, in either short or |
long form, or the mangled name may be used. If the |
demangled name contains spaces, it must be surrounded |
by double quotes. The optional parameter, N or ADDR, |
is needed for those cases where the filename or func- |
tion name is ambiguous. If the N form is used, pick |
the Nth possible choice (with the numbering starting |
from 1). If there is more than one possibility, and |
the N supplied is not within the possible range, report |
an error; if there is only one possibility, ignore any |
such error. |
If the ADDR form is used, it is written as @segment- |
number:address. The segment-number:address values should be |
specified exactly as they appear as the address metric for |
the function.
If an ambiguous name is given without the specifier, print a
list of choices instead of the annotated source. Each list
item will contain the number that can be used for N, the
name of the object module that references the function or
file and, in the case of an ambiguous function, the function
name.
The default source context for any function is defined as
the source file to which the first instruction in that func-
tion is attributed. It is normally the source file compiled
to produce the object module containing the function.
Immediately following the first instruction, add an index
line for the function. Display index lines as text within
angle brackets in the form shown below:
<Function: f_name>
Alternate source contexts consist of other files that have
instructions in the function attributed to them. Such con-
texts include instructions coming from include files and
instructions from functions inlined into the named function.
If there are any alternate source contexts, include a list
of extended index lines at the beginning of the default
source context to indicate where the alternate source con-
texts are located in the following form:
<Function: f, instructions from source file src.h>
The function name may also be specified as function`file`,
where file is used to specify an alternate source context
for the function.
Note: If the -source argument is used when invoking er_print
on the command line, the backslash escape character must
prepend the file quotes. In other words, the function name
is written as function\`file\`. The backslash is not
required, and should not be used, when er_print is in
interactive mode.
Normally, when the default source context is used, metrics
are shown for all functions from the source file. If the
source file is explicitly used as an alternate source con-
text, metrics will be shown only for the named function.
If any compiler commentary has been selected, interleave the
commentary with the source lines in the source listing.
Prepend the string "##" to lines with metrics that are equal
to or exceed a threshold percentage of the maximum for that
metric within the file, to make it easier for the user to
find the important lines. Govern the threshold and the
classes of commentary to show using the source-threshold
setting, sthresh, and the preferences setting for source
compiler commentary, scc.
Search for the file using the path as specified by a setpath
command. If the file is not found, search under the abso-
lute pathname as recorded in the executable. If the user
has moved the sources, or the experiment was recorded in a
different file system, the user put a symbolic link from the
current directory to the real source location in order to
see the annotated source, or copy the source code and load
objects into the experiment. |
src { filename | function_name } [N | ADDR] ||
Same as source. |
disasm { filename | function_name } [N | ADDR] ||
Write annotated disassembly of the given object file,
or of the object file containing the given function.
Ambiguities are resolved in the same way as for the
source command.
Prepend the line with "##" if the metric value on a
line equals or exceeds a threshold percentage of the
maximum value of that metric. This makes it easier for
the user to find the important lines. The threshold is
set using the dthresh command. The classes of commen-
tary shown are set by the dcc command.
Search for the source file corresponding to the
specified disassembly as described for the source com-
mand, and interleave the the disassembly with the
source and index lines. If the function includes code
from an alternate source context, insert an index line
referring to the alternate context, followed by the raw
disassembly without compiler commentary. If the source
file cannot be found, show the disassembly without the
source and without the compiler commentary.
scc com_spec
Specify which classes of compiler commentary are shown
with annotated source. com_spec 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.
For compatibility, the threshold for flagging important
lines can be included in the list with any of the
classes, including "all" and "none".
t[hreshold]=nn
Flag a line 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, use the default setting:
scc all
If com_spec is not specified, turn off compiler commen-
tary. The scc command is normally used only in a
.er.rc file.
sthresh value
Set the threshold for flagging important lines in the
source. Flag a line as important if it has a metric
value that is greater than value percent of the largest
value of that metric on any line in the file. The
default value of value is 75.
dcc com_spec
Specify which classes of compiler commentary are shown
with annotated disassembly. The com_spec specification
for this command can include any of the scc classes and
the following additional specifications:
h[ex] - show the hexadecimal representation of
each instruction
noh[ex] - do not show the hexadecimal representa-
tion of each instruction
s[rc] - interleave source in disassembly (default)
as[rc] - interleave annotated source, with
source-line metrics, in disassembly
nos[rc] - do not interleave source in disassembly
If no dcc command is given, use the default setting:
dcc all:src
This command is normally used only in a .er.rc file.
cc com_spec
Specify compiler-commentary for both source and
disassembly
dthresh value
Set the threshold for flagging important lines in the
disassembly. Flag a line as important if it has a
metric value which is greater than value percent of the
largest value of that metric on any line in the file.
The default value of value is 75.
setpath path_list
Set the path used to find source, object, etc. files.
path_list is a colon-separated list of directories. If
any directory has a colon character in it, it should be
escaped with a backslash. The special directory name,
$expts, refers to the set of current experiments, in
the order in which they were loaded; it may be abbrevi-
ated with a single $ character.
The default setting is: $expts:.. Use the compiled-in
full pathname if a file cannot be found by searching
the current path.
setpath with no argument means print the current path.
addpath path_list
Append path_list to the current setpath settings.
pathmap old_prefix new_prefix ||
If a file can not be found useing the path_list as set |
by addpath or setpath, one or more path remappings may |
be supplied. Any pathname for a source file, object |
file, or shared object that begins with the old_prefix |
will have that prefix replaced by the new_prefix, and |
the resulting path used to find the file. Multiple |
pathmap commands may be supplied, and they will each by |
tried until the file is found. |
Commands Controlling the Data Space List
Data Space commands are applicable only to hardware counter
experiments where aggressive backtracking was specified, and
for objects in files that were compiled with -xhwcprof.
(Available on SPARC[R] platforms for C or C++ only.) See
the compiler manual for further information.
data_objects
Write the list of data objects with their metrics.
data_single
name [N]
Write the summary metrics panel for the named data
object. The optional parameter N is needed for those
cases where the object name is ambiguous.
data_layout
Write the annotated data object layouts for all program
data objects with data-derived metric data, sorted by
the current data sort metric values for the structures
as a whole. Show each aggregate data object with the
total metrics attributed to it, followed by all of its
elements in offset order, each with their own metrics
and an indicator of its size and location relative to
32-byte blocks.
data_metrics metric_spec
Set the data-derived metrics. The metric_spec is
defined in the metrics section, except only the <fla-
vor> "d", for data-derived, may be used for dynamic
metrics.
By default, set the data-derived metrics to match the
function list metrics whenever they are changed. Set
the data-derived metrics corresponding to any visible
exclusive or inclusive metric that has a data-derived
flavor, with <visibility> corresponding to the logical
or of the <visibility> setting for those two. Copy
static metric settings to the data-derived metrics. If
the metric "name" is not in the list, it is appended to
it.
If metric_spec is omitted, print the current data-
derived metrics setting. A list of all the available
<metric-name> values for the experiments loaded can be
obtained with the data_metric_list command.
If the metric_spec has any errors, it is ignored, and
the data-derived metrics are left unchanged.
data_sort
Set the sort metric for data objects. The prefix "d."
is needed for dynamic metrics, but may be omitted for
static metrics. The data_sort metric must be either a
data-derived metric, or a static metric. If multiple
metrics are specified, sort by the first visible one
that matches.
Whenever metrics are set, either explicitly or by
default, set the data-derived sort metric based on the
function metrics: if sorting is by a dynamic metric,
either inclusive or exclusive, which has a correspond-
ing data-derived flavor, sort by the corresponding
data-derived metric; if sorting is is by an inclusive
or exclusive metric that does not have a data-derived
flavor, sort by the first visible data-derived metric;
if sorting is by a static metric, sort by it.
Commands Controlling the Memory Object Lists
Memory Object commands are applicable only to hardware
counter experiments where aggressive backtracking was speci-
fied, and for objects in files that were compiled with
-xhwcprof. (Available on SPARC[R] platforms for C or C++
only.) See the compiler manual for further information.
Memory Objects are components in the memory subsystem, such
as cache-lines, pages, memory-banks, etc. The object is
determined from an index computed from the virtual and/or
physical address as recorded. Memory objects are predefined
for virtual and physical pages, for sizes of 8KB, 64KB,
512KB, and 4 MB. Others can be defined by the user with the
mobj_define command.
The following commands control the Memory Object Lists.
memobj mobj_type
Write the list of the memory objects of the given type
with the current metrics. Metrics used and sorting
will be as for the Data Space List. The name mobj_type
may also be used directly as the command.
mobj_list
Write the list of known types of memory objects, as
used for mobj_type in the memobj command.
mobj_define mobj_type index_exp
Define a new type of memory objects with a mapping of
VA/PA to the object given by the index_exp. The syntax
of the expression is described under "Expression Gram-
mar", below. The mobj_type must not already be |
defined, and it may not match any existing command, or |
any Index Object type (see below). Its name is case- |
insensitive, and must be entirely composed of |
alphanumeric characters or the '_' character, and begin |
with an alphabetic character. The index_exp must be |
syntactically correct. If not, an error is returned and |
the definition is ignored. If the index_exp contains |
any blanks, it must be surrounded by double quote ("). |
The <Unknown> memory object has index -1, and the
expression used to define a new memory object should
support recognizing <Unknown>. For example, for
VADDR-based objects, the expression should be of the
form:
VADDR>255?<expression>:-1
and for PADDR-based objects, the expression should be
of the form:
PADDR>0?<expression>:-1
Commands Controlling the Index Object Lists |
Index Object commands are applicable to all experiments. An |
Index Object is a class of objects which can be indexed by a |
formula that is computed from the header of a packet. Index |
objects are predefined for Threads, CPUs, Samples, and |
Seconds. Others can be defined by the user with the |
indxobj_define command. |
The following commands control the Index Object Lists. |
indxobj indxobj_type ||
Write the list of the index objects of the given type |
with the current index object metrics. Metrics used |
and sorting will be as for the Function List, but con- |
taining Exlusive metrics only. The name indxobj_type |
may also be used directly as the command. |
indxobj_list ||
Write the list of known types of index objects, as used |
for indxobj_type in the indxobj command. |
indxobj_define indxobj_type index_exp ||
Define a new type of index objects with a mapping of |
packets to the object given by the index_exp. The syn- |
tax of the expression is described under "Expression |
Grammar", below. The indxobj_type must not already be |
defined, and it may not match any existing command, or |
any Memory Object type (see above). Its name is case- |
insensitive, and must be entirely composed of |
alphanumeric characters or the '_' character, and begin |
with an alphabetic character. The index_exp must be |
syntactically correct. If not, an error is returned and |
the definition is ignored. If the index_exp contains |
any blanks, it must be surrounded by double quote ("). |
indxobj_metrics metric_spec ||
Set the index-object metrics. The metric_spec is |
defined in the metrics section, except only the <fla- |
vor> "e", for exclusive, may be used for dynamic |
metrics. |
By default, set the index-object metrics to match the |
function list metrics whenever they are changed. Set |
the exclusive index-object metrics corresponding to any |
visible exclusive or inclusive metric, with <visibil- |
ity> corresponding to the logical or of the <visibil- |
ity> setting for those two. Copy static metric set- |
tings to the index-object metrics. If the metric |
"name" is not in the list, it is appended to it. |
If metric_spec is omitted, print the current index- |
object metrics setting. A list of all the available |
<metric-name> values for the experiments loaded can be |
obtained with the indx_metric_list command. |
If the metric_spec has any errors, it is ignored, and |
the index-object metrics are left unchanged. |
indxobj_sort ||
Set the sort metric for index-objects. The prefix "e." |
is needed for dynamic metrics, but may be omitted for |
static metrics. The data_sort metric must be either a |
exclusive metric, or a static metric. If multiple |
metrics are specified, sort by the first visible one |
that matches. |
Whenever metrics are set, either explicitly or by |
default, set the index-object sort metric based on the |
function metrics: if sorting is by a dynamic metric, |
either inclusive or exclusive, sort by the correspond- |
ing exclusive metric; if sorting is by a static metric, |
sort by it. |
Commands Controlling the Thread Analyzer Reports
races ||
Write the report on any detected groups of data-races |
in the experiment. Data-race reports are available |
only from experiments with data-race-detection data. |
rdetail [ race_id ] ||
Write detailed information on the specified data-race. |
If race_id is given as all, write the detailed informa- |
tion for all data-races. Data-race reports are avail- |
able only from experiments with data-race-detection |
data. |
rsummary [ race_id ] ||
Same as rdetail. |
deadlocks ||
Write the report on any detected deadlocks in the |
experiment. Deadlock reports are available only from |
experiments with deadlock-detection data. |
ddetail [ deadlock_id ] ||
Write detailed information on the specified deadlocks. |
If deadlock_id is given as all, write the detailed |
information for all data-races. Deadlock reports are |
available only from experiments with deadlock-detection |
data. |
dsummary [ deadlock_id ] ||
Same as ddetail. |
Commands Listing Experiments, Samples, Threads, and LWPs
exp_list
Display the list of experiments that are loaded. Each
experiment is listed with an index, which is used when
selecting samples, threads, or LWPs, and a PID, which
can be used for advanced filtering.
sample_list
Display the list of samples processed during the
experiment(s).
lwp_list
Display the list of LWPs processed during the
experiment(s).
thread_list
Display the list of threads processed during the
experiment(s).
cpu_list
Display the list of CPUs used during the experiment(s).
Commands Controlling Filtering of Experiment Data
There are two ways to specify filtering of experiment data,
either by specifying a filter expression, which is evaluated
for each data record to determine whether or not the record
should be included, or with the older commands to select
experiments, samples, threads, CPUs, and LWPs for filtering.
The filtering by expression is controlled by the following
command.
filters filter_exp
filter_exp is an expression which evaluates as true for
any data record that should be included, and false for
records that should not be included.
The grammar of the expression in the filters command is
described under "Expression Grammar", below. If the expres-
sion contains any blanks, it must be surrounded by double
quotes (").
The following old-style commands select the experiments,
samples, threads, CPUs, and LWPs for which data is displayed
for filtering.
sample_select sample_spec
sample_spec is a sample list, as described below.
lwp_select lwp_spec
lwp_spec is a LWP list, as described below.
thread_select thread_spec
thread_spec is a thread list, as described below.
cpu_select cpu_spec
cpu_spec is a CPU 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
preceded 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.
Apply the experiment selection from any of the select com-
mands to all four select targets -- threads, LWPs, CPUs and
samples. Retain each experiment in the experiment list, if a
selection of threads, LWPs, CPUs or samples exists; if no
experiment is specified by the user, select all experiments.
Turn off selections for experiments not in the experiment
list.
Some examples:
thread_select 1
Select 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
Select all threads from experiments 1 and 2, as listed
by exp_list.
thread_select 1:1+2:2
Select thread 1 from experiment 1 and thread 2 from
experiment 2.
Commands Controlling Load Object Function Expand/Collapse
object_list
Display a two-column list showing the status and names
of available load objects. Show the expand/collapse
status in the first column and the name in the second.
Display a selection status of yes if the load object's
functions are shown in the function list (expanded), or
no if its functions are not shown in the function list
(collapsed). All functions for a collapsed load-object
map to a single entry in the function list representing
the entire load object.
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, the name must
be surrounded by double quotes. If a load object is
selected, its functions are expanded, and all func-
tions that have non-zero metrics are shown in the func-
tion list. If a load object is not selected, its func-
tions are collapsed, and only a single line with
metrics for the entire load object instead of its indi-
vidual functions is shown.
By default, select all load objects.
Commands That List 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.
The format of the metric keywords is described under
metrics. The available metrics depend on the data
collected. See the collect(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. Display the list in the same
way as the metric_list output, but include attributed
metrics additionally.
data_metric_list
Display the currently selected data-derived metrics and
a list of metrics and keyword names for all data-
derived reports. Display the list in the same way as
the metric_list output, but include only those metrics
that have a data-derived flavor, and static metrics.
indx_metric_list
Display the currently selected index object metrics and
a list of metrics and keyword names for all index
object reports. Display the list in the same way as
the metric_list output, but include only those metrics
that have a exclusive flavor, and static metrics.
Commands Controlling the Output
outfile filename
Close any open output file and open filename for subse-
quent output. When opening filename, clear any pre-
existing content. If filename is a minus sign (-),
write output to stdout.
If filename is a pair of minus signs (--), write output
to stderr.
appendfile filename
Close any open output file and open filename, preserv-
ing any pre-existing content, so that subsequent output
is appended to the end of the file. If filename does
not exist, the functionality of appendfile is the same
as for outfile.
limit n
Limit any output to the first n entries of the report,
where n is an unsigned integer.
name { long | short | mangled } [:{soname | nosoname }]
Use long or short form of C++ function names. If
soname is specified, append the shared-object name to
the function name.
viewmode { user | expert | machine }
Set the viewing mode to user, expert or machine.
For Java experiments, user mode shows Java call stacks
for Java threads, and does not show housekeeping
threads. The function list includes a function <JVM-
System>, representing aggregated time from non-Java
threads. When the JVM software does not report a Java
call stack, time is reported against the function
<no Java callstack recorded>. Expert mode shows Java
call stack for Java threads when the user's Java code
is being executed, and a machine call stack when JVM
code is being executed or when the JVM software does
not report a Java call stack. It shows machine call
stacks for non-user-Java (housekeeping) threads.
Machine mode shows machine call stacks for all threads.
For OpenMP experiments, user and expert mode are ident-
ical. They show master-thread call stacks and slave-
thread call stacks reconciled, and add special func-
tions, with names of the form <OMP-*> when the OpenMP
runtime is performing certain operations. See the col-
lect(1) man page, or the Performance Analyzer manual
for more information. Machine mode shows machine
callstacks for all threads.
For all other experiments, all three modes show the
same data.
|
Commands That Print Other Information
header [ exp_id ]
Write descriptive information about the specified
experiment. exp_id is the numeric identifier of the
experiment as given by the experiment_list command. If
exp_id is all or is omitted, write the headers of all
experiments. Following each header, print any errors
or warnings. Separate headers for each experiment by a
line of dashes.
If the experiment directory contains a file named
notes, the contents of that file will be prepended to
the header information.
The user is required to enter exp_id on the command
line, but not in a script or in interactive mode.
objects
List the load objects with any error or warning mes-
sages that result from the use of the load object for
performance analysis.
overview [ exp_id ]
Write the sample list for the specified experiment,
with data for each sample. exp_id is the numeric iden-
tifier of the experiment as given by the
experiment_list command. If exp_id is all or is omit-
ted, write overviews for all experiments.
The user is required to enter exp_id on the command
line, but not in a script or in interactive mode.
statistics [ exp_id ]
Write the execution statistics data for the specified
experiment, aggregating data over the current sample
set. exp_id is the numeric identifier of the experiment
as given by the experiment_list command. If exp_id is
omitted, write the sum across all experiments, as
selected by their samples. If exp_id is all, write the
sum and the statistics for the selected samples in each
experiment.
The user is required to enter exp_id on the command
line, but not in a script or in interactive mode.
ifreq ||
Write the instruction-execution summary. Instruction |
frequency reports are available only from experiments |
with count data. (Available for SPARC systems only.) |
Default-setting Commands
Defaults for many of the reports in the er_print utility and
the er_src utility, as well as the displays in the Analyzer,
can be set in a resource file named .er.rc. Both the
er_print utility and the Performance Analyzer process a
system-wide .er.rc file, then a .er.rc file in the user's
home directory, if present, then a .er.rc file in the
current directory, if present. Directives read from each
file take precedence over directives read previously.
Note: Since the defaults for the Analyzer, the er_print
utility, and the er_src utility are all set by a com-
mon .er.rc file, the output of the er_print utility
is affected by saving changes in the Analyzer's Set
Data Preferences dialog, or by using any editor to
change a .er.rc file.
The Analyzer puts a message into its Errors/Warning Logs
areas naming the user .er.rc files it processed. The
er_print utility and the er_src utility print a message to
stderr naming those files.
These files can contain scc, sthresh, dcc, dthresh, setpath,
addpath, pathmap, name, mobj_define and viewmode commands,
as described above. They can also contain the following
commands, which cannot be used on the command line or in
scripts:
dmetrics metric_spec
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_spec 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 visible
by default.
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 that have
been loaded, the concatenated list of all dmetrics is
scanned for a match. The first matching entry deter-
mines both the visibility and the ordering of the
metrics in the function list and the callers-callees
list.
dsort metric_spec
Specifies the metric to be used by default for sorting
the function list. The first metric in the dsort
specification that matches any metric in the
experiment(s) is used to determine the sort metric,
subject to the following conditions. If the entry in
the dsort metric_spec 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 are concatenated in the order:
current directory, user's home directory, and system.
en_desc option
Set the mode for reading descendant experiments accord-
ing to option The allowed values of option are:
Value Meaning
on Show all experiments on descendant processes
off Do not show any experiments on descendant
processes
=<regex> ||
Show those experiments on descendant |
processes whose lineage or executable name |
match the regular expression. |
If any experiments that are loaded have descendants, |
and en_desc is set to off, a message is printed from |
er_print and a popup is posted from the Performance |
Analyzer. |
Default-setting Commands that only Affect the Performance
Analyzer
tabs tab_spec
Set the default set of tabs to be visible in the
Analyzer. The tabs are named by the er_print command
that generates the corresponding reports; in addition,
timeline specifies the Timeline tab, and headers speci-
fies the Experiments tab. Only those tabs that are
supported by the data in the loaded experiments are
shown.
rtabs tab_spec ||
Set the default set of tabs to be visible in the |
Analyzer, when invoked with the tha command (as opposed |
to being invoked as analyzer). |
tlmode tl_mode
Set the display mode options for the Timeline tab.
tl_mode is a colon-separated list of options, which are
described in the following table.
Value Meaning
lw[p] Display events for LWPs
t[hread] Display events for threads
c[pu] Display events for CPUs
r[oot] Align call stack at the root
le[af] Align call stack at the leaf
d[epth]=nn
Set the maximum depth of the call stack that
can be displayed
lwp, thread, and cpu are mutually exclusive, as are
root and leaf. If more than one mutually exclusive
option is specified, only the last one is used.
tldata tl_data
Select the default data types shown in the Timeline.
tl_data is a colon-separated list of types, which are
listed in the following table.
Value Meaning
sa[mple] Display sample data
c[lock] Display clock profiling data
hw[c] Display hardware counter profiling data
sy[nctrace]
Display thread synchronization tracing data
mp[itrace]
Display MPI tracing data
he[aptrace]
Display heap tracing data
Miscellaneous Commands
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. Order the mapfile produced using the
metric currently set to sort the function list.
procstats
Print the accumulated statistics from processing data.
script script
Process commands from the named script.
version
Print the current release version of er_print.
quit Exit interactive mode. If used in a script, no more
commands from that script are processed.
help Print help information.
# ...
Comment line; used in scripts or a .er.rc file.
Expression Grammar
A common grammar is used for an expression defining a
filter, and an expression used to compute a memory object
index.
The grammar specifies an expression as a combination of
operators and operands. For filters, if the expression
evaluates to true, the packet is included; if the expression
evaluates to false, the packet is excluded. For memory
objects, the expression is evaluated to an index that
defines the particular memory object referenced in the
packet.
Operands in an expression are either constants, or fields
within a data record, including THRID, LWPID, CPUID, STACK, |
LEAF, VIRTPC, PHYSPC, VADDR, PADDR, DOBJ, TSTAMP, SAMPLE, |
EXPID, PID, or the name of a memory object. |
VIRTPC, PHYSPC, VADDR, and PADDR are non-zero only when "+" |
is specified for Hardware-counter- or clock-profiling. |
Furthermore, VADDR will be less than 256 when the real vir- |
tual address could not be determined. PADDR will be zero if |
VADDR could not be determined, or if the virtual address |
could not be mapped to a physical address. Likewise, VIRTPC |
will be zero if backtracking failed, or was not requested, |
and PHYSPC will be zero if either VIRTPC is zero, or the |
VIRTPC could not be mapped to a physical address.
Operators include the usual logical operators and arithmetic
(including shift) operators, in C notation, with C pre-
cedence rules, and an operator for determining whether an
element is in a set (IN) or whether any or all of a set of
elements is contained in a set (SOME IN or IN, respec-
tively). If-then-else constructs are specified as in C,
with the ? and : operators. Parentheses should be used to
ensure proper parsing of all expressions. On the er_print
command-line, the expression cannot be split across lines.
In scripts, or on the command-line, the expression must be
inside double quotes if it contains any blanks.
Filter expressions evaluate to a boolean, true if the packet
should be included, and false if it should not be included.
Thread, TWP, CPU, experiment-id, process pid, and sample
filtering are based on a relational expression between the
appropriate keyword and an integer, or using the IN operator
and a comma-separated list of integers.
Time-filtering is used by specifying one or more relational
expressions between TSTAMP and a time, given in integer
nanoseconds from the start of the experiment whose packets
are being processed. Times for samples can be obtained from
the overview command; Times in the overview command are
given in seconds, and must be converted to nanoseconds for
time-filtering. Times can also be obtained from the
Analyzer's Timeline display.
Function filtering can be based either on the leaf function,
or on any function in the stack. Filtering by leaf function
is specified by a relational expression between the LEAF
keyword and an integer function id, or using the IN operator
and the construct FNAME("<regex>"), where <regex> is a regu-
lar expression, as specified on the regex(5) man page. The
entire name of the function, as given by the current setting
of name, must match.
Filtering based on any function in the call stack is speci-
fied by determining if any function in the construct
FNAME("<regex>") is in the array of functions represented by
the keyword STACK:
(FNAME("myfunc") SOME IN STACK)
Data object filtering is analogous to stack function filter-
ing, using the DOBJ keyword and the construct
DNAME("<regex>") enclosed in parentheses.
Memory object filtering is specified by using the name of
the memory object, as shown in the mobj_list command, and
the integer index of the object, or the indices of a set of
objects. (The <Unknown> memory object has index -1.)
Data object filtering and memory object filtering are mean-
ingful only for hardware counter packets with dataspace
data; all other packets are excluded under such filtering.
Direct filtering of virtual addresses or physical addresses
is specified by a relational expression between VADDR or
PADDR, and the address.
Memory object definitions (the mobj_define command) use an
expression that evaluates to an integer index, using either
the VADDR keyword or PADDR keyword. They are applicable
only to hardware counter packets for memory counters and
dataspace data. The expression should return an integer, or
-1 for the <Unknown> memory object.
COMPATIBILITY
er_print works on experiments recorded with earlier versions
of the tools (Forte Developer 7 or later), but may not work
on experiments recorded with future versions. If invoked on
such experiments, a warning is printed. Use the version of
er_print from the release with which the experiment was
recorded. A warning is also posted when reading any experi- |
ment recorded with versions prior to Sun Studio 12, saying |
that the experiments will not be readable with future |
releases. |
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), libcollector(3), tha(1), regex(5), and the Per-
formance Analyzer manual.