1LIBPFM(3) Linux Programmer's Manual LIBPFM(3)
2
6 libpfm - a helper library to develop monitoring tools
7
9 #include <perfmon/pfmlib.h>
10
13 This is a helper library used by applications to program specific per‐
14 formance monitoring events. Those events are typically provided by the
15 hardware or the OS kernel. The most common hardware events are provided
16 by the Performance Monitoring Unit (PMU) of modern processors. They
17 can measure elapsed cycles or the number of cache misses. Software
18 events usually count kernel events such as the number of context
19 switches, or pages faults.
20 The library groups events based on which source is providing them. The
22 term PMU is generalized to any event source, not just hardware sources.
23 The library supports hardware performance events from most common pro‐
24 cessors, each group under a specific PMU name, such as Intel Core, IBM
25 Power 6.
26 Programming events is usually done through a kernel API, such as Opro‐
28 file, perfmon, perfctr, or perf_events on Linux. The library provides
29 support for perf_events which is available in the Linux kernel as of
30 v2.6.31. Perf_events supports selected PMU models and several software
31 events.
32 At its core, the library provides a simple translation service, whereby
34 a user specifies an event to measure as a string and the library
35 returns the parameters needed to invoke the kernel API. It is important
36 to realize that the library does not make the system call to program
37 the event.
38 Note: You must first call pfm_initialize() in order to use any of the
40 other provided functions in the library.
41 A first part of the library provides an event listing and query inter‐
43 face. This can be used to discover the events available on a specific
44 hardware platform.
45 The second part of the library provides a set of functions to obtain
47 event encodings form event strings. Event encoding depends primarily on
48 the underlying hardware but also on the kernel API. The library offers
49 a generic API to address the first situation but it also provides entry
50 points for specific kernel APIs such as perf_events. In that case, it
51 is able to prepare the data structure which must be passed to the ker‐
52 nel to program a specific event.
53
56 When the library is initialized via pfm_initialize(), it first detects
57 the underlying hardware and software configuration. Based on this
58 information it enables certain PMU support. Multiple events tables may
59 be activated.
60 It is possible to force activation of a specific PMU (group of events)
62 using an environment variable.
63
66 Events are expressed as strings. Those string are structured and may
67 contain several components depending on the type of event and the
68 underlying hardware.
69 String parsing is always case insensitive.
71 The string structure is defined as follows:
73 [pmu::][event_name][:unit_mask][:modifier|:modifier=val]
75 or
77 [pmu::][event_name][.unit_mask][.modifier|.modifier=val]
78 The components are defined as follows:
80 pmu Optional name of the PMU (group of events) to which the event
82 belongs to. This is useful to disambiguate events in case events
83 from difference sources have the same name. If not specified,
84 the first match is used.
85 event_name
87 The name of the event. It must be the complete name, partial
88 matches are not accepted. This component is required.
89 unit_mask
91 This designate an optional sub-events. Some events can be
92 refined using sub-events. Event may have multiple unit masks
93 and it may or may be possible to combine them. If more than one
94 unit masks needs to be passed, then the [:unit_mask] pattern can
95 be repeated.
96 modifier
98 A modifier is an optional filter which modifies how the event
99 counts. Modifiers have a type and a value. The value is speci‐
100 fied after the equal sign. No space is allowed. In case of bool‐
101 ean modifiers, it is possible to omit the value true (1). The
102 presence of the modifier is interpreted as meaning true. Events
103 may support multiple modifiers, in which case the [:modi‐
104 fier|:modifier=val] pattern can be repeated. The is no ordering
105 constraint between modifier and unit masks. Modifiers may be
106 specified before unit masks and vice-versa.
107
110 It is possible to enable certain debug features of the library using
111 environment variables. The following variables are defined:
112 LIBPFM_VERBOSE
114 Enable verbose output. Value must be 0 or 1.
115 LIBPFM_DEBUG
117 Enable debug output. Value must be 0 or 1
118 LIBPFM_DEBUG_STDOUT
120 Redirect verbose and debug output to the standard output file
121 descriptor (stdout). By default, the output is directed to the
122 standard error file descriptor (stderr).
123 LIBPFM_FORCE_PMU
125 Force a specific PMU model to be activated. In this mode, only
126 that one model is activated. The value of the variable must be
127 the PMU name as returned by the pfm_get_pmu_name() function.
128 Note for some PMU models, it may be possible to specify addi‐
129 tional options, such as specific processor models or stepping.
130 Additional parameters necessarily appears after a comma. For
131 instance, LIBPFM_FORCE_PMU=amd64,16,2,1.
132 LIBPFM_ENCODE_INACTIVE
134 Set this variable to 1 to enable encoding of events for non
135 detected, but supported, PMUs models.
136 LIBPFM_DISABLED_PMUS
138 Provides a list of PMU models to disable. This is a comma sepa‐
139 rated list of PMU models. The PMU model is the string in name
140 field of the pfm_pmu_info_t structure. For instance: LIBPFM_DIS‐
141 ABLE_PMUS=core,snb, will disable both the Intel Core and Sandy‐
142 Bridge core PMU support.
143
146 Stephane Eranian <eranian@gmail.com>
147 Robert Richter <robert.richter@amd.com>
148
150 libpfm_amd64_k7(3), libpfm_amd64_k8(3), libpfm_amd64_fam10h(3),
151 libpfm_intel_core(3), libpfm_intel_atom(3), libpfm_intel_p6(3),
152 libpfm_intel_nhm(3), libpfm_intel_nhm_unc(3), pfm_get_perf_event_encod‐
153 ing(3), pfm_initialize(3)
154 Some examples are shipped with the library
156 May, 2010 LIBPFM(3)