libpfm(3) - Linux man page

Name

Synopsis

#include <perfmon/pfmlib.h>DescriptionThe libpfm library is a helper library
which is used by applications to help program the Performance Monitoring
Unit (PMU), i.e., the hardware performance counters of modern processors.
It provides a generic and portable programming interface to help setup
the PMU configuration registers given a list of events to measure.  A diversity
of PMU hardware is supported, a list can be found below under SUPPORTED
HARDWARE. The library is primarily designed to be used in conjunction with
the Perfmon2 Linux kernel interface. However, at its core, it is totally
independent of that interface and could as well be used on other operating
systems. It is important to realize that the library does not make the actual
kernel calls to program the PMU, it simply helps applications figure out
which PMU registers to use to measure certain events or access certain
advanced PMU features.   The library logically divides PMU registers into
two categories. The performance monitoring data registers (PMD) are used
to collect results, e.g., counts. The performance monitoring configuration
registers (PMCS) are used to indicate what events to measure or what feature
to enable. Programming the PMU consists in setting up the PMC registers
and collecting the results in the PMD registers. The central piece of the
library is the pfm_dispatch_events function.  The number of PMC and PMD
registers varies between architectures and CPU models. The association of
PMC to PMD can also change. Moreover the number and encodings of events
can also widely change. Finally, 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 a simple interface. The library does this
without limiting accessibility 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 across all PMU models. This layer is good enough
to setup simple monitoring sessions which count occurrences of events. Then,
there is a model-specific layer which gives access to the model-specific
features. For instance, on Itanium, applications can use the library to
setup the registers for 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 the host CPU and enables the right set of interfaces.
  The common interface is defined in the pfmlib.h header file. Model-specific
interfaces are defined in model-specific header files. For instance, pfmlib_amd64.h
provides the AMD64 interface. Environment VariablesIt is possible to enable
certain debug output of the library using environment variables. The following
variables are defined: LIBPFM_VERBOSE Enable verbose output. Value must
be 0 or 1. When not set, verbosity level can be controlled with this function.
LIBPFM_DEBUG Enable debug  output. Value must be 0 or 1. When not set, debug
level can be controlled with this function. LIBPFM_DEBUG_STDOUT Redirect
verbose and debug output to the standard output file descriptor (stdout).
By default, the output is directed to the standard error file descriptor
(stderr). Alternatively, it is possible to control verbosity and debug output
using the pfm_set_options function.
Supported Hardware
libpfm_amd64(3)     AMD64 processors K8 and Barcelona (families 0Fh and
10h)
libpfm_core(3)      Intel Core processor family
libpfm_atom(3)      Intel Atom processor family
libpfm_itanium(3)   Intel Itanium
libpfm_itanium2(3)  Intel Itanium 2
libpfm_montecito(3) Intel dual-core Itanium 2 9000 (Montecito)
libpfm_p6(3)        P6 processor family including the Pentium M processor
libpfm_powerpc(3)   IBM PowerPC and POWER processor families
                    (PPC970(FX,GX), PPC970MP POWER4, POWER4+, POWER5,
                    POWER5+, and POWER6)

Authors

Stephane Eranian <eranian@hpl.hp.com>
Robert Richter <robert.richter@amd.com>

See Alsolibpfm(3), libpfm_amd64(3), libpfm_core(3), libpfm_itanium2(3),
libpfm_itanium(3), libpfm_montecito(3), libpfm_p6(3), libpfm_powerpc(3).

pfm_dispatch_events(3), pfm_find_event(3), pfm_set_options(3),
pfm_get_cycle_event(3), pfm_get_event_name(3), pfm_get_impl_pmcs(3),
pfm_get_pmu_name(3), pfm_get_version(3), pfm_initialize(3),
pfm_regmask_set(3), pfm_set_options(3), pfm_strerror(3).