HP OpenVMS Systems

dcpilist(1)

NAME

dcpilist - Produces procedure listing annotated with profile information

SYNOPSIS

dcpilist [options] [-p] procedure-name image-file

dcpilist -V

FLAGS

-V

Prints version number and exits.

-best

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

-source

Prints source code.

-asm

Prints a disassembly of the specified procedure.

-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 optimizations levels when the compiler moves two instructions that belong to the same source line far apart from each other.

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

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

-tk

Experimental option for generating Tcl code that places the output in a Tk text widget.

-ranks n

When used in combination with the -tk option, each source line is tagged with a rank in the range 0..n-1 where the rank is determined by the number of samples that fell on that source line. Higher samples imply a higher rank.

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. That is, the named directory should contain a set of epochs. If this option is not specified, the directory name is obtained from the DCPIDB logical name. If neither of these methods succeeds 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 YYYYMMDDHHMM (year-month-day-hours-minutes). For example, an epoch started on February 4, 2002 at 23:34 is named 200202042334. 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, errors in branch predictions, etc. This is the default.

-events type(+type)*

Search for profile files for the specified event types. For example, search for cycles, icache misses, and data cache misses when the option -events cycles+imiss+dmiss is specified.

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

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 disassebled 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)), then this cost is also printed in the output.

Samples that do not belong to the specified procedure are ignored. If the relevant profile files contain samples for multiple events, then 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.

Input parameter procedure-name can be the ASCII procedure name, an address within a procedure (in C syntax, for example, 0x20000 is hex address 20000), or an explicit address range (useful when analyzing images without debug symbol information; for example, 0x20000:0x200c0).

SEE ALSO

dcpi(1), dcpi2ps(1), dcpicat(1), dcpictl(1), dcpid(1), dcpidiff(1), dcpiformat(4), dcpilist(1), dcpiprof(1), dcpitopstalls(1), dcpiwhatcg(1)  

For more information, see the HP Digital Continuous Profiling Infrastructure project home page (http://h30097.www3.hp.com/dcpi).