# libpfm

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


* * *