0001 perf-list(1)
0002 ============
0003
0004 NAME
0005 ----
0006 perf-list - List all symbolic event types
0007
0008 SYNOPSIS
0009 --------
0010 [verse]
0011 'perf list' [--no-desc] [--long-desc]
0012 [hw|sw|cache|tracepoint|pmu|sdt|metric|metricgroup|event_glob]
0013
0014 DESCRIPTION
0015 -----------
0016 This command displays the symbolic event types which can be selected in the
0017 various perf commands with the -e option.
0018
0019 OPTIONS
0020 -------
0021 -d::
0022 --desc::
0023 Print extra event descriptions. (default)
0024
0025 --no-desc::
0026 Don't print descriptions.
0027
0028 -v::
0029 --long-desc::
0030 Print longer event descriptions.
0031
0032 --debug::
0033 Enable debugging output.
0034
0035 --details::
0036 Print how named events are resolved internally into perf events, and also
0037 any extra expressions computed by perf stat.
0038
0039 --deprecated::
0040 Print deprecated events. By default the deprecated events are hidden.
0041
0042 --cputype::
0043 Print events applying cpu with this type for hybrid platform
0044 (e.g. --cputype core or --cputype atom)
0045
0046 [[EVENT_MODIFIERS]]
0047 EVENT MODIFIERS
0048 ---------------
0049
0050 Events can optionally have a modifier by appending a colon and one or
0051 more modifiers. Modifiers allow the user to restrict the events to be
0052 counted. The following modifiers exist:
0053
0054 u - user-space counting
0055 k - kernel counting
0056 h - hypervisor counting
0057 I - non idle counting
0058 G - guest counting (in KVM guests)
0059 H - host counting (not in KVM guests)
0060 p - precise level
0061 P - use maximum detected precise level
0062 S - read sample value (PERF_SAMPLE_READ)
0063 D - pin the event to the PMU
0064 W - group is weak and will fallback to non-group if not schedulable,
0065 e - group or event are exclusive and do not share the PMU
0066
0067 The 'p' modifier can be used for specifying how precise the instruction
0068 address should be. The 'p' modifier can be specified multiple times:
0069
0070 0 - SAMPLE_IP can have arbitrary skid
0071 1 - SAMPLE_IP must have constant skid
0072 2 - SAMPLE_IP requested to have 0 skid
0073 3 - SAMPLE_IP must have 0 skid, or uses randomization to avoid
0074 sample shadowing effects.
0075
0076 For Intel systems precise event sampling is implemented with PEBS
0077 which supports up to precise-level 2, and precise level 3 for
0078 some special cases
0079
0080 On AMD systems it is implemented using IBS (up to precise-level 2).
0081 The precise modifier works with event types 0x76 (cpu-cycles, CPU
0082 clocks not halted) and 0xC1 (micro-ops retired). Both events map to
0083 IBS execution sampling (IBS op) with the IBS Op Counter Control bit
0084 (IbsOpCntCtl) set respectively (see the
0085 Core Complex (CCX) -> Processor x86 Core -> Instruction Based Sampling (IBS)
0086 section of the [AMD Processor Programming Reference (PPR)] relevant to the
0087 family, model and stepping of the processor being used).
0088
0089 Manual Volume 2: System Programming, 13.3 Instruction-Based
0090 Sampling). Examples to use IBS:
0091
0092 perf record -a -e cpu-cycles:p ... # use ibs op counting cycles
0093 perf record -a -e r076:p ... # same as -e cpu-cycles:p
0094 perf record -a -e r0C1:p ... # use ibs op counting micro-ops
0095
0096 RAW HARDWARE EVENT DESCRIPTOR
0097 -----------------------------
0098 Even when an event is not available in a symbolic form within perf right now,
0099 it can be encoded in a per processor specific way.
0100
0101 For instance on x86 CPUs, N is a hexadecimal value that represents the raw register encoding with the
0102 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
0103 of IA32_PERFEVTSELx MSRs) or AMD's PERF_CTL MSRs (see the
0104 Core Complex (CCX) -> Processor x86 Core -> MSR Registers section of the
0105 [AMD Processor Programming Reference (PPR)] relevant to the family, model
0106 and stepping of the processor being used).
0107
0108 Note: Only the following bit fields can be set in x86 counter
0109 registers: event, umask, edge, inv, cmask. Esp. guest/host only and
0110 OS/user mode flags must be setup using <<EVENT_MODIFIERS, EVENT
0111 MODIFIERS>>.
0112
0113 Example:
0114
0115 If the Intel docs for a QM720 Core i7 describe an event as:
0116
0117 Event Umask Event Mask
0118 Num. Value Mnemonic Description Comment
0119
0120 A8H 01H LSD.UOPS Counts the number of micro-ops Use cmask=1 and
0121 delivered by loop stream detector invert to count
0122 cycles
0123
0124 raw encoding of 0x1A8 can be used:
0125
0126 perf stat -e r1a8 -a sleep 1
0127 perf record -e r1a8 ...
0128
0129 It's also possible to use pmu syntax:
0130
0131 perf record -e r1a8 -a sleep 1
0132 perf record -e cpu/r1a8/ ...
0133 perf record -e cpu/r0x1a8/ ...
0134
0135 Some processors, like those from AMD, support event codes and unit masks
0136 larger than a byte. In such cases, the bits corresponding to the event
0137 configuration parameters can be seen with:
0138
0139 cat /sys/bus/event_source/devices/<pmu>/format/<config>
0140
0141 Example:
0142
0143 If the AMD docs for an EPYC 7713 processor describe an event as:
0144
0145 Event Umask Event Mask
0146 Num. Value Mnemonic Description
0147
0148 28FH 03H op_cache_hit_miss.op_cache_hit Counts Op Cache micro-tag
0149 hit events.
0150
0151 raw encoding of 0x0328F cannot be used since the upper nibble of the
0152 EventSelect bits have to be specified via bits 32-35 as can be seen with:
0153
0154 cat /sys/bus/event_source/devices/cpu/format/event
0155
0156 raw encoding of 0x20000038F should be used instead:
0157
0158 perf stat -e r20000038f -a sleep 1
0159 perf record -e r20000038f ...
0160
0161 It's also possible to use pmu syntax:
0162
0163 perf record -e r20000038f -a sleep 1
0164 perf record -e cpu/r20000038f/ ...
0165 perf record -e cpu/r0x20000038f/ ...
0166
0167 You should refer to the processor specific documentation for getting these
0168 details. Some of them are referenced in the SEE ALSO section below.
0169
0170 ARBITRARY PMUS
0171 --------------
0172
0173 perf also supports an extended syntax for specifying raw parameters
0174 to PMUs. Using this typically requires looking up the specific event
0175 in the CPU vendor specific documentation.
0176
0177 The available PMUs and their raw parameters can be listed with
0178
0179 ls /sys/devices/*/format
0180
0181 For example the raw event "LSD.UOPS" core pmu event above could
0182 be specified as
0183
0184 perf stat -e cpu/event=0xa8,umask=0x1,name=LSD.UOPS_CYCLES,cmask=0x1/ ...
0185
0186 or using extended name syntax
0187
0188 perf stat -e cpu/event=0xa8,umask=0x1,cmask=0x1,name=\'LSD.UOPS_CYCLES:cmask=0x1\'/ ...
0189
0190 PER SOCKET PMUS
0191 ---------------
0192
0193 Some PMUs are not associated with a core, but with a whole CPU socket.
0194 Events on these PMUs generally cannot be sampled, but only counted globally
0195 with perf stat -a. They can be bound to one logical CPU, but will measure
0196 all the CPUs in the same socket.
0197
0198 This example measures memory bandwidth every second
0199 on the first memory controller on socket 0 of a Intel Xeon system
0200
0201 perf stat -C 0 -a uncore_imc_0/cas_count_read/,uncore_imc_0/cas_count_write/ -I 1000 ...
0202
0203 Each memory controller has its own PMU. Measuring the complete system
0204 bandwidth would require specifying all imc PMUs (see perf list output),
0205 and adding the values together. To simplify creation of multiple events,
0206 prefix and glob matching is supported in the PMU name, and the prefix
0207 'uncore_' is also ignored when performing the match. So the command above
0208 can be expanded to all memory controllers by using the syntaxes:
0209
0210 perf stat -C 0 -a imc/cas_count_read/,imc/cas_count_write/ -I 1000 ...
0211 perf stat -C 0 -a *imc*/cas_count_read/,*imc*/cas_count_write/ -I 1000 ...
0212
0213 This example measures the combined core power every second
0214
0215 perf stat -I 1000 -e power/energy-cores/ -a
0216
0217 ACCESS RESTRICTIONS
0218 -------------------
0219
0220 For non root users generally only context switched PMU events are available.
0221 This is normally only the events in the cpu PMU, the predefined events
0222 like cycles and instructions and some software events.
0223
0224 Other PMUs and global measurements are normally root only.
0225 Some event qualifiers, such as "any", are also root only.
0226
0227 This can be overridden by setting the kernel.perf_event_paranoid
0228 sysctl to -1, which allows non root to use these events.
0229
0230 For accessing trace point events perf needs to have read access to
0231 /sys/kernel/debug/tracing, even when perf_event_paranoid is in a relaxed
0232 setting.
0233
0234 TRACING
0235 -------
0236
0237 Some PMUs control advanced hardware tracing capabilities, such as Intel PT,
0238 that allows low overhead execution tracing. These are described in a separate
0239 intel-pt.txt document.
0240
0241 PARAMETERIZED EVENTS
0242 --------------------
0243
0244 Some pmu events listed by 'perf-list' will be displayed with '?' in them. For
0245 example:
0246
0247 hv_gpci/dtbp_ptitc,phys_processor_idx=?/
0248
0249 This means that when provided as an event, a value for '?' must
0250 also be supplied. For example:
0251
0252 perf stat -C 0 -e 'hv_gpci/dtbp_ptitc,phys_processor_idx=0x2/' ...
0253
0254 EVENT QUALIFIERS:
0255
0256 It is also possible to add extra qualifiers to an event:
0257
0258 percore:
0259
0260 Sums up the event counts for all hardware threads in a core, e.g.:
0261
0262
0263 perf stat -e cpu/event=0,umask=0x3,percore=1/
0264
0265
0266 EVENT GROUPS
0267 ------------
0268
0269 Perf supports time based multiplexing of events, when the number of events
0270 active exceeds the number of hardware performance counters. Multiplexing
0271 can cause measurement errors when the workload changes its execution
0272 profile.
0273
0274 When metrics are computed using formulas from event counts, it is useful to
0275 ensure some events are always measured together as a group to minimize multiplexing
0276 errors. Event groups can be specified using { }.
0277
0278 perf stat -e '{instructions,cycles}' ...
0279
0280 The number of available performance counters depend on the CPU. A group
0281 cannot contain more events than available counters.
0282 For example Intel Core CPUs typically have four generic performance counters
0283 for the core, plus three fixed counters for instructions, cycles and
0284 ref-cycles. Some special events have restrictions on which counter they
0285 can schedule, and may not support multiple instances in a single group.
0286 When too many events are specified in the group some of them will not
0287 be measured.
0288
0289 Globally pinned events can limit the number of counters available for
0290 other groups. On x86 systems, the NMI watchdog pins a counter by default.
0291 The nmi watchdog can be disabled as root with
0292
0293 echo 0 > /proc/sys/kernel/nmi_watchdog
0294
0295 Events from multiple different PMUs cannot be mixed in a group, with
0296 some exceptions for software events.
0297
0298 LEADER SAMPLING
0299 ---------------
0300
0301 perf also supports group leader sampling using the :S specifier.
0302
0303 perf record -e '{cycles,instructions}:S' ...
0304 perf report --group
0305
0306 Normally all events in an event group sample, but with :S only
0307 the first event (the leader) samples, and it only reads the values of the
0308 other events in the group.
0309
0310 However, in the case AUX area events (e.g. Intel PT or CoreSight), the AUX
0311 area event must be the leader, so then the second event samples, not the first.
0312
0313 OPTIONS
0314 -------
0315
0316 Without options all known events will be listed.
0317
0318 To limit the list use:
0319
0320 . 'hw' or 'hardware' to list hardware events such as cache-misses, etc.
0321
0322 . 'sw' or 'software' to list software events such as context switches, etc.
0323
0324 . 'cache' or 'hwcache' to list hardware cache events such as L1-dcache-loads, etc.
0325
0326 . 'tracepoint' to list all tracepoint events, alternatively use
0327 'subsys_glob:event_glob' to filter by tracepoint subsystems such as sched,
0328 block, etc.
0329
0330 . 'pmu' to print the kernel supplied PMU events.
0331
0332 . 'sdt' to list all Statically Defined Tracepoint events.
0333
0334 . 'metric' to list metrics
0335
0336 . 'metricgroup' to list metricgroups with metrics.
0337
0338 . If none of the above is matched, it will apply the supplied glob to all
0339 events, printing the ones that match.
0340
0341 . As a last resort, it will do a substring search in all event names.
0342
0343 One or more types can be used at the same time, listing the events for the
0344 types specified.
0345
0346 Support raw format:
0347
0348 . '--raw-dump', shows the raw-dump of all the events.
0349 . '--raw-dump [hw|sw|cache|tracepoint|pmu|event_glob]', shows the raw-dump of
0350 a certain kind of events.
0351
0352 SEE ALSO
0353 --------
0354 linkperf:perf-stat[1], linkperf:perf-top[1],
0355 linkperf:perf-record[1],
0356 http://www.intel.com/sdm/[Intel® 64 and IA-32 Architectures Software Developer's Manual Volume 3B: System Programming Guide],
0357 https://bugzilla.kernel.org/show_bug.cgi?id=206537[AMD Processor Programming Reference (PPR)]
