'\" t
.\" Title: perf-inject
.\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
.\" Generator: DocBook XSL Stylesheets vsnapshot
.\" Date: 2022-10-04
.\" Manual: perf Manual
.\" Source: perf
.\" Language: English
.\"
.TH "PERF\-INJECT" "1" "2022\-10\-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-inject \- Filter to augment the events stream with additional information
.SH "SYNOPSIS"
.sp
.nf
\fIperf inject \fR
.fi
.SH "DESCRIPTION"
.sp
perf\-inject reads a perf\-record event stream and repipes it to stdout\&. At any point the processing code can inject other events into the event stream \- in this case build\-ids (\-b option) are read and injected as needed into the event stream\&.
.sp
Build\-ids are just the first user of perf\-inject \- potentially anything that needs userspace processing to augment the events stream with additional information could make use of this facility\&.
.SH "OPTIONS"
.PP
\-b, \-\-build\-ids
.RS 4
Inject build\-ids of DSOs hit by samples into the output stream\&. This means it needs to process all SAMPLE records to find the DSOs\&.
.RE
.PP
\-\-buildid\-all
.RS 4
Inject build\-ids of all DSOs into the output stream regardless of hits and skip SAMPLE processing\&.
.RE
.PP
\-\-known\-build\-ids=
.RS 4
Override build\-ids to inject using these comma\-separated pairs of build\-id and path\&. Understands
\m[blue]\fBfile://filename\fR\m[]
to read these pairs from a file, which can be generated with perf buildid\-list\&.
.RE
.PP
\-v, \-\-verbose
.RS 4
Be more verbose\&.
.RE
.PP
\-i, \-\-input=
.RS 4
Input file name\&. (default: stdin)
.RE
.PP
\-o, \-\-output=
.RS 4
Output file name\&. (default: stdout)
.RE
.PP
\-s, \-\-sched\-stat
.RS 4
Merge sched_stat and sched_switch for getting events where and how long tasks slept\&. sched_switch contains a callchain where a task slept and sched_stat contains a timeslice how long a task slept\&.
.RE
.PP
\-k, \-\-vmlinux=
.RS 4
vmlinux pathname
.RE
.PP
\-\-ignore\-vmlinux
.RS 4
Ignore vmlinux files\&.
.RE
.PP
\-\-kallsyms=
.RS 4
kallsyms pathname
.RE
.PP
\-\-itrace
.RS 4
Decode Instruction Tracing data, replacing it with synthesized events\&. 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
.\}
.RE
.PP
\-\-strip
.RS 4
Use with \-\-itrace to strip out non\-synthesized events\&.
.RE
.PP
\-j, \-\-jit
.RS 4
Process jitdump files by injecting the mmap records corresponding to jitted functions\&. This option also generates the ELF images for each jitted function found in the jitdumps files captured in the input perf\&.data file\&. Use this option if you are monitoring environment using JIT runtimes, such as Java, DART or V8\&.
.RE
.PP
\-f, \-\-force
.RS 4
Don\(cqt complain, do it\&.
.RE
.PP
\-\-vm\-time\-correlation[=OPTIONS]
.RS 4
Some architectures may capture AUX area data which contains timestamps affected by virtualization\&. This option will update those timestamps in place, to correlate with host timestamps\&. The in\-place update means that an output file is not specified, and instead the input file is modified\&. The options are architecture specific, except that they may start with "dry\-run" which will cause the file to be processed but without updating it\&. Currently this option is supported only by Intel PT, refer
\fBperf-intel-pt\fR(1)
.RE
.PP
\-\-guest\-data=,[,