10.0;hpc (histogram_pc), revision 1.0, 88/01/21
HPC (HISTOGRAM_PROGRAM_COUNTER) -- Program counter histogram.
usage: hpc [-low x] [-high x] [-from procedure] [-to procedure]
[-proc procedure] [-limit n] [-rate n]
[-nhdr] [-map] [-brief] pathname
[args...]
FORMAT
hpc [options] pathname [args...]
hpc (HISTOGRAM_PROGRAM_COUNTER), part of dpak (Domain Performance Analysis
Kit), looks at the performance of programs at the pc level.
hpc produces a histogram of the program counter during program execution, thus
helping you locate the most compute-bound portions of your program.
While your program is executing, hpc samples the program counter 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 program counter --
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 regions, the better the resolution of the analysis.
When execution of your program has ended, hpc displays statistics and a
histogram (bar graph) of the program counter. 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.
ARGUMENTS
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.
EXAMPLES
For a detailed example of hpc, see the chapter on hpc in Analyzing Program
Performance with dpak. Also, see the hpc command description in the Domain
System Command Reference manual.
RELATED TOPICS
More information is available. Type:
- HELP DPAT
for details about the Domain Performance Analysis Tool.
- HELP DSPST
for details about displaying process status data.