]>
Commit | Line | Data |
---|---|---|
23a5b65a | 1 | @c Copyright (C) 2013-2014 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. | |
15 | * Dump output verbosity:: How much information to dump. | |
16 | * Dump files and streams:: Dump output file names and streams. | |
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_VEC | |
63 | Vectorization passes. Enabled by @option{-vec}. | |
64 | ||
65 | @item OPTGROUP_OTHER | |
66 | All other optimization passes which do not fall into one of the above. | |
67 | ||
68 | @item OPTGROUP_ALL | |
69 | All optimization passes. Enabled by @option{-all}. | |
70 | ||
71 | @end ftable | |
72 | ||
73 | By using groups a user could selectively enable optimization | |
74 | information only for a group of passes. By default, the optimization | |
75 | information for all the passes is dumped. | |
76 | ||
77 | @node Dump files and streams | |
78 | @subsection Dump files and streams | |
79 | @cindex optimization info file names | |
80 | ||
81 | There are two separate output streams available for outputting | |
82 | optimization information from passes. Note that both these streams | |
83 | accept @code{stderr} and @code{stdout} as valid streams and thus it is | |
84 | possible to dump output to standard output or error. This is specially | |
85 | handy for outputting all available information in a single file by | |
86 | redirecting @code{stderr}. | |
87 | ||
88 | @table @code | |
89 | @item @code{pstream} | |
90 | This stream is for pass-specific dump output. For example, | |
91 | @option{-fdump-tree-vect=foo.v} dumps tree vectorization pass output | |
92 | into the given file name @file{foo.v}. If the file name is not provided, | |
93 | the default file name is based on the source file and pass number. Note | |
94 | that one could also use special file names @code{stdout} and | |
95 | @code{stderr} for dumping to standard output and standard error | |
96 | respectively. | |
97 | ||
98 | @item @code{alt_stream} | |
99 | This steam is used for printing optimization specific output in | |
100 | response to the @option{-fopt-info}. Again a file name can be given. If | |
101 | the file name is not given, it defaults to @code{stderr}. | |
102 | @end table | |
103 | ||
104 | @node Dump output verbosity | |
105 | @subsection Dump output verbosity | |
106 | @cindex dump verbosity | |
107 | ||
108 | The dump verbosity has the following options | |
109 | ||
110 | @table @samp | |
111 | @item optimized | |
112 | Print information when an optimization is successfully applied. It is | |
113 | up to a pass to decide which information is relevant. For example, the | |
114 | vectorizer passes print the source location of loops which got | |
115 | successfully vectorized. | |
116 | ||
117 | @item missed | |
118 | Print information about missed optimizations. Individual passes | |
119 | control which information to include in the output. For example, | |
120 | ||
121 | @smallexample | |
122 | gcc -O2 -ftree-vectorize -fopt-info-vec-missed | |
123 | @end smallexample | |
124 | ||
125 | will print information about missed optimization opportunities from | |
126 | vectorization passes on stderr. | |
127 | ||
128 | @item note | |
129 | Print verbose information about optimizations, such as certain | |
130 | transformations, more detailed messages about decisions etc. | |
131 | ||
132 | @item all | |
133 | Print detailed optimization information. This includes | |
134 | @var{optimized}, @var{missed}, and @var{note}. | |
135 | @end table | |
136 | ||
137 | @node Dump types | |
138 | @subsection Dump types | |
139 | @cindex dump types | |
140 | ||
141 | @ftable @code | |
142 | ||
143 | @item dump_printf | |
144 | ||
145 | This is a generic method for doing formatted output. It takes an | |
146 | additional argument @code{dump_kind} which signifies the type of | |
147 | dump. This method outputs information only when the dumps are enabled | |
148 | for this particular @code{dump_kind}. Note that the caller doesn't | |
149 | need to know if the particular dump is enabled or not, or even the | |
150 | file name. The caller only needs to decide which dump output | |
151 | information is relevant, and under what conditions. This determines | |
152 | the associated flags. | |
153 | ||
154 | Consider the following example from @file{loop-unroll.c} where an | |
155 | informative message about a loop (along with its location) is printed | |
156 | when any of the following flags is enabled | |
157 | @itemize @minus | |
158 | ||
159 | @item optimization messages | |
160 | @item RTL dumps | |
161 | @item detailed dumps | |
162 | ||
163 | @end itemize | |
164 | ||
165 | @example | |
166 | int report_flags = MSG_OPTIMIZED_LOCATIONS | TDF_RTL | TDF_DETAILS; | |
167 | dump_printf_loc (report_flags, locus, | |
168 | "loop turned into non-loop; it never loops.\n"); | |
169 | @end example | |
170 | ||
171 | @item dump_basic_block | |
172 | Output basic block. | |
173 | @item dump_generic_expr | |
174 | Output generic expression. | |
175 | @item dump_gimple_stmt | |
176 | Output gimple statement. | |
177 | ||
178 | Note that the above methods also have variants prefixed with | |
179 | @code{_loc}, such as @code{dump_printf_loc}, which are similar except | |
180 | they also output the source location information. | |
181 | ||
182 | @end ftable | |
183 | ||
184 | @node Dump examples | |
185 | @subsection Dump examples | |
186 | @cindex dump examples | |
187 | ||
188 | @smallexample | |
189 | gcc -O3 -fopt-info-missed=missed.all | |
190 | @end smallexample | |
191 | ||
192 | outputs missed optimization report from all the passes into | |
193 | @file{missed.all}. | |
194 | ||
195 | As another example, | |
196 | @smallexample | |
197 | gcc -O3 -fopt-info-inline-optimized-missed=inline.txt | |
198 | @end smallexample | |
199 | ||
200 | will output information about missed optimizations as well as | |
201 | optimized locations from all the inlining passes into | |
202 | @file{inline.txt}. | |
203 | ||
204 | If the @var{filename} is provided, then the dumps from all the | |
205 | applicable optimizations are concatenated into the @file{filename}. | |
206 | Otherwise the dump is output onto @file{stderr}. If @var{options} is | |
207 | omitted, it defaults to @option{all-all}, which means dump all | |
208 | available optimization info from all the passes. In the following | |
209 | example, all optimization info is output on to @file{stderr}. | |
210 | ||
211 | @smallexample | |
212 | gcc -O3 -fopt-info | |
213 | @end smallexample | |
214 | ||
215 | Note that @option{-fopt-info-vec-missed} behaves the same as | |
216 | @option{-fopt-info-missed-vec}. | |
217 | ||
218 | As another example, consider | |
219 | ||
220 | @smallexample | |
221 | gcc -fopt-info-vec-missed=vec.miss -fopt-info-loop-optimized=loop.opt | |
222 | @end smallexample | |
223 | ||
224 | Here the two output file names @file{vec.miss} and @file{loop.opt} are | |
225 | in conflict since only one output file is allowed. In this case, only | |
226 | the first option takes effect and the subsequent options are | |
227 | ignored. Thus only the @file{vec.miss} is produced which containts | |
228 | dumps from the vectorizer about missed opportunities. |