libpfm - a helper library to program the hardware perfor
mance counter of IA-64 CPUs
SYNOPSIS
#include <perfmon/pfmlib.h>
DESCRIPTION
The libpfm library is a helper library which can be called
by applications using the kernel perfmonctl() system call
to program the performance monitoring unit (PMU) of IA-64
CPUs.
The kernel perfmon subsystem exports a simple interface
which allows basic reading and writing of the PMU regis
ters. There are two categories of PMU registers. The per
formance monitoring data registers (PMD) are used to col
lects counts or serve as hardware buffers. The performance
monitoring control registers (PMCS) are used to indicate
what events need to be monitored. Programming the PMU con
sists in setting up the PMC registers to monitor certain
events. The PMDS are commonly set to zero unless sampling
is used.
The number of PMC and PMD registers varies from one imple
mentation of the IA-64 architecture to another. The asso
ciation of PMC to PMD can also change. Moreover the number
and encoding of events can also widely change. In addition
the structure of a PMC register can also change. All these
factors make it quite difficult to write monitoring tools.
This library is designed to simplify the programming of
the PMC registers by hiding the complexity behind simple
interfaces. The library does this without limiting acces
sibility to model specific features by using a layered
design.
The library is structured in two layers. The common layer
provides an interface that is shared by all implementa
tions. For instance, getting an event descriptor using the
event name is the same operation on all IA-64 implementa
tion, even though the returned descriptor and the event
name can vary. This layer is good enough to setup simple
monitoring sessions which count occurrences of simple
events. Then there is a model specific layer which gives
access to the model-specific features. For instance, on
Itanium, you can use the library to figure out how to ini
tialize PMC12 which controls the Branch Trace Buffer.
Model specific interfaces have the abbreviated PMU model
name in their names. For instance,
pfm_ita2_get_event_umask() is an Itanium2 (ita2) specific
function.
When the library is initialized, it automatically probes
layered design uses a modular implementation, where sup
port for each CPU is well separated and can be compiled in
or out of the library.
The common interface is defined in the pfmlib.h header
file. The Itanium specific interface is in pfmlib_ita
nium.h. The pfmlib_itanium2.h provides the Itanium2 inter
face.
It is important to realize that the library does not make
any kernel perfmonctl() calls. Given a set of parameters
describing what needs to be measured, the library returns
a set of arguments which can then be used to program the
PMCS via the perfmonctl() system call with the
PFM_WRITE_PMCS command.
The common interface is described in individual man pages.
There is one man page for each model specific set of
interfaces.
AUTHOR
Stephane Eranian <eranian@hpl.hp.com>
SEE ALSO
pfmlib_itanium(3), pfmlib_itanium2(3) and the set of exam
ples shipped with the library
Man(1) output converted with
man2html