libpfm(3) — Linux manual page

NAME | SYNOPSIS | DESCRIPTION | EVENT DETECTION | EVENT STRINGS | ENVIRONMENT VARIABLES | AUTHORS | SEE ALSO | COLOPHON

LIBPFM(3)               Linux Programmer's Manual              LIBPFM(3)

NAME         top

       libpfm - a helper library to develop monitoring tools

SYNOPSIS         top

       #include <perfmon/pfmlib.h>

DESCRIPTION         top

       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         top

       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         top

       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         top

       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         top

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

SEE ALSO         top

       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

COLOPHON         top

       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
       perfmon2-devel@lists.sourceforge.net.  This page was obtained
       from the project's upstream Git repository
       ⟨git://git.code.sf.net/p/perfmon2/libpfm4 perfmon2-libpfm4⟩ on
       2023-12-22.  (At that time, the date of the most recent commit
       that was found in the repository was 2023-09-28.)  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 man-pages@man7.org

                                May, 2010                      LIBPFM(3)