| 1 |
@c Copyright (C) 2013-2025 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.cc}. 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 stream 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.cc} 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, insn, |
| 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. 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. |
| 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 |
| 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}. |
| 227 |
|
| 228 |
@smallexample |
| 229 |
gcc -O3 -fopt-info |
| 230 |
@end smallexample |
| 231 |
|
| 232 |
Note that @option{-fopt-info-vec-missed} behaves the same as |
| 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. |
| 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. |