Mercurial > hg > CbC > CbC_gcc
diff gcc/doc/optinfo.texi @ 111:04ced10e8804
gcc 7
author | kono |
---|---|
date | Fri, 27 Oct 2017 22:46:09 +0900 |
parents | |
children | 84e7813d76e9 |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/gcc/doc/optinfo.texi Fri Oct 27 22:46:09 2017 +0900 @@ -0,0 +1,234 @@ +@c Copyright (C) 2013-2017 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, locus, + "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. + +@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.