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] [hw|sw|cache|tracepoint|pmu|event_glob]
  12
  13 DESCRIPTION
  14 -----------
  15 This command displays the symbolic event types which can be selected in the
  16 various perf commands with the -e option.
  17
  18 OPTIONS
  19 -------
  20 --no-desc::
  21 Don't print descriptions.
  22
  23 -v::
  24 --long-desc::
  25 Print longer event descriptions.
  26
  27
  28 [[EVENT_MODIFIERS]]
  29 EVENT MODIFIERS
  30 ---------------
  31
  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:
  35
  36  u - user-space counting
  37  k - kernel counting
  38  h - hypervisor counting
  39  I - non idle counting
  40  G - guest counting (in KVM guests)
  41  H - host counting (not in KVM guests)
  42  p - precise level
  43  P - use maximum detected precise level
  44  S - read sample value (PERF_SAMPLE_READ)
  45  D - pin the event to the PMU
  46
  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:
  49
  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.
  55
  56 For Intel systems precise event sampling is implemented with PEBS
  57 which supports up to precise-level 2, and precise level 3 for
  58 some special cases
  59
  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:
  67
  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
  71
  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.
  76
  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)).
  81
  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
  85 MODIFIERS>>.
  86
  87 Example:
  88
  89 If the Intel docs for a QM720 Core i7 describe an event as:
  90
  91   Event  Umask  Event Mask
  92   Num.   Value  Mnemonic    Description                        Comment
  93
  94   A8H      01H  LSD.UOPS    Counts the number of micro-ops     Use cmask=1 and
  95                             delivered by loop stream detector  invert to count
  96                                                                cycles
  97
  98 raw encoding of 0x1A8 can be used:
  99
 100  perf stat -e r1a8 -a sleep 1
 101  perf record -e r1a8 ...
 102
 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.
 105
 106 ARBITRARY PMUS
 107 --------------
 108
 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.
 112
 113 The available PMUs and their raw parameters can be listed with
 114
 115   ls /sys/devices/*/format
 116
 117 For example the raw event "LSD.UOPS" core pmu event above could
 118 be specified as
 119
 120   perf stat -e cpu/event=0xa8,umask=0x1,name=LSD.UOPS_CYCLES,cmask=1/ ...
 121
 122 PER SOCKET PMUS
 123 ---------------
 124
 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.
 129
 130 This example measures memory bandwidth every second
 131 on the first memory controller on socket 0 of a Intel Xeon system
 132
 133   perf stat -C 0 -a uncore_imc_0/cas_count_read/,uncore_imc_0/cas_count_write/ -I 1000 ...
 134
 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.
 138
 139 This example measures the combined core power every second
 140
 141   perf stat -I 1000 -e power/energy-cores/  -a
 142
 143 ACCESS RESTRICTIONS
 144 -------------------
 145
 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.
 149
 150 Other PMUs and global measurements are normally root only.
 151 Some event qualifiers, such as "any", are also root only.
 152
 153 This can be overriden by setting the kernel.perf_event_paranoid
 154 sysctl to -1, which allows non root to use these events.
 155
 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
 158 setting.
 159
 160 TRACING
 161 -------
 162
 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.
 166
 167 PARAMETERIZED EVENTS
 168 --------------------
 169
 170 Some pmu events listed by 'perf-list' will be displayed with '?' in them. For
 171 example:
 172
 173   hv_gpci/dtbp_ptitc,phys_processor_idx=?/
 174
 175 This means that when provided as an event, a value for '?' must
 176 also be supplied. For example:
 177
 178   perf stat -C 0 -e 'hv_gpci/dtbp_ptitc,phys_processor_idx=0x2/' ...
 179
 180 EVENT GROUPS
 181 ------------
 182
 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
 186 profile.
 187
 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 { }.
 191
 192   perf stat -e '{instructions,cycles}' ...
 193
 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
 201 be measured.
 202
 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
 206
 207         echo 0 > /proc/sys/kernel/nmi_watchdog
 208
 209 Events from multiple different PMUs cannot be mixed in a group, with
 210 some exceptions for software events.
 211
 212 LEADER SAMPLING
 213 ---------------
 214
 215 perf also supports group leader sampling using the :S specifier.
 216
 217   perf record -e '{cycles,instructions}:S' ...
 218   perf report --group
 219
 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.
 223
 224 OPTIONS
 225 -------
 226
 227 Without options all known events will be listed.
 228
 229 To limit the list use:
 230
 231 . 'hw' or 'hardware' to list hardware events such as cache-misses, etc.
 232
 233 . 'sw' or 'software' to list software events such as context switches, etc.
 234
 235 . 'cache' or 'hwcache' to list hardware cache events such as L1-dcache-loads, etc.
 236
 237 . 'tracepoint' to list all tracepoint events, alternatively use
 238   'subsys_glob:event_glob' to filter by tracepoint subsystems such as sched,
 239   block, etc.
 240
 241 . 'pmu' to print the kernel supplied PMU events.
 242
 243 . If none of the above is matched, it will apply the supplied glob to all
 244   events, printing the ones that match.
 245
 246 . As a last resort, it will do a substring search in all event names.
 247
 248 One or more types can be used at the same time, listing the events for the
 249 types specified.
 250
 251 Support raw format:
 252
 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.
 256
 257 SEE ALSO
 258 --------
 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]