1 @c Copyright (C) 2013-2018 Free Software Foundation, Inc.
2 @c This is part of the GCC manual.
3 @c For copying conditions, see the file gcc.texi.
5 @cindex optimization dumps
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.
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.
22 @subsection Dump setup
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}.
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
42 The recommended way to setup the dump output is via @code{dump_start}
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
54 IPA optimization passes. Enabled by @option{-ipa}
57 Loop optimization passes. Enabled by @option{-loop}.
60 Inlining passes. Enabled by @option{-inline}.
63 OMP (Offloading and Multi Processing) passes. Enabled by
67 Vectorization passes. Enabled by @option{-vec}.
70 All other optimization passes which do not fall into one of the above.
73 All optimization passes. Enabled by @option{-optall}.
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.
81 @node Dump files and streams
82 @subsection Dump files and streams
83 @cindex optimization info file names
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}.
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
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}.
108 @node Dump output verbosity
109 @subsection Dump output verbosity
110 @cindex dump verbosity
112 The dump verbosity has the following options
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.
122 Print information about missed optimizations. Individual passes
123 control which information to include in the output. For example,
126 gcc -O2 -ftree-vectorize -fopt-info-vec-missed
129 will print information about missed optimization opportunities from
130 vectorization passes on stderr.
133 Print verbose information about optimizations, such as certain
134 transformations, more detailed messages about decisions etc.
137 Print detailed optimization information. This includes
138 @var{optimized}, @var{missed}, and @var{note}.
142 @subsection Dump types
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.
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
163 @item optimization messages
170 int report_flags = MSG_OPTIMIZED_LOCATIONS | TDF_RTL | TDF_DETAILS;
171 dump_printf_loc (report_flags, locus,
172 "loop turned into non-loop; it never loops.\n");
175 @item dump_basic_block
177 @item dump_generic_expr
178 Output generic expression.
179 @item dump_gimple_stmt
180 Output gimple statement.
182 Note that the above methods also have variants prefixed with
183 @code{_loc}, such as @code{dump_printf_loc}, which are similar except
184 they also output the source location information.
189 @subsection Dump examples
190 @cindex dump examples
193 gcc -O3 -fopt-info-missed=missed.all
196 outputs missed optimization report from all the passes into
201 gcc -O3 -fopt-info-inline-optimized-missed=inline.txt
204 will output information about missed optimizations as well as
205 optimized locations from all the inlining passes into
208 If the @var{filename} is provided, then the dumps from all the
209 applicable optimizations are concatenated into the @file{filename}.
210 Otherwise the dump is output onto @file{stderr}. If @var{options} is
211 omitted, it defaults to @option{optimized-optall}, which means dump
212 all information about successful optimizations from all the passes.
213 In the following example, the optimization information is output on
220 Note that @option{-fopt-info-vec-missed} behaves the same as
221 @option{-fopt-info-missed-vec}. The order of the optimization group
222 names and message types listed after @option{-fopt-info} does not matter.
224 As another example, consider
227 gcc -fopt-info-vec-missed=vec.miss -fopt-info-loop-optimized=loop.opt
230 Here the two output file names @file{vec.miss} and @file{loop.opt} are
231 in conflict since only one output file is allowed. In this case, only
232 the first option takes effect and the subsequent options are
233 ignored. Thus only the @file{vec.miss} is produced which containts
234 dumps from the vectorizer about missed opportunities.