1perf-list(1) 2============ 3 4NAME 5---- 6perf-list - List all symbolic event types 7 8SYNOPSIS 9-------- 10[verse] 11'perf list' [--no-desc] [--long-desc] 12 [hw|sw|cache|tracepoint|pmu|sdt|metric|metricgroup|event_glob] 13 14DESCRIPTION 15----------- 16This command displays the symbolic event types which can be selected in the 17various perf commands with the -e option. 18 19OPTIONS 20------- 21-d:: 22--desc:: 23Print extra event descriptions. (default) 24 25--no-desc:: 26Don't print descriptions. 27 28-v:: 29--long-desc:: 30Print longer event descriptions. 31 32--debug:: 33Enable debugging output. 34 35--details:: 36Print how named events are resolved internally into perf events, and also 37any extra expressions computed by perf stat. 38 39--deprecated:: 40Print deprecated events. By default the deprecated events are hidden. 41 42--unit:: 43Print 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:: 48Output in JSON format. 49 50-o:: 51--output=:: 52 Output file name. By default output is written to stdout. 53 54[[EVENT_MODIFIERS]] 55EVENT MODIFIERS 56--------------- 57 58Events can optionally have a modifier by appending a colon and one or 59more modifiers. Modifiers allow the user to restrict the events to be 60counted. 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 75The 'p' modifier can be used for specifying how precise the instruction 76address 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 84For Intel systems precise event sampling is implemented with PEBS 85which supports up to precise-level 2, and precise level 3 for 86some special cases 87 88On AMD systems it is implemented using IBS OP (up to precise-level 2). 89Unlike Intel PEBS which provides levels of precision, AMD core pmu is 90inherently non-precise and IBS is inherently precise. (i.e. ibs_op//, 91ibs_op//p, ibs_op//pp and ibs_op//ppp are all same). The precise modifier 92works 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) 94with the IBS Op Counter Control bit (IbsOpCntCtl) set respectively (see the 95Core Complex (CCX) -> Processor x86 Core -> Instruction Based Sampling (IBS) 96section of the [AMD Processor Programming Reference (PPR)] relevant to the 97family, model and stepping of the processor being used). 98 99Manual Volume 2: System Programming, 13.3 Instruction-Based 100Sampling). 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 106RAW HARDWARE EVENT DESCRIPTOR 107----------------------------- 108Even when an event is not available in a symbolic form within perf right now, 109it can be encoded in a per processor specific way. 110 111For instance on x86 CPUs, N is a hexadecimal value that represents the raw register encoding with the 112layout of IA32_PERFEVTSELx MSRs (see [Intel�� 64 and IA-32 Architectures Software Developer's Manual Volume 3B: System Programming Guide] Figure 30-1 Layout 113of IA32_PERFEVTSELx MSRs) or AMD's PERF_CTL MSRs (see the 114Core Complex (CCX) -> Processor x86 Core -> MSR Registers section of the 115[AMD Processor Programming Reference (PPR)] relevant to the family, model 116and stepping of the processor being used). 117 118Note: Only the following bit fields can be set in x86 counter 119registers: event, umask, edge, inv, cmask. Esp. guest/host only and 120OS/user mode flags must be setup using <<EVENT_MODIFIERS, EVENT 121MODIFIERS>>. 122 123Example: 124 125If 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 134raw encoding of 0x1A8 can be used: 135 136 perf stat -e r1a8 -a sleep 1 137 perf record -e r1a8 ... 138 139It'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 145Some processors, like those from AMD, support event codes and unit masks 146larger than a byte. In such cases, the bits corresponding to the event 147configuration parameters can be seen with: 148 149 cat /sys/bus/event_source/devices/<pmu>/format/<config> 150 151Example: 152 153If 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 161raw encoding of 0x0328F cannot be used since the upper nibble of the 162EventSelect 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 166raw encoding of 0x20000038F should be used instead: 167 168 perf stat -e r20000038f -a sleep 1 169 perf record -e r20000038f ... 170 171It'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 177You should refer to the processor specific documentation for getting these 178details. Some of them are referenced in the SEE ALSO section below. 179 180ARBITRARY PMUS 181-------------- 182 183perf also supports an extended syntax for specifying raw parameters 184to PMUs. Using this typically requires looking up the specific event 185in the CPU vendor specific documentation. 186 187The available PMUs and their raw parameters can be listed with 188 189 ls /sys/devices/*/format 190 191For example the raw event "LSD.UOPS" core pmu event above could 192be 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 200PER SOCKET PMUS 201--------------- 202 203Some PMUs are not associated with a core, but with a whole CPU socket. 204Events on these PMUs generally cannot be sampled, but only counted globally 205with perf stat -a. They can be bound to one logical CPU, but will measure 206all the CPUs in the same socket. 207 208This example measures memory bandwidth every second 209on 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 213Each memory controller has its own PMU. Measuring the complete system 214bandwidth would require specifying all imc PMUs (see perf list output), 215and adding the values together. To simplify creation of multiple events, 216prefix 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 218can 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 223This example measures the combined core power every second 224 225 perf stat -I 1000 -e power/energy-cores/ -a 226 227ACCESS RESTRICTIONS 228------------------- 229 230For non root users generally only context switched PMU events are available. 231This is normally only the events in the cpu PMU, the predefined events 232like cycles and instructions and some software events. 233 234Other PMUs and global measurements are normally root only. 235Some event qualifiers, such as "any", are also root only. 236 237This can be overridden by setting the kernel.perf_event_paranoid 238sysctl to -1, which allows non root to use these events. 239 240For accessing trace point events perf needs to have read access to 241/sys/kernel/tracing, even when perf_event_paranoid is in a relaxed 242setting. 243 244TRACING 245------- 246 247Some PMUs control advanced hardware tracing capabilities, such as Intel PT, 248that allows low overhead execution tracing. These are described in a separate 249intel-pt.txt document. 250 251PARAMETERIZED EVENTS 252-------------------- 253 254Some pmu events listed by 'perf-list' will be displayed with '?' in them. For 255example: 256 257 hv_gpci/dtbp_ptitc,phys_processor_idx=?/ 258 259This means that when provided as an event, a value for '?' must 260also be supplied. For example: 261 262 perf stat -C 0 -e 'hv_gpci/dtbp_ptitc,phys_processor_idx=0x2/' ... 263 264EVENT QUALIFIERS: 265 266It is also possible to add extra qualifiers to an event: 267 268percore: 269 270Sums 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 276EVENT GROUPS 277------------ 278 279Perf supports time based multiplexing of events, when the number of events 280active exceeds the number of hardware performance counters. Multiplexing 281can cause measurement errors when the workload changes its execution 282profile. 283 284When metrics are computed using formulas from event counts, it is useful to 285ensure some events are always measured together as a group to minimize multiplexing 286errors. Event groups can be specified using { }. 287 288 perf stat -e '{instructions,cycles}' ... 289 290The number of available performance counters depend on the CPU. A group 291cannot contain more events than available counters. 292For example Intel Core CPUs typically have four generic performance counters 293for the core, plus three fixed counters for instructions, cycles and 294ref-cycles. Some special events have restrictions on which counter they 295can schedule, and may not support multiple instances in a single group. 296When too many events are specified in the group some of them will not 297be measured. 298 299Globally pinned events can limit the number of counters available for 300other groups. On x86 systems, the NMI watchdog pins a counter by default. 301The nmi watchdog can be disabled as root with 302 303 echo 0 > /proc/sys/kernel/nmi_watchdog 304 305Events from multiple different PMUs cannot be mixed in a group, with 306some exceptions for software events. 307 308LEADER SAMPLING 309--------------- 310 311perf also supports group leader sampling using the :S specifier. 312 313 perf record -e '{cycles,instructions}:S' ... 314 perf report --group 315 316Normally all events in an event group sample, but with :S only 317the first event (the leader) samples, and it only reads the values of the 318other events in the group. 319 320However, in the case AUX area events (e.g. Intel PT or CoreSight), the AUX 321area event must be the leader, so then the second event samples, not the first. 322 323OPTIONS 324------- 325 326Without options all known events will be listed. 327 328To 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 353One or more types can be used at the same time, listing the events for the 354types specified. 355 356Support 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 362SEE ALSO 363-------- 364linkperf:perf-stat[1], linkperf:perf-top[1], 365linkperf:perf-record[1], 366http://www.intel.com/sdm/[Intel�� 64 and IA-32 Architectures Software Developer's Manual Volume 3B: System Programming Guide], 367https://bugzilla.kernel.org/show_bug.cgi?id=206537[AMD Processor Programming Reference (PPR)] 368