|
145
|
1 @c Copyright (C) 2013-2020 Free Software Foundation, Inc.
|
|
111
|
2 @c This is part of the GCC manual.
|
|
|
3 @c For copying conditions, see the file gcc.texi.
|
|
|
4
|
|
|
5 @cindex optimization dumps
|
|
|
6
|
|
|
7 This section is describes dump infrastructure which is common to both
|
|
|
8 pass dumps as well as optimization dumps. The goal for this
|
|
|
9 infrastructure is to provide both gcc developers and users detailed
|
|
|
10 information about various compiler transformations and optimizations.
|
|
|
11
|
|
|
12 @menu
|
|
|
13 * Dump setup:: Setup of optimization dumps.
|
|
|
14 * Optimization groups:: Groups made up of optimization passes.
|
|
|
15 * Dump files and streams:: Dump output file names and streams.
|
|
|
16 * Dump output verbosity:: How much information to dump.
|
|
|
17 * Dump types:: Various types of dump functions.
|
|
|
18 * Dump examples:: Sample usage.
|
|
|
19 @end menu
|
|
|
20
|
|
|
21 @node Dump setup
|
|
|
22 @subsection Dump setup
|
|
|
23 @cindex dump setup
|
|
|
24
|
|
|
25 A dump_manager class is defined in @file{dumpfile.h}. Various passes
|
|
|
26 register dumping pass-specific information via @code{dump_register} in
|
|
|
27 @file{passes.c}. During the registration, an optimization pass can
|
|
|
28 select its optimization group (@pxref{Optimization groups}). After
|
|
|
29 that optimization information corresponding to the entire group
|
|
|
30 (presumably from multiple passes) can be output via command-line
|
|
|
31 switches. Note that if a pass does not fit into any of the pre-defined
|
|
|
32 groups, it can select @code{OPTGROUP_NONE}.
|
|
|
33
|
|
|
34 Note that in general, a pass need not know its dump output file name,
|
|
|
35 whether certain flags are enabled, etc. However, for legacy reasons,
|
|
|
36 passes could also call @code{dump_begin} which returns a stream in
|
|
|
37 case the particular pass has optimization dumps enabled. A pass could
|
|
|
38 call @code{dump_end} when the dump has ended. These methods should go
|
|
|
39 away once all the passes are converted to use the new dump
|
|
|
40 infrastructure.
|
|
|
41
|
|
|
42 The recommended way to setup the dump output is via @code{dump_start}
|
|
|
43 and @code{dump_end}.
|
|
|
44
|
|
|
45 @node Optimization groups
|
|
|
46 @subsection Optimization groups
|
|
|
47 @cindex optimization groups
|
|
|
48 The optimization passes are grouped into several categories. Currently
|
|
|
49 defined categories in @file{dumpfile.h} are
|
|
|
50
|
|
|
51 @ftable @code
|
|
|
52
|
|
|
53 @item OPTGROUP_IPA
|
|
|
54 IPA optimization passes. Enabled by @option{-ipa}
|
|
|
55
|
|
|
56 @item OPTGROUP_LOOP
|
|
|
57 Loop optimization passes. Enabled by @option{-loop}.
|
|
|
58
|
|
|
59 @item OPTGROUP_INLINE
|
|
|
60 Inlining passes. Enabled by @option{-inline}.
|
|
|
61
|
|
|
62 @item OPTGROUP_OMP
|
|
|
63 OMP (Offloading and Multi Processing) passes. Enabled by
|
|
|
64 @option{-omp}.
|
|
|
65
|
|
|
66 @item OPTGROUP_VEC
|
|
|
67 Vectorization passes. Enabled by @option{-vec}.
|
|
|
68
|
|
|
69 @item OPTGROUP_OTHER
|
|
|
70 All other optimization passes which do not fall into one of the above.
|
|
|
71
|
|
|
72 @item OPTGROUP_ALL
|
|
|
73 All optimization passes. Enabled by @option{-optall}.
|
|
|
74
|
|
|
75 @end ftable
|
|
|
76
|
|
|
77 By using groups a user could selectively enable optimization
|
|
|
78 information only for a group of passes. By default, the optimization
|
|
|
79 information for all the passes is dumped.
|
|
|
80
|
|
|
81 @node Dump files and streams
|
|
|
82 @subsection Dump files and streams
|
|
|
83 @cindex optimization info file names
|
|
|
84
|
|
|
85 There are two separate output streams available for outputting
|
|
|
86 optimization information from passes. Note that both these streams
|
|
|
87 accept @code{stderr} and @code{stdout} as valid streams and thus it is
|
|
|
88 possible to dump output to standard output or error. This is specially
|
|
|
89 handy for outputting all available information in a single file by
|
|
|
90 redirecting @code{stderr}.
|
|
|
91
|
|
|
92 @table @code
|
|
|
93 @item @code{pstream}
|
|
|
94 This stream is for pass-specific dump output. For example,
|
|
|
95 @option{-fdump-tree-vect=foo.v} dumps tree vectorization pass output
|
|
|
96 into the given file name @file{foo.v}. If the file name is not provided,
|
|
|
97 the default file name is based on the source file and pass number. Note
|
|
|
98 that one could also use special file names @code{stdout} and
|
|
|
99 @code{stderr} for dumping to standard output and standard error
|
|
|
100 respectively.
|
|
|
101
|
|
|
102 @item @code{alt_stream}
|
|
|
103 This steam is used for printing optimization specific output in
|
|
|
104 response to the @option{-fopt-info}. Again a file name can be given. If
|
|
|
105 the file name is not given, it defaults to @code{stderr}.
|
|
|
106 @end table
|
|
|
107
|
|
|
108 @node Dump output verbosity
|
|
|
109 @subsection Dump output verbosity
|
|
|
110 @cindex dump verbosity
|
|
|
111
|
|
|
112 The dump verbosity has the following options
|
|
|
113
|
|
|
114 @table @samp
|
|
|
115 @item optimized
|
|
|
116 Print information when an optimization is successfully applied. It is
|
|
|
117 up to a pass to decide which information is relevant. For example, the
|
|
|
118 vectorizer passes print the source location of loops which got
|
|
|
119 successfully vectorized.
|
|
|
120
|
|
|
121 @item missed
|
|
|
122 Print information about missed optimizations. Individual passes
|
|
|
123 control which information to include in the output. For example,
|
|
|
124
|
|
|
125 @smallexample
|
|
|
126 gcc -O2 -ftree-vectorize -fopt-info-vec-missed
|
|
|
127 @end smallexample
|
|
|
128
|
|
|
129 will print information about missed optimization opportunities from
|
|
|
130 vectorization passes on stderr.
|
|
|
131
|
|
|
132 @item note
|
|
|
133 Print verbose information about optimizations, such as certain
|
|
|
134 transformations, more detailed messages about decisions etc.
|
|
|
135
|
|
|
136 @item all
|
|
|
137 Print detailed optimization information. This includes
|
|
|
138 @var{optimized}, @var{missed}, and @var{note}.
|
|
|
139 @end table
|
|
|
140
|
|
|
141 @node Dump types
|
|
|
142 @subsection Dump types
|
|
|
143 @cindex dump types
|
|
|
144
|
|
|
145 @ftable @code
|
|
|
146
|
|
|
147 @item dump_printf
|
|
|
148
|
|
|
149 This is a generic method for doing formatted output. It takes an
|
|
|
150 additional argument @code{dump_kind} which signifies the type of
|
|
|
151 dump. This method outputs information only when the dumps are enabled
|
|
|
152 for this particular @code{dump_kind}. Note that the caller doesn't
|
|
|
153 need to know if the particular dump is enabled or not, or even the
|
|
|
154 file name. The caller only needs to decide which dump output
|
|
|
155 information is relevant, and under what conditions. This determines
|
|
|
156 the associated flags.
|
|
|
157
|
|
|
158 Consider the following example from @file{loop-unroll.c} where an
|
|
|
159 informative message about a loop (along with its location) is printed
|
|
|
160 when any of the following flags is enabled
|
|
|
161 @itemize @minus
|
|
|
162
|
|
|
163 @item optimization messages
|
|
|
164 @item RTL dumps
|
|
|
165 @item detailed dumps
|
|
|
166
|
|
|
167 @end itemize
|
|
|
168
|
|
|
169 @example
|
|
|
170 int report_flags = MSG_OPTIMIZED_LOCATIONS | TDF_RTL | TDF_DETAILS;
|
|
131
|
171 dump_printf_loc (report_flags, insn,
|
|
111
|
172 "loop turned into non-loop; it never loops.\n");
|
|
|
173 @end example
|
|
|
174
|
|
|
175 @item dump_basic_block
|
|
|
176 Output basic block.
|
|
|
177 @item dump_generic_expr
|
|
|
178 Output generic expression.
|
|
|
179 @item dump_gimple_stmt
|
|
|
180 Output gimple statement.
|
|
|
181
|
|
|
182 Note that the above methods also have variants prefixed with
|
|
|
183 @code{_loc}, such as @code{dump_printf_loc}, which are similar except
|
|
131
|
184 they also output the source location information. The @code{_loc} variants
|
|
|
185 take a @code{const dump_location_t &}. This class can be constructed from
|
|
|
186 a @code{gimple *} or from a @code{rtx_insn *}, and so callers can pass
|
|
|
187 a @code{gimple *} or a @code{rtx_insn *} as the @code{_loc} argument.
|
|
|
188 The @code{dump_location_t} constructor will extract the source location
|
|
|
189 from the statement or instruction, along with the profile count, and
|
|
|
190 the location in GCC's own source code (or the plugin) from which the dump
|
|
|
191 call was emitted. Only the source location is currently used.
|
|
|
192 There is also a @code{dump_user_location_t} class, capturing the
|
|
|
193 source location and profile count, but not the dump emission location,
|
|
|
194 so that locations in the user's code can be passed around. This
|
|
|
195 can also be constructed from a @code{gimple *} and from a @code{rtx_insn *},
|
|
|
196 and it too can be passed as the @code{_loc} argument.
|
|
111
|
197
|
|
|
198 @end ftable
|
|
|
199
|
|
|
200 @node Dump examples
|
|
|
201 @subsection Dump examples
|
|
|
202 @cindex dump examples
|
|
|
203
|
|
|
204 @smallexample
|
|
|
205 gcc -O3 -fopt-info-missed=missed.all
|
|
|
206 @end smallexample
|
|
|
207
|
|
|
208 outputs missed optimization report from all the passes into
|
|
|
209 @file{missed.all}.
|
|
|
210
|
|
|
211 As another example,
|
|
|
212 @smallexample
|
|
|
213 gcc -O3 -fopt-info-inline-optimized-missed=inline.txt
|
|
|
214 @end smallexample
|
|
|
215
|
|
|
216 will output information about missed optimizations as well as
|
|
|
217 optimized locations from all the inlining passes into
|
|
|
218 @file{inline.txt}.
|
|
|
219
|
|
|
220 If the @var{filename} is provided, then the dumps from all the
|
|
|
221 applicable optimizations are concatenated into the @file{filename}.
|
|
|
222 Otherwise the dump is output onto @file{stderr}. If @var{options} is
|
|
|
223 omitted, it defaults to @option{optimized-optall}, which means dump
|
|
|
224 all information about successful optimizations from all the passes.
|
|
|
225 In the following example, the optimization information is output on
|
|
|
226 to @file{stderr}.
|
|
|
227
|
|
|
228 @smallexample
|
|
|
229 gcc -O3 -fopt-info
|
|
|
230 @end smallexample
|
|
|
231
|
|
|
232 Note that @option{-fopt-info-vec-missed} behaves the same as
|
|
|
233 @option{-fopt-info-missed-vec}. The order of the optimization group
|
|
|
234 names and message types listed after @option{-fopt-info} does not matter.
|
|
|
235
|
|
|
236 As another example, consider
|
|
|
237
|
|
|
238 @smallexample
|
|
|
239 gcc -fopt-info-vec-missed=vec.miss -fopt-info-loop-optimized=loop.opt
|
|
|
240 @end smallexample
|
|
|
241
|
|
|
242 Here the two output file names @file{vec.miss} and @file{loop.opt} are
|
|
|
243 in conflict since only one output file is allowed. In this case, only
|
|
|
244 the first option takes effect and the subsequent options are
|
|
|
245 ignored. Thus only the @file{vec.miss} is produced which containts
|
|
|
246 dumps from the vectorizer about missed opportunities.
|
