|
HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|
|
NAME | SYNOPSIS | DESCRIPTION | EVENT DETECTION | EVENT STRINGS | ENVIRONMENT VARIABLES | AUTHORS | SEE ALSO | COLOPHON |
|
|
|
LIBPFM(3) Linux Programmer's Manual LIBPFM(3)
libpfm - a helper library to develop monitoring tools
#include <perfmon/pfmlib.h>
This is a helper library used by applications to program specific
performance 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 processors, 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
Oprofile, 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
interface. 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 kernel to program a specific
event.
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.
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]
or
[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 specified after the equal sign. No space is allowed. In
case of boolean 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 [:modifier|: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.
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 additional 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.
LIBPFM_DISABLED_PMUS
Provides a list of PMU models to disable. This is a comma
separated list of PMU models. The PMU model is the string
in name field of the pfm_pmu_info_t structure. For
instance: LIBPFM_DISABLE_PMUS=core,snb, will disable both
the Intel Core and SandyBridge core PMU support.
Stephane Eranian <[email protected]>
Robert Richter <[email protected]>
libpfm_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_encoding(3), pfm_initialize(3)
Some examples are shipped with the library
This page is part of the perfmon2 (a performance monitoring
library) project. Information about the project can be found at
⟨http://perfmon2.sourceforge.net/⟩. If you have a bug report for
this manual page, send it to [email protected].
This page was obtained from the project's upstream Git repository
⟨git://git.code.sf.net/p/perfmon2/libpfm4 perfmon2-libpfm4⟩ on
2025-08-11. (At that time, the date of the most recent commit
that was found in the repository was 2025-06-29.) If you discover
any rendering problems in this HTML version of the page, or you
believe there is a better or more up-to-date source for the page,
or you have corrections or improvements to the information in this
COLOPHON (which is not part of the original manual page), send a
mail to [email protected]
May, 2010 LIBPFM(3)
|
HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|