Re: undocumented optimization options

Re: undocumented optimization options

[Kenneth Zadeck]

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

Janis Johnson 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
>   -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
>
>
>   
This patch gets me off of janis's bad list (or at least the one
associated with undocumented options).  As directed by diego, I sorted
the option lists for -O, -Os and -O2 since this had rotted. 

2007-11-05  Kenneth Zadeck <zadeck@naturalbridge.com>

    * common.opt: Add pointer to doc/options.texi.
    * doc/invoke.texi (-fdse, -fdce, -fauto-inc-dec, -fipa-pure-const,
    -fipa-reference): Add or correct doc.  Sorted options list for -Os
    -O, -O2.

Ok to commit?

Kenny
   

[-- Attachment #2: options1.diff --]
[-- Type: text/x-patch, Size: 10136 bytes --]

Index: doc/invoke.texi
===================================================================
--- doc/invoke.texi	(revision 129907)
+++ doc/invoke.texi	(working copy)
@@ -315,57 +315,51 @@ Objective-C and Objective-C++ Dialects}.
 
 @item Optimization Options
 @xref{Optimize Options,,Options that Control Optimization}.
-@gccoptlist{-falign-functions[=@var{n}]  -falign-jumps[=@var{n}] @gol
--falign-labels[=@var{n}]  -falign-loops[=@var{n}]  @gol
--fassociative-math  -freciprocal-math @gol
--fmudflap -fmudflapth -fmudflapir @gol
--fbranch-probabilities -fprofile-values -fvpt  @gol
--fbranch-target-load-optimize @gol
--fbranch-target-load-optimize2 -fbtr-bb-exclusive @gol
--fcaller-saves  -fcprop-registers  -fcse-follow-jumps @gol
--fcse-skip-blocks  -fcx-limited-range  -fdata-sections  -fdce @gol
--fdelayed-branch  -fdelete-null-pointer-checks  -fdse  -fearly-inlining @gol
--fexpensive-optimizations  -ffast-math  -ffloat-store @gol
--fforce-addr  -fforward-propagate  -ffunction-sections @gol
--fgcse  -fgcse-lm  -fgcse-sm  -fgcse-las  -fgcse-after-reload @gol
--fcrossjumping  -fif-conversion  -fif-conversion2 @gol
--finline-functions  -finline-functions-called-once @gol
--finline-small-functions -finline-limit=@var{n}  -fkeep-inline-functions @gol
--fkeep-static-consts  -fmerge-constants  -fmerge-all-constants @gol
--fmodulo-sched -fmodulo-sched-allow-regmoves -fno-branch-count-reg @gol
--fno-default-inline  -fno-defer-pop -fmove-loop-invariants @gol
--fno-function-cse  -fno-guess-branch-probability @gol
--fno-inline  -fno-math-errno  -fno-peephole  -fno-peephole2 @gol
--funsafe-math-optimizations  -funsafe-loop-optimizations @gol
--ffinite-math-only  -fno-signed-zeros @gol
--fno-toplevel-reorder -fno-trapping-math  -fno-zero-initialized-in-bss @gol
--fomit-frame-pointer  -foptimize-register-move @gol
--foptimize-sibling-calls  -fpredictive-commoning -fprefetch-loop-arrays @gol
--fprofile-generate -fprofile-use @gol
--fregmove  -frename-registers @gol
--freorder-blocks  -freorder-blocks-and-partition -freorder-functions @gol
--frerun-cse-after-loop @gol
--frounding-math -frtl-abstract-sequences @gol
--fschedule-insns  -fschedule-insns2 @gol
--fno-sched-interblock  -fno-sched-spec  -fsched-spec-load @gol
--fsched-spec-load-dangerous  @gol
--fsched-stalled-insns[=@var{n}] -fsched-stalled-insns-dep[=@var{n}] @gol
--fsched2-use-superblocks @gol
--fsched2-use-traces -fsee -freschedule-modulo-scheduled-loops @gol
--fsection-anchors  -fsignaling-nans  -fsingle-precision-constant @gol
--fsplit-wide-types -fstack-protector  -fstack-protector-all @gol
--fstrict-aliasing  -fstrict-overflow  -ftracer  -fthread-jumps @gol
--funroll-all-loops  -funroll-loops  -fpeel-loops @gol
--fsplit-ivs-in-unroller -funswitch-loops @gol
--fvariable-expansion-in-unroller -ftree-reassoc @gol
--ftree-pre  -ftree-ccp  -ftree-dce -ftree-loop-optimize @gol
--ftree-loop-linear -ftree-loop-im -ftree-loop-ivcanon -fivopts @gol
--fcheck-data-deps -ftree-parallelize-loops=@var{n} @gol
--ftree-dominator-opts -ftree-dse -ftree-copyrename -ftree-sink @gol
--ftree-ch -ftree-sra -ftree-ter -ftree-fre -ftree-vectorize @gol
--ftree-vect-loop-version -fvect-cost-model -ftree-salias -fipa-pta -fweb @gol
--ftree-copy-prop -ftree-store-ccp -ftree-vrp @gol
--funit-at-a-time -fwhole-program @gol
+@gccoptlist{
+-falign-functions[=@var{n}] -falign-jumps[=@var{n}] @gol
+-falign-labels[=@var{n}] -falign-loops[=@var{n}] -fassociative-math @gol
+-fauto-inc-dec -fbranch-probabilities -fbranch-target-load-optimize @gol
+-fbranch-target-load-optimize2 -fbtr-bb-exclusive -fcaller-saves @gol
+-fcheck-data-deps -fcprop-registers -fcrossjumping -fcse-follow-jumps @gol
+-fcse-skip-blocks -fcx-limited-range -fdata-sections -fdce -fdce @gol
+-fdelayed-branch -fdelete-null-pointer-checks -fdse -fdse @gol
+-fearly-inlining -fexpensive-optimizations -ffast-math @gol
+-ffinite-math-only -ffloat-store -fforce-addr -fforward-propagate @gol
+-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
+-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
+-fmudflapir -fmudflapth -fno-branch-count-reg -fno-default-inline @gol
+-fno-defer-pop -fno-function-cse -fno-guess-branch-probability @gol
+-fno-inline -fno-math-errno -fno-peephole -fno-peephole2 @gol
+-fno-sched-interblock -fno-sched-spec -fno-signed-zeros @gol
+-fno-toplevel-reorder -fno-trapping-math -fno-zero-initialized-in-bss @gol
+-fomit-frame-pointer -foptimize-register-move -foptimize-sibling-calls @gol
+-fpeel-loops -fpredictive-commoning -fprefetch-loop-arrays @gol
+-fprofile-generate -fprofile-use -fprofile-values -freciprocal-math @gol
+-fregmove -frename-registers -freorder-blocks @gol
+-freorder-blocks-and-partition -freorder-functions @gol
+-frerun-cse-after-loop -freschedule-modulo-scheduled-loops @gol
+-frounding-math -frtl-abstract-sequences -fsched2-use-superblocks @gol
+-fsched2-use-traces -fsched-spec-load -fsched-spec-load-dangerous @gol
+-fsched-stalled-insns-dep[=@var{n}] -fsched-stalled-insns[=@var{n}] @gol
+-fschedule-insns -fschedule-insns2 -fsection-anchors -fsee @gol
+-fsignaling-nans -fsingle-precision-constant -fsplit-ivs-in-unroller @gol
+-fsplit-wide-types -fstack-protector -fstack-protector-all @gol
+-fstrict-aliasing -fstrict-overflow -fthread-jumps -ftracer -ftree-ccp @gol
+-ftree-ch -ftree-copy-prop -ftree-copyrename -ftree-dce @gol
+-ftree-dominator-opts -ftree-dse -ftree-fre -ftree-loop-im @gol
+-ftree-loop-ivcanon -ftree-loop-linear -ftree-loop-optimize @gol
+-ftree-parallelize-loops=@var{n} -ftree-pre -ftree-reassoc -ftree-salias @gol
+-ftree-sink -ftree-sra -ftree-store-ccp -ftree-ter @gol
+-ftree-vect-loop-version -ftree-vectorize -ftree-vrp -funit-at-a-time @gol
+-funroll-all-loops -funroll-loops -funsafe-loop-optimizations @gol
+-funsafe-math-optimizations -funswitch-loops @gol
+-fvariable-expansion-in-unroller -fvect-cost-model -fvpt -fweb @gol
+-fwhole-program @gol
 --param @var{name}=@var{value}
 -O  -O0  -O1  -O2  -O3  -Os}
 
@@ -5027,27 +5021,31 @@ time, without performing any optimizatio
 compilation time.
 
 @option{-O} turns on the following optimization flags:
-@gccoptlist{-fdefer-pop @gol
--fdelayed-branch @gol
--fguess-branch-probability @gol
+@gccoptlist{
+-fauto-inc-dec @gol
 -fcprop-registers @gol
 -fdce @gol
+-fdefer-pop @gol
+-fdelayed-branch @gol
 -fdse @gol
--fif-conversion @gol
+-fguess-branch-probability @gol
 -fif-conversion2 @gol
+-fif-conversion @gol
+-finline-small-functions @gol
+-fipa-pure-const @gol
+-fipa-reference @gol
+-fmerge-constants
 -fsplit-wide-types @gol
 -ftree-ccp @gol
+-ftree-ch @gol
+-ftree-copyrename @gol
 -ftree-dce @gol
 -ftree-dominator-opts @gol
 -ftree-dse @gol
--ftree-ter @gol
--ftree-sra @gol
--ftree-copyrename @gol
 -ftree-fre @gol
--ftree-ch @gol
--funit-at-a-time @gol
--finline-small-functions @gol
--fmerge-constants}
+-ftree-sra @gol
+-ftree-ter @gol
+-funit-at-a-time}
 
 @option{-O} also turns on @option{-fomit-frame-pointer} on machines
 where doing so does not interfere with debugging.
@@ -5063,24 +5061,24 @@ and the performance of the generated cod
 @option{-O2} turns on all optimization flags specified by @option{-O}.  It
 also turns on the following optimization flags:
 @gccoptlist{-fthread-jumps @gol
+-falign-functions  -falign-jumps @gol
+-falign-loops  -falign-labels @gol
+-fcaller-saves @gol
 -fcrossjumping @gol
--foptimize-sibling-calls @gol
 -fcse-follow-jumps  -fcse-skip-blocks @gol
--fgcse  -fgcse-lm  @gol
+-fdelete-null-pointer-checks @gol
 -fexpensive-optimizations @gol
--frerun-cse-after-loop  @gol
--fcaller-saves @gol
+-fgcse  -fgcse-lm  @gol
+-foptimize-sibling-calls @gol
 -fpeephole2 @gol
--fschedule-insns  -fschedule-insns2 @gol
--fsched-interblock  -fsched-spec @gol
 -fregmove @gol
--fstrict-aliasing -fstrict-overflow @gol
--fdelete-null-pointer-checks @gol
 -freorder-blocks  -freorder-functions @gol
--falign-functions  -falign-jumps @gol
--falign-loops  -falign-labels @gol
--ftree-vrp @gol
--ftree-pre}
+-frerun-cse-after-loop  @gol
+-fsched-interblock  -fsched-spec @gol
+-fschedule-insns  -fschedule-insns2 @gol
+-fstrict-aliasing -fstrict-overflow @gol
+-ftree-pre @gol
+-ftree-vrp}
 
 Please note the warning under @option{-fgcse} about
 invoking @option{-O2} on programs that use computed gotos.
@@ -5485,6 +5483,13 @@ resulting code may or may not perform be
 
 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
 
+@item -fauto-inc-dec
+@opindex fauto-inc-dec
+Combine increments or decrements of addresses with memory accesses.
+This pass is always skipped on architectures that do not have
+instructions to support this.  Enabled by default at @option{-O} and
+higher on architectures that support this.
+
 @item -fdce
 @opindex fdce
 Perform dead code elimination (DCE) on RTL.
@@ -5694,6 +5699,17 @@ higher.
 Perform structural alias analysis on trees.  This flag
 is enabled by default at @option{-O} and higher.
 
+@item -fipa-pure-const
+@opindex fipa-pure-const
+Discover which functions are pure or constant.
+Enabled by default at @option{-O} and higher.
+
+@item -fipa-reference
+@opindex fipa-reference
+Discover which static variables do not escape cannot escape the
+compilation unit.
+Enabled by default at @option{-O} and higher.
+
 @item -fipa-pta
 @opindex fipa-pta
 Perform interprocedural pointer analysis.
Index: common.opt
===================================================================
--- common.opt	(revision 129907)
+++ common.opt	(working copy)
@@ -18,7 +18,7 @@
 ; along with GCC; see the file COPYING3.  If not see
 ; <http://www.gnu.org/licenses/>.
 
-; See the GCC internals manual for a description of this file's format.
+; See the GCC internals manual (options.texi) for a description of this file's format.
 
 ; Please try to keep this file in ASCII collating order.
 

Re: undocumented optimization options

[Richard Guenther]

On 11/5/07, Kenneth Zadeck <zadeck@naturalbridge.com> wrote:
> Janis Johnson 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
> >   -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
> >
> >
> >
> This patch gets me off of janis's bad list (or at least the one
> associated with undocumented options).  As directed by diego, I sorted
> the option lists for -O, -Os and -O2 since this had rotted.
>
> 2007-11-05  Kenneth Zadeck <zadeck@naturalbridge.com>
>
>     * common.opt: Add pointer to doc/options.texi.
>     * doc/invoke.texi (-fdse, -fdce, -fauto-inc-dec, -fipa-pure-const,
>     -fipa-reference): Add or correct doc.  Sorted options list for -Os
>     -O, -O2.
>
> Ok to commit?

Ok, thanks.
Richard.

> Kenny
>
>
>

Re: undocumented optimization options

[Kenneth Zadeck]

Richard Guenther wrote:
> On 11/5/07, Kenneth Zadeck <zadeck@naturalbridge.com> wrote:
>   
>> Janis Johnson 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
>>>   -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
>>>
>>>
>>>
>>>       
>> This patch gets me off of janis's bad list (or at least the one
>> associated with undocumented options).  As directed by diego, I sorted
>> the option lists for -O, -Os and -O2 since this had rotted.
>>
>> 2007-11-05  Kenneth Zadeck <zadeck@naturalbridge.com>
>>
>>     * common.opt: Add pointer to doc/options.texi.
>>     * doc/invoke.texi (-fdse, -fdce, -fauto-inc-dec, -fipa-pure-const,
>>     -fipa-reference): Add or correct doc.  Sorted options list for -Os
>>     -O, -O2.
>>
>> Ok to commit?
>>     
>
> Ok, thanks.
> Richard.
>
>   
>> Kenny
>>
>>
>>
>>     
committed as revision 130000

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

[Manfred Hollstein]

On Tue, 20 Nov 2007, 12:32:54 +0100, Razya Ladelsky wrote:
> [...]
> Thanks.
> Described these two optimizations in more detail.
> O.K now?

Sorry, two typos:

> +Transpoing is enabled only if profiling information is avaliable.

This should probably read:

  +Transposing is enabled only if profiling information is available.

Cheers.

l8er
manfred

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

[Ian Lance Taylor]

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

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

Sorry, I missed the later discussion.

Yes, more detailed documentation would certainly be better.  This is a
user manual.

But if the choice is between bad documentation and no documentation,
bad documentation is better.

Ian