Man Linux: Main Page and Category List


       libpfm  - a helper library to program the hardware performance counters
       of IA-64 CPUs


       #include <perfmon/pfmlib.h>


       The  libpfm  library  is  a  helper  library  which  can  be  used   by
       applications  to  program  the IA-64 Performance Monitoring Unit (PMU).
       While it is being developed on Linux in conjunction with the Linux/ia64
       subsystem.  It  is  generic  enough to be used on other IA-64 operating
       systems. It is important to realize that the library does not make  the
       actual kernel calls to program the PMU, it simply helps you  figure out
       which PMU registers to use to measure certains events.  On  Linux/ia64,
       for instance, it does not make any perfmonctl call.

       There  are  two categories of PMU registers. The performance monitoring
       data registers (PMD) are used to collects counts or serve  as  hardware
       buffers.  The  performance monitoring control registers (PMCS) are used
       to indicate what events need  to  be  monitored.  Programming  the  PMU
       consists in setting up the PMC registers to monitor certain events. The
       PMDS are commonly set to zero unless sampling is used.

       The number of PMC and PMD registers varies from one  implementation  of
       the  IA-64  architecture  to another. The association of PMC to PMD can
       also change. Moreover the number and encoding of events can also widely
       change.  Finally,  the structure of a PMC register can also change. All
       these factors make it quite difficult to write monitoring tools.

       This library is  designed  to  simplify  the  programming  of  the  PMC
       registers  by  hiding  the  complexity  behind  simple  interfaces. The
       library does this without  limiting  accessibility  to  model  specific
       features by using a layered design.

       The  library  is structured in two layers. The common layer provides an
       interface that is shared by all implementations. For instance,  getting
       an  event  descriptor using the event name is the same operation on all
       IA-64 implementation, even though the returned descriptor and the event
       name  can  vary.   This layer is good enough to setup simple monitoring
       sessions which count occurrences of simple  events.  Then  there  is  a
       model specific layer which gives access to the model-specific features.
       For instance, on Itanium, you can use the library to figure out how  to
       initialize PMC12 which controls the Branch Trace Buffer. Model specific
       interfaces have the abbreviated PMU model  name  in  their  names.  For
       instance,  pfm_ita2_get_event_umask()  is  an  Itanium2 (ita2) specific

       When the library is initialized, it automatically probes the  host  CPU
       and  enables  the  right  set  of interfaces. The layered design uses a
       modular implementation, where support for each CPU  is  well  separated
       and can be compiled in or out of the library.

       The  common  interface  is  defined  in  the  pfmlib.h header file. The
       Itanium   specific    interface    is    in    pfmlib_itanium.h.    The
       pfmlib_itanium2.h provides the Itanium2 interface.

       The common interface is described in individual man pages. There is one
       man page for each model specific set of interfaces.


       Stephane Eranian <>


       pfmlib_itanium(3), pfmlib_itanium2(3) and the set of  examples  shipped
       with the library

                                November, 2003