1*ec02198aSmrg@c Copyright (C) 2013-2020 Free Software Foundation, Inc. 210d565efSmrg@c This is part of the GCC manual. 310d565efSmrg@c For copying conditions, see the file gcc.texi. 410d565efSmrg 510d565efSmrg@cindex optimization dumps 610d565efSmrg 710d565efSmrgThis section is describes dump infrastructure which is common to both 810d565efSmrgpass dumps as well as optimization dumps. The goal for this 910d565efSmrginfrastructure is to provide both gcc developers and users detailed 1010d565efSmrginformation about various compiler transformations and optimizations. 1110d565efSmrg 1210d565efSmrg@menu 1310d565efSmrg* Dump setup:: Setup of optimization dumps. 1410d565efSmrg* Optimization groups:: Groups made up of optimization passes. 1510d565efSmrg* Dump files and streams:: Dump output file names and streams. 1610d565efSmrg* Dump output verbosity:: How much information to dump. 1710d565efSmrg* Dump types:: Various types of dump functions. 1810d565efSmrg* Dump examples:: Sample usage. 1910d565efSmrg@end menu 2010d565efSmrg 2110d565efSmrg@node Dump setup 2210d565efSmrg@subsection Dump setup 2310d565efSmrg@cindex dump setup 2410d565efSmrg 2510d565efSmrgA dump_manager class is defined in @file{dumpfile.h}. Various passes 2610d565efSmrgregister dumping pass-specific information via @code{dump_register} in 2710d565efSmrg@file{passes.c}. During the registration, an optimization pass can 2810d565efSmrgselect its optimization group (@pxref{Optimization groups}). After 2910d565efSmrgthat optimization information corresponding to the entire group 3010d565efSmrg(presumably from multiple passes) can be output via command-line 3110d565efSmrgswitches. Note that if a pass does not fit into any of the pre-defined 3210d565efSmrggroups, it can select @code{OPTGROUP_NONE}. 3310d565efSmrg 3410d565efSmrgNote that in general, a pass need not know its dump output file name, 3510d565efSmrgwhether certain flags are enabled, etc. However, for legacy reasons, 3610d565efSmrgpasses could also call @code{dump_begin} which returns a stream in 3710d565efSmrgcase the particular pass has optimization dumps enabled. A pass could 3810d565efSmrgcall @code{dump_end} when the dump has ended. These methods should go 3910d565efSmrgaway once all the passes are converted to use the new dump 4010d565efSmrginfrastructure. 4110d565efSmrg 4210d565efSmrgThe recommended way to setup the dump output is via @code{dump_start} 4310d565efSmrgand @code{dump_end}. 4410d565efSmrg 4510d565efSmrg@node Optimization groups 4610d565efSmrg@subsection Optimization groups 4710d565efSmrg@cindex optimization groups 4810d565efSmrgThe optimization passes are grouped into several categories. Currently 4910d565efSmrgdefined categories in @file{dumpfile.h} are 5010d565efSmrg 5110d565efSmrg@ftable @code 5210d565efSmrg 5310d565efSmrg@item OPTGROUP_IPA 5410d565efSmrgIPA optimization passes. Enabled by @option{-ipa} 5510d565efSmrg 5610d565efSmrg@item OPTGROUP_LOOP 5710d565efSmrgLoop optimization passes. Enabled by @option{-loop}. 5810d565efSmrg 5910d565efSmrg@item OPTGROUP_INLINE 6010d565efSmrgInlining passes. Enabled by @option{-inline}. 6110d565efSmrg 6210d565efSmrg@item OPTGROUP_OMP 6310d565efSmrgOMP (Offloading and Multi Processing) passes. Enabled by 6410d565efSmrg@option{-omp}. 6510d565efSmrg 6610d565efSmrg@item OPTGROUP_VEC 6710d565efSmrgVectorization passes. Enabled by @option{-vec}. 6810d565efSmrg 6910d565efSmrg@item OPTGROUP_OTHER 7010d565efSmrgAll other optimization passes which do not fall into one of the above. 7110d565efSmrg 7210d565efSmrg@item OPTGROUP_ALL 7310d565efSmrgAll optimization passes. Enabled by @option{-optall}. 7410d565efSmrg 7510d565efSmrg@end ftable 7610d565efSmrg 7710d565efSmrgBy using groups a user could selectively enable optimization 7810d565efSmrginformation only for a group of passes. By default, the optimization 7910d565efSmrginformation for all the passes is dumped. 8010d565efSmrg 8110d565efSmrg@node Dump files and streams 8210d565efSmrg@subsection Dump files and streams 8310d565efSmrg@cindex optimization info file names 8410d565efSmrg 8510d565efSmrgThere are two separate output streams available for outputting 8610d565efSmrgoptimization information from passes. Note that both these streams 8710d565efSmrgaccept @code{stderr} and @code{stdout} as valid streams and thus it is 8810d565efSmrgpossible to dump output to standard output or error. This is specially 8910d565efSmrghandy for outputting all available information in a single file by 9010d565efSmrgredirecting @code{stderr}. 9110d565efSmrg 9210d565efSmrg@table @code 9310d565efSmrg@item @code{pstream} 9410d565efSmrgThis stream is for pass-specific dump output. For example, 9510d565efSmrg@option{-fdump-tree-vect=foo.v} dumps tree vectorization pass output 9610d565efSmrginto the given file name @file{foo.v}. If the file name is not provided, 9710d565efSmrgthe default file name is based on the source file and pass number. Note 9810d565efSmrgthat one could also use special file names @code{stdout} and 9910d565efSmrg@code{stderr} for dumping to standard output and standard error 10010d565efSmrgrespectively. 10110d565efSmrg 10210d565efSmrg@item @code{alt_stream} 10310d565efSmrgThis steam is used for printing optimization specific output in 10410d565efSmrgresponse to the @option{-fopt-info}. Again a file name can be given. If 10510d565efSmrgthe file name is not given, it defaults to @code{stderr}. 10610d565efSmrg@end table 10710d565efSmrg 10810d565efSmrg@node Dump output verbosity 10910d565efSmrg@subsection Dump output verbosity 11010d565efSmrg@cindex dump verbosity 11110d565efSmrg 11210d565efSmrgThe dump verbosity has the following options 11310d565efSmrg 11410d565efSmrg@table @samp 11510d565efSmrg@item optimized 11610d565efSmrgPrint information when an optimization is successfully applied. It is 11710d565efSmrgup to a pass to decide which information is relevant. For example, the 11810d565efSmrgvectorizer passes print the source location of loops which got 11910d565efSmrgsuccessfully vectorized. 12010d565efSmrg 12110d565efSmrg@item missed 12210d565efSmrgPrint information about missed optimizations. Individual passes 12310d565efSmrgcontrol which information to include in the output. For example, 12410d565efSmrg 12510d565efSmrg@smallexample 12610d565efSmrggcc -O2 -ftree-vectorize -fopt-info-vec-missed 12710d565efSmrg@end smallexample 12810d565efSmrg 12910d565efSmrgwill print information about missed optimization opportunities from 13010d565efSmrgvectorization passes on stderr. 13110d565efSmrg 13210d565efSmrg@item note 13310d565efSmrgPrint verbose information about optimizations, such as certain 13410d565efSmrgtransformations, more detailed messages about decisions etc. 13510d565efSmrg 13610d565efSmrg@item all 13710d565efSmrgPrint detailed optimization information. This includes 13810d565efSmrg@var{optimized}, @var{missed}, and @var{note}. 13910d565efSmrg@end table 14010d565efSmrg 14110d565efSmrg@node Dump types 14210d565efSmrg@subsection Dump types 14310d565efSmrg@cindex dump types 14410d565efSmrg 14510d565efSmrg@ftable @code 14610d565efSmrg 14710d565efSmrg@item dump_printf 14810d565efSmrg 14910d565efSmrgThis is a generic method for doing formatted output. It takes an 15010d565efSmrgadditional argument @code{dump_kind} which signifies the type of 15110d565efSmrgdump. This method outputs information only when the dumps are enabled 15210d565efSmrgfor this particular @code{dump_kind}. Note that the caller doesn't 15310d565efSmrgneed to know if the particular dump is enabled or not, or even the 15410d565efSmrgfile name. The caller only needs to decide which dump output 15510d565efSmrginformation is relevant, and under what conditions. This determines 15610d565efSmrgthe associated flags. 15710d565efSmrg 15810d565efSmrgConsider the following example from @file{loop-unroll.c} where an 15910d565efSmrginformative message about a loop (along with its location) is printed 16010d565efSmrgwhen any of the following flags is enabled 16110d565efSmrg@itemize @minus 16210d565efSmrg 16310d565efSmrg@item optimization messages 16410d565efSmrg@item RTL dumps 16510d565efSmrg@item detailed dumps 16610d565efSmrg 16710d565efSmrg@end itemize 16810d565efSmrg 16910d565efSmrg@example 17010d565efSmrgint report_flags = MSG_OPTIMIZED_LOCATIONS | TDF_RTL | TDF_DETAILS; 1710fc04c29Smrgdump_printf_loc (report_flags, insn, 17210d565efSmrg "loop turned into non-loop; it never loops.\n"); 17310d565efSmrg@end example 17410d565efSmrg 17510d565efSmrg@item dump_basic_block 17610d565efSmrgOutput basic block. 17710d565efSmrg@item dump_generic_expr 17810d565efSmrgOutput generic expression. 17910d565efSmrg@item dump_gimple_stmt 18010d565efSmrgOutput gimple statement. 18110d565efSmrg 18210d565efSmrgNote that the above methods also have variants prefixed with 18310d565efSmrg@code{_loc}, such as @code{dump_printf_loc}, which are similar except 1840fc04c29Smrgthey also output the source location information. The @code{_loc} variants 1850fc04c29Smrgtake a @code{const dump_location_t &}. This class can be constructed from 1860fc04c29Smrga @code{gimple *} or from a @code{rtx_insn *}, and so callers can pass 1870fc04c29Smrga @code{gimple *} or a @code{rtx_insn *} as the @code{_loc} argument. 1880fc04c29SmrgThe @code{dump_location_t} constructor will extract the source location 1890fc04c29Smrgfrom the statement or instruction, along with the profile count, and 1900fc04c29Smrgthe location in GCC's own source code (or the plugin) from which the dump 1910fc04c29Smrgcall was emitted. Only the source location is currently used. 1920fc04c29SmrgThere is also a @code{dump_user_location_t} class, capturing the 1930fc04c29Smrgsource location and profile count, but not the dump emission location, 1940fc04c29Smrgso that locations in the user's code can be passed around. This 1950fc04c29Smrgcan also be constructed from a @code{gimple *} and from a @code{rtx_insn *}, 1960fc04c29Smrgand it too can be passed as the @code{_loc} argument. 19710d565efSmrg 19810d565efSmrg@end ftable 19910d565efSmrg 20010d565efSmrg@node Dump examples 20110d565efSmrg@subsection Dump examples 20210d565efSmrg@cindex dump examples 20310d565efSmrg 20410d565efSmrg@smallexample 20510d565efSmrggcc -O3 -fopt-info-missed=missed.all 20610d565efSmrg@end smallexample 20710d565efSmrg 20810d565efSmrgoutputs missed optimization report from all the passes into 20910d565efSmrg@file{missed.all}. 21010d565efSmrg 21110d565efSmrgAs another example, 21210d565efSmrg@smallexample 21310d565efSmrggcc -O3 -fopt-info-inline-optimized-missed=inline.txt 21410d565efSmrg@end smallexample 21510d565efSmrg 21610d565efSmrgwill output information about missed optimizations as well as 21710d565efSmrgoptimized locations from all the inlining passes into 21810d565efSmrg@file{inline.txt}. 21910d565efSmrg 22010d565efSmrgIf the @var{filename} is provided, then the dumps from all the 22110d565efSmrgapplicable optimizations are concatenated into the @file{filename}. 22210d565efSmrgOtherwise the dump is output onto @file{stderr}. If @var{options} is 223c7a68eb7Smrgomitted, it defaults to @option{optimized-optall}, which means dump 224c7a68eb7Smrgall information about successful optimizations from all the passes. 225c7a68eb7SmrgIn the following example, the optimization information is output on 226c7a68eb7Smrgto @file{stderr}. 22710d565efSmrg 22810d565efSmrg@smallexample 22910d565efSmrggcc -O3 -fopt-info 23010d565efSmrg@end smallexample 23110d565efSmrg 23210d565efSmrgNote that @option{-fopt-info-vec-missed} behaves the same as 233c7a68eb7Smrg@option{-fopt-info-missed-vec}. The order of the optimization group 234c7a68eb7Smrgnames and message types listed after @option{-fopt-info} does not matter. 23510d565efSmrg 23610d565efSmrgAs another example, consider 23710d565efSmrg 23810d565efSmrg@smallexample 23910d565efSmrggcc -fopt-info-vec-missed=vec.miss -fopt-info-loop-optimized=loop.opt 24010d565efSmrg@end smallexample 24110d565efSmrg 24210d565efSmrgHere the two output file names @file{vec.miss} and @file{loop.opt} are 24310d565efSmrgin conflict since only one output file is allowed. In this case, only 24410d565efSmrgthe first option takes effect and the subsequent options are 24510d565efSmrgignored. Thus only the @file{vec.miss} is produced which containts 24610d565efSmrgdumps from the vectorizer about missed opportunities. 247