undocumented optimization options

undocumented optimization options

[Janis Johnson]

Several options reported by --help=optimize are not documented in the
GCC Manual (via invoke.texi) but are still reported with
--help=optimize,^undocumented.  Here are the options along with the
people who checked in the entries to common.opt:

  -fipa-cp               steven
  -fipa-matrix-reorg     razya
  -fipa-pure-const       zadeck  (enabled with -O)
  -fipa-reference        zadeck  (enabled with -O)
  -fipa-type-escape      zadeck
  -fvar-tracking-uninit  ctice

Is there a policy about whether an experimental option can be left
undocumented, or should it be documented with a statement that it is
experimental?

If an option is left undocumented on purpose then its entry in common.opt
should include "Undocumented".

Janis

Re: undocumented optimization options

[Gerald Pfeifer]

On Thu, 1 Nov 2007, Janis Johnson wrote:
>   -fipa-cp               steven
>   -fipa-matrix-reorg     razya
>   -fipa-pure-const       zadeck  (enabled with -O)
>   -fipa-reference        zadeck  (enabled with -O)
>   -fipa-type-escape      zadeck
>   -fvar-tracking-uninit  ctice
> 
> Is there a policy about whether an experimental option can be left
> undocumented, or should it be documented with a statement that it is
> experimental?

I'd prefer the latter.  And for options enabled by default or via one
of the commonly used options (such as -O) I believe we should always
include documentation _or_ we might want to remove those options and
make the associated active unconditionally.

> If an option is left undocumented on purpose then its entry in 
> common.opt should include "Undocumented".

So far we don't seem to use that in common.opt.

Gerald

Re: undocumented optimization options

[Mark Mitchell]

Gerald Pfeifer wrote:
> On Thu, 1 Nov 2007, Janis Johnson wrote:
>>   -fipa-cp               steven
>>   -fipa-matrix-reorg     razya
>>   -fipa-pure-const       zadeck  (enabled with -O)
>>   -fipa-reference        zadeck  (enabled with -O)
>>   -fipa-type-escape      zadeck
>>   -fvar-tracking-uninit  ctice
>>
>> Is there a policy about whether an experimental option can be left
>> undocumented, or should it be documented with a statement that it is
>> experimental?
> 
> I'd prefer the latter. 

I believe our policy to be that *all* command line options must be
clearly documented.  The document can say that the option is
experimental, deprecated, or otherwise in danger of being removed or
changes, but we should document the option.

If an option is only useful for developers, and we really think that
users should not be allowed to twiddle it, we should hide it under an
#ifdef.

Thanks,

-- 
Mark Mitchell
CodeSourcery
mark@codesourcery.com
(650) 331-3385 x713

Re: undocumented optimization options

[Razya Ladelsky]

Mark Mitchell <mark@codesourcery.com> wrote on 05/11/2007 01:51:33:

> Gerald Pfeifer wrote:
> > On Thu, 1 Nov 2007, Janis Johnson wrote:
> >>   -fipa-cp               steven
> >>   -fipa-matrix-reorg     razya
> >>   -fipa-pure-const       zadeck  (enabled with -O)
> >>   -fipa-reference        zadeck  (enabled with -O)
> >>   -fipa-type-escape      zadeck
> >>   -fvar-tracking-uninit  ctice
> >>

I'll add documentation for ipa-cp and ipa-matrix-reorg as soon as 
Zadeck commits his changes to invoke.texi.

Thanks,
Razya


> >> Is there a policy about whether an experimental option can be left
> >> undocumented, or should it be documented with a statement that it is
> >> experimental?
> > 
> > I'd prefer the latter. 
> 
> I believe our policy to be that *all* command line options must be
> clearly documented.  The document can say that the option is
> experimental, deprecated, or otherwise in danger of being removed or
> changes, but we should document the option.
> 
> If an option is only useful for developers, and we really think that
> users should not be allowed to twiddle it, we should hide it under an
> #ifdef.
> 
> Thanks,
> 
> -- 
> Mark Mitchell
> CodeSourcery
> mark@codesourcery.com
> (650) 331-3385 x713

Re: undocumented optimization options

[Kenneth Zadeck]

Razya Ladelsky wrote:
> Mark Mitchell <mark@codesourcery.com> wrote on 05/11/2007 01:51:33:
>
>   
>> Gerald Pfeifer wrote:
>>     
>>> On Thu, 1 Nov 2007, Janis Johnson wrote:
>>>       
>>>>   -fipa-cp               steven
>>>>   -fipa-matrix-reorg     razya
>>>>   -fipa-pure-const       zadeck  (enabled with -O)
>>>>   -fipa-reference        zadeck  (enabled with -O)
>>>>   -fipa-type-escape      zadeck
>>>>   -fvar-tracking-uninit  ctice
>>>>
>>>>         
>
> I'll add documentation for ipa-cp and ipa-matrix-reorg as soon as 
> Zadeck commits his changes to invoke.texi.
>
> Thanks,
> Razya
>
>
>   
>>>> Is there a policy about whether an experimental option can be left
>>>> undocumented, or should it be documented with a statement that it is
>>>> experimental?
>>>>         
>>> I'd prefer the latter. 
>>>       
>> I believe our policy to be that *all* command line options must be
>> clearly documented.  The document can say that the option is
>> experimental, deprecated, or otherwise in danger of being removed or
>> changes, but we should document the option.
>>
>> If an option is only useful for developers, and we really think that
>> users should not be allowed to twiddle it, we should hide it under an
>> #ifdef.
>>
>> Thanks,
>>
>> -- 
>> Mark Mitchell
>> CodeSourcery
>> mark@codesourcery.com
>> (650) 331-3385 x713
>>     
>
>   
i am waiting for an approval, hint hint hint.

Kenny

Re: undocumented optimization options

[Razya Ladelsky]

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

Kenneth Zadeck <zadeck@naturalbridge.com> wrote on 07/11/2007 19:49:29:

> Razya Ladelsky wrote:
> > Mark Mitchell <mark@codesourcery.com> wrote on 05/11/2007 01:51:33:
> >
> > 
> >> Gerald Pfeifer wrote:
> >> 
> >>> On Thu, 1 Nov 2007, Janis Johnson wrote:
> >>> 
> >>>>   -fipa-cp               steven
> >>>>   -fipa-matrix-reorg     razya
> >>>>   -fipa-pure-const       zadeck  (enabled with -O)
> >>>>   -fipa-reference        zadeck  (enabled with -O)
> >>>>   -fipa-type-escape      zadeck
> >>>>   -fvar-tracking-uninit  ctice
> >>>>
> >>>> 
> >
> > I'll add documentation for fipa-cp and fipa-matrix-reorg as soon as 
> > Zadeck commits his changes to invoke.texi.
> >
> > Thanks,
> > Razya
> >
> >

Hi,

This patch adds documentation for fipa-cp and -fipa-matrix-reorg.

2007-11-12  Razya Ladelsky <razya@il.ibm.com>

    * doc/invoke.texi (fipa-cp, fipa-matrix-reorg): Add documentation.

Ok to commit?



[-- Attachment #2: document.diff --]
[-- Type: application/octet-stream, Size: 1141 bytes --]

Index: doc/invoke.texi
===================================================================
--- doc/invoke.texi	(revision 130095)
+++ doc/invoke.texi	(working copy)
@@ -328,7 +328,8 @@
 -ffunction-sections -fgcse -fgcse-after-reload -fgcse-las -fgcse-lm @gol
 -fgcse-sm -fif-conversion -fif-conversion2 -finline-functions @gol
 -finline-functions-called-once -finline-limit=@var{n} @gol
--finline-small-functions -fipa-pta -fipa-pure-const -fipa-reference @gol
+-finline-small-functions -fipa-cp -fipa-marix-reorg -fipa-pta @gol 
+-fipa-pure-const -fipa-reference @gol
 -fipa-type-escape -fivopts -fkeep-inline-functions -fkeep-static-consts @gol
 -fmerge-all-constants -fmerge-constants -fmodulo-sched @gol
 -fmodulo-sched-allow-regmoves -fmove-loop-invariants -fmudflap @gol
@@ -5714,6 +5715,14 @@
 @opindex fipa-pta
 Perform interprocedural pointer analysis.
 
+@item -fipa-cp
+@opindex fipa-cp
+Perform interprocedural constant propagation.
+
+@item -fipa-matrix-reorg
+@opindex fipa-matrix-reorg
+Perform matrix flattening and transposing.
+
 @item -ftree-sink
 @opindex ftree-sink
 Perform forward store motion  on trees.  This flag is

Re: undocumented optimization options

[Richard Guenther]

On Nov 12, 2007 10:06 AM, Razya Ladelsky <RAZYA@il.ibm.com> wrote:
> Kenneth Zadeck <zadeck@naturalbridge.com> wrote on 07/11/2007 19:49:29:
>
> > Razya Ladelsky wrote:
> > > Mark Mitchell <mark@codesourcery.com> wrote on 05/11/2007 01:51:33:
> > >
> > >
> > >> Gerald Pfeifer wrote:
> > >>
> > >>> On Thu, 1 Nov 2007, Janis Johnson wrote:
> > >>>
> > >>>>   -fipa-cp               steven
> > >>>>   -fipa-matrix-reorg     razya
> > >>>>   -fipa-pure-const       zadeck  (enabled with -O)
> > >>>>   -fipa-reference        zadeck  (enabled with -O)
> > >>>>   -fipa-type-escape      zadeck
> > >>>>   -fvar-tracking-uninit  ctice
> > >>>>
> > >>>>
> > >
> > > I'll add documentation for fipa-cp and fipa-matrix-reorg as soon as
> > > Zadeck commits his changes to invoke.texi.
> > >
> > > Thanks,
> > > Razya
> > >
> > >
>
> Hi,
>
> This patch adds documentation for fipa-cp and -fipa-matrix-reorg.
>
> 2007-11-12  Razya Ladelsky <razya@il.ibm.com>
>
>     * doc/invoke.texi (fipa-cp, fipa-matrix-reorg): Add documentation.
>
> Ok to commit?

Please be more verbose.  While people might have an idea what interprocedural
constant propagation is (though they probably don't immediately see that it
might increase code-size by versioning functions), certainly matrix flattening
deserves more comments.

Of course we might stay with the sparse documentation and just say in
addition "This optimization is experimental." to steer people away from it ;)

Richard.

For reference here's part of the patch:

@@ -5714,6 +5715,14 @@
 @opindex fipa-pta
 Perform interprocedural pointer analysis.

+@item -fipa-cp
+@opindex fipa-cp
+Perform interprocedural constant propagation.
+
+@item -fipa-matrix-reorg
+@opindex fipa-matrix-reorg
+Perform matrix flattening and transposing.
+

Re: undocumented optimization options

[Razya Ladelsky]

"Richard Guenther" <richard.guenther@gmail.com> wrote on 12/11/2007 
12:28:05:

> On Nov 12, 2007 10:06 AM, Razya Ladelsky <RAZYA@il.ibm.com> wrote:
> > Kenneth Zadeck <zadeck@naturalbridge.com> wrote on 07/11/2007 
19:49:29:
> >
> > > Razya Ladelsky wrote:
> > > > Mark Mitchell <mark@codesourcery.com> wrote on 05/11/2007 
01:51:33:
> > > >
> > > >
> > > >> Gerald Pfeifer wrote:
> > > >>
> > > >>> On Thu, 1 Nov 2007, Janis Johnson wrote:
> > > >>>
> > > >>>>   -fipa-cp               steven
> > > >>>>   -fipa-matrix-reorg     razya
> > > >>>>   -fipa-pure-const       zadeck  (enabled with -O)
> > > >>>>   -fipa-reference        zadeck  (enabled with -O)
> > > >>>>   -fipa-type-escape      zadeck
> > > >>>>   -fvar-tracking-uninit  ctice
> > > >>>>
> > > >>>>
> > > >
> > > > I'll add documentation for fipa-cp and fipa-matrix-reorg as soon 
as
> > > > Zadeck commits his changes to invoke.texi.
> > > >
> > > > Thanks,
> > > > Razya
> > > >
> > > >
> >
> > Hi,
> >
> > This patch adds documentation for fipa-cp and -fipa-matrix-reorg.
> >
> > 2007-11-12  Razya Ladelsky <razya@il.ibm.com>
> >
> >     * doc/invoke.texi (fipa-cp, fipa-matrix-reorg): Add documentation.
> >
> > Ok to commit?
> 
> Please be more verbose.  While people might have an idea what 
interprocedural
> constant propagation is (though they probably don't immediately see that 
it
> might increase code-size by versioning functions), certainly matrix 
flattening
> deserves more comments.
> 

I was under the impression that in invoke.texi we just document the 
options.
The optimizations' full documentation is at the corresponding files.
(ipa-cp.c and matrix-reorg.c)
Do you think a more detailed description of these optimizations 
in doc/invoke.texi is necessary?

Thanks,
Razya


> Of course we might stay with the sparse documentation and just say in
> addition "This optimization is experimental." to steer people away from 
it ;)
> 
> Richard.
> 
> For reference here's part of the patch:
> 
> @@ -5714,6 +5715,14 @@
>  @opindex fipa-pta
>  Perform interprocedural pointer analysis.
> 
> +@item -fipa-cp
> +@opindex fipa-cp
> +Perform interprocedural constant propagation.
> +
> +@item -fipa-matrix-reorg
> +@opindex fipa-matrix-reorg
> +Perform matrix flattening and transposing.
> +

Re: undocumented optimization options

[Richard Guenther]

On Nov 12, 2007 3:27 PM, Razya Ladelsky <RAZYA@il.ibm.com> wrote:
> "Richard Guenther" <richard.guenther@gmail.com> wrote on 12/11/2007
> 12:28:05:
>
>
> > On Nov 12, 2007 10:06 AM, Razya Ladelsky <RAZYA@il.ibm.com> wrote:
> > > Kenneth Zadeck <zadeck@naturalbridge.com> wrote on 07/11/2007
> 19:49:29:
> > >
> > > > Razya Ladelsky wrote:
> > > > > Mark Mitchell <mark@codesourcery.com> wrote on 05/11/2007
> 01:51:33:
> > > > >
> > > > >
> > > > >> Gerald Pfeifer wrote:
> > > > >>
> > > > >>> On Thu, 1 Nov 2007, Janis Johnson wrote:
> > > > >>>
> > > > >>>>   -fipa-cp               steven
> > > > >>>>   -fipa-matrix-reorg     razya
> > > > >>>>   -fipa-pure-const       zadeck  (enabled with -O)
> > > > >>>>   -fipa-reference        zadeck  (enabled with -O)
> > > > >>>>   -fipa-type-escape      zadeck
> > > > >>>>   -fvar-tracking-uninit  ctice
> > > > >>>>
> > > > >>>>
> > > > >
> > > > > I'll add documentation for fipa-cp and fipa-matrix-reorg as soon
> as
> > > > > Zadeck commits his changes to invoke.texi.
> > > > >
> > > > > Thanks,
> > > > > Razya
> > > > >
> > > > >
> > >
> > > Hi,
> > >
> > > This patch adds documentation for fipa-cp and -fipa-matrix-reorg.
> > >
> > > 2007-11-12  Razya Ladelsky <razya@il.ibm.com>
> > >
> > >     * doc/invoke.texi (fipa-cp, fipa-matrix-reorg): Add documentation.
> > >
> > > Ok to commit?
> >
> > Please be more verbose.  While people might have an idea what
> interprocedural
> > constant propagation is (though they probably don't immediately see that
> it
> > might increase code-size by versioning functions), certainly matrix
> flattening
> > deserves more comments.
> >
>
> I was under the impression that in invoke.texi we just document the
> options.
> The optimizations' full documentation is at the corresponding files.
> (ipa-cp.c and matrix-reorg.c)
> Do you think a more detailed description of these optimizations
> in doc/invoke.texi is necessary?

For options that are not enabled by default at any -O level the documentation
should be a help for the user to decide whether to enable or not enable it.
So, yes, if there are non-standard terms used or if there are not obvious
side-effects (like performing function versioning for ipa-cp) those should be
documented.

For example googling for "interprocedural constant propagation" gives you
an idea what it does by citing papers.  Googling for "matrix flattening
transposing" instead gives you only patches ;)

Richard.

Re: undocumented optimization options

[Mark Mitchell]

Richard Guenther wrote:

> For options that are not enabled by default at any -O level the documentation
> should be a help for the user to decide whether to enable or not enable it.
> So, yes, if there are non-standard terms used or if there are not obvious
> side-effects (like performing function versioning for ipa-cp) those should be
> documented.
> 
> For example googling for "interprocedural constant propagation" gives you
> an idea what it does by citing papers.  Googling for "matrix flattening
> transposing" instead gives you only patches ;)

To echo Richard: this is a user manual, so we don't need to say exactly
what the option does, but we have to say when you should use it. :-)  In
other words, we certainly don't want to say anything about SSA names or
whatever, but we do want to explain what it's for.  For interprocedural
constant propagation, maybe something like:

==
This optimization analyzes the program to determine when values passed
to, or return from, functions are constants and then optimizes
accordingly.  This optimization can substantially increase performance
if the application has lots of functions that return constants, but,
because this optimization can create multiple copies of code fragments,
it may significantly increase code size.
==

-- 
Mark Mitchell
CodeSourcery
mark@codesourcery.com
(650) 331-3385 x713

Re: undocumented optimization options

[Razya Ladelsky]

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

Mark Mitchell <mark@codesourcery.com> wrote on 12/11/2007 18:25:03:

> Richard Guenther wrote:
> 
> > For options that are not enabled by default at any -O level the 
> documentation
> > should be a help for the user to decide whether to enable or not 
enable it.
> > So, yes, if there are non-standard terms used or if there are not 
obvious
> > side-effects (like performing function versioning for ipa-cp) 
> those should be
> > documented.
> > 
> > For example googling for "interprocedural constant propagation" gives 
you
> > an idea what it does by citing papers.  Googling for "matrix 
flattening
> > transposing" instead gives you only patches ;)
> 
> To echo Richard: this is a user manual, so we don't need to say exactly
> what the option does, but we have to say when you should use it. :-)  In
> other words, we certainly don't want to say anything about SSA names or
> whatever, but we do want to explain what it's for.  For interprocedural
> constant propagation, maybe something like:
> 
> ==
> This optimization analyzes the program to determine when values passed
> to, or return from, functions are constants and then optimizes
> accordingly.  This optimization can substantially increase performance
> if the application has lots of functions that return constants, but,
> because this optimization can create multiple copies of code fragments,
> it may significantly increase code size.
> ==
> 

Thanks.
Described these two optimizations in more detail.
O.K now?

Thanks,
Razya

2007-11-20  Razya Ladelsky <razya@il.ibm.com>

    * doc/invoke.texi (fipa-cp, fipa-matrix-reorg): Add documentation.






> -- 
> Mark Mitchell
> CodeSourcery
> mark@codesourcery.com
> (650) 331-3385 x713

[-- Attachment #2: document.txt --]
[-- Type: text/plain, Size: 2001 bytes --]

Index: invoke.texi
===================================================================
--- invoke.texi	(revision 130311)
+++ invoke.texi	(working copy)
@@ -328,7 +328,8 @@
 -ffunction-sections -fgcse -fgcse-after-reload -fgcse-las -fgcse-lm @gol
 -fgcse-sm -fif-conversion -fif-conversion2 -finline-functions @gol
 -finline-functions-called-once -finline-limit=@var{n} @gol
--finline-small-functions -fipa-pta -fipa-pure-const -fipa-reference @gol
+-finline-small-functions -fipa-cp -fipa-marix-reorg -fipa-pta @gol 
+-fipa-pure-const -fipa-reference @gol
 -fipa-type-escape -fivopts -fkeep-inline-functions -fkeep-static-consts @gol
 -fmerge-all-constants -fmerge-constants -fmodulo-sched @gol
 -fmodulo-sched-allow-regmoves -fmove-loop-invariants -fmudflap @gol
@@ -5715,6 +5716,29 @@
 @opindex fipa-pta
 Perform interprocedural pointer analysis.
 
+@item -fipa-cp
+@opindex fipa-cp
+Perform interprocedural constant propagation.
+This optimization analyzes the program to determine when values passed
+to functions are constants and then optimizes accordingly.  
+This optimization can substantially increase performance
+if the application has constants passed to functions, but
+because this optimization can create multiple copies of functions,
+it may significantly increase code size.
+
+@item -fipa-matrix-reorg
+@opindex fipa-matrix-reorg
+Perform matrix flattening and transposing.
+Matrix flattening tries to replace a m-dimensional matrix 
+with its equivalent n-dimensional matrix, where n < m.
+This reduces the level of indirection needed for accessing the elements
+of the matrix. The second optimization is matrix transposing that
+attemps to change the order of the matrix's dimensions in order to 
+improve cache locality.
+Both optimizations need fwhole-program flag. 
+Transpoing is enabled only if profiling information is avaliable.
+
+
 @item -ftree-sink
 @opindex ftree-sink
 Perform forward store motion  on trees.  This flag is
=

Re: undocumented optimization options

[Richard Guenther]

On Nov 20, 2007 12:32 PM, Razya Ladelsky <RAZYA@il.ibm.com> wrote:
> Mark Mitchell <mark@codesourcery.com> wrote on 12/11/2007 18:25:03:
>
>
> > Richard Guenther wrote:
> >
> > > For options that are not enabled by default at any -O level the
> > documentation
> > > should be a help for the user to decide whether to enable or not
> enable it.
> > > So, yes, if there are non-standard terms used or if there are not
> obvious
> > > side-effects (like performing function versioning for ipa-cp)
> > those should be
> > > documented.
> > >
> > > For example googling for "interprocedural constant propagation" gives
> you
> > > an idea what it does by citing papers.  Googling for "matrix
> flattening
> > > transposing" instead gives you only patches ;)
> >
> > To echo Richard: this is a user manual, so we don't need to say exactly
> > what the option does, but we have to say when you should use it. :-)  In
> > other words, we certainly don't want to say anything about SSA names or
> > whatever, but we do want to explain what it's for.  For interprocedural
> > constant propagation, maybe something like:
> >
> > ==
> > This optimization analyzes the program to determine when values passed
> > to, or return from, functions are constants and then optimizes
> > accordingly.  This optimization can substantially increase performance
> > if the application has lots of functions that return constants, but,
> > because this optimization can create multiple copies of code fragments,
> > it may significantly increase code size.
> > ==
> >
>
> Thanks.
> Described these two optimizations in more detail.
> O.K now?

Ok.  Thanks!
Richard.

> Thanks,
> Razya
>
> 2007-11-20  Razya Ladelsky <razya@il.ibm.com>
>
>     * doc/invoke.texi (fipa-cp, fipa-matrix-reorg): Add documentation.

Re: undocumented optimization options

[Ian Lance Taylor]

Razya Ladelsky <RAZYA@il.ibm.com> writes:

> This patch adds documentation for fipa-cp and -fipa-matrix-reorg.
> 
> 2007-11-12  Razya Ladelsky <razya@il.ibm.com>
> 
>     * doc/invoke.texi (fipa-cp, fipa-matrix-reorg): Add documentation.
> 
> Ok to commit?

This is OK.

Thanks.

Ian

Re: undocumented optimization options

[Razya Ladelsky]

Ian Lance Taylor <iant@google.com> wrote on 13/11/2007 20:11:35:

> Razya Ladelsky <RAZYA@il.ibm.com> writes:
> 
> > This patch adds documentation for fipa-cp and -fipa-matrix-reorg.
> > 
> > 2007-11-12  Razya Ladelsky <razya@il.ibm.com>
> > 
> >     * doc/invoke.texi (fipa-cp, fipa-matrix-reorg): Add documentation.
> > 
> > Ok to commit?
> 
> This is OK.
> 

Should I add a more detailed documentation for 
these optimizations, though?

Thanks,
Razya

> Thanks.
> 
> Ian

Re: undocumented optimization options

[Steven Bosscher]

On 11/1/07, Janis Johnson <janis187@us.ibm.com> wrote:
> Several options reported by --help=optimize are not documented in the
> GCC Manual (via invoke.texi) but are still reported with
> --help=optimize,^undocumented.  Here are the options along with the
> people who checked in the entries to common.opt:
>
>   -fipa-cp               steven

I may have moved it around, I don't recall. But I did not add this option.
Gr.
Steven

Re: undocumented optimization options

[Steven Bosscher]

On 11/1/07, Janis Johnson <janis187@us.ibm.com> wrote:
> Several options reported by --help=optimize are not documented in the
> GCC Manual (via invoke.texi) but are still reported with
> --help=optimize,^undocumented.  Here are the options along with the
> people who checked in the entries to common.opt:
>
>   -fipa-cp               steven

I may have moved it around, I don't recall. But I did not add this option.
Gr.
Steven