dcpiprof - Analyze profile data collected by dcpid
dcpiprof [-i] [-s event-type] [-keep percentage] [-p image-file-name]
[-m map-file-name] [-no_header] [-full_output] [image-names...]
- Lists samples collected per image (instead of the default samples per procedure).
- -s event
- The named event type is used to sort the profile output. Otherwise, the output is sorted
by cycles so that the procedure or image that accounts for the most cycles is listed
- -keep p
- Lists just enough top routines to account for the top p percent of the samples of
the event type used to sort the profile output. The value p may be a floating point
number in the range [0..100].
- -p image-file-name
- Use the specified image file as a candidate when associating profiles with named image
files. This option can be repeated, allowing several image names to be specified on the
- -m map-file-name
- Use specified map file generated by dcpiscan(1) for associating profiles with named
images. This option can be repeated, allowing several map files to be specified;
information from all of the supplied map files is merged. The -m option works
like the -p option, except that instead of specifying one image at a time, a
whole set of images can be entered into a map file via dcpiscan(1) and the entire set can
be specified with one command line option.
- Do not print any header in the output. This option may be useful for programs that parse
the output of dcpiprof.
- Prints extra information per line. This information may be useful for programs that
parse the output of dcpiprof. The format of this extra information has not yet been
documented because it is evolving.
PROFILE FILE FLAGS
By default, this command automatically finds all of the relevant profile files. The
following options can be used to guide the search for the profile files.
- -db <directory name>
- Search for profile files in the specified profile database directory. The directory name
should be the same name as the one specified when dcpid was started. I.e., the
named directory should contain a set of epochs. If this option is not specified, the
directory name is obtained from the DCPIDB environment variable. If neither this
option, nor the DCPIDB environment variable are set, the name of the directory
used by the last invocation of dcpid on this machine is used. If none of these
methods succeed in finding the appropriate directory, and no explicit set of profile files
is provided via the -profiles option, then the command fails.
- -epoch latest
- Search for profile files in the latest epoch. This is the default.
- -epoch latest-k
- Search for profile files in the "k+1"th oldest epoch. For example, search in
the third last epoch if "-epoch latest-2" is specified.
- -epoch all
- Search for profile files in all epochs.
- -epoch <name>
- Search for profile files in the named epoch. The epoch name should be the name of a
subdirectory corresponding to a single epoch within the profile database directory. Epoch
subdirectory names usually take the form YYMMDDHHMM
(year-month-day-hours-minutes). For example, an epoch started on December 4, 1996 at 23:34
is named 9612042334. If an epoch is given a symbolic name by creating a symbol
link to the actual epoch directory, then the symbolic name can also be used as an argument
to the -epoch option.
- -events all
- Search for profile files corresponding to all event types such as cycles, icache misses,
branch mispredictions, etc. This is the default.
- -events type(+type)*
- Search for profiles files for the specified event types. For example, search for cycles,
icache misses, and data cache misses when the option -events cycles+imiss+dmiss
- -events all(-type)*
- Search for profile files for all event types except for the specified types. For
example, search for all event types except for branch mispredictions when the option -events
all-branchmp is specified.
- -label <label>
- Search for profile files with the specified label (see dcpilabel). If no labels
are specified on the command line, profile file labels are ignored entirely. If any labels
are specified on the command line (this option can be repeated several times), only
profile files that have one of the specified labels are used.
- -profiles <file names...> --
- Use just the profile files named by the specified file names. The list of profile file
names can be terminated either via --, or by the end of the option list. The
command prints an error message and fails if the -profiles option is used in
conjunction with any of the earlier automatic profile finding options. (Use either the
automatic profile lookup mechanism, or explicitly name the profile file with the -profile
option, but not both.)
Dcpiprof summarizes a set of profile files by printing a histogram of the number of
samples per procedure (or the number of samples per image with the -i option.) The output
is sorted by decreasing number of samples found within that procedure (or image). Each
entry in the listing is annotated with the number of samples, the percentage of samples
that belong to this entry, and a cumulative percentage value.
If some image names are specified on the command line, then only the profile files
corresponding to the specified images are used to generate the output. Otherwise, if the
-i option is specified and no image names are listed on the command line, then dcpiprof
reads all profile files found in the profile database. If the -i option is not specified,
and no images are listed on the command line, then dcpiprof prints an error message and
Dcpiprof sometimes reports that it could not open some image files. In such cases, you
can help dcpiprof locate the appropriate image files either by using the -p
option to specify the name of an image file of interest, or by using the -m
option to supply an image map generated by dcpiscan(1).
- dcpiprof -i
- Use dcpiprof to analyze the breakdown of cpu time across all images that contribute to
the contents of the profile database.
- dcpiprof <image names...>
- Use dcpiprof to analyze the breakdown of cpu time across all procedures for the
- dcpiprof -keep 99.99 ...
- Stop the output after accounting for 99.99% of the samples.
INTERPRETING THE OUTPUT
Dcpiprof prints a header, followed by a number of lines of output. If per-image
profiles are being produced, then there is a line per image, and the last column in the
line is the name of the image. Otherwise there is a line per procedure and the last two
columns contain the name of the procedure and the image to which the procedure belongs.
For example, consider the following output:
Total samples for event type cycles = 21761024463
Total samples for event type imiss = 1943063555
The counts given below are the number of samples for each
listed event type.
cycles % cum% imiss % procedure image
9479311336 43.56% 43.56% 94570129 4.87% idle_thread /vmunix
3093399786 14.22% 57.78% 359058745 18.48% _XentInt /vmunix
2982861812 13.71% 71.48% 32386524 1.67% gh_zero_memory /vmunix
This provides information on two different types of events: cycles events and imiss
events (i.e., instruction cache misses).
The first three columns in each line contain information about the number of event
samples that correspond to the event used to sort the dcpiprof output (cycles by
default.) The first one of these columns lists the number of event samples that fell
within this image/procedure (i.e. 9479311336 within idle_thread). The second
column lists the percentage these event samples form of the total number of samples of
this event type listed in dcpiprof's output (i.e. 14.22% of all cycle samples in
dcpiprof's output fell within _XentInt). The third column gives the cumulative
percentage of all event samples on this line and above (i.e. the top three procedures in
the example account for 71.48% of the cycle samples.)
The remaining columns report the number of samples of other secondary event types.
There are two such columns per secondary event type. The first column lists of the number
of samples of that type (i.e. 94570129 imiss samples for idle_thread). The second
column lists the percentage this number forms of the total number of samples of that type
listed in dcpiprof's output (i.e. 18.48% of all imiss samples in dcpiprof's output fell
If the environment variable DCPIPROF_OLDSYNTAX is set, dcpiprof emulates
versions of dcpiprof older than 1.45. The old versions support the syntax:
dcpiprof [options] [<profile file names...>]
I.e., the profile file names are specified explicitly on the command line, instead of
via the profile file flags described earlier in this document. If no profile file names
are listed on the command line, the names are read from standard input.
The old command line interface is supported for the use of old shell scripts. Users
should just use the -profiles option if they need to specify profile file names
dcpi(1), dcpiflow(1), dcpilist(1), dcpidis(1), dcpiscan(1), dcpid(1), dcpiepoch(1), dcpiflush(1), dcpicalc(1), dcpilabel(1), dcpi2ps(1), dcpicat(1), dcpiquit(1), dcpidiff(1), dcpitopstalls(1), dcpiwhatcg(1),
For more information, see the HP Continuous Profiling Infrastructure project home page (http://h30097.www3.hp.com/dcpi).
Copyright 1996-2004, Hewlett-Packard Development Company, L.P.
Sanjay Ghemawat, Monika Henzinger
This page was generated automatically by mtex software.