Mercurial > hg > CbC > CbC_gcc

comparison gcc/doc/optinfo.texi @ 111:04ced10e8804

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
gcc 7
author kono
date Fri, 27 Oct 2017 22:46:09 +0900
parents
children 84e7813d76e9
comparison
equal deleted inserted replaced
68:561a7518be6b 111:04ced10e8804
1 @c Copyright (C) 2013-2017 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_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;
171 dump_printf_loc (report_flags, locus,
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
184 they also output the source location information.
185
186 @end ftable
187
188 @node Dump examples
189 @subsection Dump examples
190 @cindex dump examples
191
192 @smallexample
193 gcc -O3 -fopt-info-missed=missed.all
194 @end smallexample
195
196 outputs missed optimization report from all the passes into
197 @file{missed.all}.
198
199 As another example,
200 @smallexample
201 gcc -O3 -fopt-info-inline-optimized-missed=inline.txt
202 @end smallexample
203
204 will output information about missed optimizations as well as
205 optimized locations from all the inlining passes into
206 @file{inline.txt}.
207
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
214 to @file{stderr}.
215
216 @smallexample
217 gcc -O3 -fopt-info
218 @end smallexample
219
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.
223
224 As another example, consider
225
226 @smallexample
227 gcc -fopt-info-vec-missed=vec.miss -fopt-info-loop-optimized=loop.opt
228 @end smallexample
229
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.