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