perf-list(1)

1PERF-LIST(1)                      perf Manual                     PERF-LIST(1)
2
3
4

NAME

6       perf-list - List all symbolic event types
7

SYNOPSIS

9       perf list [--no-desc] [--long-desc]
10                   [hw|sw|cache|tracepoint|pmu|sdt|metric|metricgroup|event_glob]
11

DESCRIPTION

13       This command displays the symbolic event types which can be selected in
14       the various perf commands with the -e option.
15

OPTIONS

17       -d, --desc
18           Print extra event descriptions. (default)
19
20       --no-desc
21           Don’t print descriptions.
22
23       -v, --long-desc
24           Print longer event descriptions.
25
26       --debug
27           Enable debugging output.
28
29       --details
30           Print how named events are resolved internally into perf events,
31           and also any extra expressions computed by perf stat.
32
33       --deprecated
34           Print deprecated events. By default the deprecated events are
35           hidden.
36

EVENT MODIFIERS

38       Events can optionally have a modifier by appending a colon and one or
39       more modifiers. Modifiers allow the user to restrict the events to be
40       counted. The following modifiers exist:
41
42           u - user-space counting
43           k - kernel counting
44           h - hypervisor counting
45           I - non idle counting
46           G - guest counting (in KVM guests)
47           H - host counting (not in KVM guests)
48           p - precise level
49           P - use maximum detected precise level
50           S - read sample value (PERF_SAMPLE_READ)
51           D - pin the event to the PMU
52           W - group is weak and will fallback to non-group if not schedulable,
53
54       The p modifier can be used for specifying how precise the instruction
55       address should be. The p modifier can be specified multiple times:
56
57           0 - SAMPLE_IP can have arbitrary skid
58           1 - SAMPLE_IP must have constant skid
59           2 - SAMPLE_IP requested to have 0 skid
60           3 - SAMPLE_IP must have 0 skid, or uses randomization to avoid
61               sample shadowing effects.
62
63       For Intel systems precise event sampling is implemented with PEBS which
64       supports up to precise-level 2, and precise level 3 for some special
65       cases
66
67       On AMD systems it is implemented using IBS (up to precise-level 2). The
68       precise modifier works with event types 0x76 (cpu-cycles, CPU clocks
69       not halted) and 0xC1 (micro-ops retired). Both events map to IBS
70       execution sampling (IBS op) with the IBS Op Counter Control bit
71       (IbsOpCntCtl) set respectively (see AMD64 Architecture Programmer’s
72       Manual Volume 2: System Programming, 13.3 Instruction-Based Sampling).
73       Examples to use IBS:
74
75           perf record -a -e cpu-cycles:p ...    # use ibs op counting cycles
76           perf record -a -e r076:p ...          # same as -e cpu-cycles:p
77           perf record -a -e r0C1:p ...          # use ibs op counting micro-ops
78

RAW HARDWARE EVENT DESCRIPTOR

80       Even when an event is not available in a symbolic form within perf
81       right now, it can be encoded in a per processor specific way.
82
83       For instance For x86 CPUs NNN represents the raw register encoding with
84       the layout of IA32_PERFEVTSELx MSRs (see [Intel® 64 and IA-32
85       Architectures Software Developer’s Manual Volume 3B: System Programming
86       Guide] Figure 30-1 Layout of IA32_PERFEVTSELx MSRs) or AMD’s
87       PerfEvtSeln (see [AMD64 Architecture Programmer’s Manual Volume 2:
88       System Programming], Page 344, Figure 13-7 Performance Event-Select
89       Register (PerfEvtSeln)).
90
91       Note: Only the following bit fields can be set in x86 counter
92       registers: event, umask, edge, inv, cmask. Esp. guest/host only and
93       OS/user mode flags must be setup using EVENT MODIFIERS.
94
95       Example:
96
97       If the Intel docs for a QM720 Core i7 describe an event as:
98
99           Event  Umask  Event Mask
100           Num.   Value  Mnemonic    Description                        Comment
101
102           A8H      01H  LSD.UOPS    Counts the number of micro-ops     Use cmask=1 and
103                                     delivered by loop stream detector  invert to count
104                                                                        cycles
105
106       raw encoding of 0x1A8 can be used:
107
108           perf stat -e r1a8 -a sleep 1
109           perf record -e r1a8 ...
110
111       You should refer to the processor specific documentation for getting
112       these details. Some of them are referenced in the SEE ALSO section
113       below.
114

ARBITRARY PMUS

116       perf also supports an extended syntax for specifying raw parameters to
117       PMUs. Using this typically requires looking up the specific event in
118       the CPU vendor specific documentation.
119
120       The available PMUs and their raw parameters can be listed with
121
122           ls /sys/devices/*/format
123
124       For example the raw event "LSD.UOPS" core pmu event above could be
125       specified as
126
127           perf stat -e cpu/event=0xa8,umask=0x1,name=LSD.UOPS_CYCLES,cmask=0x1/ ...
128
129           or using extended name syntax
130
131           perf stat -e cpu/event=0xa8,umask=0x1,cmask=0x1,name=\'LSD.UOPS_CYCLES:cmask=0x1\'/ ...
132

PER SOCKET PMUS

134       Some PMUs are not associated with a core, but with a whole CPU socket.
135       Events on these PMUs generally cannot be sampled, but only counted
136       globally with perf stat -a. They can be bound to one logical CPU, but
137       will measure all the CPUs in the same socket.
138
139       This example measures memory bandwidth every second on the first memory
140       controller on socket 0 of a Intel Xeon system
141
142           perf stat -C 0 -a uncore_imc_0/cas_count_read/,uncore_imc_0/cas_count_write/ -I 1000 ...
143
144       Each memory controller has its own PMU. Measuring the complete system
145       bandwidth would require specifying all imc PMUs (see perf list output),
146       and adding the values together. To simplify creation of multiple
147       events, prefix and glob matching is supported in the PMU name, and the
148       prefix uncore_ is also ignored when performing the match. So the
149       command above can be expanded to all memory controllers by using the
150       syntaxes:
151
152           perf stat -C 0 -a imc/cas_count_read/,imc/cas_count_write/ -I 1000 ...
153           perf stat -C 0 -a *imc*/cas_count_read/,*imc*/cas_count_write/ -I 1000 ...
154
155       This example measures the combined core power every second
156
157           perf stat -I 1000 -e power/energy-cores/  -a
158

ACCESS RESTRICTIONS

160       For non root users generally only context switched PMU events are
161       available. This is normally only the events in the cpu PMU, the
162       predefined events like cycles and instructions and some software
163       events.
164
165       Other PMUs and global measurements are normally root only. Some event
166       qualifiers, such as "any", are also root only.
167
168       This can be overridden by setting the kernel.perf_event_paranoid sysctl
169       to -1, which allows non root to use these events.
170
171       For accessing trace point events perf needs to have read access to
172       /sys/kernel/debug/tracing, even when perf_event_paranoid is in a
173       relaxed setting.
174

TRACING

176       Some PMUs control advanced hardware tracing capabilities, such as Intel
177       PT, that allows low overhead execution tracing. These are described in
178       a separate intel-pt.txt document.
179

PARAMETERIZED EVENTS

181       Some pmu events listed by perf-list will be displayed with ? in them.
182       For example:
183
184           hv_gpci/dtbp_ptitc,phys_processor_idx=?/
185
186       This means that when provided as an event, a value for ? must also be
187       supplied. For example:
188
189           perf stat -C 0 -e 'hv_gpci/dtbp_ptitc,phys_processor_idx=0x2/' ...
190
191       EVENT QUALIFIERS:
192
193       It is also possible to add extra qualifiers to an event:
194
195       percore:
196
197       Sums up the event counts for all hardware threads in a core, e.g.:
198
199           perf stat -e cpu/event=0,umask=0x3,percore=1/
200

EVENT GROUPS

202       Perf supports time based multiplexing of events, when the number of
203       events active exceeds the number of hardware performance counters.
204       Multiplexing can cause measurement errors when the workload changes its
205       execution profile.
206
207       When metrics are computed using formulas from event counts, it is
208       useful to ensure some events are always measured together as a group to
209       minimize multiplexing errors. Event groups can be specified using { }.
210
211           perf stat -e '{instructions,cycles}' ...
212
213       The number of available performance counters depend on the CPU. A group
214       cannot contain more events than available counters. For example Intel
215       Core CPUs typically have four generic performance counters for the
216       core, plus three fixed counters for instructions, cycles and
217       ref-cycles. Some special events have restrictions on which counter they
218       can schedule, and may not support multiple instances in a single group.
219       When too many events are specified in the group some of them will not
220       be measured.
221
222       Globally pinned events can limit the number of counters available for
223       other groups. On x86 systems, the NMI watchdog pins a counter by
224       default. The nmi watchdog can be disabled as root with
225
226           echo 0 > /proc/sys/kernel/nmi_watchdog
227
228       Events from multiple different PMUs cannot be mixed in a group, with
229       some exceptions for software events.
230

LEADER SAMPLING

232       perf also supports group leader sampling using the :S specifier.
233
234           perf record -e '{cycles,instructions}:S' ...
235           perf report --group
236
237       Normally all events in an event group sample, but with :S only the
238       first event (the leader) samples, and it only reads the values of the
239       other events in the group.
240

OPTIONS

242       Without options all known events will be listed.
243
244       To limit the list use:
245
246        1. hw or hardware to list hardware events such as cache-misses, etc.
247
248        2. sw or software to list software events such as context switches,
249           etc.
250
251        3. cache or hwcache to list hardware cache events such as
252           L1-dcache-loads, etc.
253
254        4. tracepoint to list all tracepoint events, alternatively use
255           subsys_glob:event_glob to filter by tracepoint subsystems such as
256           sched, block, etc.
257
258        5. pmu to print the kernel supplied PMU events.
259
260        6. sdt to list all Statically Defined Tracepoint events.
261
262        7. metric to list metrics
263
264        8. metricgroup to list metricgroups with metrics.
265
266        9. If none of the above is matched, it will apply the supplied glob to
267           all events, printing the ones that match.
268
269       10. As a last resort, it will do a substring search in all event names.
270
271       One or more types can be used at the same time, listing the events for
272       the types specified.
273
274       Support raw format:
275
276        1. --raw-dump, shows the raw-dump of all the events.
277
278        2. --raw-dump [hw|sw|cache|tracepoint|pmu|event_glob], shows the
279           raw-dump of a certain kind of events.
280

NOTES

288        1. Intel® 64 and IA-32 Architectures Software Developer’s Manual
289           Volume 3B: System Programming Guide
290           http://www.intel.com/sdm/
291
292        2. AMD64 Architecture Programmer’s Manual Volume 2: System Programming
293           http://support.amd.com/us/Processor_TechDocs/24593_APM_v2.pdf
294
295
296
297perf                              04/23/2020                      PERF-LIST(1)