gcc/doc/optinfo.texi

   1 @c Copyright (C) 2013-2024 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.