tools/perf/Documentation/perf-list.txt

   1 perf-list(1)
   2 ============
   3
   4 NAME
   5 ----
   6 perf-list - List all symbolic event types
   7
   8 SYNOPSIS
   9 --------
  10 [verse]
  11 'perf list' [--no-desc] [--long-desc]
  12             [hw|sw|cache|tracepoint|pmu|sdt|metric|metricgroup|event_glob]
  13
  14 DESCRIPTION
  15 -----------
  16 This command displays the symbolic event types which can be selected in the
  17 various perf commands with the -e option.
  18
  19 OPTIONS
  20 -------
  21 -d::
  22 --desc::
  23 Print extra event descriptions. (default)
  24
  25 --no-desc::
  26 Don't print descriptions.
  27
  28 -v::
  29 --long-desc::
  30 Print longer event descriptions.
  31
  32 --debug::
  33 Enable debugging output.
  34
  35 --details::
  36 Print how named events are resolved internally into perf events, and also
  37 any extra expressions computed by perf stat.
  38
  39 --deprecated::
  40 Print deprecated events. By default the deprecated events are hidden.
  41
  42 --unit::
  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)
  45
  46 -j::
  47 --json::
  48 Output in JSON format.
  49
  50 -o::
  51 --output=::
  52         Output file name. By default output is written to stdout.
  53
  54 [[EVENT_MODIFIERS]]
  55 EVENT MODIFIERS
  56 ---------------
  57
  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:
  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
  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:
  77
  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.
  83
  84 For Intel systems precise event sampling is implemented with PEBS
  85 which supports up to precise-level 2, and precise level 3 for
  86 some special cases
  87
  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).
  98
  99 Manual Volume 2: System Programming, 13.3 Instruction-Based
 100 Sampling). Examples to use IBS:
 101
 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
 105
 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.
 110
 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).
 117
 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
 121 MODIFIERS>>.
 122
 123 Example:
 124
 125 If the Intel docs for a QM720 Core i7 describe an event as:
 126
 127   Event  Umask  Event Mask
 128   Num.   Value  Mnemonic    Description                        Comment
 129
 130   A8H      01H  LSD.UOPS    Counts the number of micro-ops     Use cmask=1 and
 131                             delivered by loop stream detector  invert to count
 132                                                                cycles
 133
 134 raw encoding of 0x1A8 can be used:
 135
 136  perf stat -e r1a8 -a sleep 1
 137  perf record -e r1a8 ...
 138
 139 It's also possible to use pmu syntax:
 140
 141  perf record -e r1a8 -a sleep 1
 142  perf record -e cpu/r1a8/ ...
 143  perf record -e cpu/r0x1a8/ ...
 144
 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:
 148
 149   cat /sys/bus/event_source/devices/<pmu>/format/<config>
 150
 151 Example:
 152
 153 If the AMD docs for an EPYC 7713 processor describe an event as:
 154
 155   Event  Umask  Event Mask
 156   Num.   Value  Mnemonic                        Description
 157
 158   28FH     03H  op_cache_hit_miss.op_cache_hit  Counts Op Cache micro-tag
 159                                                 hit events.
 160
 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:
 163
 164   cat /sys/bus/event_source/devices/cpu/format/event
 165
 166 raw encoding of 0x20000038F should be used instead:
 167
 168  perf stat -e r20000038f -a sleep 1
 169  perf record -e r20000038f ...
 170
 171 It's also possible to use pmu syntax:
 172
 173  perf record -e r20000038f -a sleep 1
 174  perf record -e cpu/r20000038f/ ...
 175  perf record -e cpu/r0x20000038f/ ...
 176
 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.
 179
 180 ARBITRARY PMUS
 181 --------------
 182
 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.
 186
 187 The available PMUs and their raw parameters can be listed with
 188
 189   ls /sys/devices/*/format
 190
 191 For example the raw event "LSD.UOPS" core pmu event above could
 192 be specified as
 193
 194   perf stat -e cpu/event=0xa8,umask=0x1,name=LSD.UOPS_CYCLES,cmask=0x1/ ...
 195
 196   or using extended name syntax
 197
 198   perf stat -e cpu/event=0xa8,umask=0x1,cmask=0x1,name=\'LSD.UOPS_CYCLES:cmask=0x1\'/ ...
 199
 200 PER SOCKET PMUS
 201 ---------------
 202
 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.
 207
 208 This example measures memory bandwidth every second
 209 on the first memory controller on socket 0 of a Intel Xeon system
 210
 211   perf stat -C 0 -a uncore_imc_0/cas_count_read/,uncore_imc_0/cas_count_write/ -I 1000 ...
 212
 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:
 219
 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 ...
 222
 223 This example measures the combined core power every second
 224
 225   perf stat -I 1000 -e power/energy-cores/  -a
 226
 227 ACCESS RESTRICTIONS
 228 -------------------
 229
 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.
 233
 234 Other PMUs and global measurements are normally root only.
 235 Some event qualifiers, such as "any", are also root only.
 236
 237 This can be overridden by setting the kernel.perf_event_paranoid
 238 sysctl to -1, which allows non root to use these events.
 239
 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
 242 setting.
 243
 244 TRACING
 245 -------
 246
 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.
 250
 251 PARAMETERIZED EVENTS
 252 --------------------
 253
 254 Some pmu events listed by 'perf-list' will be displayed with '?' in them. For
 255 example:
 256
 257   hv_gpci/dtbp_ptitc,phys_processor_idx=?/
 258
 259 This means that when provided as an event, a value for '?' must
 260 also be supplied. For example:
 261
 262   perf stat -C 0 -e 'hv_gpci/dtbp_ptitc,phys_processor_idx=0x2/' ...
 263
 264 EVENT QUALIFIERS:
 265
 266 It is also possible to add extra qualifiers to an event:
 267
 268 percore:
 269
 270 Sums up the event counts for all hardware threads in a core, e.g.:
 271
 272
 273   perf stat -e cpu/event=0,umask=0x3,percore=1/
 274
 275
 276 EVENT GROUPS
 277 ------------
 278
 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
 282 profile.
 283
 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 { }.
 287
 288   perf stat -e '{instructions,cycles}' ...
 289
 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
 297 be measured.
 298
 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
 302
 303         echo 0 > /proc/sys/kernel/nmi_watchdog
 304
 305 Events from multiple different PMUs cannot be mixed in a group, with
 306 some exceptions for software events.
 307
 308 LEADER SAMPLING
 309 ---------------
 310
 311 perf also supports group leader sampling using the :S specifier.
 312
 313   perf record -e '{cycles,instructions}:S' ...
 314   perf report --group
 315
 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.
 319
 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.
 322
 323 OPTIONS
 324 -------
 325
 326 Without options all known events will be listed.
 327
 328 To limit the list use:
 329
 330 . 'hw' or 'hardware' to list hardware events such as cache-misses, etc.
 331
 332 . 'sw' or 'software' to list software events such as context switches, etc.
 333
 334 . 'cache' or 'hwcache' to list hardware cache events such as L1-dcache-loads, etc.
 335
 336 . 'tracepoint' to list all tracepoint events, alternatively use
 337   'subsys_glob:event_glob' to filter by tracepoint subsystems such as sched,
 338   block, etc.
 339
 340 . 'pmu' to print the kernel supplied PMU events.
 341
 342 . 'sdt' to list all Statically Defined Tracepoint events.
 343
 344 . 'metric' to list metrics
 345
 346 . 'metricgroup' to list metricgroups with metrics.
 347
 348 . If none of the above is matched, it will apply the supplied glob to all
 349   events, printing the ones that match.
 350
 351 . As a last resort, it will do a substring search in all event names.
 352
 353 One or more types can be used at the same time, listing the events for the
 354 types specified.
 355
 356 Support raw format:
 357
 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.
 361
 362 SEE ALSO
 363 --------
 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)]