NAME
er_generic - command used to generate an experiment from
text files containing profile information
SYNOPSIS
er_generic args target directory [directory2 ...]
DESCRIPTION
The er_generic command can process one or more directories
of text files containing profile data, and generate a simu-
lated performance experiment from that data. The experiment
appears as a hardware-counter-overflow profiling experiment
with multiple counters in the same run. The data may be
examined with a GUI program (analyzer) or a command-line
version (er_print). Since the data does not present time-
ordered information, the Analyzer Timeline is not available
for such an experiment. Similarly, call stack information is
also not available.
target is the path name of the executable for which you want
to collect performance data. Programs that are targets for
the er_generic command can be compiled with any level of
optimization. In order to see annotated source, targets
should be compiled with the -g flag, and should not be
stripped.
Each directory contains various output files that contain
program-counter (PC) and event-counter data from the simula-
tor. All the files within a directory are converted into a
single experiment. If the argument is not a directory the
run fails with an error message. Files that do not contain
valid data are skipped.
Each directory must contain a file named format.txt this
file contains the information that er_generic uses to inter-
prete the files that are to be converted into an analyzer
experiment.
Each directory can contain a file named mapfile.txt which
contains information about the mappings of files to loca-
tions in memory.
OPTIONS
If invoked with no arguments, print a usage message.
-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 run.
DATA RECORDED
Limitations of profiling
Normally, hardware counter overflow profiling records
the callstack of each LWP at the time an overflow
occurs in the hardware counter for the CPU on which the
experiment is running. The data also includes a time-
stamp, the CPU ID, thread ID, and LWP IDs. Records
generated by er_generic have only a leaf PC in their
callstacks. Timestamps are generated, but are meaning-
less. Support for multithreading and multiple-CPU
experiments is not yet available.
The counters available depend on the specific simulated
chip parameters.
Details of file formats
Profile data input file format
The files to be processed by er_generic are text files,
the first line of which is a comment (annotated by "\\
text"). er_generic will expect the format to be defined
in a format.txt file located in the same directory. The
data recorded in the file is multiple space delimited
columns, at a minimum the file should comprise:
context
This is an optional field which is currently
ignored, but will be used in the future for
results of from traces that contain multiple con-
texts.
pc Address of the instruction
event-count
Count of events that occur at that particular pc.
There can be many columns of event-counts, the
columns are defined by the format.txt file.
The resulting lines should look something like:
Context pc event-count1 event-count2 ...
Comments (denoted by \\) are recorded into the result-
ing experiment file.
Specifying format using format.txt file
The format.txt file should be placed in the same direc-
tory as the files to be processed. It can contain the
following case-sensitive commands.
context
This tells er_generic to expect the first column
of data to be a context for the pc. Currently con-
text information is ignored. If needed, this key-
word should be the first in the file.
clock=N
This sets the clock speed of the simulated proces-
sor in MHz. This is necessary for counters which
can be represented as time.
counter=name[,HEX][,TIME]
This defines a particular counter, the counters
should be listed in the format.txt file in the
order that the columns appear in the simulator
output files. Counter values will be interpreted
as decimal, unless the HEX specifier is used. If a
counter represents time in cycles, and should be
shown that way, then the specifier TIME can be
used.
Specifying memory locations using mapfile.txt file
The mapfile specifies where in memory the libraries and
executable are located. Currently only one mapfile.txt
is used because only one context can be specified. The
mapfile contains comma delimited data as follows:
LOAD filename, address, time
filename
Complete path to the file being loaded.
address
Address in memory where the file is loaded
time A time stamp indicating when the file was loaded,
this is currently ignored.
SEE ALSO
analyzer(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.