247 lines
8.7 KiB
Plaintext
247 lines
8.7 KiB
Plaintext
@c Copyright (C) 2013-2021 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.c}. 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.c} 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.
|