This section is describes dump infrastructure which is common to both pass dumps as well as optimization dumps. The goal for this infrastructure is to provide both gcc developers and users detailed information about various compiler transformations and optimizations.

Dump setup
----------

A dump_manager class is defined in dumpfile.h. Various passes register dumping pass-specific information via dump_register in passes.c. During the registration, an optimization pass can select its optimization group (see Optimization groups). After that optimization information corresponding to the entire group (presumably from multiple passes) can be output via command-line switches. Note that if a pass does not fit into any of the pre-defined groups, it can select OPTGROUP_NONE.

Note that in general, a pass need not know its dump output file name, whether certain flags are enabled, etc. However, for legacy reasons, passes could also call dump_begin which returns a stream in case the particular pass has optimization dumps enabled. A pass could call dump_end when the dump has ended. These methods should go away once all the passes are converted to use the new dump infrastructure.

The recommended way to setup the dump output is via dump_start and dump_end.

Optimization groups
-------------------

The optimization passes are grouped into several categories. Currently defined categories in dumpfile.h are

OPTGROUP_IPA
     IPA optimization passes. Enabled by -ipa

OPTGROUP_LOOP
     Loop optimization passes. Enabled by -loop.

OPTGROUP_INLINE
     Inlining passes. Enabled by -inline.

OPTGROUP_OMP
     OMP (Offloading and Multi Processing) passes. Enabled by -omp.

OPTGROUP_VEC
     Vectorization passes. Enabled by -vec.

OPTGROUP_OTHER
     All other optimization passes which do not fall into one of the above.

OPTGROUP_ALL
     All optimization passes. Enabled by -optall.

By using groups a user could selectively enable optimization information only for a group of passes. By default, the optimization information for all the passes is dumped.

Dump files and streams
----------------------

There are two separate output streams available for outputting optimization information from passes. Note that both these streams accept stderr and stdout as valid streams and thus it is possible to dump output to standard output or error. This is specially handy for outputting all available information in a single file by redirecting stderr.

pstream
     This stream is for pass-specific dump output. For example, -fdump-tree-vect=foo.v dumps tree vectorization pass output into the given file name foo.v. If the file name is not provided, the default file name is based on the source file and pass number. Note that one could also use special file names stdout and stderr for dumping to standard output and standard error respectively.

alt_stream
     This steam is used for printing optimization specific output in response to the -fopt-info. Again a file name can be given. If the file name is not given, it defaults to stderr.

Dump output verbosity
---------------------

The dump verbosity has the following options

optimized
     Print information when an optimization is successfully applied. It is up to a pass to decide which information is relevant. For example, the vectorizer passes print the source location of loops which got successfully vectorized.

missed
     Print information about missed optimizations. Individual passes control which information to include in the output. For example,

          gcc -O2 -ftree-vectorize -fopt-info-vec-missed

     will print information about missed optimization opportunities from vectorization passes on stderr.

note
     Print verbose information about optimizations, such as certain transformations, more detailed messages about decisions etc.

all
     Print detailed optimization information. This includes OPTIMIZED, MISSED, and NOTE.

Dump types
----------

dump_printf

     This is a generic method for doing formatted output. It takes an additional argument dump_kind which signifies the type of dump. This method outputs information only when the dumps are enabled for this particular dump_kind. Note that the caller doesn't need to know if the particular dump is enabled or not, or even the file name. The caller only needs to decide which dump output information is relevant, and under what conditions. This determines the associated flags.

     Consider the following example from loop-unroll.c where an informative message about a loop (along with its location) is printed when any of the following flags is enabled

       - optimization messages

       - RTL dumps

       - detailed dumps

          int report_flags = MSG_OPTIMIZED_LOCATIONS | TDF_RTL | TDF_DETAILS;
          dump_printf_loc (report_flags, locus,
                           "loop turned into non-loop; it never loops.\n");

dump_basic_block
     Output basic block.

dump_generic_expr
     Output generic expression.

dump_gimple_stmt
     Output gimple statement.

     Note that the above methods also have variants prefixed with _loc, such as dump_printf_loc, which are similar except they also output the source location information.

Dump examples
-------------

     gcc -O3 -fopt-info-missed=missed.all

outputs missed optimization report from all the passes into missed.all.

As another example,

     gcc -O3 -fopt-info-inline-optimized-missed=inline.txt

will output information about missed optimizations as well as optimized locations from all the inlining passes into inline.txt.

If the FILENAME is provided, then the dumps from all the applicable optimizations are concatenated into the filename. Otherwise the dump is output onto stderr. If OPTIONS is omitted, it defaults to all-all, which means dump all available optimization info from all the passes. In the following example, all optimization info is output on to stderr.

     gcc -O3 -fopt-info

Note that -fopt-info-vec-missed behaves the same as -fopt-info-missed-vec.

As another example, consider

     gcc -fopt-info-vec-missed=vec.miss -fopt-info-loop-optimized=loop.opt

Here the two output file names vec.miss and loop.opt are in conflict since only one output file is allowed. In this case, only the first option takes effect and the subsequent options are ignored. Thus only the vec.miss is produced which containts dumps from the vectorizer about missed opportunities.