[PATCH] Documentation for dump and optinfo output

[PATCH] Documentation for dump and optinfo output

[Sharad Singhai]

[-- 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

Re: [PATCH] Documentation for dump and optinfo output

[Richard Biener]

On Thu, 19 Dec 2013, Sharad Singhai wrote:

> 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?

Ok.

Thanks,
Richard.

Re: [PATCH] Documentation for dump and optinfo output

[Thomas Schwinge]

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

Hi!

On Thu, 19 Dec 2013 01:44:08 -0800, Sharad Singhai <singhai@google.com> wrote:
> I ran 'make doc' and browsed the info output for basic sanity. Okay for trunk?

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

Thanks for contributing to the documentation!

During build, I'm seeing the following warnings; would be great if you
could address these:

    ../../source/gcc/doc/optinfo.texi:45: warning: node next `Optimization groups' in menu `Dump output verbosity' and in sectioning `Dump files and streams' differ
    ../../source/gcc/doc/optinfo.texi:77: warning: node next `Dump files and streams' in menu `Dump types' and in sectioning `Dump output verbosity' differ
    ../../source/gcc/doc/optinfo.texi:77: warning: node prev `Dump files and streams' in menu `Dump output verbosity' and in sectioning `Optimization groups' differ
    ../../source/gcc/doc/optinfo.texi:104: warning: node next `Dump output verbosity' in menu `Dump files and streams' and in sectioning `Dump types' differ
    ../../source/gcc/doc/optinfo.texi:104: warning: node prev `Dump output verbosity' in menu `Optimization groups' and in sectioning `Dump files and streams' differ
    ../../source/gcc/doc/optinfo.texi:137: warning: node prev `Dump types' in menu `Dump files and streams' and in sectioning `Dump output verbosity' differ


Grüße,
 Thomas

[-- Attachment #2: Type: application/pgp-signature, Size: 489 bytes --]

Re: [PATCH] Documentation for dump and optinfo output

[Sharad Singhai]

I am really sorry about the delay. I couldn't exactly reproduce the
warning which you described, but I found a place where two nodes were
out of order in optinfo.texi. Could you please apply the following
patch and see if the problem goes away? If it works for you, I will
commit the doc fixes.

Also I would appreciate the exact command which produces these warnings.

Thanks,
Sharad

2014-02-05  Sharad Singhai  <singhai@google.com>

* doc/optinfo.texi: Fix order of nodes.

Index: doc/optinfo.texi
===================================================================
--- doc/optinfo.texi (revision 207525)
+++ doc/optinfo.texi (working copy)
@@ -12,8 +12,8 @@ information about various compiler transformations
 @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 files and streams::             Dump output file names and streams.
 * Dump types::                         Various types of dump functions.
 * Dump examples::                      Sample usage.
 @end menu

Thanks,
Sharad


On Fri, Jan 24, 2014 at 2:20 AM, Thomas Schwinge
<thomas@codesourcery.com> wrote:
> Hi!
>
> On Thu, 19 Dec 2013 01:44:08 -0800, Sharad Singhai <singhai@google.com> wrote:
>> I ran 'make doc' and browsed the info output for basic sanity. Okay for trunk?
>
>>       * Makefile.in: Add optinfo.texi.
>>       * doc/optinfo.texi: New documentation for optimization info.
>>       * doc/passes.texi: Add new node.
>
> Thanks for contributing to the documentation!
>
> During build, I'm seeing the following warnings; would be great if you
> could address these:
>
>     ../../source/gcc/doc/optinfo.texi:45: warning: node next `Optimization groups' in menu `Dump output verbosity' and in sectioning `Dump files and streams' differ
>     ../../source/gcc/doc/optinfo.texi:77: warning: node next `Dump files and streams' in menu `Dump types' and in sectioning `Dump output verbosity' differ
>     ../../source/gcc/doc/optinfo.texi:77: warning: node prev `Dump files and streams' in menu `Dump output verbosity' and in sectioning `Optimization groups' differ
>     ../../source/gcc/doc/optinfo.texi:104: warning: node next `Dump output verbosity' in menu `Dump files and streams' and in sectioning `Dump types' differ
>     ../../source/gcc/doc/optinfo.texi:104: warning: node prev `Dump output verbosity' in menu `Optimization groups' and in sectioning `Dump files and streams' differ
>     ../../source/gcc/doc/optinfo.texi:137: warning: node prev `Dump types' in menu `Dump files and streams' and in sectioning `Dump output verbosity' differ
>
>
> Grüße,
>  Thomas

Re: [PATCH] Documentation for dump and optinfo output

[Thomas Schwinge]

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

Hi!

On Wed, 5 Feb 2014 16:33:19 -0800, Sharad Singhai <singhai@google.com> wrote:
> I am really sorry about the delay.

No worries; not exactly a severe issue.  ;-)

> I couldn't exactly reproduce the
> warning which you described

Maybe the version of makeinfo is relevant?

    $ makeinfo --version | head -n 1
    makeinfo (GNU texinfo) 5.1

> but I found a place where two nodes were
> out of order in optinfo.texi. Could you please apply the following
> patch and see if the problem goes away? If it works for you, I will
> commit the doc fixes.
> 
> Also I would appreciate the exact command which produces these warnings.

Your patch does fix the problem; see the following diff of the build log,
where the warnings are now gone, and which also happens to contain the
makeinfo command line.

@@ -4199,12 +4199,6 @@ if [ xinfo = xinfo ]; then \
 		makeinfo --split-size=5000000 --split-size=5000000 --no-split -I . -I ../../source/gcc/doc \
 			-I ../../source/gcc/doc/include -o doc/gccint.info ../../source/gcc/doc/gccint.texi; \
 	fi
-../../source/gcc/doc/optinfo.texi:45: warning: node next `Optimization groups' in menu `Dump output verbosity' and in sectioning `Dump files and streams' differ
-../../source/gcc/doc/optinfo.texi:77: warning: node next `Dump files and streams' in menu `Dump types' and in sectioning `Dump output verbosity' differ
-../../source/gcc/doc/optinfo.texi:77: warning: node prev `Dump files and streams' in menu `Dump output verbosity' and in sectioning `Optimization groups' differ
-../../source/gcc/doc/optinfo.texi:104: warning: node next `Dump output verbosity' in menu `Dump files and streams' and in sectioning `Dump types' differ
-../../source/gcc/doc/optinfo.texi:104: warning: node prev `Dump output verbosity' in menu `Optimization groups' and in sectioning `Dump files and streams' differ
-../../source/gcc/doc/optinfo.texi:137: warning: node prev `Dump types' in menu `Dump files and streams' and in sectioning `Dump output verbosity' differ
 if [ xinfo = xinfo ]; then \
 		makeinfo --split-size=5000000 --split-size=5000000 --no-split -I ../../source/gcc/doc \
 			-I ../../source/gcc/doc/include -o doc/gccinstall.info ../../source/gcc/doc/install.texi; \

> * doc/optinfo.texi: Fix order of nodes.

Thanks, please commit.


Grüße,
 Thomas

[-- Attachment #2: Type: application/pgp-signature, Size: 489 bytes --]

Re: [PATCH] Documentation for dump and optinfo output

[Sharad Singhai]

Committed as r207767.

Indeed, I had an older version of makeinfo. Once I updated to the
latest version 5.2, I saw the warnings. Those are fixed by this patch.

Thanks,
Sharad

> On Tue, Feb 11, 2014 at 11:42 PM, Thomas Schwinge <thomas@codesourcery.com>
> wrote:
>>
>> Hi!
>>
>> On Wed, 5 Feb 2014 16:33:19 -0800, Sharad Singhai <singhai@google.com>
>> wrote:
>> > I am really sorry about the delay.
>>
>> No worries; not exactly a severe issue.  ;-)
>>
>> > I couldn't exactly reproduce the
>> > warning which you described
>>
>> Maybe the version of makeinfo is relevant?
>>
>>     $ makeinfo --version | head -n 1
>>     makeinfo (GNU texinfo) 5.1
>>
>> > but I found a place where two nodes were
>> > out of order in optinfo.texi. Could you please apply the following
>> > patch and see if the problem goes away? If it works for you, I will
>> > commit the doc fixes.
>> >
>> > Also I would appreciate the exact command which produces these warnings.
>>
>> Your patch does fix the problem; see the following diff of the build log,
>> where the warnings are now gone, and which also happens to contain the
>> makeinfo command line.
>>
>> @@ -4199,12 +4199,6 @@ if [ xinfo = xinfo ]; then \
>>                 makeinfo --split-size=5000000 --split-size=5000000
>> --no-split -I . -I ../../source/gcc/doc \
>>                         -I ../../source/gcc/doc/include -o doc/gccint.info
>> ../../source/gcc/doc/gccint.texi; \
>>         fi
>> -../../source/gcc/doc/optinfo.texi:45: warning: node next `Optimization
>> groups' in menu `Dump output verbosity' and in sectioning `Dump files and
>> streams' differ
>> -../../source/gcc/doc/optinfo.texi:77: warning: node next `Dump files and
>> streams' in menu `Dump types' and in sectioning `Dump output verbosity'
>> differ
>> -../../source/gcc/doc/optinfo.texi:77: warning: node prev `Dump files and
>> streams' in menu `Dump output verbosity' and in sectioning `Optimization
>> groups' differ
>> -../../source/gcc/doc/optinfo.texi:104: warning: node next `Dump output
>> verbosity' in menu `Dump files and streams' and in sectioning `Dump types'
>> differ
>> -../../source/gcc/doc/optinfo.texi:104: warning: node prev `Dump output
>> verbosity' in menu `Optimization groups' and in sectioning `Dump files and
>> streams' differ
>> -../../source/gcc/doc/optinfo.texi:137: warning: node prev `Dump types' in
>> menu `Dump files and streams' and in sectioning `Dump output verbosity'
>> differ
>>  if [ xinfo = xinfo ]; then \
>>                 makeinfo --split-size=5000000 --split-size=5000000
>> --no-split -I ../../source/gcc/doc \
>>                         -I ../../source/gcc/doc/include -o
>> doc/gccinstall.info ../../source/gcc/doc/install.texi; \
>>
>> > * doc/optinfo.texi: Fix order of nodes.
>>
>> Thanks, please commit.
>>
>>
>> Grüße,
>>  Thomas
>
>