Makefile.in: Add optinfo.texi.

2013-12-20  Sharad Singhai  <singhai@google.com>

	* Makefile.in: Add optinfo.texi.
	* doc/invoke.texi: Fix typo.
	* doc/optinfo.texi: New documentation for optimization info.
	* doc/passes.texi: Add new node.

From-SVN: r206161

5 files changed, 243 insertions, 2 deletions

diff --git a/gcc/ChangeLog b/gcc/ChangeLog
index c6f01720c61..529180a1ff4 100644
--- a/gcc/ChangeLog
+++ b/gcc/ChangeLog
@@ -1,3 +1,10 @@
+2013-12-20  Sharad Singhai  <singhai@google.com>
+
+	* Makefile.in: Add optinfo.texi.
+	* doc/invoke.texi: Fix typo.
+	* doc/optinfo.texi: New documentation for optimization info.
+	* doc/passes.texi: Add new node.
+
 2013-12-20  Trevor saunders  <tsaunders@mozilla.com>
 
 	* vec.h (stack_vec): Convert to a templaate specialization of
diff --git a/gcc/Makefile.in b/gcc/Makefile.in
index b79bb0c0aca..d824551b081 100644
--- a/gcc/Makefile.in
+++ b/gcc/Makefile.in
@@ -2808,7 +2808,7 @@ TEXI_GCCINT_FILES = gccint.texi gcc-common.texi gcc-vers.texi		\
 	 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
diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
index 63bd23b7668..93468a8e1b3 100644
--- a/gcc/doc/invoke.texi
+++ b/gcc/doc/invoke.texi
@@ -6507,7 +6507,7 @@ gcc -fopt-info-vec-missed=vec.miss -fopt-info-loop-optimized=loop.opt
 Here the two output filenames @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 cotaints
+ignored. Thus only the @file{vec.miss} is produced which contains
 dumps from the vectorizer about missed opportunities.
 
 @item -frandom-seed=@var{string}
diff --git a/gcc/doc/optinfo.texi b/gcc/doc/optinfo.texi
new file mode 100644
index 00000000000..983d653ddbd
--- /dev/null
+++ b/gcc/doc/optinfo.texi
@@ -0,0 +1,228 @@
+@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 files and streams::             Dump 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 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_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 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{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.
diff --git a/gcc/doc/passes.texi b/gcc/doc/passes.texi
index 9a68ad29c5c..a1f57cc3701 100644
--- a/gcc/doc/passes.texi
+++ b/gcc/doc/passes.texi
@@ -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 VMS debug symbol table
 format.
 
 @end itemize
+
+@node Optimization info
+@section Optimization info
+@include optinfo.texi