profile.pl - a Perl script to run profile experiments
using pfmon
SYNOPSIS
profile.pl [-n name] -c <cpulist> [-x <bitmask>] [-s skip]
[-no_dplace] \
[-E event] [-N number] [-S tmpfile] [-O pro
file] [-P prog] \
[-K] [-T seconds] [-L pidlist] [command] [args]
DESCRIPTION
profile.pl is a Perl script that provides a simple way to
do procedure-level profiling of a program on a Linux IA64
system. Symbol information is required to be present in
the program text -- profile.pl does not produce useful
output on programs that have been processed by strip.
While profile.pl is designed to work with the SGI Altix
3000 system, the only real dependency profile.pl has on
that system is that profile.pl will use dplace to control
binding of processes to processors.
profile.pl will also work on Linux IA64 systems without
dplace. (See below under Using profile.pl without
dplace.)
The simplest way to use profile.pl is as follows:
profile.pl -c0-3 test_program
In this case, it is assumed that the test_program uses 4
processes. The 4 processes will be bound to processors
0-3 (via dplace) and the program will be profiled under
control of pfmon. The profile event will be CPU_CYCLES
and the PMU will be set up to generate approximately 100
interrupts per second (this is the default event and
rate).
One can specify all of the normal dplace options to pro
file.pl. Except for the -c option, they are not parsed by
profile.pl and are merely handed along to dplace. The -c
option is parsed so that profile.pl can tell pfmon which
processors to monitor. (The -c option must thus be speci
fied even if dplace is not used or available.)
The profile.pl script will create a map file (using
makemap.pl) for test_program and put it into test_pro
gram.map. The profile samples themselves will go into
sample.out. The analyzed profile will go into pro
file.out. (All of the names can be modified using options
to profile.pl.) The map file will not be created again
until it is deleted or test_program is updated.
specify the "-x 6" option as well (to get dplace to ignore
the two shepherd processes that the OpenMP library cre
ates):
profile.pl -c0-3 -x 6 test_program
Program arguments can be supplied as follows:
profile.pl -c0-3 test_program arg1 arg2 arg3 etc
To make input or output redirection apply to test_program
only, you need to put quotes around the program name as
follows:
profile.pl -c0-3 'test_program <input >output'
otherwise the redirection applies to profile.pl instead,
which is probably not what you wanted.
profile.pl requires that pfmon, makemap.pl, and analyze.pl
are all accessible in the current search path.
profile.pl assumes that the file named System.map in the
current working directory is the correct System.map for
the currently running kernel and will (by default) produce
a kernel profile as well as a profile for test_program.
If there is no System.map file in the current working
directory, then profile observations from the kernel will
be thrown away during profile analysis.
OPTIONS
Lowercase letter options are options to dplace or some
other program that profile.pl calls; uppercase options are
options to profile.pl.
-c, -s, -n, -s, -p
are all options as for dplace. Of these, the -c
option is the only option that is parsed by pro
file.pl. (This is how profile.pl determines which
CPU's to profile). The other dplace options are
just handed through to dplace. The -p option is
unimplemented in dplace or profile.pl at present.
-c <cpulist>
The cpulist is specified as a comma separate list
of cpu ranges, e. g.: -c0,3-5,7,9,13-20. These are
absolute cpu numbers (not relative to an enclosing
cpuset. See BUGS).
-no_dplace
Do not use dplace, even if it is present on the
system. (You still need to specify the -c option
to tell profile.pl which CPU's to profile.)
is the event name (as specified to pfmon). It
defaults to CPU_CYCLES. Use pfmon -l to get a list
of events supported on this processor.
-N number
gives the number of events/profile tick. If the
event being measured is CPU_CYCLES, the number of
events/profile tick defaults to 10000*cpuMHz which
implies 100 samples per second. (cpuMHz is
obtained from /proc/cpuinfo) The default only
applies to CPU_CYCLES; you must explicitly specify
the number of events/profile tick if you use some
other event.
The number of profile_ticks/second is the recipro
cal of the number of events/profile_tick as fol
lows:
profile_ticks/second = (event_rate/second) /
(events/profile_tick).
So, if your event is CPU_CYCLES, and you specify a
value of '-N 10000000' on a 1 GHZ machine, then the
profile_tick rate is 100 Hz:
profile_ticks/second = (1000000000 Hz) /
(10000000) = 100 Hz.
For other events, you will need to determine the
event_rate/second for your application, and then
determine a events/profile_tick value that gives a
reasonable number of profile_ticks/second. Use of
pfmon in event counting mode can help in estimating
the event_rate/second for your application.
-S tmpfile
gives the file name for the profile samples.
Defaults to sample.out.
-O profile
gives the file name for the analyzed profile.
Defaults to profile.out.
-P program
If first word of command is not the program to pro
file, use this option to specify the program name.
-K keep the separate per cpu sample files around and
produce a separate profile report for each cpu.
The file names for the intermediate files are based
on the default name or as specified with the -S
flag. The file names for the profile results files
are based on the default name or as specified by
in the file with suffix 'cpu.NN'.
-T secs
Run a timed profile experiment for the given number
of seconds. profile.pl will not run the command
under control of pfmon. (It is assumed the user
will run the command manually.) The program to
profile is either given as the first word of the
command or is specified by the -P option.
-L pidlist
pidlist is a comma separated list of process id's
(containing no blanks) This list will be passed to
the profile analyzer and will restrict profiling to
these process id's. This is normally used with the
-T option.
'command'
is the program to be profiled. Unless the -T
option is specified, command will be run under con
trol of pfmon. It will also be run under dplace if
dplace is available on the system and the
-no_dplace option is not specified. Command starts
with the first nonoption word on the command line.
Use quotes around command to have input or output
redirection apply only to the command.
NOTES
The above options allow you to profile on any performance
monitor event that makes sense (e. g. IA64_INST_RETIRED,
L3_MISSES, L3_LINES_REPLACED, L3_REFERENCES). You will
have to figure out, by trial and error, what value to
specify for samples/tick (the -N option) to get a reason
able number of ticks per second for your application.
profile.pl uses the following subsidiary scripts to create
the profile: makemap.pl and analyze.pl. makemap.pl cre
ates the map file used to map addresses to procedure
names. analyze.pl uses the map file and the profile sam
ples to create the actual profile. In certain cases, you
may wish to call these scripts directly. See the man
pages for these other scripts for further information on
how to do this.
Using profile.pl without dplace
pfmon profiles everything that runs on each measured pro
cessor. Use of the -c argument to profile.pl causes pfmon
to only measure those processors. However, profile.pl
itself has no control of what runs on those processors.
Instead, it uses dplace (if it is present on the system)
to bind processes to processors. Implicit in the design
of profile.pl is the assumption that only the measured
program runs on the measured processors during the
However, on a Linux IA64 system without dplace, there are
two possible problems: (1) profile.pl has no idea which
processors your program will run on, and (2) the rule that
only one particular program and process runs on each pro
cessor may be violated. To solve (1) in this case, pro
file.pl will tell pfmon to measure all of the processors.
However, your program may not use all of the processors in
the system, or there may be periods of time when processes
other than the ones you wish to measure can be running on
the measured processors. As a result, the profile may be
nonsensical (ticks for other programs, with a different
map file will be mixed in with those of the measured pro
gram, and interpreted according to the program.map file).
To get around this problem, you can tell analyze.pl which
process id's you want it to use (these are the process ids
for the program you wish to measure) as follows:
analyze.pl program.map sample.out PID1 PID2 PID3 etc
or analyze.pl program.map sample.out PID1,PID2,PID3,etc
You can determine the process id's either by examining the
sample.out file (the process id's are in the second column
and the CPU numbers are in the third column -- it is usu
ally good enough to use the most common process id's) or
you can modify your test program to print out the PIDs
(call getpid() and print out the result, hopefully only
once per process).
If you are running a timed experiment, (e. g. you will
start the processes to be measured "by hand" instead of
having profile.pl start them for you), then you can some
times come up with the list of process id's before you run
profile.pl (e. g. by running "top" in another window and
writing the process id's down by hand). In this case you
can specify the pid list to profile.pl with the -L option.
All that happens in this case is that the pid list is
given to the analyzer during the analysis phase.
An example of this might go something like the following:
(1) start up the program to be measured (we assume this
will run for a long time)
(2) Manually get the list of process id's somehow.
(3) Run profile.pl to do the measurement for 60 sec
onds, let us say:
profile.pl -T 60 -P program_foo -L pid,pid,pid -O
try1
(4) Repeat the above for a different 60 second
(5) Terminate the test programs.
FILES
/usr/bin/pfmon
/usr/local/bin/profile.pl
/usr/local/bin/makemap.pl
/usr/local/bin/analyze.pl
/usr/bin/dplace
/proc/cpuinfo
BUGS
Since profile.pl invokes pfmon in a way that causes pfmon
to create ASCII output files, the output files can grow to
be quite large (gigabytes in size) if an event rate of
1,000 HZ is specified and the profile is allowed to run
for tens of minutes. For such long runs, either reduce
the event rate or run the program manually and use the -T
option of profile.pl to run a profile that is shorter than
the entire run time of the program. One can run multiple
such experiments during the program run and use the -O
option to name the profile output files appropriately.
makemap.pl is normally called by profile.pl; in certain
cases profile.pl can't determine where the binary of the
program is, or doesn't notice that the binary bas been
modified and that makemap.pl needs to be rerun. In those
cases, makemap.pl needs to be run manually.
On the Altix 3000, pfmon is NOT currently cpumemset
enabled. So if you actually have an enclosing cpumemset,
then pfmon and dplace will be using different processors
number. So, for the moment, only use profile.pl when the
enclosing cpumemset is the default, global set.
The -N option has caused much confusion. This is NOT the
number of profile_ticks/second. Rather it is the recipro
cal of the number of profile_ticks/second as discussed
above.
SEE ALSO
pfmon, makemap.pl, analyze.pl, dplace.
Man(1) output converted with
man2html