1LIBPFM(3) Linux Programmer's Manual LIBPFM(3)
2
6 libpfm - a helper library to program the hardware performance counters
7 of IA-64 CPUs
8
10 #include <perfmon/pfmlib.h>
11
13 The libpfm library is a helper library which can be used by applica‐
14 tions to program the IA-64 Performance Monitoring Unit (PMU). While it
15 is being developed on Linux in conjunction with the Linux/ia64 subsys‐
16 tem. It is generic enough to be used on other IA-64 operating systems.
17 It is important to realize that the library does not make the actual
18 kernel calls to program the PMU, it simply helps you figure out which
19 PMU registers to use to measure certains events. On Linux/ia64, for
20 instance, it does not make any perfmonctl call.
21 There are two categories of PMU registers. The performance monitoring
23 data registers (PMD) are used to collects counts or serve as hardware
24 buffers. The performance monitoring control registers (PMCS) are used
25 to indicate what events need to be monitored. Programming the PMU con‐
26 sists in setting up the PMC registers to monitor certain events. The
27 PMDS are commonly set to zero unless sampling is used.
28 The number of PMC and PMD registers varies from one implementation of
30 the IA-64 architecture to another. The association of PMC to PMD can
31 also change. Moreover the number and encoding of events can also widely
32 change. Finally, the structure of a PMC register can also change. All
33 these factors make it quite difficult to write monitoring tools.
34 This library is designed to simplify the programming of the PMC regis‐
36 ters by hiding the complexity behind simple interfaces. The library
37 does this without limiting accessibility to model specific features by
38 using a layered design.
39 The library is structured in two layers. The common layer provides an
41 interface that is shared by all implementations. For instance, getting
42 an event descriptor using the event name is the same operation on all
43 IA-64 implementation, even though the returned descriptor and the event
44 name can vary. This layer is good enough to setup simple monitoring
45 sessions which count occurrences of simple events. Then there is a
46 model specific layer which gives access to the model-specific features.
47 For instance, on Itanium, you can use the library to figure out how to
48 initialize PMC12 which controls the Branch Trace Buffer. Model specific
49 interfaces have the abbreviated PMU model name in their names. For
50 instance, pfm_ita2_get_event_umask() is an Itanium2 (ita2) specific
51 function.
52 When the library is initialized, it automatically probes the host CPU
54 and enables the right set of interfaces. The layered design uses a mod‐
55 ular implementation, where support for each CPU is well separated and
56 can be compiled in or out of the library.
57 The common interface is defined in the pfmlib.h header file. The Ita‐
59 nium specific interface is in pfmlib_itanium.h. The pfmlib_itanium2.h
60 provides the Itanium2 interface.
61 The common interface is described in individual man pages. There is one
63 man page for each model specific set of interfaces.
64
67 Stephane Eranian <eranian@hpl.hp.com>
68
70 pfmlib_itanium(3), pfmlib_itanium2(3) and the set of examples shipped
71 with the library
72 November, 2003 LIBPFM(3)