HP DCPI tool

dcpilist(1)

NAME

dcpilist - Produce procedure listing annotated with profile information

SYNOPSIS

dcpilist [flags] procedure_name image_file

dcpilist -V

DESCRIPTION

Dcpilist prints the contents of the procedure specified on the command line. The name of the image in which the procedure can be found is also specified on the command line. Instead of a procedure name, you can specify an instruction address -- the procedure that contains the specified address is printed. If multiple procedures in the image have the same name, you can give the address of one of these procedures instead of an ambiguous name.

Dcpilist can print the source code for the procedure, a disassembly of the procedure, or a mixed output that contains both the source code and the disassembly. Each source line and disassembled instruction in the output is annotated with the sample counts obtained from corresponding profile files. When the cycle cost of an instruction or a source line can be determined (see dcpicalc(1)), this cost is also printed in the output in the "cpi" column. The "freq" column, if present, shows an estimate of how many times each instruction is executed (aborted speculative executions are excluded). If ProfileMe data are available, these estimates are based on retire sample counts; if not, they are calculated using heuristics.

Samples that do not belong to the specified procedure are ignored. If the relevant profile files contain samples for multiple events, a column for the count of each unique event type is included in the listing. If multiple profile files with the same event type contribute to the samples for the specified procedure, these samples are merged together in the output.

FLAGS

-V

Prints version number and exits.

-source

Prints source code if it is available.

-asm

Prints a disassembly of the specified procedure. Branch targets are prefixed by ": ".

-best

Prints source code if it is available, else prints a disassembly of the specified procedure. This is the default output format.

-both

Prints both the source code, and a disassembly of the specified procedure. The source code is always printed in line-number order. If the -order option is not given, for each source line, the set of instructions that correspond to the source line are printed immediately after the source line in address order. Since the compiler can mix instructions that come from different source lines, there may be gaps in the instruction output for a given source line. These gaps are indicated with a line of the form .... For example,

    if (x->ptr != NULL)
    0x120022464 ldq     t2, 0(s6)
    ...
    0x120022470 beq     t2, 0x120023fc4

This output format does not guarantee that the instructions are displayed in address order. For example, in the listing below, the instructions for the first two source lines are intermixed.

    a += x[0];
    0x120022504 ldq     t1, 0(s1)
    ...
    0x12002250c addq    s2, t1, s2
    b += x[1];
    0x120022508 ldq     t2, 0(s1)
    ...
    0x120022510 addq    s3, t2, s3

Therefore, the last instruction corresponding to the first source line occurs after the first instruction corresponding to the second source line, but is displayed earlier.

If you specify the -order option, dcpilist produces a different interleaving of the source code and the disassembled instructions. The source lines are still printed in line number order. In addition, the instructions are all printed in address order. To handle instructions reordering, dcpilist will group a set of source lines together and show the corresponding assembly instructions immediately after the group of source lines. The example above will produce the following output if you specify the -order option.

    a += x[0];
    b += x[1];
    0x120022504 ldq     t1, 0(s1)
    0x120022508 ldq     t2, 0(s1)
    0x12002250c addq    s2, t1, s2
    0x120022510 addq    s3, t2, s3

The -order option is not turned on by default because it does not work well under high optimization levels when the compiler moves two instructions that belong to the same source line far apart from each other.

-f source_file

If dcpilist cannot find the source file automatically, the user can specify the file name explicitly with this option.

-lines

If this option is specified, dcpilist labels each source line and disassembled instruction with the corresponding source line number. This option can be helpful in understanding the output of -both -order.

-order

See the description of the -both option above.

-stalls

If this option is specified on an Alpha 21064/EV4 or a 21164/EV5 system, dcpilist adds a new column for each source line and disassembled instruction that shows the reasons and lengths of any static and dynamic stalls associated with the source line or instruction. The reasons are printed using the same characters that the dcpicalc tool uses to display stall reasons (see dcpicalc(1)). Stalls whose length is less than 0.5 cycles per execution are not shown, and stalls whose lengths are greater than one cycle are rounded to the nearest cycle. The stall lengths may sum to more than the actual stall length when the analysis tools are not able to fully disambiguate the reason for a stall.

-vprof

List value profile information, in addition to normal dcpilist output. Requires -vprof when running dcpid(1).

-vreplay

List value profile replay trap culprits, in addition to normal dcpilist output. For each instruction, lists the PCs of other instructions that might trigger a replay trap on Alpha 21264. A 'T' indicates the other PC might cause a troll trap (mod 32K conflict for same primary dcache line). Lack of 'T' indicates access to some byte(s) in common, i.e., either a wrong-size trap or some kind of order trap. Requires -vreplay when running dcpid(1).

For more information on replay traps, see section 3.7 of the Alpha 21264 Compiler Writer's Guide, http://ftp.digital.com/pub/Digital/info/semiconductor/literature/cmpwrgd.pdf

-vtrace library

List profile information captured with the value profiler library, in addition to normal dcpilist output. It requires that the value profiler was used when dcpid(1) was run. See dcpivprofiler(1) for more on value profilers.

-vconcise

Report counts (and derived percentages) of value profiles based on concise samples, rather than counting samples. Concise samples more truly represent a uniformly random sampling of the distribution, but the percentage estimates are often less accurate, especially for random or near-random distributions.

-vcutoff P

Only list profile data values that were seen in more than P percent of the total value samples.

-vshow N

Only list in full the N value profile data values accounting for the most value samples. Other profile data values, that pass the -vcutoff, if it is set, are shown as dots.

-vindent N

Format value profiling information so it can be read by humans. Items are displayed one per line and indented N spaces.

-vtotcut S

Do not output value profiles if they are based on S or fewer value samples.

-conf_low

Output low, medium, and high confidence data.

-conf_med

Output medium and high confidence data. This is the default.

-conf_high

Output only high confidence data.

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.

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), dcpiprof(1), dcpiprofileme(1), dcpiquit(1), dcpiscan(1), dcpisource(1), dcpistats(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.