1LIBPFM(3) Linux Programmer's Manual LIBPFM(3)
2
6 libpfm - a helper library to program Hardware Performance Units (PMUs)
7
9 #include <perfmon/pfmlib.h>
10
12 The libpfm library is a helper library which is used by applications to
13 help program the Performance Monitoring Unit (PMU), i.e., the hardware
14 performance counters of modern processors. It provides a generic and
15 portable programming interface to help setup the PMU configuration reg‐
16 isters given a list of events to measure.
17 A diversity of PMU hardware is supported, a list can be found below
19 under SUPPORTED HARDWARE. The library is primarily designed to be used
20 in conjunction with the Perfmon2 Linux kernel interface. However, at
21 its core, it is totally independent of that interface and could as well
22 be used on other operating systems. It is important to realize that the
23 library does not make the actual kernel calls to program the PMU, it
24 simply helps applications figure out which PMU registers to use to mea‐
25 sure certain events or access certain advanced PMU features.
26 The library logically divides PMU registers into two categories. The
28 performance monitoring data registers (PMD) are used to collect
29 results, e.g., counts. The performance monitoring configuration regis‐
30 ters (PMCS) are used to indicate what events to measure or what feature
31 to enable. Programming the PMU consists in setting up the PMC registers
32 and collecting the results in the PMD registers. The central piece of
33 the library is the pfm_dispatch_events function.
34 The number of PMC and PMD registers varies between architectures and
36 CPU models. The association of PMC to PMD can also change. Moreover the
37 number and encodings of events can also widely change. Finally, the
38 structure of a PMC register can also change. All these factors make it
39 quite difficult to write monitoring tools.
40 This library is designed to simplify the programming of the PMC regis‐
42 ters by hiding the complexity behind a simple interface. The library
43 does this without limiting accessibility to model specific features by
44 using a layered design.
45 The library is structured in two layers. The common layer provides an
47 interface that is shared across all PMU models. This layer is good
48 enough to setup simple monitoring sessions which count occurrences of
49 events. Then, there is a model-specific layer which gives access to the
50 model-specific features. For instance, on Itanium, applications can
51 use the library to setup the registers for the Branch Trace Buffer.
52 Model-specific interfaces have the abbreviated PMU model name in their
53 names. For instance, pfm_ita2_get_event_umask() is an Itanium2 (ita2)
54 specific function.
55 When the library is initialized, it automatically probes the host CPU
57 and enables the right set of interfaces.
58 The common interface is defined in the pfmlib.h header file. Model-
60 specific interfaces are defined in model-specific header files. For
61 instance, pfmlib_amd64.h provides the AMD64 interface.
62
64 It is possible to enable certain debug output of the library using
65 environment variables. The following variables are defined:
66 LIBPFM_VERBOSE
68 Enable verbose output. Value must be 0 or 1. When not set, ver‐
69 bosity level can be controlled with this function.
70 LIBPFM_DEBUG
72 Enable debug output. Value must be 0 or 1. When not set, debug
73 level can be controlled with this function.
74 LIBPFM_DEBUG_STDOUT
76 Redirect verbose and debug output to the standard output file
77 descriptor (stdout). By default, the output is directed to the
78 standard error file descriptor (stderr).
79 Alternatively, it is possible to control verbosity and debug
81 output using the pfm_set_options function.
82
84 libpfm_amd64(3) AMD64 processors K8 and Barcelona (families 0Fh and 10h)
85 libpfm_core(3) Intel Core processor family
86 libpfm_atom(3) Intel Atom processor family
87 libpfm_itanium(3) Intel Itanium
88 libpfm_itanium2(3) Intel Itanium 2
89 libpfm_montecito(3) Intel dual-core Itanium 2 9000 (Montecito)
90 libpfm_p6(3) P6 processor family including the Pentium M processor
91 libpfm_powerpc(3) IBM PowerPC and POWER processor families
92 (PPC970(FX,GX), PPC970MP POWER4, POWER4+, POWER5,
93 POWER5+, and POWER6)
94
96 Stephane Eranian <eranian@hpl.hp.com>
97 Robert Richter <robert.richter@amd.com>
98
100 libpfm(3), libpfm_amd64(3), libpfm_core(3), libpfm_itanium2(3),
101 libpfm_itanium(3), libpfm_montecito(3), libpfm_p6(3), libpfm_pow‐
102 erpc(3).
103 pfm_dispatch_events(3), pfm_find_event(3), pfm_set_options(3),
104 pfm_get_cycle_event(3), pfm_get_event_name(3), pfm_get_impl_pmcs(3),
105 pfm_get_pmu_name(3), pfm_get_version(3), pfm_initialize(3),
106 pfm_regmask_set(3), pfm_set_options(3), pfm_strerror(3).
107 Examples shipped with the library
109 March, 2008 LIBPFM(3)