er_bit(1)er_bit(1)NAMEer_bit - generates an experiment from data collected on a bit-instru‐
mented program (Solaris only)
SYNOPSISer_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 performance experiment from
that data. The command is not normally 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.
NOTE: er_bit is currently only available on Solaris and OpenSolaris
platforms.
The experiment generated appears as a hardware-counter-overflow profil‐
ing 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 result‐
ing instrumented binary (e.g., target.binstr) must be run on a typical
workload. This run creates the instrumentation 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 directory.
-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 val‐
ues of option are:
Value Meaning
on Archive load objects into the experiment.
off Do not archive load objects into the experiment.
copy Copy and archive load objects into the experiment.
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
responsibility 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 information 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 gener‐
ated 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 execu‐
tion frequency of various instructions in the run. The data is
shown in response to the ifreq command in er_print, and on the
Inst.Freq. tab in the Analyzer.
SEE ALSOanalyzer(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 Ana‐
lyzer manual.
April 2005 er_bit(1)