Ubuntu Manpage: libpfm - a helper library to develop monitoring tools

name
synopsis
description
event detection
event strings
environment variables
authors
see also

NAME

       libpfm - a helper library to develop monitoring tools

SYNOPSIS

       #include <perfmon/pfmlib.h>

DESCRIPTION

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.

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]

       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.

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 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.

AUTHORS

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