Printed 1/15/91 Page 1
PROF(1-SysV) RISC/os Reference Manual PROF(1-SysV)
NAME
prof - analyze profile data
SYNOPSIS
prof [ options ] [ prog_name [ pcsampling_data_file ... ] ]
prof -note "comment string" -pixie [ options ] [ prog_name [
bbaddrs_file [ bbcounts_file ... ] ] ]
DESCRIPTION
prof analyzes one or more data files generated by the MIPS
compiler's execution-profiling system and produces a list-
ing. prof can also combine those data files or produce a
feedback file that lets the optimizer take into account the
program's runtime behavior during a subsequent compilation.
Profiling is a three-step process: first compile the pro-
gram, then execute it, and finally run prof to analyze the
data.
The compiler system provides two kinds of profiling:
1. pc-sampling interrupts the program periodically, record-
ing the value of the program counter.
2. basic-block counting divides the program into blocks
delimited by labels, jump instructions, and branch instruc-
tions. It counts the number of times each block executes.
This provides more detailed (line by line) information than
pc-sampling.
Using pc-sampling
To use pc-sampling, compile your program with the option -p
(strictly speaking, it is sufficient to use this option only
when linking the program). Then run the program, which allo-
cates extra memory to hold the profile data, and (provided
the program terminates normally or calls exit(2)) records
the data in a file at the end of execution.
The environment variable PROFDIR determines the name of the
pc-sampling data file and determines whether pc-sampling
takes place: if it is not set, the pc-sampling data file is
named "mon.out"; if it is set to the empty string, no pro-
filing occurs; if it is set to a non-empty string, the file
is named "string/pid.progname," where "pid" is the process
id of the executing program and "progname" is the program's
name, as it appears in argv[0]. The subdirectory "string"
must already exist.
After running your program, use prof to analyze the pc-
sampling data file.
Printed 1/15/91 Page 1
PROF(1-SysV) RISC/os Reference Manual PROF(1-SysV)
For example:
cc -c myprog.c
cc -p -o myprog myprog.o
myprog (generates "mon.out")
prof myprog mon.out
When you use prof for pc-sampling, the program name defaults
to a.out and the pc-sampling data file name defaults to
mon.out; if you specify more than one pc-sampling data file,
prof reports the sum of the data.
Using basic-block counting
To use basic-block counting, compile your program without
the option -p. Use pixie(1) to translate your program into
a profiling version and generate a file, whose name ends in
".Addrs", containing block addresses. Then run the profiling
version, which (assuming the program terminates normally or
calls exit(2)) will generate a file, whose name ends in
".Counts", containing block counts. Then use prof with the
-pixie option to analyze the bbaddrs and bbcounts files.
Notice that you must tell prof the name of your original
program, not the name of the profiling version.
For example:
cc -c myprog.c
cc -o myprog myprog.o
pixie -o myprog.pixie myprog (generates "myprog.Addrs")
myprog.pixie (generates "myprog.Counts")
prof -pixie myprog myprog.Addrs myprog.Counts
When you use prof with the -pixie option, the program name
defaults to a.out, the bbaddrs file name defaults to
"program_name.Addrs", and the bbcounts file name defaults to
"program_name.Counts". If you specify more than one bbcounts
file (never specify more than one bbaddrs file), prof
reports the sum of the data.
Options to prof
For each prof option, you need type only enough of the name
to distinguish it from the other options (usually the first
character is sufficient). Unless otherwise noted, each part
of the listing operates only on the set of procedures that
results from the combination of the -exclude and -only
options.
If the options you specify would neither produce a listing
nor generate a file, prof uses -procedures plus -heavy by
default.
Page 2 Printed 1/15/91
PROF(1-SysV) RISC/os Reference Manual PROF(1-SysV)
-note "comment string"
If you use this argument, the "comment string" appears
near the beginning of the listing as a comment.
-pixie
Selects pixie mode, as opposed to pc-sampling mode.
-procedures
Reports time spent per procedure (using data obtained
from pc-sampling or basic-block counting; the listing
tells which one). For basic-block counting, this
option also reports the number of invocations per pro-
cedure.
-heavy
Reports the most heavily used lines in descending order
of use (requires basic-block counting).
-lines
Like -heavy, but gives the lines in order of
occurrence.
-invocations
For each procedure, reports how many times the pro-
cedure was invoked from each of its possible callers
(requires basic-block counting). For this listing, the
-exclude and -only options apply to callees, but not to
callers.
-zero
Prints a list of procedures that were never invoked
(requires basic-block counting).
-testcoverage
Reports all lines that never executed (requires basic-
block counting).
-feedback filename
Produces a file with information that the compiler sys-
tem can use to decide what parts of the program will
benefit most from global optimization and what parts
will benefit most from in-line procedure substitution
(requires basic-block counting).
-merge filename
Sums the pc-sampling data files (or, in pixie mode, the
bbcounts files) and writes the result into a new file
with the specified name. The -only and -exclude options
have no affect on the merged data.
-only procedure_name
If you use one or more -only options, the profile
Printed 1/15/91 Page 3
PROF(1-SysV) RISC/os Reference Manual PROF(1-SysV)
listing includes only the named procedures, rather than
the entire program. If any option uses an uppercase "O"
for "Only," prof uses only the named procedures, rather
than the entire program, as the base upon which it cal-
culates percentages.
-exclude procedure_name
If you use one or more -exclude options, the profiler
omits the specified procedure and its descendents from
the listing. If any option uses an uppercase "E" for
"Exclude," prof also omits that procedure from the base
upon which it calculates percentages.
-clock megahertz
Alters the appropriate parts of the listing to reflect
the clock speed of the CPU. If you do not specify
megahertz, it defaults to "8.0".
-quit n
Truncates the -procedures and -heavy listings. It can
truncate after n lines (if n is an integer), after the
first entry that represents less than n percent of the
total (if n is followed immediately by a "%" charac-
ter), or after enough entries have been printed to
account for n percent of the total (if n is followed
immediately by "cum%"). For example, "-quit 15" trun-
cates each part of the listing after 15 lines of text,
"-quit 15%" truncates each part after the first line
that represents less than 15 percent of the whole, and
"-quit 15cum%" truncates each part after the line that
brought the cumulative percentage above 15 percent.
-gprof
generate gprof-like listing, it produces a dynamic call
graph execution profile of programs. The effect of
called routines is incorporated in the profile of each
caller.
FILES
crt0.o normal startup code
mcrt0.o startup code for pc-sampling
libprof1.a library for pc-sampling
mon.out default pc-sampling data file
SEE ALSO
as(1), cc(1), f77(1), pc(1).
profil(2), pixie(2), monitor(3) in the Programmer's Refer-
ence Manual.
RISC/os Programmer's Guide.
Page 4 Printed 1/15/91
PROF(1-SysV) RISC/os Reference Manual PROF(1-SysV)
FEATURES
Provided you do not use -pixie, prof processes "mon.out"
files produced by earlier versions of the compiler system
using the obsolete -p2 or -p3 options.
BUGS
prof does not yet take into account interactions among
floating-point instructions.
Printed 1/15/91 Page 5