6 perf-list - List all symbolic event types
11 'perf list' [--no-desc] [--long-desc] [hw|sw|cache|tracepoint|pmu|event_glob]
15 This command displays the symbolic event types which can be selected in the
16 various perf commands with the -e option.
21 Don't print descriptions.
25 Print longer event descriptions.
32 Events can optionally have a modifier by appending a colon and one or
33 more modifiers. Modifiers allow the user to restrict the events to be
34 counted. The following modifiers exist:
36 u - user-space counting
38 h - hypervisor counting
40 G - guest counting (in KVM guests)
41 H - host counting (not in KVM guests)
43 P - use maximum detected precise level
44 S - read sample value (PERF_SAMPLE_READ)
45 D - pin the event to the PMU
47 The 'p' modifier can be used for specifying how precise the instruction
48 address should be. The 'p' modifier can be specified multiple times:
50 0 - SAMPLE_IP can have arbitrary skid
51 1 - SAMPLE_IP must have constant skid
52 2 - SAMPLE_IP requested to have 0 skid
53 3 - SAMPLE_IP must have 0 skid, or uses randomization to avoid
54 sample shadowing effects.
56 For Intel systems precise event sampling is implemented with PEBS
57 which supports up to precise-level 2, and precise level 3 for
60 On AMD systems it is implemented using IBS (up to precise-level 2).
61 The precise modifier works with event types 0x76 (cpu-cycles, CPU
62 clocks not halted) and 0xC1 (micro-ops retired). Both events map to
63 IBS execution sampling (IBS op) with the IBS Op Counter Control bit
64 (IbsOpCntCtl) set respectively (see AMD64 Architecture Programmer’s
65 Manual Volume 2: System Programming, 13.3 Instruction-Based
66 Sampling). Examples to use IBS:
68 perf record -a -e cpu-cycles:p ... # use ibs op counting cycles
69 perf record -a -e r076:p ... # same as -e cpu-cycles:p
70 perf record -a -e r0C1:p ... # use ibs op counting micro-ops
72 RAW HARDWARE EVENT DESCRIPTOR
73 -----------------------------
74 Even when an event is not available in a symbolic form within perf right now,
75 it can be encoded in a per processor specific way.
77 For instance For x86 CPUs NNN represents the raw register encoding with the
78 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
79 of IA32_PERFEVTSELx MSRs) or AMD's PerfEvtSeln (see [AMD64 Architecture Programmer’s Manual Volume 2: System Programming], Page 344,
80 Figure 13-7 Performance Event-Select Register (PerfEvtSeln)).
82 Note: Only the following bit fields can be set in x86 counter
83 registers: event, umask, edge, inv, cmask. Esp. guest/host only and
84 OS/user mode flags must be setup using <<EVENT_MODIFIERS, EVENT
89 If the Intel docs for a QM720 Core i7 describe an event as:
91 Event Umask Event Mask
92 Num. Value Mnemonic Description Comment
94 A8H 01H LSD.UOPS Counts the number of micro-ops Use cmask=1 and
95 delivered by loop stream detector invert to count
98 raw encoding of 0x1A8 can be used:
100 perf stat -e r1a8 -a sleep 1
101 perf record -e r1a8 ...
103 You should refer to the processor specific documentation for getting these
104 details. Some of them are referenced in the SEE ALSO section below.
109 perf also supports an extended syntax for specifying raw parameters
110 to PMUs. Using this typically requires looking up the specific event
111 in the CPU vendor specific documentation.
113 The available PMUs and their raw parameters can be listed with
115 ls /sys/devices/*/format
117 For example the raw event "LSD.UOPS" core pmu event above could
120 perf stat -e cpu/event=0xa8,umask=0x1,name=LSD.UOPS_CYCLES,cmask=1/ ...
125 Some PMUs are not associated with a core, but with a whole CPU socket.
126 Events on these PMUs generally cannot be sampled, but only counted globally
127 with perf stat -a. They can be bound to one logical CPU, but will measure
128 all the CPUs in the same socket.
130 This example measures memory bandwidth every second
131 on the first memory controller on socket 0 of a Intel Xeon system
133 perf stat -C 0 -a uncore_imc_0/cas_count_read/,uncore_imc_0/cas_count_write/ -I 1000 ...
135 Each memory controller has its own PMU. Measuring the complete system
136 bandwidth would require specifying all imc PMUs (see perf list output),
137 and adding the values together.
139 This example measures the combined core power every second
141 perf stat -I 1000 -e power/energy-cores/ -a
146 For non root users generally only context switched PMU events are available.
147 This is normally only the events in the cpu PMU, the predefined events
148 like cycles and instructions and some software events.
150 Other PMUs and global measurements are normally root only.
151 Some event qualifiers, such as "any", are also root only.
153 This can be overriden by setting the kernel.perf_event_paranoid
154 sysctl to -1, which allows non root to use these events.
156 For accessing trace point events perf needs to have read access to
157 /sys/kernel/debug/tracing, even when perf_event_paranoid is in a relaxed
163 Some PMUs control advanced hardware tracing capabilities, such as Intel PT,
164 that allows low overhead execution tracing. These are described in a separate
165 intel-pt.txt document.
170 Some pmu events listed by 'perf-list' will be displayed with '?' in them. For
173 hv_gpci/dtbp_ptitc,phys_processor_idx=?/
175 This means that when provided as an event, a value for '?' must
176 also be supplied. For example:
178 perf stat -C 0 -e 'hv_gpci/dtbp_ptitc,phys_processor_idx=0x2/' ...
183 Perf supports time based multiplexing of events, when the number of events
184 active exceeds the number of hardware performance counters. Multiplexing
185 can cause measurement errors when the workload changes its execution
188 When metrics are computed using formulas from event counts, it is useful to
189 ensure some events are always measured together as a group to minimize multiplexing
190 errors. Event groups can be specified using { }.
192 perf stat -e '{instructions,cycles}' ...
194 The number of available performance counters depend on the CPU. A group
195 cannot contain more events than available counters.
196 For example Intel Core CPUs typically have four generic performance counters
197 for the core, plus three fixed counters for instructions, cycles and
198 ref-cycles. Some special events have restrictions on which counter they
199 can schedule, and may not support multiple instances in a single group.
200 When too many events are specified in the group none of them will not
203 Globally pinned events can limit the number of counters available for
204 other groups. On x86 systems, the NMI watchdog pins a counter by default.
205 The nmi watchdog can be disabled as root with
207 echo 0 > /proc/sys/kernel/nmi_watchdog
209 Events from multiple different PMUs cannot be mixed in a group, with
210 some exceptions for software events.
215 perf also supports group leader sampling using the :S specifier.
217 perf record -e '{cycles,instructions}:S' ...
220 Normally all events in a event group sample, but with :S only
221 the first event (the leader) samples, and it only reads the values of the
222 other events in the group.
227 Without options all known events will be listed.
229 To limit the list use:
231 . 'hw' or 'hardware' to list hardware events such as cache-misses, etc.
233 . 'sw' or 'software' to list software events such as context switches, etc.
235 . 'cache' or 'hwcache' to list hardware cache events such as L1-dcache-loads, etc.
237 . 'tracepoint' to list all tracepoint events, alternatively use
238 'subsys_glob:event_glob' to filter by tracepoint subsystems such as sched,
241 . 'pmu' to print the kernel supplied PMU events.
243 . If none of the above is matched, it will apply the supplied glob to all
244 events, printing the ones that match.
246 . As a last resort, it will do a substring search in all event names.
248 One or more types can be used at the same time, listing the events for the
253 . '--raw-dump', shows the raw-dump of all the events.
254 . '--raw-dump [hw|sw|cache|tracepoint|pmu|event_glob]', shows the raw-dump of
255 a certain kind of events.
259 linkperf:perf-stat[1], linkperf:perf-top[1],
260 linkperf:perf-record[1],
261 http://www.intel.com/sdm/[Intel® 64 and IA-32 Architectures Software Developer's Manual Volume 3B: System Programming Guide],
262 http://support.amd.com/us/Processor_TechDocs/24593_APM_v2.pdf[AMD64 Architecture Programmer’s Manual Volume 2: System Programming]