HP DCPI tool

»

DCPI

Site information

» Send us your comments

Installation

» Download DCPI
» Installing DCPI

Product information

» Frequently asked questions
» Documentation
» Publications
customer times newsletter link

dcpistats(1)

NAME

dcpistats - Print statistics comparing sets of profile data

SYNOPSIS

dcpistats [flags] [-set] [-factor n] profile_selection_spec [...]

DESCRIPTION

Dcpistats compares sets of raw sample counts and prints various statistics about them. Dcpistats is useful for comparing variations across multiple runs of the same program, or for comparing differences between slightly different versions of a program.

It runs dcpiprof(1) for each set of samples (separated by the -set flag), parses the output and prints the range -- the difference between the maximum and the minimum sample count -- for each procedure (or image) across all sample sets. The entries are sorted by range, so that procedures (or images) with the largest differences appear at the top of the listing. If the -norm flag is set, then the normalized range is used instead of the range, where the normalized range is the range expressed as a percentage of the total samples for an entry.

The image files can be the same or different across different sample sets. Dcpistats bins the data according to procedure name (or image name with -i). The -show_images flag can be used to list the images in which each procedure appears.

FLAGS

-set
Denote the start of a set of sample files. All samples within a set are combined, and samples across different sets are compared. Any number of sets is acceptable. The -set flag can be omitted if the only set-specific arguments are the image names, i.e., each set can be described using only its image name. In this case, all non-flag command-line arguments are treated as images in separate sets.

-V
Print out the version number.

-i
Print statistics per image (default is per procedure).

-cutoff percentage
Don't print procedures with ranges (i.e., the difference between the maximum and the minimum sample count) less than percentage of the total range between sets.

-norm
Sort by and print normalized ranges (default is to sort by the absolute value of the range).

-range_value
Sort by range value (default is to sort by the absolute value of the range). This option is useful when comparing two sets of samples to see why one is faster than the other. Procedures that have more samples in set #2 show up at the top of the listing (with a positive range), and procedures that have more samples in set #1 end up at the bottom (with a negative range). If both -norm and -range_value are set, then -norm is used.

-all_stats
Print all statistics. This prints the mean, standard deviation, minimum and maximum of the sample counts across sets for each procedure.

-range_only
Only print ranges, don't print sample counts (ignored if -all_stats is set).

-show_images
Print the images in which each procedure appears (ignored if -i is set).

-s event
Sort by event event. Default is cycles.

-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.

-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 command line.

-factor n
Scale the samples in the set by n. The sample counts in the set are multiplied by n. This option applies to each set individually.

PROFILE SELECTION 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. 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 oldest epoch if -epoch latest-2 is specified.

-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 YYYYMMDDHHMM (year-month-day-hours-minutes). For example, an epoch started on June 11, 2002 at 22:33 would be named 200206112233. 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.

-epoch all
Search for profile files in all epochs.

-ihost <hostnames...> --

Include just those profile files associated with the specified host names. The list of host names must be terminated either via -- or by the end of the option list. The command prints an error message and fails if both the -ihost and -ehost options are specified.

-ehost <hostnames...> --

Exclude any profile files associated with the specified host names. The list of host names must be terminated either via -- or by the end of the option list. The command prints an error message and fails if both the -ihost and -ehost options are specified.

-label <label>
Search for profile files with the specified label(s) (see dcpilabel(1)). This option can be repeated multiple times. If no labels are specified on the command line, profile file labels are ignored entirely. If any labels are specified on the command line, 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 the automatic profile lookup mechanism, or explicitly name the profile file with the -profile option; but don't do both.)

STATISTIC SELECTION FLAGS

Different kinds of performance counter statistics are available on various models of Alpha CPUs. Alpha 21064/EV4, 21164/EV5 and 21264/EV6 CPUs have traditional aggregate event counters. Alpha 21264A/EV67 and later processors have a mix of some traditional aggregate event counters and newer ProfileMe counters which allow accurate and precise instruction execution profiles on out-of-order processors. (See dcpiprofileme(1) for more information on ProfileMe statistics.)

The default statistic selection on an aggregate counter machine is to select all the aggregate events. The default on a ProfileMe machine is to select ProfileMe retire delay, retire count, !retired (i.e. aborted) count, !notrap (i.e. trap) count, and aggregate cycles.

The options below can be used to select various statistics when available. Use -event for aggregate statistics and -pm for ProfileMe statistics. Note: there can be multiple, mixed -event and -pm specifications. You can also specify the ratio of two statistics (written as stat1::stat2).

-pm pm_stat(+pm_stat)
Select the specified ProfileMe statistic plus any added in by optional +pm_stat specifications. For example, select various trap statistics by specifying the option -pm trap+replays+ldstorder+mispredict.

-pm default(+pm_stat)
Select the default set of ProfileMe statistics plus those added in by +pm_stat specifications. At least one additional statistic is mandatory; -pm default without modifications is extraneous and not allowed. The additional ProfileMe statistics will take the place of the aggregate cycles statistic which is selected by default.

-pm all(-pm_stat)
Select all ProfileMe statistics less those subtracted out. You can repeat the optional -pm_stat specification to deselect multiple ProfileMe statistics. Note: there are a lot of ProfileMe statistics. Unless you deselect a bunch of them, this will select more statistics than are appropriate for human consumption.

-event ag_stat(+ag_stat)
Select the specified aggregate statistic plus any added in by optional +ag_stat specifications. For example, select cycles, icache misses, and data cache misses when the option -event cycles+imiss+dmiss is specified.

-event all(-ag_stat)
Select all aggregate statistics less those subtracted out. You can repeat the optional -ag_stat specification to deselect multiple aggregate statistics.

-allevents
Select profile events corresponding to all event types, both aggregate and ProfileMe. However, if there are ProfileMe events, this will produce a large number of statistics, which in most cases will not be useful.

EXAMPLE USAGE

dcpistats -i -set -epoch latest -set -epoch latest-1 -set -epoch latest-2
Use dcpistats to compare images across the last three epochs.

dcpistats -set -factor 1.5 -epoch latest prog -set -epoch latest-1 prog
Use dcpistats to compare runs of the program prog in two different epochs. All sample counts in the first set are multiplied by 1.5.

dcpistats -epoch latest prog1 prog2
Use dcpistats to compare runs of the programs prog1 and prog2 in the same epoch.

INTERPRETING THE OUTPUT

Dcpistats prints a header that summarizes the sample counts for each event type and each sample set. Similar to dcpiprof(1), if per-image profiles are being produced, there is a line per image in the body of the listing, and the last column in the line is the name of the image. Otherwise there is a line per procedure and the last column is the name of the procedure.

For example, consider the following output, generated with the command: dcpistats -cutoff 10 prog1 prog2:

=======================================================================

Total number of samples for each set:

Set#  Set name              cycles  dmiss  imiss

   1  prog1                   9210   1138     54
   2  prog2                    862    141      9


9210 cycles samples for set ``prog1'' is the maximum
 862 cycles samples for set ``prog2'' is the minimum
8348 is the total range

Printing entries where the absolute value of the range
is at least 834 cycles samples (10% of total range)

=======================================================================

             cycles  dmiss  imiss
  -----------------  -----  -----
  range  set1  set2  range  range  procedure  

  -8340  9139   799  -1001    -47  main       
   1796  3639  5435     23     12  calc       
   ...
Dcpistats is comparing the profiles for two sample sets in the same epoch; the first set contains samples for the program prog1, and the second set contains samples for the program prog2. Both sample sets contain data for three events, cycles, dmiss (data cache misses) and imiss (instruction cache misses).

The header lists the number of samples of each event type for both sample sets. It also lists the minimum and maximum number of cycle samples, along with the range. Since a cutoff value of 10 was specified on the command-line, the body of the listing will only include those procedures that have ranges of at least 834 cycle samples (10% of the total range of 8348).

The first column lists the range of cycle samples. The sample sets are ordered, so a negative range means that the set with the maximum cycle samples had a lower set number than the set with the minimum cycle samples. In the above example, set #1 has 9139 cycle samples and set #2 has 799 cycle samples, resulting in a range of -8340. The output is sorted by the absolute values of the ranges, so that procedures with larger absolute differences appear at the top of the listing. The -range_value flag can be used to sort the output by the actual value of the range instead of the absolute value. The positive ranges would show up at the top of the listing (i.e., those procedures in which set #2 has more cycle samples than set #1), and the negative ranges would end up at the bottom of the listing.

The next two columns list the number of cycle samples for the procedure in each of the sample sets. If the -range_only flag were set, then these columns containing the number of samples would be omitted. The remaining columns report the ranges for the secondary events, in this example, dmiss and imiss.

SEE ALSO

dcpi(1), dcpi2bb(1), dcpi2pix(1), dcpi2ps(1), dcpicalc(1), dcpicat(1), dcpicc(1), dcpicoverage(1), dcpictl(1), dcpid(1), dcpidiff(1), dcpidis(1), dcpiepoch(1), dcpiflow(1), dcpiflush(1), dcpikdiff(1), dcpilabel(1), dcpildlatency(1), dcpilist(1), dcpiprof(1), dcpiprofileme(1), dcpiquit(1), dcpiscan(1), dcpisource(1), dcpisumxct(1), dcpitar(1), dcpitopcounts(1), dcpitopstalls(1), dcpiuninstall(1), dcpiupcalls(1), dcpivarg(1), dcpivcat(1), dcpiversion(1), dcpivlst(1), dcpivprofiler(1), dcpiwhatcg(1), dcpix(1), dcpiformat(4), dcpiexclusions(4)

For more information, see the DCPI project home page http://h30097.www3.hp.com/dcpi.

COPYRIGHT

Copyright 1996-2004, Hewlett-Packard Company. All rights reserved.