Loading...
1perf-list(1)
2============
3
4NAME
5----
6perf-list - List all symbolic event types
7
8SYNOPSIS
9--------
10[verse]
11'perf list' [--no-desc] [--long-desc]
12 [hw|sw|cache|tracepoint|pmu|sdt|metric|metricgroup|event_glob]
13
14DESCRIPTION
15-----------
16This command displays the symbolic event types which can be selected in the
17various perf commands with the -e option.
18
19OPTIONS
20-------
21-d::
22--desc::
23Print extra event descriptions. (default)
24
25--no-desc::
26Don't print descriptions.
27
28-v::
29--long-desc::
30Print longer event descriptions.
31
32--debug::
33Enable debugging output.
34
35--details::
36Print how named events are resolved internally into perf events, and also
37any extra expressions computed by perf stat.
38
39--deprecated::
40Print deprecated events. By default the deprecated events are hidden.
41
42[[EVENT_MODIFIERS]]
43EVENT MODIFIERS
44---------------
45
46Events can optionally have a modifier by appending a colon and one or
47more modifiers. Modifiers allow the user to restrict the events to be
48counted. The following modifiers exist:
49
50 u - user-space counting
51 k - kernel counting
52 h - hypervisor counting
53 I - non idle counting
54 G - guest counting (in KVM guests)
55 H - host counting (not in KVM guests)
56 p - precise level
57 P - use maximum detected precise level
58 S - read sample value (PERF_SAMPLE_READ)
59 D - pin the event to the PMU
60 W - group is weak and will fallback to non-group if not schedulable,
61 e - group or event are exclusive and do not share the PMU
62
63The 'p' modifier can be used for specifying how precise the instruction
64address should be. The 'p' modifier can be specified multiple times:
65
66 0 - SAMPLE_IP can have arbitrary skid
67 1 - SAMPLE_IP must have constant skid
68 2 - SAMPLE_IP requested to have 0 skid
69 3 - SAMPLE_IP must have 0 skid, or uses randomization to avoid
70 sample shadowing effects.
71
72For Intel systems precise event sampling is implemented with PEBS
73which supports up to precise-level 2, and precise level 3 for
74some special cases
75
76On AMD systems it is implemented using IBS (up to precise-level 2).
77The precise modifier works with event types 0x76 (cpu-cycles, CPU
78clocks not halted) and 0xC1 (micro-ops retired). Both events map to
79IBS execution sampling (IBS op) with the IBS Op Counter Control bit
80(IbsOpCntCtl) set respectively (see AMD64 Architecture Programmer’s
81Manual Volume 2: System Programming, 13.3 Instruction-Based
82Sampling). Examples to use IBS:
83
84 perf record -a -e cpu-cycles:p ... # use ibs op counting cycles
85 perf record -a -e r076:p ... # same as -e cpu-cycles:p
86 perf record -a -e r0C1:p ... # use ibs op counting micro-ops
87
88RAW HARDWARE EVENT DESCRIPTOR
89-----------------------------
90Even when an event is not available in a symbolic form within perf right now,
91it can be encoded in a per processor specific way.
92
93For instance For x86 CPUs NNN represents the raw register encoding with the
94layout of IA32_PERFEVTSELx MSRs (see [Intel® 64 and IA-32 Architectures Software Developer's Manual Volume 3B: System Programming Guide] Figure 30-1 Layout
95of IA32_PERFEVTSELx MSRs) or AMD's PerfEvtSeln (see [AMD64 Architecture Programmer’s Manual Volume 2: System Programming], Page 344,
96Figure 13-7 Performance Event-Select Register (PerfEvtSeln)).
97
98Note: Only the following bit fields can be set in x86 counter
99registers: event, umask, edge, inv, cmask. Esp. guest/host only and
100OS/user mode flags must be setup using <<EVENT_MODIFIERS, EVENT
101MODIFIERS>>.
102
103Example:
104
105If the Intel docs for a QM720 Core i7 describe an event as:
106
107 Event Umask Event Mask
108 Num. Value Mnemonic Description Comment
109
110 A8H 01H LSD.UOPS Counts the number of micro-ops Use cmask=1 and
111 delivered by loop stream detector invert to count
112 cycles
113
114raw encoding of 0x1A8 can be used:
115
116 perf stat -e r1a8 -a sleep 1
117 perf record -e r1a8 ...
118
119It's also possible to use pmu syntax:
120
121 perf record -e r1a8 -a sleep 1
122 perf record -e cpu/r1a8/ ...
123 perf record -e cpu/r0x1a8/ ...
124
125You should refer to the processor specific documentation for getting these
126details. Some of them are referenced in the SEE ALSO section below.
127
128ARBITRARY PMUS
129--------------
130
131perf also supports an extended syntax for specifying raw parameters
132to PMUs. Using this typically requires looking up the specific event
133in the CPU vendor specific documentation.
134
135The available PMUs and their raw parameters can be listed with
136
137 ls /sys/devices/*/format
138
139For example the raw event "LSD.UOPS" core pmu event above could
140be specified as
141
142 perf stat -e cpu/event=0xa8,umask=0x1,name=LSD.UOPS_CYCLES,cmask=0x1/ ...
143
144 or using extended name syntax
145
146 perf stat -e cpu/event=0xa8,umask=0x1,cmask=0x1,name=\'LSD.UOPS_CYCLES:cmask=0x1\'/ ...
147
148PER SOCKET PMUS
149---------------
150
151Some PMUs are not associated with a core, but with a whole CPU socket.
152Events on these PMUs generally cannot be sampled, but only counted globally
153with perf stat -a. They can be bound to one logical CPU, but will measure
154all the CPUs in the same socket.
155
156This example measures memory bandwidth every second
157on the first memory controller on socket 0 of a Intel Xeon system
158
159 perf stat -C 0 -a uncore_imc_0/cas_count_read/,uncore_imc_0/cas_count_write/ -I 1000 ...
160
161Each memory controller has its own PMU. Measuring the complete system
162bandwidth would require specifying all imc PMUs (see perf list output),
163and adding the values together. To simplify creation of multiple events,
164prefix and glob matching is supported in the PMU name, and the prefix
165'uncore_' is also ignored when performing the match. So the command above
166can be expanded to all memory controllers by using the syntaxes:
167
168 perf stat -C 0 -a imc/cas_count_read/,imc/cas_count_write/ -I 1000 ...
169 perf stat -C 0 -a *imc*/cas_count_read/,*imc*/cas_count_write/ -I 1000 ...
170
171This example measures the combined core power every second
172
173 perf stat -I 1000 -e power/energy-cores/ -a
174
175ACCESS RESTRICTIONS
176-------------------
177
178For non root users generally only context switched PMU events are available.
179This is normally only the events in the cpu PMU, the predefined events
180like cycles and instructions and some software events.
181
182Other PMUs and global measurements are normally root only.
183Some event qualifiers, such as "any", are also root only.
184
185This can be overridden by setting the kernel.perf_event_paranoid
186sysctl to -1, which allows non root to use these events.
187
188For accessing trace point events perf needs to have read access to
189/sys/kernel/debug/tracing, even when perf_event_paranoid is in a relaxed
190setting.
191
192TRACING
193-------
194
195Some PMUs control advanced hardware tracing capabilities, such as Intel PT,
196that allows low overhead execution tracing. These are described in a separate
197intel-pt.txt document.
198
199PARAMETERIZED EVENTS
200--------------------
201
202Some pmu events listed by 'perf-list' will be displayed with '?' in them. For
203example:
204
205 hv_gpci/dtbp_ptitc,phys_processor_idx=?/
206
207This means that when provided as an event, a value for '?' must
208also be supplied. For example:
209
210 perf stat -C 0 -e 'hv_gpci/dtbp_ptitc,phys_processor_idx=0x2/' ...
211
212EVENT QUALIFIERS:
213
214It is also possible to add extra qualifiers to an event:
215
216percore:
217
218Sums up the event counts for all hardware threads in a core, e.g.:
219
220
221 perf stat -e cpu/event=0,umask=0x3,percore=1/
222
223
224EVENT GROUPS
225------------
226
227Perf supports time based multiplexing of events, when the number of events
228active exceeds the number of hardware performance counters. Multiplexing
229can cause measurement errors when the workload changes its execution
230profile.
231
232When metrics are computed using formulas from event counts, it is useful to
233ensure some events are always measured together as a group to minimize multiplexing
234errors. Event groups can be specified using { }.
235
236 perf stat -e '{instructions,cycles}' ...
237
238The number of available performance counters depend on the CPU. A group
239cannot contain more events than available counters.
240For example Intel Core CPUs typically have four generic performance counters
241for the core, plus three fixed counters for instructions, cycles and
242ref-cycles. Some special events have restrictions on which counter they
243can schedule, and may not support multiple instances in a single group.
244When too many events are specified in the group some of them will not
245be measured.
246
247Globally pinned events can limit the number of counters available for
248other groups. On x86 systems, the NMI watchdog pins a counter by default.
249The nmi watchdog can be disabled as root with
250
251 echo 0 > /proc/sys/kernel/nmi_watchdog
252
253Events from multiple different PMUs cannot be mixed in a group, with
254some exceptions for software events.
255
256LEADER SAMPLING
257---------------
258
259perf also supports group leader sampling using the :S specifier.
260
261 perf record -e '{cycles,instructions}:S' ...
262 perf report --group
263
264Normally all events in an event group sample, but with :S only
265the first event (the leader) samples, and it only reads the values of the
266other events in the group.
267
268However, in the case AUX area events (e.g. Intel PT or CoreSight), the AUX
269area event must be the leader, so then the second event samples, not the first.
270
271OPTIONS
272-------
273
274Without options all known events will be listed.
275
276To limit the list use:
277
278. 'hw' or 'hardware' to list hardware events such as cache-misses, etc.
279
280. 'sw' or 'software' to list software events such as context switches, etc.
281
282. 'cache' or 'hwcache' to list hardware cache events such as L1-dcache-loads, etc.
283
284. 'tracepoint' to list all tracepoint events, alternatively use
285 'subsys_glob:event_glob' to filter by tracepoint subsystems such as sched,
286 block, etc.
287
288. 'pmu' to print the kernel supplied PMU events.
289
290. 'sdt' to list all Statically Defined Tracepoint events.
291
292. 'metric' to list metrics
293
294. 'metricgroup' to list metricgroups with metrics.
295
296. If none of the above is matched, it will apply the supplied glob to all
297 events, printing the ones that match.
298
299. As a last resort, it will do a substring search in all event names.
300
301One or more types can be used at the same time, listing the events for the
302types specified.
303
304Support raw format:
305
306. '--raw-dump', shows the raw-dump of all the events.
307. '--raw-dump [hw|sw|cache|tracepoint|pmu|event_glob]', shows the raw-dump of
308 a certain kind of events.
309
310SEE ALSO
311--------
312linkperf:perf-stat[1], linkperf:perf-top[1],
313linkperf:perf-record[1],
314http://www.intel.com/sdm/[Intel® 64 and IA-32 Architectures Software Developer's Manual Volume 3B: System Programming Guide],
315http://support.amd.com/us/Processor_TechDocs/24593_APM_v2.pdf[AMD64 Architecture Programmer’s Manual Volume 2: System Programming]
1perf-list(1)
2============
3
4NAME
5----
6perf-list - List all symbolic event types
7
8SYNOPSIS
9--------
10[verse]
11'perf list' [--no-desc] [--long-desc]
12 [hw|sw|cache|tracepoint|pmu|sdt|metric|metricgroup|event_glob]
13
14DESCRIPTION
15-----------
16This command displays the symbolic event types which can be selected in the
17various perf commands with the -e option.
18
19OPTIONS
20-------
21-d::
22--desc::
23Print extra event descriptions. (default)
24
25--no-desc::
26Don't print descriptions.
27
28-v::
29--long-desc::
30Print longer event descriptions.
31
32--debug::
33Enable debugging output.
34
35--details::
36Print how named events are resolved internally into perf events, and also
37any extra expressions computed by perf stat.
38
39--deprecated::
40Print deprecated events. By default the deprecated events are hidden.
41
42--unit::
43Print PMU events and metrics limited to the specific PMU name.
44(e.g. --unit cpu, --unit msr, --unit cpu_core, --unit cpu_atom)
45
46-j::
47--json::
48Output in JSON format.
49
50-o::
51--output=::
52 Output file name. By default output is written to stdout.
53
54[[EVENT_MODIFIERS]]
55EVENT MODIFIERS
56---------------
57
58Events can optionally have a modifier by appending a colon and one or
59more modifiers. Modifiers allow the user to restrict the events to be
60counted. The following modifiers exist:
61
62 u - user-space counting
63 k - kernel counting
64 h - hypervisor counting
65 I - non idle counting
66 G - guest counting (in KVM guests)
67 H - host counting (not in KVM guests)
68 p - precise level
69 P - use maximum detected precise level
70 S - read sample value (PERF_SAMPLE_READ)
71 D - pin the event to the PMU
72 W - group is weak and will fallback to non-group if not schedulable,
73 e - group or event are exclusive and do not share the PMU
74 b - use BPF aggregration (see perf stat --bpf-counters)
75
76The 'p' modifier can be used for specifying how precise the instruction
77address should be. The 'p' modifier can be specified multiple times:
78
79 0 - SAMPLE_IP can have arbitrary skid
80 1 - SAMPLE_IP must have constant skid
81 2 - SAMPLE_IP requested to have 0 skid
82 3 - SAMPLE_IP must have 0 skid, or uses randomization to avoid
83 sample shadowing effects.
84
85For Intel systems precise event sampling is implemented with PEBS
86which supports up to precise-level 2, and precise level 3 for
87some special cases
88
89On AMD systems it is implemented using IBS OP (up to precise-level 2).
90Unlike Intel PEBS which provides levels of precision, AMD core pmu is
91inherently non-precise and IBS is inherently precise. (i.e. ibs_op//,
92ibs_op//p, ibs_op//pp and ibs_op//ppp are all same). The precise modifier
93works with event types 0x76 (cpu-cycles, CPU clocks not halted) and 0xC1
94(micro-ops retired). Both events map to IBS execution sampling (IBS op)
95with the IBS Op Counter Control bit (IbsOpCntCtl) set respectively (see the
96Core Complex (CCX) -> Processor x86 Core -> Instruction Based Sampling (IBS)
97section of the [AMD Processor Programming Reference (PPR)] relevant to the
98family, model and stepping of the processor being used).
99
100Manual Volume 2: System Programming, 13.3 Instruction-Based
101Sampling). Examples to use IBS:
102
103 perf record -a -e cpu-cycles:p ... # use ibs op counting cycles
104 perf record -a -e r076:p ... # same as -e cpu-cycles:p
105 perf record -a -e r0C1:p ... # use ibs op counting micro-ops
106
107RAW HARDWARE EVENT DESCRIPTOR
108-----------------------------
109Even when an event is not available in a symbolic form within perf right now,
110it can be encoded in a per processor specific way.
111
112For instance on x86 CPUs, N is a hexadecimal value that represents the raw register encoding with the
113layout of IA32_PERFEVTSELx MSRs (see [Intel® 64 and IA-32 Architectures Software Developer's Manual Volume 3B: System Programming Guide] Figure 30-1 Layout
114of IA32_PERFEVTSELx MSRs) or AMD's PERF_CTL MSRs (see the
115Core Complex (CCX) -> Processor x86 Core -> MSR Registers section of the
116[AMD Processor Programming Reference (PPR)] relevant to the family, model
117and stepping of the processor being used).
118
119Note: Only the following bit fields can be set in x86 counter
120registers: event, umask, edge, inv, cmask. Esp. guest/host only and
121OS/user mode flags must be setup using <<EVENT_MODIFIERS, EVENT
122MODIFIERS>>.
123
124Example:
125
126If the Intel docs for a QM720 Core i7 describe an event as:
127
128 Event Umask Event Mask
129 Num. Value Mnemonic Description Comment
130
131 A8H 01H LSD.UOPS Counts the number of micro-ops Use cmask=1 and
132 delivered by loop stream detector invert to count
133 cycles
134
135raw encoding of 0x1A8 can be used:
136
137 perf stat -e r1a8 -a sleep 1
138 perf record -e r1a8 ...
139
140It's also possible to use pmu syntax:
141
142 perf record -e r1a8 -a sleep 1
143 perf record -e cpu/r1a8/ ...
144 perf record -e cpu/r0x1a8/ ...
145
146Some processors, like those from AMD, support event codes and unit masks
147larger than a byte. In such cases, the bits corresponding to the event
148configuration parameters can be seen with:
149
150 cat /sys/bus/event_source/devices/<pmu>/format/<config>
151
152Example:
153
154If the AMD docs for an EPYC 7713 processor describe an event as:
155
156 Event Umask Event Mask
157 Num. Value Mnemonic Description
158
159 28FH 03H op_cache_hit_miss.op_cache_hit Counts Op Cache micro-tag
160 hit events.
161
162raw encoding of 0x0328F cannot be used since the upper nibble of the
163EventSelect bits have to be specified via bits 32-35 as can be seen with:
164
165 cat /sys/bus/event_source/devices/cpu/format/event
166
167raw encoding of 0x20000038F should be used instead:
168
169 perf stat -e r20000038f -a sleep 1
170 perf record -e r20000038f ...
171
172It's also possible to use pmu syntax:
173
174 perf record -e r20000038f -a sleep 1
175 perf record -e cpu/r20000038f/ ...
176 perf record -e cpu/r0x20000038f/ ...
177
178You should refer to the processor specific documentation for getting these
179details. Some of them are referenced in the SEE ALSO section below.
180
181ARBITRARY PMUS
182--------------
183
184perf also supports an extended syntax for specifying raw parameters
185to PMUs. Using this typically requires looking up the specific event
186in the CPU vendor specific documentation.
187
188The available PMUs and their raw parameters can be listed with
189
190 ls /sys/devices/*/format
191
192For example the raw event "LSD.UOPS" core pmu event above could
193be specified as
194
195 perf stat -e cpu/event=0xa8,umask=0x1,name=LSD.UOPS_CYCLES,cmask=0x1/ ...
196
197 or using extended name syntax
198
199 perf stat -e cpu/event=0xa8,umask=0x1,cmask=0x1,name=\'LSD.UOPS_CYCLES:cmask=0x1\'/ ...
200
201PER SOCKET PMUS
202---------------
203
204Some PMUs are not associated with a core, but with a whole CPU socket.
205Events on these PMUs generally cannot be sampled, but only counted globally
206with perf stat -a. They can be bound to one logical CPU, but will measure
207all the CPUs in the same socket.
208
209This example measures memory bandwidth every second
210on the first memory controller on socket 0 of a Intel Xeon system
211
212 perf stat -C 0 -a uncore_imc_0/cas_count_read/,uncore_imc_0/cas_count_write/ -I 1000 ...
213
214Each memory controller has its own PMU. Measuring the complete system
215bandwidth would require specifying all imc PMUs (see perf list output),
216and adding the values together. To simplify creation of multiple events,
217prefix and glob matching is supported in the PMU name, and the prefix
218'uncore_' is also ignored when performing the match. So the command above
219can be expanded to all memory controllers by using the syntaxes:
220
221 perf stat -C 0 -a imc/cas_count_read/,imc/cas_count_write/ -I 1000 ...
222 perf stat -C 0 -a *imc*/cas_count_read/,*imc*/cas_count_write/ -I 1000 ...
223
224This example measures the combined core power every second
225
226 perf stat -I 1000 -e power/energy-cores/ -a
227
228ACCESS RESTRICTIONS
229-------------------
230
231For non root users generally only context switched PMU events are available.
232This is normally only the events in the cpu PMU, the predefined events
233like cycles and instructions and some software events.
234
235Other PMUs and global measurements are normally root only.
236Some event qualifiers, such as "any", are also root only.
237
238This can be overridden by setting the kernel.perf_event_paranoid
239sysctl to -1, which allows non root to use these events.
240
241For accessing trace point events perf needs to have read access to
242/sys/kernel/tracing, even when perf_event_paranoid is in a relaxed
243setting.
244
245TRACING
246-------
247
248Some PMUs control advanced hardware tracing capabilities, such as Intel PT,
249that allows low overhead execution tracing. These are described in a separate
250intel-pt.txt document.
251
252PARAMETERIZED EVENTS
253--------------------
254
255Some pmu events listed by 'perf-list' will be displayed with '?' in them. For
256example:
257
258 hv_gpci/dtbp_ptitc,phys_processor_idx=?/
259
260This means that when provided as an event, a value for '?' must
261also be supplied. For example:
262
263 perf stat -C 0 -e 'hv_gpci/dtbp_ptitc,phys_processor_idx=0x2/' ...
264
265EVENT QUALIFIERS:
266
267It is also possible to add extra qualifiers to an event:
268
269percore:
270
271Sums up the event counts for all hardware threads in a core, e.g.:
272
273
274 perf stat -e cpu/event=0,umask=0x3,percore=1/
275
276
277EVENT GROUPS
278------------
279
280Perf supports time based multiplexing of events, when the number of events
281active exceeds the number of hardware performance counters. Multiplexing
282can cause measurement errors when the workload changes its execution
283profile.
284
285When metrics are computed using formulas from event counts, it is useful to
286ensure some events are always measured together as a group to minimize multiplexing
287errors. Event groups can be specified using { }.
288
289 perf stat -e '{instructions,cycles}' ...
290
291The number of available performance counters depend on the CPU. A group
292cannot contain more events than available counters.
293For example Intel Core CPUs typically have four generic performance counters
294for the core, plus three fixed counters for instructions, cycles and
295ref-cycles. Some special events have restrictions on which counter they
296can schedule, and may not support multiple instances in a single group.
297When too many events are specified in the group some of them will not
298be measured.
299
300Globally pinned events can limit the number of counters available for
301other groups. On x86 systems, the NMI watchdog pins a counter by default.
302The nmi watchdog can be disabled as root with
303
304 echo 0 > /proc/sys/kernel/nmi_watchdog
305
306Events from multiple different PMUs cannot be mixed in a group, with
307some exceptions for software events.
308
309LEADER SAMPLING
310---------------
311
312perf also supports group leader sampling using the :S specifier.
313
314 perf record -e '{cycles,instructions}:S' ...
315 perf report --group
316
317Normally all events in an event group sample, but with :S only
318the first event (the leader) samples, and it only reads the values of the
319other events in the group.
320
321However, in the case AUX area events (e.g. Intel PT or CoreSight), the AUX
322area event must be the leader, so then the second event samples, not the first.
323
324OPTIONS
325-------
326
327Without options all known events will be listed.
328
329To limit the list use:
330
331. 'hw' or 'hardware' to list hardware events such as cache-misses, etc.
332
333. 'sw' or 'software' to list software events such as context switches, etc.
334
335. 'cache' or 'hwcache' to list hardware cache events such as L1-dcache-loads, etc.
336
337. 'tracepoint' to list all tracepoint events, alternatively use
338 'subsys_glob:event_glob' to filter by tracepoint subsystems such as sched,
339 block, etc.
340
341. 'pmu' to print the kernel supplied PMU events.
342
343. 'sdt' to list all Statically Defined Tracepoint events.
344
345. 'metric' to list metrics
346
347. 'metricgroup' to list metricgroups with metrics.
348
349. If none of the above is matched, it will apply the supplied glob to all
350 events, printing the ones that match.
351
352. As a last resort, it will do a substring search in all event names.
353
354One or more types can be used at the same time, listing the events for the
355types specified.
356
357Support raw format:
358
359. '--raw-dump', shows the raw-dump of all the events.
360. '--raw-dump [hw|sw|cache|tracepoint|pmu|event_glob]', shows the raw-dump of
361 a certain kind of events.
362
363SEE ALSO
364--------
365linkperf:perf-stat[1], linkperf:perf-top[1],
366linkperf:perf-record[1],
367http://www.intel.com/sdm/[Intel® 64 and IA-32 Architectures Software Developer's Manual Volume 3B: System Programming Guide],
368https://bugzilla.kernel.org/show_bug.cgi?id=206537[AMD Processor Programming Reference (PPR)]