]>
Commit | Line | Data |
---|---|---|
7adcbafe | 1 | @c Copyright (C) 2013-2022 Free Software Foundation, Inc. |
b1055be0 SS |
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. | |
b1055be0 | 15 | * Dump files and streams:: Dump output file names and streams. |
69479ebd | 16 | * Dump output verbosity:: How much information to dump. |
b1055be0 SS |
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 | |
e53b6e56 | 27 | @file{passes.cc}. During the registration, an optimization pass can |
b1055be0 SS |
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 | ||
fd2b8c8b TS |
62 | @item OPTGROUP_OMP |
63 | OMP (Offloading and Multi Processing) passes. Enabled by | |
64 | @option{-omp}. | |
56b1c60e | 65 | |
b1055be0 SS |
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 | |
d03958cf | 73 | All optimization passes. Enabled by @option{-optall}. |
b1055be0 SS |
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 | ||
e53b6e56 | 158 | Consider the following example from @file{loop-unroll.cc} where an |
b1055be0 SS |
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; | |
4f5b9c80 | 171 | dump_printf_loc (report_flags, insn, |
b1055be0 SS |
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 | |
4f5b9c80 DM |
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. | |
b1055be0 SS |
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 | |
b4a3af07 SE |
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}. | |
b1055be0 SS |
227 | |
228 | @smallexample | |
229 | gcc -O3 -fopt-info | |
230 | @end smallexample | |
231 | ||
232 | Note that @option{-fopt-info-vec-missed} behaves the same as | |
b4a3af07 SE |
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. | |
b1055be0 SS |
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. |