'\" t
.\"     Title: perf-annotate
.\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 2023-04-04
.\"    Manual: perf Manual
.\"    Source: perf
.\"  Language: English
.\"
.TH "PERF\-ANNOTATE" "1" "2023\-04\-04" "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-annotate \- Read perf\&.data (created by perf record) and display annotated code
.SH "SYNOPSIS"
.sp
.nf
\fIperf annotate\fR [\-i <file> | \-\-input=file] [symbol_name]
.fi
.SH "DESCRIPTION"
.sp
This command reads the input file and displays an annotated version of the code\&. If the object file has debug symbols then the source code will be displayed alongside assembly code\&.
.sp
If there is no debug info in the object, then annotated assembly is displayed\&.
.SH "OPTIONS"
.PP
\-i, \-\-input=<file>
.RS 4
Input file name\&. (default: perf\&.data unless stdin is a fifo)
.RE
.PP
\-d, \-\-dsos=<dso[,dso\&...]>
.RS 4
Only consider symbols in these dsos\&.
.RE
.PP
\-s, \-\-symbol=<symbol>
.RS 4
Symbol to annotate\&.
.RE
.PP
\-f, \-\-force
.RS 4
Don\(cqt do ownership validation\&.
.RE
.PP
\-v, \-\-verbose
.RS 4
Be more verbose\&. (Show symbol address, etc)
.RE
.PP
\-q, \-\-quiet
.RS 4
Do not show any warnings or messages\&. (Suppress \-v)
.RE
.PP
\-n, \-\-show\-nr\-samples
.RS 4
Show the number of samples for each symbol
.RE
.PP
\-D, \-\-dump\-raw\-trace
.RS 4
Dump raw trace in ASCII\&.
.RE
.PP
\-k, \-\-vmlinux=<file>
.RS 4
vmlinux pathname\&.
.RE
.PP
\-\-ignore\-vmlinux
.RS 4
Ignore vmlinux files\&.
.RE
.PP
\-\-itrace
.RS 4
Options for decoding instruction tracing data\&. The options are:
.sp
.if n \{\
.RS 4
.\}
.nf
i       synthesize instructions events
y       synthesize cycles events
b       synthesize branches events (branch misses for Arm SPE)
c       synthesize branches events (calls only)
r       synthesize branches events (returns only)
x       synthesize transactions events
w       synthesize ptwrite events
p       synthesize power events (incl\&. PSB events for Intel PT)
o       synthesize other events recorded due to the use
        of aux\-output (refer to perf record)
I       synthesize interrupt or similar (asynchronous) events
        (e\&.g\&. Intel PT Event Trace)
e       synthesize error events
d       create a debug log
f       synthesize first level cache events
m       synthesize last level cache events
M       synthesize memory events
t       synthesize TLB events
a       synthesize remote access events
g       synthesize a call chain (use with i or x)
G       synthesize a call chain on existing event records
l       synthesize last branch entries (use with i or x)
L       synthesize last branch entries on existing event records
s       skip initial number of events
q       quicker (less detailed) decoding
A       approximate IPC
Z       prefer to ignore timestamps (so\-called "timeless" decoding)
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
The default is all events i\&.e\&. the same as \-\-itrace=iybxwpe,
except for perf script where it is \-\-itrace=ce
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
In addition, the period (default 100000, except for perf script where it is 1)
for instructions events can be specified in units of:
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
i       instructions
t       ticks
ms      milliseconds
us      microseconds
ns      nanoseconds (default)
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
Also the call chain size (default 16, max\&. 1024) for instructions or
transactions events can be specified\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
Also the number of last branch entries (default 64, max\&. 1024) for
instructions or transactions events can be specified\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
Similar to options g and l, size may also be specified for options G and L\&.
On x86, note that G and L work poorly when data has been recorded with
large PEBS\&. Refer linkperf:perf\-intel\-pt[1] man page for details\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
It is also possible to skip events generated (instructions, branches, transactions,
ptwrite, power) at the beginning\&. This is useful to ignore initialization code\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
\-\-itrace=i0nss1000000
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
skips the first million instructions\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
The \*(Aqe\*(Aq option may be followed by flags which affect what errors will or
will not be reported\&. Each flag must be preceded by either \*(Aq+\*(Aq or \*(Aq\-\*(Aq\&.
The flags are:
        o       overflow
        l       trace data lost
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
If supported, the \*(Aqd\*(Aq option may be followed by flags which affect what
debug messages will or will not be logged\&. Each flag must be preceded
by either \*(Aq+\*(Aq or \*(Aq\-\*(Aq\&. The flags are:
        a       all perf events
        e       output only on errors (size configurable \- see linkperf:perf\-config[1])
        o       output to stdout
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
If supported, the \*(Aqq\*(Aq option may be repeated to increase the effect\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
To disable decoding entirely, use \-\-no\-itrace\&.
.fi
.if n \{\
.RE
.\}
.RE
.PP
\-m, \-\-modules
.RS 4
Load module symbols\&. WARNING: use only with \-k and LIVE kernel\&.
.RE
.PP
\-l, \-\-print\-line
.RS 4
Print matching source lines (may be slow)\&.
.RE
.PP
\-P, \-\-full\-paths
.RS 4
Don\(cqt shorten the displayed pathnames\&.
.RE
.PP
\-\-stdio
.RS 4
Use the stdio interface\&.
.RE
.PP
\-\-stdio2
.RS 4
Use the stdio2 interface, non\-interactive, uses the TUI formatting\&.
.RE
.PP
\-\-stdio\-color=<mode>
.RS 4
\fIalways\fR,
\fInever\fR
or
\fIauto\fR, allowing configuring color output via the command line, in addition to via "color\&.ui" \&.perfconfig\&. Use
\fI\-\-stdio\-color always\fR
to generate color even when redirecting to a pipe or file\&. Using just
\fI\-\-stdio\-color\fR
is equivalent to using
\fIalways\fR\&.
.RE
.PP
\-\-tui
.RS 4
Use the TUI interface\&. Use of \-\-tui requires a tty, if one is not present, as when piping to other commands, the stdio interface is used\&. This interfaces starts by centering on the line with more samples, TAB/UNTAB cycles through the lines with more samples\&.
.RE
.PP
\-\-gtk
.RS 4
Use the GTK interface\&.
.RE
.PP
\-C, \-\-cpu=<cpu>
.RS 4
Only report samples for the list of CPUs provided\&. Multiple CPUs can be provided as a comma\-separated list with no space: 0,1\&. Ranges of CPUs are specified with \-: 0\-2\&. Default is to report samples on all CPUs\&.
.RE
.PP
\-\-asm\-raw
.RS 4
Show raw instruction encoding of assembly instructions\&.
.RE
.PP
\-\-show\-total\-period
.RS 4
Show a column with the sum of periods\&.
.RE
.PP
\-\-source
.RS 4
Interleave source code with assembly code\&. Enabled by default, disable with \-\-no\-source\&.
.RE
.PP
\-\-symfs=<directory>
.RS 4
Look for files with symbols relative to this directory\&.
.RE
.PP
\-M, \-\-disassembler\-style=
.RS 4
Set disassembler style for objdump\&.
.RE
.PP
\-\-addr2line=<path>
.RS 4
Path to addr2line binary\&.
.RE
.PP
\-\-objdump=<path>
.RS 4
Path to objdump binary\&.
.RE
.PP
\-\-prefix=PREFIX, \-\-prefix\-strip=N
.RS 4
Remove first N entries from source file path names in executables and add PREFIX\&. This allows to display source code compiled on systems with different file system layout\&.
.RE
.PP
\-\-skip\-missing
.RS 4
Skip symbols that cannot be annotated\&.
.RE
.PP
\-\-group
.RS 4
Show event group information together
.RE
.PP
\-\-demangle
.RS 4
Demangle symbol names to human readable form\&. It\(cqs enabled by default, disable with \-\-no\-demangle\&.
.RE
.PP
\-\-demangle\-kernel
.RS 4
Demangle kernel symbol names to human readable form (for C++ kernels)\&.
.RE
.PP
\-\-percent\-type
.RS 4
Set annotation percent type from following choices: global\-period, local\-period, global\-hits, local\-hits
.sp
.if n \{\
.RS 4
.\}
.nf
The local/global keywords set if the percentage is computed
in the scope of the function (local) or the whole data (global)\&.
The period/hits keywords set the base the percentage is computed
on \- the samples period or the number of samples (hits)\&.
.fi
.if n \{\
.RE
.\}
.RE
.PP
\-\-percent\-limit
.RS 4
Do not show functions which have an overhead under that percent on stdio or stdio2 (Default: 0)\&. Note that this is about selection of functions to display, not about lines within the function\&.
.RE
.SH "SEE ALSO"
.sp
\fBperf-record\fR(1), \fBperf-report\fR(1)