public inbox for gcc-patches@gcc.gnu.org
 help / color / mirror / Atom feed
* [PATCH] Documentation for dump and optinfo output
@ 2013-12-19  9:44 Sharad Singhai
  2013-12-19  9:59 ` Richard Biener
  2014-01-24 10:21 ` Thomas Schwinge
  0 siblings, 2 replies; 6+ messages in thread
From: Sharad Singhai @ 2013-12-19  9:44 UTC (permalink / raw)
  To: gcc-patches; +Cc: Martin Jambor, Richard Biener

[-- Attachment #1: Type: text/plain, Size: 498 bytes --]

I am really sorry, I forgot to add gcc internal documentation for dump
functions. Sorry about a very long delay.

The attached patch adds some documentation about how to use the new
dump infrastructure. This doc is attached to 'passes' documentation
node as that seemed the most logical place. Also, I am not sure what
level of details would be useful. I could perhaps add some more
details if needed.

I ran 'make doc' and browsed the info output for basic sanity. Okay for trunk?

Thanks,
Sharad

[-- Attachment #2: dumpdoc.patch.diff --]
[-- Type: text/plain, Size: 9287 bytes --]

2013-12-19    <singhai@google.com>

	* 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

^ permalink raw reply	[flat|nested] 6+ messages in thread
end of thread, other threads:[~2014-02-13 21:51 UTC | newest]

Thread overview: 6+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2013-12-19  9:44 [PATCH] Documentation for dump and optinfo output Sharad Singhai
2013-12-19  9:59 ` Richard Biener
2014-01-24 10:21 ` Thomas Schwinge
2014-02-06  0:34   ` Sharad Singhai
2014-02-12  7:42     ` Thomas Schwinge
     [not found]       ` <CAKxPW67V8NEKQ8q4tjHGn3r5n53g4cuZ=SCGbK6Wi97EmCOb-g@mail.gmail.com>
2014-02-13 21:51         ` Sharad Singhai

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).