er_generic - command used to generate an experiment from text files containing profile information
er_generic args target directory [directory2 ...]
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 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 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.
If invoked with no arguments, print a usage message.
Put the comment, either a single token, or a quoted string, into the experiment. Up to ten comments may be provided.
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 warning if the name is changed.
Place the experiment in directory directory_name. if none is given, record into the current working directory.
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.
Control whether to perform archiving as part of data collection. Archiving is required to make an experiment self-contained and portable. The allowed values of option are:
Archive the target and all load objects referenced into the experiment.
Copy and archive all source files and .anc files that can be found into the experiment.
Copy and archive all source files and .anc files that are referenced in the recorded data and can be found into the experiment.
Do not 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.
Print the current version. Do not examine further arguments, and do no further processing.
Print the current version and further detailed information about the experiment being run.
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 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 meaningless. Support for multithreading and multiple-CPU experiments is not yet available.
The counters available depend on the specific simulated chip parameters.
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:
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.
Address of the instruction
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 experiment 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.
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.
This sets the clock speed of the simulated processor in MHz. This is necessary for counters which can be represented as 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.
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
Complete path to the file being loaded.
Address in memory where the file is loaded
A time stamp indicating when the file was loaded, this is currently ignored.
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)
Performance Analyzer manual