gcc/doc/optinfo.texi

   1 @c Copyright (C) 2013 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 output verbosity::              How much information to dump.
  16 * Dump files and streams::             Dump output file names and streams.
  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.