libpfm library overview

The libpfm library is a helper library which can be used monitoring tools. The library contains all the PMU model-specific information such as the events names and encodings, and the various constraints between events. You specify what you want to measure and the library returns how you need to program to PMU.

The library is designed in a modular fashion such that new PMU models can be added in the future. Conceptually the library is structured with two layers:

• a generic layer which provides a common interface across all PMU models
• a model specific layer which implements the features specific to a PMU model

This design allows for maximum flexibility while still hiding much PMU specific requirements for most common operations, such as for simple counting sessions.

The role of the library is to help applications setup parameters needed to program the PMU. Given a set of events to monitor, the challenge is to figure out on which PMC registers to program them and what values to use. Once you get the value pairs, you are free to use whatever kernel interface you have available to actually program the PMU. It is very important to realize that the library DOES NOT program the PMU for you. It is totally decoupled from any OS-specific interface, at least starting at version 3.0.

Events are manipulated using their symbolic names (a string). An event name must be converted into an encoding which must then be written to a PMC register. From one PMU model to another the set of events is different, fortunately some events remain. The encoding of an event can change from one PMU model to another. Moreover, any event cannot necessarily be measured by any counter or with other events due to some hardware design constraints. Managing this complexity can be tedious and this is what the library does for you.

The library currently supports the following processors architectures: during initialization:

• The Itanium® processor family (Itanium®, Itanium® 2 and generic)
• The X86-64 processor family
• The P6 processor family

The interface of the library manipulates events using opaque descriptors, i.e., simple integers. The library provides lookup functions to find an event descriptor given a name. Applications never manipulate the encoding of an event. The key call for the library is the pfm_dispatch_events() function which, given a set of event descriptors and some configuration parameters, figures out which PMC registers to use and the values to load into them. The entire configuration is described in the arguments to the call. For each event, it possible to specify the privilege level mask at which to monitor. Upon return from the call, a structure contains the PMU control registers indexes and their respective values. Those value pairs can then be copied into the kernel interface specific data structures to pass to the kernel. Model specific parameters can be passed to the pfm_dispatch_events() function.

There exists several versions of the library:

1. libpfm-2.x (Itanium® processors ONLY):

   This library is mostly used by pfmon-2.0. It incoporates features that are specific to the perfmon-1.x kernel interface. Therefore it is meant to be used only on 2.4-based kernels.

   
   
2. libpfm-3.0 and libpfm-3.1 (Itanium® processors ONLY):

   This library is used by pfmon-3.0. The core of the library is independent of the underlying OS interface. However due to some packaging issues, the library comes with some header files that are specific to the perfmon-2.x kernel interface. Therefore it is recommend that this library be used to develop perfmon-2.x-based applications.

libpfm-2.x and libpfm-3.x do not have compatible interfaces. Some simple recoding is necessary for all 2.0-based applications.