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