gcc/doc/optinfo.texi

@c Copyright (C) 2013-2022 Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.

@cindex optimization dumps

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.

@menu
* Dump setup::                         Setup of optimization dumps.
* Optimization groups::                Groups made up of optimization passes.
* Dump files and streams::             Dump output file names and streams.
* Dump output verbosity::              How much information to dump.
* Dump types::                         Various types of dump functions.
* Dump examples::                      Sample usage.
@end menu

@node Dump setup
@subsection Dump setup
@cindex dump setup

A dump_manager class is defined in @file{dumpfile.h}. Various passes
register dumping pass-specific information via @code{dump_register} in
@file{passes.cc}. During the registration, an optimization pass can
select its optimization group (@pxref{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 @code{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 @code{dump_begin} which returns a stream in
case the particular pass has optimization dumps enabled. A pass could
call @code{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 @code{dump_start}
and @code{dump_end}.

@node Optimization groups
@subsection Optimization groups
@cindex optimization groups
The optimization passes are grouped into several categories. Currently
defined categories in @file{dumpfile.h} are

@ftable @code

@item OPTGROUP_IPA
IPA optimization passes. Enabled by @option{-ipa}

@item OPTGROUP_LOOP
Loop optimization passes. Enabled by @option{-loop}.

@item OPTGROUP_INLINE
Inlining passes. Enabled by @option{-inline}.

@item OPTGROUP_OMP
OMP (Offloading and Multi Processing) passes. Enabled by
@option{-omp}.

@item OPTGROUP_VEC
Vectorization passes. Enabled by @option{-vec}.

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

@item OPTGROUP_ALL
All optimization passes. Enabled by @option{-optall}.

@end ftable

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.

@node Dump files and streams
@subsection Dump files and streams
@cindex optimization info file names

There are two separate output streams available for outputting
optimization information from passes. Note that both these streams
accept @code{stderr} and @code{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 @code{stderr}.

@table @code
@item @code{pstream}
This stream is for pass-specific dump output. For example,
@option{-fdump-tree-vect=foo.v} dumps tree vectorization pass output
into the given file name @file{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 @code{stdout} and
@code{stderr} for dumping to standard output and standard error
respectively.

@item @code{alt_stream}
This steam is used for printing optimization specific output in
response to the @option{-fopt-info}. Again a file name can be given. If
the file name is not given, it defaults to @code{stderr}.
@end table

@node Dump output verbosity
@subsection Dump output verbosity
@cindex dump verbosity

The dump verbosity has the following options

@table @samp
@item 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.

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

@smallexample
gcc -O2 -ftree-vectorize -fopt-info-vec-missed
@end smallexample

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

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

@item all
Print detailed optimization information. This includes
@var{optimized}, @var{missed}, and @var{note}.
@end table

@node Dump types
@subsection Dump types
@cindex dump types

@ftable @code

@item dump_printf

This is a generic method for doing formatted output. It takes an
additional argument @code{dump_kind} which signifies the type of
dump. This method outputs information only when the dumps are enabled
for this particular @code{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 @file{loop-unroll.cc} where an
informative message about a loop (along with its location) is printed
when any of the following flags is enabled
@itemize @minus

@item optimization messages
@item RTL dumps
@item detailed dumps

@end itemize

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

@item dump_basic_block
Output basic block.
@item dump_generic_expr
Output generic expression.
@item dump_gimple_stmt
Output gimple statement.

Note that the above methods also have variants prefixed with
@code{_loc}, such as @code{dump_printf_loc}, which are similar except
they also output the source location information.  The @code{_loc} variants
take a @code{const dump_location_t &}.  This class can be constructed from
a @code{gimple *} or from a @code{rtx_insn *}, and so callers can pass
a @code{gimple *} or a @code{rtx_insn *} as the @code{_loc} argument.
The @code{dump_location_t} constructor will extract the source location
from the statement or instruction, along with the profile count, and
the location in GCC's own source code (or the plugin) from which the dump
call was emitted.  Only the source location is currently used.
There is also a @code{dump_user_location_t} class, capturing the
source location and profile count, but not the dump emission location,
so that locations in the user's code can be passed around.  This
can also be constructed from a @code{gimple *} and from a @code{rtx_insn *},
and it too can be passed as the @code{_loc} argument.

@end ftable

@node Dump examples
@subsection Dump examples
@cindex dump examples

@smallexample
gcc -O3 -fopt-info-missed=missed.all
@end smallexample

outputs missed optimization report from all the passes into
@file{missed.all}.

As another example,
@smallexample
gcc -O3 -fopt-info-inline-optimized-missed=inline.txt
@end smallexample

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

If the @var{filename} is provided, then the dumps from all the
applicable optimizations are concatenated into the @file{filename}.
Otherwise the dump is output onto @file{stderr}. If @var{options} is
omitted, it defaults to @option{optimized-optall}, which means dump
all information about successful optimizations from all the passes.
In the following example, the optimization information is output on
to @file{stderr}.

@smallexample
gcc -O3 -fopt-info
@end smallexample

Note that @option{-fopt-info-vec-missed} behaves the same as
@option{-fopt-info-missed-vec}.  The order of the optimization group
names and message types listed after @option{-fopt-info} does not matter.

As another example, consider

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

Here the two output file names @file{vec.miss} and @file{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 @file{vec.miss} is produced which containts
dumps from the vectorizer about missed opportunities.