| Program Performance Analysis Tools |    
|
| Program Performance Analysis Tools |
|
| C H A P T E R 8 |
|
Manipulating Experiments and Viewing Annotated Code Listings |
This chapter describes the utilities which are available for use with the Collector and Performance Analyzer.
This chapter covers the following topics:
Experiments are stored in a hidden directory, which is created by the Collector. To manipulate experiments, you cannot use the usual Unix commands cp, mv and rm. Three utilities which behave like the Unix commands have been provided to copy, move and delete experiments. These are er_cp(1), er_mv(1) and er_rm(1), and are described below.
The visible experiment file contains an absolute path to the experiment when the experiment is created. If you change the path without using one of these utilities to move the experiment, the path in the experiment no longer matches the location of the experiment. Running the Analyzer or er_print on the experiment in the new location either does not find the experiment, because the path is not valid, or finds the wrong experiment, if a new experiment has been created in the old location. The utilities remove the path from the experiment name when they copy or move an experiment.
The data in the experiment includes archive files for each of the load objects used by your program. These archive files contain the absolute path of the load object and the date on which it was last modified. This information is not changed when you move or copy an experiment.
er_cp [-V] experiment-list directory
The first form of the er_cp command copies experiment1 to experiment2. If experiment2 exists, er_cp exits with an error message. The second form copies a blank-separated list of experiments to a directory. If the directory already contains an experiment with the same name as one of the experiments being copied, er_mv exits with an error message. The -V option prints the version of er_cp.
er_mv [-V] experiment-list directory
The first form of the er_mv command moves experiment1 to experiment2. If experiment2 exists, er_mv exits with an error message. The second form moves a blank-separated list of experiments to a directory. If the directory already contains an experiment with the same name as one of the experiments being moved, er_mv exits with an error message. The -V option prints the version of er_mv.
Removes a list of experiments or experiment groups. When experiment groups are removed, each experiment in the group is removed then the group file is removed. The -f option suppresses error messages and ensures successful completion, whether or not the experiments are found. The -V option prints the version of er_rm.
Annotated source code and annotated disassembly code can be viewed using the er_src utility, without running an experiment. The display is generated in the same way as in the Performance Analyzer, except that it does not display any metrics. The syntax of the er_src command is
er_src [ options ] object item tag |
object is the name of an executable, a shared object, or an object file (.o file).
item is the name of a function or of a source or object file used to build the executable or shared object; it can be omitted when an object file is specified.
tag is an index used to determine which item is being referred to when multiple functions have the same name. If it is not needed, it can be omitted. If it is needed and is omitted, a message listing the possible choices is printed.
The following sections describe the options accepted by the er_src utility.
Define the compiler commentary classes to be shown. commentary-classes is a list of classes separated by colons. See Source and Disassembly Listing Commands for a description of these classes.
The commentary classes can be specified in a defaults file. The system wide er.rc defaults file is read first, then a .er.rc file in the user's home directory, if present, then a .er.rc file in the current directory. Defaults from the .er.rc file in your home directory override the system defaults, and defaults from the .er.rc file in the current directory override both home and system defaults. These files are also used by the Performance Analyzer and er_print, but only the settings for source and disassembly compiler commentary are used by er_src.
See Defaults Commands for a description of the defaults files. Commands in a defaults file other than scc and dcc are ignored by er_src.
Include the disassembly in the listing. The default listing does not include the disassembly. If there is no source available, a listing of the disassembly without compiler commentary is produced.
Open the file filename for output of the listing. By default, output is written to stdout.
Print the current release version.
There are some other utilities that should not need to be used in normal circumstances. They are documented here for completeness, with a description of the circumstances in which it might be necessary to use them.
The syntax of the er_archive command is as follows.
er_archive [-q] [-F] [-V] experiment |
The er_archive utility is automatically run when an experiment completes normally, or when the Performance Analyzer or er_print command is started on an experiment. It reads the list of shared objects referenced in the experiment, and constructs an archive file for each. Each output file is named with a suffix of .archive, and contains function and module mappings for the shared object.
If the target program terminates abnormally, er_archive might not be run by the Collector. If you want to examine the experiment from an abnormally-terminated run on a different machine from the one on which it was recorded, you must run er_archive on the experiment, on the machine on which the data was recorded.
An archive file is generated for all shared objects referred to in the experiment. These archives contain the addresses, sizes and names of each object file and each function in the load object, as well as the absolute path of the load object and a time stamp for its last modification.
If the shared object cannot be found when er_archive is run, or if it has a time stamp differing from that recorded in the experiment, or if er_archive is run on a different machine from that on which the experiment was recorded, the archive file contains a warning. Warnings are also written to stderr whenever er_archive is run manually (without the -q flag).
The following sections describe the options accepted by the er_archive utility.
Do not write any warnings to stderr. Warnings are incorporated into the archive file, and shown in the Performance Analyzer or er_print output.
Force writing or rewriting of archive files. This argument can be used to run er_archive by hand, to rewrite files that had warnings.
Write version number information.
The syntax of the er_export command is as follows.
er_export [-V] experiment |
The er_export utility converts the raw data in an experiment into ASCII text. The format and the content of the file are subject to change, and should not be relied on for any use. This utility is intended to be used only when the Performance Analyzer cannot read an experiment; the output allows the tool developers to understand the raw data and analyze the failure. The -V option prints version number information.
| Program Performance Analysis Tools | 816-2458-10 |
|
Copyright © 2002, Sun Microsystems, Inc. All rights reserved.