Merge branch 'vendor/GCC50' - gcc 5.0 snapshot 1 FEB 2015
[dragonfly.git] / contrib / gcc-5.0 / gcc / doc / optinfo.texi
1 @c Copyright (C) 2013-2015 Free Software Foundation, Inc.
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_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.