2013-12-19 * Makefile.in: Add optinfo.texi. * doc/optinfo.texi: New documentation for optimization info. * doc/passes.texi: Add new node. Index: Makefile.in =================================================================== --- Makefile.in (revision 206105) +++ Makefile.in (working copy) @@ -2807,7 +2807,7 @@ TEXI_GCCINT_FILES = gccint.texi gcc-common.texi gc configfiles.texi collect2.texi headerdirs.texi funding.texi \ gnu.texi gpl_v3.texi fdl.texi contrib.texi languages.texi \ sourcebuild.texi gty.texi libgcc.texi cfg.texi tree-ssa.texi \ - loop.texi generic.texi gimple.texi plugins.texi + loop.texi generic.texi gimple.texi plugins.texi optinfo.texi TEXI_GCCINSTALL_FILES = install.texi install-old.texi fdl.texi \ gcc-common.texi gcc-vers.texi Index: doc/optinfo.texi =================================================================== --- doc/optinfo.texi (revision 0) +++ doc/optinfo.texi (revision 0) @@ -0,0 +1,208 @@ +@c Copyright (C) 2013 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 output verbosity:: How much information to dump. +* Dump output files and streams:: Output file names and streams. +* 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 registration, an optimization pass can select +its optimization group (@pxref{Optimization groups}). Then the +optimization information from the entire group 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}. + +In general, a pass need not worry about 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_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{-all}. + +@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 output files and streams +@subsection Dump output 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. + +@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 also have variants prefixed with @code{_loc}, such +as @code{dump_printf_loc}, which are similar except they also output +the source location information. + +@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{all-all}, which means dump all +available optimization info from all the passes. In the following +example, all optimization info 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}. + +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. Index: doc/passes.texi =================================================================== --- doc/passes.texi (revision 206105) +++ doc/passes.texi (working copy) @@ -9,6 +9,7 @@ @cindex passes and files of the compiler @cindex files and passes of the compiler @cindex compiler passes and files +@cindex pass dumps This chapter is dedicated to giving an overview of the optimization and code generation passes of the compiler. In the process, it describes @@ -22,6 +23,7 @@ where near complete. * Pass manager:: Sequencing the optimization passes. * Tree SSA passes:: Optimizations on a high-level representation. * RTL passes:: Optimizations on a low-level representation. +* Optimization info:: Dumping optimization information from passes. @end menu @node Parsing pass @@ -975,3 +977,7 @@ symbol table format, and @file{vmsdbgout.c} for VM format. @end itemize + +@node Optimization info +@section Optimization info +@include optinfo.texi