'\" t
.\"     Title: perf-list
.\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
.\"      Date: 02/24/2016
.\"    Manual: perf Manual
.\"    Source: perf
.\"  Language: English
.\"
.TH "PERF_3.16\-LIST" "1" "02/24/2016" "perf" "perf Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
perf-list \- List all symbolic event types
.SH "SYNOPSIS"
.sp
.nf
\fIperf list\fR [hw|sw|cache|tracepoint|pmu|event_glob]
.fi
.SH "DESCRIPTION"
.sp
This command displays the symbolic event types which can be selected in the various perf commands with the \-e option\&.
.SH "EVENT MODIFIERS"
.sp
Events can optionally have a modifer by appending a colon and one or more modifiers\&. Modifiers allow the user to restrict the events to be counted\&. The following modifiers exist:
.sp
.if n \{\
.RS 4
.\}
.nf
u \- user\-space counting
k \- kernel counting
h \- hypervisor counting
G \- guest counting (in KVM guests)
H \- host counting (not in KVM guests)
p \- precise level
S \- read sample value (PERF_SAMPLE_READ)
D \- pin the event to the PMU
.fi
.if n \{\
.RE
.\}
.sp
The \fIp\fR modifier can be used for specifying how precise the instruction address should be\&. The \fIp\fR modifier can be specified multiple times:
.sp
.if n \{\
.RS 4
.\}
.nf
0 \- SAMPLE_IP can have arbitrary skid
1 \- SAMPLE_IP must have constant skid
2 \- SAMPLE_IP requested to have 0 skid
3 \- SAMPLE_IP must have 0 skid
.fi
.if n \{\
.RE
.\}
.sp
For Intel systems precise event sampling is implemented with PEBS which supports up to precise\-level 2\&.
.sp
On AMD systems it is implemented using IBS (up to precise\-level 2)\&. The precise modifier works with event types 0x76 (cpu\-cycles, CPU clocks not halted) and 0xC1 (micro\-ops retired)\&. Both events map to IBS execution sampling (IBS op) with the IBS Op Counter Control bit (IbsOpCntCtl) set respectively (see AMD64 Architecture Programmer\(cqs Manual Volume 2: System Programming, 13\&.3 Instruction\-Based Sampling)\&. Examples to use IBS:
.sp
.if n \{\
.RS 4
.\}
.nf
perf record \-a \-e cpu\-cycles:p \&.\&.\&.    # use ibs op counting cycles
perf record \-a \-e r076:p \&.\&.\&.          # same as \-e cpu\-cycles:p
perf record \-a \-e r0C1:p \&.\&.\&.          # use ibs op counting micro\-ops
.fi
.if n \{\
.RE
.\}
.SH "RAW HARDWARE EVENT DESCRIPTOR"
.sp
Even when an event is not available in a symbolic form within perf right now, it can be encoded in a per processor specific way\&.
.sp
For instance For x86 CPUs NNN represents the raw register encoding with the layout of IA32_PERFEVTSELx MSRs (see [Intel\(rg 64 and IA\-32 Architectures Software Developer\(cqs Manual Volume 3B: System Programming Guide] Figure 30\-1 Layout of IA32_PERFEVTSELx MSRs) or AMD\(cqs PerfEvtSeln (see [AMD64 Architecture Programmer\(cqs Manual Volume 2: System Programming], Page 344, Figure 13\-7 Performance Event\-Select Register (PerfEvtSeln))\&.
.sp
Note: Only the following bit fields can be set in x86 counter registers: event, umask, edge, inv, cmask\&. Esp\&. guest/host only and OS/user mode flags must be setup using EVENT MODIFIERS\&.
.sp
Example:
.sp
If the Intel docs for a QM720 Core i7 describe an event as:
.sp
.if n \{\
.RS 4
.\}
.nf
Event  Umask  Event Mask
Num\&.   Value  Mnemonic    Description                        Comment
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
A8H      01H  LSD\&.UOPS    Counts the number of micro\-ops     Use cmask=1 and
                          delivered by loop stream detector  invert to count
                                                             cycles
.fi
.if n \{\
.RE
.\}
.sp
raw encoding of 0x1A8 can be used:
.sp
.if n \{\
.RS 4
.\}
.nf
perf stat \-e r1a8 \-a sleep 1
perf record \-e r1a8 \&.\&.\&.
.fi
.if n \{\
.RE
.\}
.sp
You should refer to the processor specific documentation for getting these details\&. Some of them are referenced in the SEE ALSO section below\&.
.SH "OPTIONS"
.sp
Without options all known events will be listed\&.
.sp
To limit the list use:
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  1." 4.2
.\}

\fIhw\fR
or
\fIhardware\fR
to list hardware events such as cache\-misses, etc\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  2." 4.2
.\}

\fIsw\fR
or
\fIsoftware\fR
to list software events such as context switches, etc\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  3." 4.2
.\}

\fIcache\fR
or
\fIhwcache\fR
to list hardware cache events such as L1\-dcache\-loads, etc\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 4.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  4." 4.2
.\}

\fItracepoint\fR
to list all tracepoint events, alternatively use
\fIsubsys_glob:event_glob\fR
to filter by tracepoint subsystems such as sched, block, etc\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 5.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  5." 4.2
.\}

\fIpmu\fR
to print the kernel supplied PMU events\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 6.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  6." 4.2
.\}
If none of the above is matched, it will apply the supplied glob to all events, printing the ones that match\&.
.RE
.sp
One or more types can be used at the same time, listing the events for the types specified\&.
.SH "SEE ALSO"
.sp
\fBperf_3.16-stat\fR(1), \fBperf_3.16-top\fR(1), \fBperf_3.16-record\fR(1), \m[blue]\fBIntel\(rg 64 and IA\-32 Architectures Software Developer\(cqs Manual Volume 3B: System Programming Guide\fR\m[]\&\s-2\u[1]\d\s+2, \m[blue]\fBAMD64 Architecture Programmer\(cqs Manual Volume 2: System Programming\fR\m[]\&\s-2\u[2]\d\s+2
.SH "NOTES"
.IP " 1." 4
Intel\(rg 64 and IA-32 Architectures Software Developer\(cqs Manual Volume 3B: System Programming Guide
.RS 4
\%http://www.intel.com/Assets/PDF/manual/253669.pdf
.RE
.IP " 2." 4
AMD64 Architecture Programmer\(cqs Manual Volume 2: System Programming
.RS 4
\%http://support.amd.com/us/Processor_TechDocs/24593_APM_v2.pdf
.RE