6 perf-list - List all symbolic event types
11 'perf list' [--no-desc] [--long-desc]
12 [hw|sw|cache|tracepoint|pmu|sdt|metric|metricgroup|event_glob]
16 This command displays the symbolic event types which can be selected in the
17 various perf commands with the -e option.
23 Print extra event descriptions. (default)
26 Don't print descriptions.
30 Print longer event descriptions.
33 Enable debugging output.
36 Print how named events are resolved internally into perf events, and also
37 any extra expressions computed by perf stat.
40 Print deprecated events. By default the deprecated events are hidden.
43 Print PMU events and metrics limited to the specific PMU name.
44 (e.g. --unit cpu, --unit msr, --unit cpu_core, --unit cpu_atom)
48 Output in JSON format.
52 Output file name. By default output is written to stdout.
58 Events can optionally have a modifier by appending a colon and one or
59 more modifiers. Modifiers allow the user to restrict the events to be
60 counted. The following modifiers exist:
62 u - user-space counting
64 h - hypervisor counting
66 G - guest counting (in KVM guests)
67 H - host counting (not in KVM guests)
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
75 The 'p' modifier can be used for specifying how precise the instruction
76 address should be. The 'p' modifier can be specified multiple times:
78 0 - SAMPLE_IP can have arbitrary skid
79 1 - SAMPLE_IP must have constant skid
80 2 - SAMPLE_IP requested to have 0 skid
81 3 - SAMPLE_IP must have 0 skid, or uses randomization to avoid
82 sample shadowing effects.
84 For Intel systems precise event sampling is implemented with PEBS
85 which supports up to precise-level 2, and precise level 3 for
88 On AMD systems it is implemented using IBS OP (up to precise-level 2).
89 Unlike Intel PEBS which provides levels of precision, AMD core pmu is
90 inherently non-precise and IBS is inherently precise. (i.e. ibs_op//,
91 ibs_op//p, ibs_op//pp and ibs_op//ppp are all same). The precise modifier
92 works with event types 0x76 (cpu-cycles, CPU clocks not halted) and 0xC1
93 (micro-ops retired). Both events map to IBS execution sampling (IBS op)
94 with the IBS Op Counter Control bit (IbsOpCntCtl) set respectively (see the
95 Core Complex (CCX) -> Processor x86 Core -> Instruction Based Sampling (IBS)
96 section of the [AMD Processor Programming Reference (PPR)] relevant to the
97 family, model and stepping of the processor being used).
99 Manual Volume 2: System Programming, 13.3 Instruction-Based
100 Sampling). Examples to use IBS:
102 perf record -a -e cpu-cycles:p ... # use ibs op counting cycles
103 perf record -a -e r076:p ... # same as -e cpu-cycles:p
104 perf record -a -e r0C1:p ... # use ibs op counting micro-ops
106 RAW HARDWARE EVENT DESCRIPTOR
107 -----------------------------
108 Even when an event is not available in a symbolic form within perf right now,
109 it can be encoded in a per processor specific way.
111 For instance on x86 CPUs, N is a hexadecimal value that represents the raw register encoding with the
112 layout of IA32_PERFEVTSELx MSRs (see [IntelĀ® 64 and IA-32 Architectures Software Developer's Manual Volume 3B: System Programming Guide] Figure 30-1 Layout
113 of IA32_PERFEVTSELx MSRs) or AMD's PERF_CTL MSRs (see the
114 Core Complex (CCX) -> Processor x86 Core -> MSR Registers section of the
115 [AMD Processor Programming Reference (PPR)] relevant to the family, model
116 and stepping of the processor being used).
118 Note: Only the following bit fields can be set in x86 counter
119 registers: event, umask, edge, inv, cmask. Esp. guest/host only and
120 OS/user mode flags must be setup using <<EVENT_MODIFIERS, EVENT
125 If the Intel docs for a QM720 Core i7 describe an event as:
127 Event Umask Event Mask
128 Num. Value Mnemonic Description Comment
130 A8H 01H LSD.UOPS Counts the number of micro-ops Use cmask=1 and
131 delivered by loop stream detector invert to count
134 raw encoding of 0x1A8 can be used:
136 perf stat -e r1a8 -a sleep 1
137 perf record -e r1a8 ...
139 It's also possible to use pmu syntax:
141 perf record -e r1a8 -a sleep 1
142 perf record -e cpu/r1a8/ ...
143 perf record -e cpu/r0x1a8/ ...
145 Some processors, like those from AMD, support event codes and unit masks
146 larger than a byte. In such cases, the bits corresponding to the event
147 configuration parameters can be seen with:
149 cat /sys/bus/event_source/devices/<pmu>/format/<config>
153 If the AMD docs for an EPYC 7713 processor describe an event as:
155 Event Umask Event Mask
156 Num. Value Mnemonic Description
158 28FH 03H op_cache_hit_miss.op_cache_hit Counts Op Cache micro-tag
161 raw encoding of 0x0328F cannot be used since the upper nibble of the
162 EventSelect bits have to be specified via bits 32-35 as can be seen with:
164 cat /sys/bus/event_source/devices/cpu/format/event
166 raw encoding of 0x20000038F should be used instead:
168 perf stat -e r20000038f -a sleep 1
169 perf record -e r20000038f ...
171 It's also possible to use pmu syntax:
173 perf record -e r20000038f -a sleep 1
174 perf record -e cpu/r20000038f/ ...
175 perf record -e cpu/r0x20000038f/ ...
177 You should refer to the processor specific documentation for getting these
178 details. Some of them are referenced in the SEE ALSO section below.
183 perf also supports an extended syntax for specifying raw parameters
184 to PMUs. Using this typically requires looking up the specific event
185 in the CPU vendor specific documentation.
187 The available PMUs and their raw parameters can be listed with
189 ls /sys/devices/*/format
191 For example the raw event "LSD.UOPS" core pmu event above could
194 perf stat -e cpu/event=0xa8,umask=0x1,name=LSD.UOPS_CYCLES,cmask=0x1/ ...
196 or using extended name syntax
198 perf stat -e cpu/event=0xa8,umask=0x1,cmask=0x1,name=\'LSD.UOPS_CYCLES:cmask=0x1\'/ ...
203 Some PMUs are not associated with a core, but with a whole CPU socket.
204 Events on these PMUs generally cannot be sampled, but only counted globally
205 with perf stat -a. They can be bound to one logical CPU, but will measure
206 all the CPUs in the same socket.
208 This example measures memory bandwidth every second
209 on the first memory controller on socket 0 of a Intel Xeon system
211 perf stat -C 0 -a uncore_imc_0/cas_count_read/,uncore_imc_0/cas_count_write/ -I 1000 ...
213 Each memory controller has its own PMU. Measuring the complete system
214 bandwidth would require specifying all imc PMUs (see perf list output),
215 and adding the values together. To simplify creation of multiple events,
216 prefix and glob matching is supported in the PMU name, and the prefix
217 'uncore_' is also ignored when performing the match. So the command above
218 can be expanded to all memory controllers by using the syntaxes:
220 perf stat -C 0 -a imc/cas_count_read/,imc/cas_count_write/ -I 1000 ...
221 perf stat -C 0 -a *imc*/cas_count_read/,*imc*/cas_count_write/ -I 1000 ...
223 This example measures the combined core power every second
225 perf stat -I 1000 -e power/energy-cores/ -a
230 For non root users generally only context switched PMU events are available.
231 This is normally only the events in the cpu PMU, the predefined events
232 like cycles and instructions and some software events.
234 Other PMUs and global measurements are normally root only.
235 Some event qualifiers, such as "any", are also root only.
237 This can be overridden by setting the kernel.perf_event_paranoid
238 sysctl to -1, which allows non root to use these events.
240 For accessing trace point events perf needs to have read access to
241 /sys/kernel/tracing, even when perf_event_paranoid is in a relaxed
247 Some PMUs control advanced hardware tracing capabilities, such as Intel PT,
248 that allows low overhead execution tracing. These are described in a separate
249 intel-pt.txt document.
254 Some pmu events listed by 'perf-list' will be displayed with '?' in them. For
257 hv_gpci/dtbp_ptitc,phys_processor_idx=?/
259 This means that when provided as an event, a value for '?' must
260 also be supplied. For example:
262 perf stat -C 0 -e 'hv_gpci/dtbp_ptitc,phys_processor_idx=0x2/' ...
266 It is also possible to add extra qualifiers to an event:
270 Sums up the event counts for all hardware threads in a core, e.g.:
273 perf stat -e cpu/event=0,umask=0x3,percore=1/
279 Perf supports time based multiplexing of events, when the number of events
280 active exceeds the number of hardware performance counters. Multiplexing
281 can cause measurement errors when the workload changes its execution
284 When metrics are computed using formulas from event counts, it is useful to
285 ensure some events are always measured together as a group to minimize multiplexing
286 errors. Event groups can be specified using { }.
288 perf stat -e '{instructions,cycles}' ...
290 The number of available performance counters depend on the CPU. A group
291 cannot contain more events than available counters.
292 For example Intel Core CPUs typically have four generic performance counters
293 for the core, plus three fixed counters for instructions, cycles and
294 ref-cycles. Some special events have restrictions on which counter they
295 can schedule, and may not support multiple instances in a single group.
296 When too many events are specified in the group some of them will not
299 Globally pinned events can limit the number of counters available for
300 other groups. On x86 systems, the NMI watchdog pins a counter by default.
301 The nmi watchdog can be disabled as root with
303 echo 0 > /proc/sys/kernel/nmi_watchdog
305 Events from multiple different PMUs cannot be mixed in a group, with
306 some exceptions for software events.
311 perf also supports group leader sampling using the :S specifier.
313 perf record -e '{cycles,instructions}:S' ...
316 Normally all events in an event group sample, but with :S only
317 the first event (the leader) samples, and it only reads the values of the
318 other events in the group.
320 However, in the case AUX area events (e.g. Intel PT or CoreSight), the AUX
321 area event must be the leader, so then the second event samples, not the first.
326 Without options all known events will be listed.
328 To limit the list use:
330 . 'hw' or 'hardware' to list hardware events such as cache-misses, etc.
332 . 'sw' or 'software' to list software events such as context switches, etc.
334 . 'cache' or 'hwcache' to list hardware cache events such as L1-dcache-loads, etc.
336 . 'tracepoint' to list all tracepoint events, alternatively use
337 'subsys_glob:event_glob' to filter by tracepoint subsystems such as sched,
340 . 'pmu' to print the kernel supplied PMU events.
342 . 'sdt' to list all Statically Defined Tracepoint events.
344 . 'metric' to list metrics
346 . 'metricgroup' to list metricgroups with metrics.
348 . If none of the above is matched, it will apply the supplied glob to all
349 events, printing the ones that match.
351 . As a last resort, it will do a substring search in all event names.
353 One or more types can be used at the same time, listing the events for the
358 . '--raw-dump', shows the raw-dump of all the events.
359 . '--raw-dump [hw|sw|cache|tracepoint|pmu|event_glob]', shows the raw-dump of
360 a certain kind of events.
364 linkperf:perf-stat[1], linkperf:perf-top[1],
365 linkperf:perf-record[1],
366 http://www.intel.com/sdm/[IntelĀ® 64 and IA-32 Architectures Software Developer's Manual Volume 3B: System Programming Guide],
367 https://bugzilla.kernel.org/show_bug.cgi?id=206537[AMD Processor Programming Reference (PPR)]