10.2;hpc (histogram_pc), revision 4.1, 89/08/25
hpc (histogram_pc) - program counter histogram
usage: hpc [-low x] [-high x]
[-from procedure]
[-to procedure]
[-proc procedure]
[-limit n] [-rate n]
[-nhdr] [-map]
[-brief] pathname
[args...]
DESCRIPTION
hpc (histogram_program_counter), part of Domain/PAK (Domain Performance
Analysis Kit), looks at the performance of programs at the PC level.
hpc produces a histogram of the program counter (PC) during program
execution, thus helping you locate the most compute-bound portions of
your program.
While your program is executing, hpc samples the PC at regular intervals,
gathering a set of data points. Each data point records the region in
which the program was executing the location of the PC when the sample
was taken.
hpc divides your program into 256 equally sized regions called "buckets."
The size of the region depends on the size of your program or the range
you select. The smaller the region, the better the resolution of the
analysis.
When execution of your program has ended, hpc displays statistics and a
histogram (bar graph) of the PC. Each bar corresponds to an area of
program memory. The length of the bar indicates how much time the
program spent executing in the corresponding area. hpc tells you which
procedures and line numbers each bar represents.
While hpc and your program are executing, a serial line is not available
for output.
pathname (required) Specify the name of the program to be evaluated.
args (optional) Specify any arguments to be passed to the program
pathname. These are not processed by hpc, but passed
directly to your program.
Default if omitted: no arguments passed
OPTIONS
If no options are specified, a histogram is produced for the entire
program, with 500 samples taken per second.
-low x Specify lowest address x to be included in the histogram.
x must be a hexadecimal value. If this option is omitted,
the histogram starts at the beginning of the program or
procedure (see -from below).
-high x Specify highest address x to be included in the histogram.
x must be a hexadecimal value. If this option is omitted,
the histogram continues to the end of the program or
procedure (see -to below).
-from procedure
Specify the beginning of a procedure as the lowest address
to be included in the histogram. If both -from and -low
are omitted, the histogram starts at the beginning of the
program. Note the the procedure name is case-insensitive.
-to procedure Specify the end of a procedure as the highest address to
be included in the histogram. If both -to and -high are
omitted, the histogram stops at the end of the program.
Note the the procedure name is case-insensitive.
-proc procedure
Specify a single procedure to be included in the
histogram. Note the the procedure name is case-
insensitive.
By limiting the range of addresses in the histogram with
-low, -high, -from, -to, and -proc, you can study a
specific part of your program, such as an I/O routine.
-limit n Limit the displayed histogram bars to those that represent
more than n% of the monitored program execution. The
default value for n is 1. Use -limit 0 to show all
histogram entries.
-rate n Specify how many times n hpc samples the program counter
per second. n must be a decimal number in the range 5 to
2000. The default is 500 samples per second. A higher
rate results in a more accurate histogram, but tends to
slow program execution.
-nhdr Generate the histogram without the header information.
Using this option makes filtering the output easier.
-map Generate a list of the names and starting and ending
locations of the procedures in the program. This list is
reduced if -from, -to, -high, or -low are used to restrict
monitoring to specific procedures or memory addresses.
The output from this option can be quite verbose for large
programs.
-brief Produce a compact bar chart by showing only the name of
the first procedure, or procedure fragment, contained in
the bucket represented by each bar. By default, dpat
shows the names of all procedures or procedure fragments
contained in the bucket. This option also suppresses
source-line information.
SEE ALSO
More information is available. Type
help dpat For details about the domain performance analysis tool
help dspst For details about displaying process status data