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' [<options>]
  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  b - use BPF aggregration (see perf stat --bpf-counters)
  75  R - retire latency value of the event
  76
  77 The 'p' modifier can be used for specifying how precise the instruction
  78 address should be. The 'p' modifier can be specified multiple times:
  79
  80  0 - SAMPLE_IP can have arbitrary skid
  81  1 - SAMPLE_IP must have constant skid
  82  2 - SAMPLE_IP requested to have 0 skid
  83  3 - SAMPLE_IP must have 0 skid, or uses randomization to avoid
  84      sample shadowing effects.
  85
  86 For Intel systems precise event sampling is implemented with PEBS
  87 which supports up to precise-level 2, and precise level 3 for
  88 some special cases
  89
  90 On AMD systems it is implemented using IBS OP (up to precise-level 2).
  91 Unlike Intel PEBS which provides levels of precision, AMD core pmu is
  92 inherently non-precise and IBS is inherently precise. (i.e. ibs_op//,
  93 ibs_op//p, ibs_op//pp and ibs_op//ppp are all same). The precise modifier
  94 works with event types 0x76 (cpu-cycles, CPU clocks not halted) and 0xC1
  95 (micro-ops retired). Both events map to IBS execution sampling (IBS op)
  96 with the IBS Op Counter Control bit (IbsOpCntCtl) set respectively (see the
  97 Core Complex (CCX) -> Processor x86 Core -> Instruction Based Sampling (IBS)
  98 section of the [AMD Processor Programming Reference (PPR)] relevant to the
  99 family, model and stepping of the processor being used).
 100
 101 Manual Volume 2: System Programming, 13.3 Instruction-Based
 102 Sampling). Examples to use IBS:
 103
 104  perf record -a -e cpu-cycles:p ...    # use ibs op counting cycles
 105  perf record -a -e r076:p ...          # same as -e cpu-cycles:p
 106  perf record -a -e r0C1:p ...          # use ibs op counting micro-ops
 107
 108 RAW HARDWARE EVENT DESCRIPTOR
 109 -----------------------------
 110 Even when an event is not available in a symbolic form within perf right now,
 111 it can be encoded in a per processor specific way.
 112
 113 For instance on x86 CPUs, N is a hexadecimal value that represents the raw register encoding with the
 114 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
 115 of IA32_PERFEVTSELx MSRs) or AMD's PERF_CTL MSRs (see the
 116 Core Complex (CCX) -> Processor x86 Core -> MSR Registers section of the
 117 [AMD Processor Programming Reference (PPR)] relevant to the family, model
 118 and stepping of the processor being used).
 119
 120 Note: Only the following bit fields can be set in x86 counter
 121 registers: event, umask, edge, inv, cmask. Esp. guest/host only and
 122 OS/user mode flags must be setup using <<EVENT_MODIFIERS, EVENT
 123 MODIFIERS>>.
 124
 125 Example:
 126
 127 If the Intel docs for a QM720 Core i7 describe an event as:
 128
 129   Event  Umask  Event Mask
 130   Num.   Value  Mnemonic    Description                        Comment
 131
 132   A8H      01H  LSD.UOPS    Counts the number of micro-ops     Use cmask=1 and
 133                             delivered by loop stream detector  invert to count
 134                                                                cycles
 135
 136 raw encoding of 0x1A8 can be used:
 137
 138  perf stat -e r1a8 -a sleep 1
 139  perf record -e r1a8 ...
 140
 141 It's also possible to use pmu syntax:
 142
 143  perf record -e r1a8 -a sleep 1
 144  perf record -e cpu/r1a8/ ...
 145  perf record -e cpu/r0x1a8/ ...
 146
 147 Some processors, like those from AMD, support event codes and unit masks
 148 larger than a byte. In such cases, the bits corresponding to the event
 149 configuration parameters can be seen with:
 150
 151   cat /sys/bus/event_source/devices/<pmu>/format/<config>
 152
 153 Example:
 154
 155 If the AMD docs for an EPYC 7713 processor describe an event as:
 156
 157   Event  Umask  Event Mask
 158   Num.   Value  Mnemonic                        Description
 159
 160   28FH     03H  op_cache_hit_miss.op_cache_hit  Counts Op Cache micro-tag
 161                                                 hit events.
 162
 163 raw encoding of 0x0328F cannot be used since the upper nibble of the
 164 EventSelect bits have to be specified via bits 32-35 as can be seen with:
 165
 166   cat /sys/bus/event_source/devices/cpu/format/event
 167
 168 raw encoding of 0x20000038F should be used instead:
 169
 170  perf stat -e r20000038f -a sleep 1
 171  perf record -e r20000038f ...
 172
 173 It's also possible to use pmu syntax:
 174
 175  perf record -e r20000038f -a sleep 1
 176  perf record -e cpu/r20000038f/ ...
 177  perf record -e cpu/r0x20000038f/ ...
 178
 179 You should refer to the processor specific documentation for getting these
 180 details. Some of them are referenced in the SEE ALSO section below.
 181
 182 ARBITRARY PMUS
 183 --------------
 184
 185 perf also supports an extended syntax for specifying raw parameters
 186 to PMUs. Using this typically requires looking up the specific event
 187 in the CPU vendor specific documentation.
 188
 189 The available PMUs and their raw parameters can be listed with
 190
 191   ls /sys/devices/*/format
 192
 193 For example the raw event "LSD.UOPS" core pmu event above could
 194 be specified as
 195
 196   perf stat -e cpu/event=0xa8,umask=0x1,name=LSD.UOPS_CYCLES,cmask=0x1/ ...
 197
 198   or using extended name syntax
 199
 200   perf stat -e cpu/event=0xa8,umask=0x1,cmask=0x1,name=\'LSD.UOPS_CYCLES:cmask=0x1\'/ ...
 201
 202 PER SOCKET PMUS
 203 ---------------
 204
 205 Some PMUs are not associated with a core, but with a whole CPU socket.
 206 Events on these PMUs generally cannot be sampled, but only counted globally
 207 with perf stat -a. They can be bound to one logical CPU, but will measure
 208 all the CPUs in the same socket.
 209
 210 This example measures memory bandwidth every second
 211 on the first memory controller on socket 0 of a Intel Xeon system
 212
 213   perf stat -C 0 -a uncore_imc_0/cas_count_read/,uncore_imc_0/cas_count_write/ -I 1000 ...
 214
 215 Each memory controller has its own PMU.  Measuring the complete system
 216 bandwidth would require specifying all imc PMUs (see perf list output),
 217 and adding the values together. To simplify creation of multiple events,
 218 prefix and glob matching is supported in the PMU name, and the prefix
 219 'uncore_' is also ignored when performing the match. So the command above
 220 can be expanded to all memory controllers by using the syntaxes:
 221
 222   perf stat -C 0 -a imc/cas_count_read/,imc/cas_count_write/ -I 1000 ...
 223   perf stat -C 0 -a *imc*/cas_count_read/,*imc*/cas_count_write/ -I 1000 ...
 224
 225 This example measures the combined core power every second
 226
 227   perf stat -I 1000 -e power/energy-cores/  -a
 228
 229 ACCESS RESTRICTIONS
 230 -------------------
 231
 232 For non root users generally only context switched PMU events are available.
 233 This is normally only the events in the cpu PMU, the predefined events
 234 like cycles and instructions and some software events.
 235
 236 Other PMUs and global measurements are normally root only.
 237 Some event qualifiers, such as "any", are also root only.
 238
 239 This can be overridden by setting the kernel.perf_event_paranoid
 240 sysctl to -1, which allows non root to use these events.
 241
 242 For accessing trace point events perf needs to have read access to
 243 /sys/kernel/tracing, even when perf_event_paranoid is in a relaxed
 244 setting.
 245
 246 TOOL/HWMON EVENTS
 247 -----------------
 248
 249 Some events don't have an associated PMU instead reading values
 250 available to software without perf_event_open. As these events don't
 251 support sampling they can only really be read by tools like perf stat.
 252
 253 Tool events provide times and certain system parameters. Examples
 254 include duration_time, user_time, system_time and num_cpus_online.
 255
 256 Hwmon events provide easy access to hwmon sysfs data typically in
 257 /sys/class/hwmon. This information includes temperatures, fan speeds
 258 and energy usage.
 259
 260
 261 TRACING
 262 -------
 263
 264 Some PMUs control advanced hardware tracing capabilities, such as Intel PT,
 265 that allows low overhead execution tracing.  These are described in a separate
 266 intel-pt.txt document.
 267
 268 PARAMETERIZED EVENTS
 269 --------------------
 270
 271 Some pmu events listed by 'perf-list' will be displayed with '?' in them. For
 272 example:
 273
 274   hv_gpci/dtbp_ptitc,phys_processor_idx=?/
 275
 276 This means that when provided as an event, a value for '?' must
 277 also be supplied. For example:
 278
 279   perf stat -C 0 -e 'hv_gpci/dtbp_ptitc,phys_processor_idx=0x2/' ...
 280
 281 EVENT QUALIFIERS:
 282
 283 It is also possible to add extra qualifiers to an event:
 284
 285 percore:
 286
 287 Sums up the event counts for all hardware threads in a core, e.g.:
 288
 289
 290   perf stat -e cpu/event=0,umask=0x3,percore=1/
 291
 292
 293 EVENT GROUPS
 294 ------------
 295
 296 Perf supports time based multiplexing of events, when the number of events
 297 active exceeds the number of hardware performance counters. Multiplexing
 298 can cause measurement errors when the workload changes its execution
 299 profile.
 300
 301 When metrics are computed using formulas from event counts, it is useful to
 302 ensure some events are always measured together as a group to minimize multiplexing
 303 errors. Event groups can be specified using { }.
 304
 305   perf stat -e '{instructions,cycles}' ...
 306
 307 The number of available performance counters depend on the CPU. A group
 308 cannot contain more events than available counters.
 309 For example Intel Core CPUs typically have four generic performance counters
 310 for the core, plus three fixed counters for instructions, cycles and
 311 ref-cycles. Some special events have restrictions on which counter they
 312 can schedule, and may not support multiple instances in a single group.
 313 When too many events are specified in the group some of them will not
 314 be measured.
 315
 316 Globally pinned events can limit the number of counters available for
 317 other groups. On x86 systems, the NMI watchdog pins a counter by default.
 318 The nmi watchdog can be disabled as root with
 319
 320         echo 0 > /proc/sys/kernel/nmi_watchdog
 321
 322 Events from multiple different PMUs cannot be mixed in a group, with
 323 some exceptions for software events.
 324
 325 LEADER SAMPLING
 326 ---------------
 327
 328 perf also supports group leader sampling using the :S specifier.
 329
 330   perf record -e '{cycles,instructions}:S' ...
 331   perf report --group
 332
 333 Normally all events in an event group sample, but with :S only
 334 the first event (the leader) samples, and it only reads the values of the
 335 other events in the group.
 336
 337 However, in the case AUX area events (e.g. Intel PT or CoreSight), the AUX
 338 area event must be the leader, so then the second event samples, not the first.
 339
 340 OPTIONS
 341 -------
 342
 343 Without options all known events will be listed.
 344
 345 To limit the list use:
 346
 347 . 'hw' or 'hardware' to list hardware events such as cache-misses, etc.
 348
 349 . 'sw' or 'software' to list software events such as context switches, etc.
 350
 351 . 'cache' or 'hwcache' to list hardware cache events such as L1-dcache-loads, etc.
 352
 353 . 'tracepoint' to list all tracepoint events, alternatively use
 354   'subsys_glob:event_glob' to filter by tracepoint subsystems such as sched,
 355   block, etc.
 356
 357 . 'pmu' to print the kernel supplied PMU events.
 358
 359 . 'sdt' to list all Statically Defined Tracepoint events.
 360
 361 . 'metric' to list metrics
 362
 363 . 'metricgroup' to list metricgroups with metrics.
 364
 365 . If none of the above is matched, it will apply the supplied glob to all
 366   events, printing the ones that match.
 367
 368 . As a last resort, it will do a substring search in all event names.
 369
 370 One or more types can be used at the same time, listing the events for the
 371 types specified.
 372
 373 Support raw format:
 374
 375 . '--raw-dump', shows the raw-dump of all the events.
 376 . '--raw-dump [hw|sw|cache|tracepoint|pmu|event_glob]', shows the raw-dump of
 377   a certain kind of events.
 378
 379 SEE ALSO
 380 --------
 381 linkperf:perf-stat[1], linkperf:perf-top[1],
 382 linkperf:perf-record[1],
 383 http://www.intel.com/sdm/[Intel® 64 and IA-32 Architectures Software Developer's Manual Volume 3B: System Programming Guide],
 384 https://bugzilla.kernel.org/show_bug.cgi?id=206537[AMD Processor Programming Reference (PPR)]