blob: d1deb573877fe5d84a8a7a7a63fe700585e4d8d5 [file] [log] [blame]
Arnaldo Carvalho de Melo86a9eee2009-12-14 20:09:31 -02001perf-diff(1)
Arnaldo Carvalho de Melo4778e0e2010-05-05 11:23:27 -03002============
Arnaldo Carvalho de Melo86a9eee2009-12-14 20:09:31 -02003
4NAME
5----
Jiri Olsa3a3beae2012-10-24 14:56:51 +02006perf-diff - Read perf.data files and display the differential profile
Arnaldo Carvalho de Melo86a9eee2009-12-14 20:09:31 -02007
8SYNOPSIS
9--------
10[verse]
Jiri Olsa3a3beae2012-10-24 14:56:51 +020011'perf diff' [baseline file] [data file1] [[data file2] ... ]
Arnaldo Carvalho de Melo86a9eee2009-12-14 20:09:31 -020012
13DESCRIPTION
14-----------
Jiri Olsa3a3beae2012-10-24 14:56:51 +020015This command displays the performance difference amongst two or more perf.data
16files captured via perf record.
Arnaldo Carvalho de Melo86a9eee2009-12-14 20:09:31 -020017
18If no parameters are passed it will assume perf.data.old and perf.data.
19
Jiri Olsa863e4512012-09-06 17:46:55 +020020The differential profile is displayed only for events matching both
21specified perf.data files.
22
Kan Liang94ba4622015-02-09 05:39:44 +000023If no parameters are passed the samples will be sorted by dso and symbol.
24As the perf.data files could come from different binaries, the symbols addresses
25could vary. So perf diff is based on the comparison of the files and
26symbols name.
27
Arnaldo Carvalho de Melo86a9eee2009-12-14 20:09:31 -020028OPTIONS
29-------
Shawn Bohrer5ea4f852010-11-30 19:57:12 -060030-D::
31--dump-raw-trace::
32 Dump raw trace in ASCII.
33
David Ahern6b1f3422015-03-24 09:51:57 -060034--kallsyms=<file>::
35 kallsyms pathname
36
Shawn Bohrer5ea4f852010-11-30 19:57:12 -060037-m::
38--modules::
39 Load module symbols. WARNING: use only with -k and LIVE kernel
40
Arnaldo Carvalho de Meloc351c282009-12-16 13:49:27 -020041-d::
42--dsos=::
43 Only consider symbols in these dsos. CSV that understands
Namhyung Kim8810f6c2014-02-07 12:06:07 +090044 file://filename entries. This option will affect the percentage
45 of the Baseline/Delta column. See --percentage for more info.
Arnaldo Carvalho de Meloc351c282009-12-16 13:49:27 -020046
47-C::
48--comms=::
49 Only consider symbols in these comms. CSV that understands
Namhyung Kim8810f6c2014-02-07 12:06:07 +090050 file://filename entries. This option will affect the percentage
51 of the Baseline/Delta column. See --percentage for more info.
Arnaldo Carvalho de Meloc351c282009-12-16 13:49:27 -020052
53-S::
54--symbols=::
55 Only consider these symbols. CSV that understands
Namhyung Kim8810f6c2014-02-07 12:06:07 +090056 file://filename entries. This option will affect the percentage
57 of the Baseline/Delta column. See --percentage for more info.
Arnaldo Carvalho de Meloc351c282009-12-16 13:49:27 -020058
59-s::
60--sort=::
Namhyung Kima2ce0672014-03-04 09:06:42 +090061 Sort by key(s): pid, comm, dso, symbol, cpu, parent, srcline.
62 Please see description of --sort in the perf-report man page.
Arnaldo Carvalho de Meloc351c282009-12-16 13:49:27 -020063
64-t::
65--field-separator=::
66
67 Use a special separator character and don't pad with spaces, replacing
Shawn Bohrer5ea4f852010-11-30 19:57:12 -060068 all occurrences of this separator in symbol names (and other output)
Arnaldo Carvalho de Meloc351c282009-12-16 13:49:27 -020069 with a '.' character, that thus it's the only non valid separator.
70
Arnaldo Carvalho de Melo86a9eee2009-12-14 20:09:31 -020071-v::
72--verbose::
Ingo Molnard30531c2009-12-15 10:24:08 +010073 Be verbose, for instance, show the raw counts in addition to the
Arnaldo Carvalho de Melo86a9eee2009-12-14 20:09:31 -020074 diff.
Arnaldo Carvalho de Melocdccc692009-12-15 11:01:22 -020075
Shawn Bohrer5ea4f852010-11-30 19:57:12 -060076-f::
77--force::
78 Don't complain, do it.
79
David Ahernec5761e2010-12-09 13:27:07 -070080--symfs=<directory>::
81 Look for files with symbols relative to this directory.
Shawn Bohrer5ea4f852010-11-30 19:57:12 -060082
Jiri Olsaa06d1432012-10-05 16:44:40 +020083-b::
84--baseline-only::
85 Show only items with match in baseline.
86
Jiri Olsa7aaf6b32012-10-05 16:44:41 +020087-c::
88--compute::
Jiri Olsa81d5f952012-10-05 16:44:43 +020089 Differential computation selection - delta,ratio,wdiff (default is delta).
Jiri Olsa7aaf6b32012-10-05 16:44:41 +020090 See COMPARISON METHODS section for more info.
91
Jiri Olsa61949b22012-10-05 16:44:44 +020092-p::
93--period::
94 Show period values for both compared hist entries.
95
Jiri Olsaed279da2012-10-05 16:44:45 +020096-F::
97--formula::
98 Show formula for given computation.
99
Jiri Olsa5f3f8d32012-11-25 23:10:20 +0100100-o::
101--order::
102 Specify compute sorting column number.
103
Namhyung Kim8810f6c2014-02-07 12:06:07 +0900104--percentage::
105 Determine how to display the overhead percentage of filtered entries.
106 Filters can be applied by --comms, --dsos and/or --symbols options.
107
108 "relative" means it's relative to filtered entries only so that the
109 sum of shown entries will be always 100%. "absolute" means it retains
110 the original value before and after the filter is applied.
111
Jiri Olsa3a3beae2012-10-24 14:56:51 +0200112COMPARISON
113----------
114The comparison is governed by the baseline file. The baseline perf.data
115file is iterated for samples. All other perf.data files specified on
116the command line are searched for the baseline sample pair. If the pair
117is found, specified computation is made and result is displayed.
118
119All samples from non-baseline perf.data files, that do not match any
120baseline entry, are displayed with empty space within baseline column
121and possible computation results (delta) in their related column.
122
123Example files samples:
124- file A with samples f1, f2, f3, f4, f6
125- file B with samples f2, f4, f5
126- file C with samples f1, f2, f5
127
128Example output:
129 x - computation takes place for pair
130 b - baseline sample percentage
131
132- perf diff A B C
133
134 baseline/A compute/B compute/C samples
135 ---------------------------------------
136 b x f1
137 b x x f2
138 b f3
139 b x f4
140 b f6
141 x x f5
142
143- perf diff B A C
144
145 baseline/B compute/A compute/C samples
146 ---------------------------------------
147 b x x f2
148 b x f4
149 b x f5
150 x x f1
151 x f3
152 x f6
153
154- perf diff C B A
155
156 baseline/C compute/B compute/A samples
157 ---------------------------------------
158 b x f1
159 b x x f2
160 b x f5
161 x f3
162 x x f4
163 x f6
164
Jiri Olsa7aaf6b32012-10-05 16:44:41 +0200165COMPARISON METHODS
166------------------
167delta
168~~~~~
169If specified the 'Delta' column is displayed with value 'd' computed as:
170
171 d = A->period_percent - B->period_percent
172
173with:
Jiri Olsa3a3beae2012-10-24 14:56:51 +0200174 - A/B being matching hist entry from data/baseline file specified
Jiri Olsa7aaf6b32012-10-05 16:44:41 +0200175 (or perf.data/perf.data.old) respectively.
176
177 - period_percent being the % of the hist entry period value within
178 single data file
179
Namhyung Kim8810f6c2014-02-07 12:06:07 +0900180 - with filtering by -C, -d and/or -S, period_percent might be changed
181 relative to how entries are filtered. Use --percentage=absolute to
182 prevent such fluctuation.
183
Jiri Olsa7aaf6b32012-10-05 16:44:41 +0200184ratio
185~~~~~
186If specified the 'Ratio' column is displayed with value 'r' computed as:
187
188 r = A->period / B->period
189
190with:
Jiri Olsa3a3beae2012-10-24 14:56:51 +0200191 - A/B being matching hist entry from data/baseline file specified
Jiri Olsa7aaf6b32012-10-05 16:44:41 +0200192 (or perf.data/perf.data.old) respectively.
193
194 - period being the hist entry period value
195
Jiri Olsa3a3beae2012-10-24 14:56:51 +0200196wdiff:WEIGHT-B,WEIGHT-A
197~~~~~~~~~~~~~~~~~~~~~~~
Jiri Olsa81d5f952012-10-05 16:44:43 +0200198If specified the 'Weighted diff' column is displayed with value 'd' computed as:
199
200 d = B->period * WEIGHT-A - A->period * WEIGHT-B
201
Jiri Olsa3a3beae2012-10-24 14:56:51 +0200202 - A/B being matching hist entry from data/baseline file specified
Jiri Olsa81d5f952012-10-05 16:44:43 +0200203 (or perf.data/perf.data.old) respectively.
204
205 - period being the hist entry period value
206
Masanari Iida96355f22014-09-10 00:18:50 +0900207 - WEIGHT-A/WEIGHT-B being user supplied weights in the the '-c' option
Jiri Olsa81d5f952012-10-05 16:44:43 +0200208 behind ':' separator like '-c wdiff:1,2'.
Masanari Iida96355f22014-09-10 00:18:50 +0900209 - WEIGHT-A being the weight of the data file
210 - WEIGHT-B being the weight of the baseline data file
Jiri Olsa7aaf6b32012-10-05 16:44:41 +0200211
Arnaldo Carvalho de Melo86a9eee2009-12-14 20:09:31 -0200212SEE ALSO
213--------
Namhyung Kima2ce0672014-03-04 09:06:42 +0900214linkperf:perf-record[1], linkperf:perf-report[1]