LIBPFM(3) Linux Programmer's Manual LIBPFM(3)NAMElibpfm - a helper library to develop monitoring tools
SYNOPSIS
#include <perfmon/pfmlib.h>
DESCRIPTION
This is a helper library used by applications to program specific per‐
formance monitoring events. Those events are typically provided by the
hardware or the OS kernel. The most common hardware events are provided
by the Performance Monitoring Unit (PMU) of modern processors. They
can measure elapsed cycles or the number of cache misses. Software
events usually count kernel events such as the number of context
switches, or pages faults.
The library groups events based on which source is providing them. The
term PMU is generalized to any event source, not just hardware sources.
The library supports hardware performance events from most common pro‐
cessors, each group under a specific PMU name, such as Intel Core, IBM
Power 6.
Programming events is usually done through a kernel API, such as Opro‐
file, perfmon, perfctr, or perf_events on Linux. The library provides
support for perf_events which is available in the Linux kernel as of
v2.6.31. Perf_events supports selected PMU models and several software
events.
At its core, the library provides a simple translation service, whereby
a user specifies an event to measure as a string and the library
returns the parameters needed to invoke the kernel API. It is important
to realize that the library does not make the system call to program
the event.
Note: You must first call pfm_initialize() in order to use any of the
other provided functions in the library.
A first part of the library provides an event listing and query inter‐
face. This can be used to discover the events available on a specific
hardware platform.
The second part of the library provides a set of functions to obtain
event encodings form event strings. Event encoding depends primarily on
the underlying hardware but also on the kernel API. The library offers
a generic API to address the first situation but it also provides entry
points for specific kernel APIs such as perf_events. In that case, it
is able to prepare the data structure which must be passed to the ker‐
nel to program a specific event.
EVENT DETECTION
When the library is initialized via pfm_initialize(), it first detects
the underlying hardware and software configuration. Based on this
information it enables certain PMU support. Multiple events tables may
be activated.
It is possible to force activation of a specific PMU (group of events)
using an environment variable.
EVENT STRINGS
Events are expressed as strings. Those string are structured and may
contain several components depending on the type of event and the
underlying hardware.
String parsing is always case insensitive.
The string structure is defined as follows:
[pmu::][event_name][:unit_mask][:modifier|:modifier=val]
The components are defined as follows:
pmu Optional name of the PMU (group of events) to which the event
belongs to. This is useful to disambiguate events in case events
from difference sources have the same name. If not specified,
the first match is used.
event_name
The name of the event. It must be the complete name, partial
matches are not accepted. This component is required.
unit_mask
This designate an optional sub-events. Some events can be
refined using sub-events. Event may have multiple unit masks
and it may or may be possible to combine them. If more than one
unit masks needs to be passed, then the [:unit_mask] pattern can
be repeated.
modifier
A modifier is an optional filter which modifies how the event
counts. Modifiers have a type and a value. The value is speci‐
fied after the equal sign. No space is allowed. In case of bool‐
ean modifiers, it is possible to omit the value true (1). The
presence of the modifier is interpreted as meaning true. Events
may support multiple modifiers, in which case the [:modi‐
fier|:modifier=val] pattern can be repeated. The is no ordering
constraint between modifier and unit masks. Modifiers may be
specified before unit masks and vice-versa.
ENVIRONMENT VARIABLES
It is possible to enable certain debug features of the library using
environment variables. The following variables are defined:
LIBPFM_VERBOSE
Enable verbose output. Value must be 0 or 1.
LIBPFM_DEBUG
Enable debug output. Value must be 0 or 1
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).
LIBPFM_FORCE_PMU
Force a specific PMU model to be activated. In this mode, only
that one model is activated. The value of the variable must be
the PMU name as returned by the pfm_get_pmu_name() function.
Note for some PMU models, it may be possible to specify addi‐
tional options, such as specific processor models or stepping.
Additional parameters necessarily appears after a comma. For
instance, LIBPFM_FORCE_PMU=amd64,16,2,1.
LIBPFM_ENCODE_INACTIVE
Set this variable to 1 to enable encoding of events for non
detected, but supported, PMUs models.
AUTHORS
Stephane Eranian <eranian@gmail.com>
Robert Richter <robert.richter@amd.com>
SEE ALSOlibpfm_amd64_k7(3), libpfm_amd64_k8(3), libpfm_amd64_fam10h(3),
libpfm_intel_core(3), libpfm_intel_atom(3), libpfm_intel_p6(3),
libpfm_intel_nhm(3), libpfm_intel_nhm_unc(3), pfm_get_perf_event_encod‐
ing(3), pfm_initialize(3)
Some examples are shipped with the library
May, 2010 LIBPFM(3)
