pfmon - user interface to IPF Performance Monitoring Unit
SYNOPSIS
pfmon [-h | --help] [-V | --version] [-l[regex] | --show-
event-list[=regex]] [-i <event> | --event-
info=event]
[-u | --user-level] [-k | --kernel-level] [-e |
--events=ev1,ev2,...] [-I | --info] [--debug]
[--verbose]
[--outfile=filename] [--append] [--overflow-block]
[--system-wide] [--cpu-mask=0xn]
[-S format | --smpl-output-info=format] [-t secs |
--session-timeout=secs] [--smpl-outfile=filename]
[--smpl-entries=val] [--long-smpl-peri
ods=val1,val2,...] [--short-smpl-peri
ods=val1,val2,...]
[--compact-smpl-output] [--raw-trace-file] [--with-
header] [--aggregate-results] [--tigger-
address=addr]
[--priv-levels=lvl1,lvl2,...] [--show-time] [--us-
counter-format] [--eu-counter-format]
[--hex-counter-format] [--smpl-output-format=fmt]
[--long-show-events[=regex] [--symbol-file=file
name]
[--sysmap-file=filename] [--check-events-only]
[--smpl-periods-random=mask1:seed1,...]
DESCRIPTION
pfmon is a performance monitoring tool that provides a
user-level interface to the Performance Monitoring Unit
(PMU) built into the Itanium 2 [TM] (IPF) processor chip.
pfmon can be used to count or sample PMU events for unmod
ified binaries in its per-process mode and it can also be
used to run system-wide monitoring sessions. Pfmon can
monitor activities happening at the user and/or kernel
level for both type of sessions. These counts and samples
can be used to optimize program performance on the IPF
processor.
In per-process mode, pfmon can only monitor the first pro
cess (task). Subsequent processes or threads created by
that initial process will not be monitored.
pfmon can run on any IPF CPU model and provides the mini
mal features mandated by the architecture but it also pro
vides model specific extensions. For instance, on Itanium
2 pfmon has support for the EAR and BTB features.
pfmon is based on a generic helper library called libpfm
which is included in this package. The library is not
specific to pfmon and can be used directly by other pro
grams as is demonstrated in the set of examples also
a modular architecture which makes it easier to support
new PMU models as they become available.
FURTHER DETAILS
Further details on pfmon can be found in the users guide
at /usr/share/doc/pfmon-1.1/pfmon_usersguide.txt.
Further details on libpfm can be found on the man page for
libpfm.
Further details on the Itanium 2 PMU can be found in
"Intel Itanium 2 Processor Referenece Manual for Software
Development and Optimization," available as a .pdf file
from www.intel.com.
OPTIONS
-h, --help
display the list of supported options
-V, --version
display pfmon version information
-l[regex], --show-event-list[=regex]
show list of supported events by host PMU
-i <event>, --event-info=event
get information about a particular event.
-u, --user-level
monitor at the user level for all events. Per-
event setting is possible with --priv-levels
-k, --kernel-level
monitor at the kernel level for all events. Per-
event setting is possible with --priv-levels
-e, --events=ev1,ev2,...
select events to monitor. There should be no space
between the events.The number of events that you
can specify is dependent on the underlying PMU
model. Four events is typical.
-I,--info
list the compiled in PMU models supported by pfmon
and detected host PMU as well as sampling output
formats.
--debug
enable debug prints.
--verbose
print more information during execution.
print counts in a file
--append
when used with --outfile, will open the file in
append mode.
--overflow-block
do not block the monitored program on overflow
notifications (per process mode only).
--system-wide
create a system wide monitoring session. Default
session type is per process.
--cpu-mask=0xn
bitmask indicating on which CPU to start system
wide monitoring. When this option is not specified,
pfmon will monitor on all CPUs.
-S format, --smpl-output-info=format
display information about a sampling output format.
-t secs, --session-timeout=secs
duration of the session in seconds. In per process
mode, the process will get killed if the timeout
expires.
--smpl-outfile=filename
save sampling results in a file.
--smpl-entries=val
size of the sampling buffer in number of entries
default=2048).
--long-smpl-periods=val1,val2,...
set sampling periods for each event after user
level notification.
--short-smpl-periods=val1,val2,...
set sampling period for each event.
--compact-smpl-output
enable compact output for sampling results.
--raw-trace-file
enable raw output for sampling results.
--with-header
generate a machine description header with results.
--aggregate-results
aggregate counts and sampling buffer outputs when
running system wide monitoring on multiple CPUs.
start monitoring only when execution reaches addr
(code) for the first time.
--priv-levels=lvl1,lvl2,...
set privilege level per event. lvl can be any of u
(user), k( kernel), uk (kernel & user). Unspecified
events, will get global setting which is user only
by default.
--show-time
show real,user, and system time for the executed
command.
--us-counter-format
print counters using commas (1,024).
--eu-counter-format
print counters using points (1.024).
--hex-counter-format
print counters in hexadecimal (0x400).
--smpl-output-format=fmt
select fmt as sampling output format, use -L to
list formats. There is no default format, so you
need to specify one each time you enable sampling
via --long-smpl-periods or --short-smpl-periods.
--long-show-events[=regex]
display detailed information about matching events
in a single (easy grep)
--symbol-file=filename
use the ELF archive filename to look for symbols
--sysmap-file=filename
use the System.map filename to look for symbols
--check-events-only
check that the event combination is valid and exit
(no measurement)
--smpl-periods-random=mask1:seed1,...
apply randomization to long and short periods.
This is used to avoid sampling defects that occur
if some system process has the same period
(exactly) as the long or short sampling intervales.
(Note for: Altix 3000 see Bugs.)
DIAGNOSTICS
The kernel perfmon susbsystem upon which pfmon depends is
built into the Altix 3000 Linux Kernel by default (the
option CONFIG_PERFMON is enabled is enabled by default).
will fail with the message "host kernel does not have
perfmon support".
If someone on the system has already started a system-wide
performance monitoring session, then attempts to start
another system-wide session will result in the additional
sessions failing with the error: "concurrent conflicting
monitoring session is present in your system". Sometimes
this error occurs because the previous monitoring session
did not close down completely. Try " killall pfmon" in
this case to terminate the previous monitoring session.
Numerous other diagnostics related to the specific events
and syntatic and semantic errors of the command invocation
are also provided.
BUGS
The --smpl-periods-random option requires a 2.4.20 or
later kernel and is not currently supported on the SGI
Altix 3000 system.
SEE ALSO
/usr/share/doc/pfmon-2.0/pfmon_usersguide.txt, man 1
libpfm
man libpfm
AUTHOR
Stephane Eranian (eranian@hpl.hp.com) at Hewlett-Packard.
Man(1) output converted with
man2html