libpfm  - a helper library to program the hardware perfor­
       mance counter of IA-64 CPUs


SYNOPSIS

       #include <perfmon/pfmlib.h>


DESCRIPTION

       The libpfm library is a helper library which can be called
       by  applications using the kernel perfmonctl() system call
       to program the performance monitoring unit (PMU) of  IA-64
       CPUs.

       The  kernel  perfmon  subsystem exports a simple interface
       which allows basic reading and writing of the  PMU  regis­
       ters.  There are two categories of PMU registers. The per­
       formance monitoring data registers (PMD) are used to  col­
       lects 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 con­
       sists 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 imple­
       mentation  of the IA-64 architecture to another. The asso­
       ciation of PMC to PMD can also change. Moreover the number
       and encoding of events can also widely change. In addition
       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  acces­
       sibility  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 implementa­
       tions. For instance, getting an event descriptor using the
       event  name is the same operation on all IA-64 implementa­
       tion, 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 ini­
       tialize 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
       function.

       When the library is initialized, it  automatically  probes

       layered design uses a modular implementation,  where  sup­
       port 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_ita­
       nium.h. The pfmlib_itanium2.h provides the Itanium2 inter­
       face.

       It  is important to realize that the library does not make
       any kernel perfmonctl() calls.  Given a set of  parameters
       describing  what needs to be measured, the library returns
       a set of arguments which can then be used to  program  the
       PMCS   via   the   perfmonctl()   system   call  with  the
       PFM_WRITE_PMCS command.

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


AUTHOR

       Stephane Eranian <eranian@hpl.hp.com>


SEE ALSO

       pfmlib_itanium(3), pfmlib_itanium2(3) and the set of exam­
       ples shipped with the library


Man(1) output converted with man2html