NAME
er_bit - generates an experiment from data collected on a
bit-instrumented program
SYNOPSIS
er_bit experiment_args target [ debug_args ] bat_args
er_bit experiment_args target bit-snap-file1 [ bit-snap-
file2 ...]
DESCRIPTION
The er_bit command can process instrumentation data from a
run of a program instrumented by bit, and generate a perfor-
mance experiment from that data. The command is not nor-
mally invoked directly by a user, but is invoked by bit,
typically in response to the user collecting count data with
the -c option to collect.
The experiment generated appears as a hardware-counter-
overflow profiling experiment with multiple counters in the
same run, generated on the uninstrumented target. Only
leaf-PCs are captured, no CPU or thread IDs are recorded,
and no timestamps are recorded. The data may be examined
with a GUI program (analyzer) or a command-line version
(er_print).
target is the path name of the executable for which you want
to collect performance data. Programs that are targets for
the er_bit command can be compiled with any optimization
-xO1 or greater, and must be prepared by compiling with -
xbinopt=prepare. In order to see annotated source, targets
should be compiled with the -g flag, and should not be
stripped.
The prepared binaries must be instrumented using bit, then
the resulting instrumented binary (e.g., target.binstr) must
be run on a typical workload. This run creates the instru-
mentation datafile which is used by er_bit to create the
experiment. Typically both these steps are accomplished by
using bit -collect.
When the -er option is provided to bit, bit invokes er_bit
using the first synopsis. er_bit then invokes postopt to
create temporary bit-snap-files which it then uses to create
the experiment. The second synopsis is mostly used for
debugging. It makes use of bit-snap-files which have been
created by a previous invocation of er_bit -vv -keeptmp
-er*.
OPTIONS
If invoked with no arguments, print a usage message.
experiment_args
-C comment
Put the comment, either a single token, or a quoted
string, into the experiment. Up to ten comments may be
provided.
-o experiment-name
Use experiment-name as the name of the experiment to be
recorded. The experiment-name string must end in the
string .er; if not, report an error and do not run the
experiment.
If -o is not specified, record an experiment with a
name in the form stem.n.er, where stem is a string, and
n is a number. If a -g argument is given, use the
string appearing before the .erg suffix in the group
name as the stem prefix; if no -g argument is given,
set the stem prefix to the string test.
If the name is not specified in the form stem.n.er,
and the given name is in use, print an error message
and do not run the experiment. If the name is of the
form stem.n.er, and the name is in use, record the
experiment under a name corresponding to the first
available value of n that is not in use. Issue a warn-
ing if the name is changed.
-d directory_name
Place the experiment in directory directory_name. if
none is given, record into the current working direc-
tory.
-g group_name
Consider the experiment to be part of experiment group
group_name. The group_name string must end in the
string .erg; if not, report an error and do not run the
experiment.
-A option
Control whether or not load-objects used by the target
process should be copied into the recorded experiment.
The allowed values of option are:
Value Meaning
on Archive load objects into the experiment.
off Do not archive load objects into the experi-
ment.
copy Copy and archive load objects into the exper-
iment.
If the user copies experiments onto a different
machine, or reads them on a different machine, the user
should specify -A copy. Note that doing so does not
copy any sources or object files. It is the responsi-
bility of the user to ensure that those files are
accessible on the machine where the experiment is
copied.
-V Print the current version. Do not examine further
arguments, and do no further processing.
-v Print the current version and further detailed informa-
tion about the experiment being generated.
debug_args
-vv Print verbose information about er_bit processing.
-keeptmp
Don't delete temporary files.
-Yo,path
Find postopt using path.
bat_args
All bat (binary analyzer) arguments are passed on by er_bit
when it invokes postopt. See the binary analyzer section of
the bit(1) man page. Any binary analyzer arguments can be
used, and the appropriate reports will be generated, but the
-er arguments are special to er_bit:
-er* At least one bit argument beginning with -er must be
provided in order to create an experiment. Note that
the =<filename> suffix of the -er bit argument can be
omitted when using er_bit. er_bit will create the
necessary temporary file names and pass them on to bit.
See bit(1) for further information about the options.
DATA RECORDED
Program-based metrics
Hardware Counter Overflow Profiling
Count data is recorded as hardware counter overflow
profiling records. The data does not include the CPU
ID, thread ID, and LWP IDs; it is aggregated across all
threads and CPUs. Records generated by er_bit have
only a leaf PC in their callstacks, and PCs refer to
the uninstrumented target. Timestamps are meaningless.
The counters generated depend on the arguments passed
to bit. See bit(1) for information on custom counter
information available by means of filtering options.
Instruction frequency metrics
An er_bit experiment contains summary data describing
the execution frequency of various instructions in the
run. The data is shown in response to the ifreq com-
mand in er_print, and on the Inst.Freq. tab in the
Analyzer.
SEE ALSO
analyzer(1), bit(1), collect(1), er_archive(1), er_cp(1),
er_export(1), er_mv(1), er_print(1), er_rm(1), er_src(1),
and the Performance Analyzer manual.