er_generic(1)er_generic(1)NAMEer_generic - command used to generate an experiment from text files
containing profile information
SYNOPSISer_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 simulated 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 anno‐
tated 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 simulator. 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 interprete 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 locations 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 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 run.
DATA RECORDED
Limitations of profiling
Normally, hardware counter overflow profiling records the call‐
stack 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 timestamp, 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 contexts.
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 resulting experi‐
ment file.
Specifying format using format.txt file
The format.txt file should be placed in the same directory 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 context information
is ignored. If needed, this keyword should be the first
in the file.
clock=N
This sets the clock speed of the simulated processor in
MHz. This is necessary for counters which can be repre‐
sented 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 col‐
umns 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 exe‐
cutable 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 ALSOanalyzer(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.
June 2008 er_generic(1)