Re: [patch, doc] documenting new options

[Olga Golovanevsky <OLGA at il dot ibm dot com>]

Diego Novillo <dnovillo@google.com> wrote on 06/12/2007 17:41:06:

> On 12/06/07 09:14, Olga Golovanevsky wrote:
> >
> > +@item -fipa-struct-reorg
> > +@opindex fipa-struct-reorg
> > +Perform structure reorganization optimization, that change C-like
> > structures
> > +layout in order to better utilize spatial locality. Effective for
programs
>
> Two spaces after '.'.  This occurs in several places.

done.

> s/Effective for/This transformation is effective/

done.

>
> > +containing arrays of structures. Available in two compilation modes:
> > +profile-based, as with @option{-fprofile-generate} and @option
>     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> profile-based (enabled with @option{-fprofile-generate})

done.

>
> > {-fprofile-use},
> > +or static. Require @option{-fipa-type-escape} to provide the safety of
>     ^^^^^^^^^
> or static (which uses built-in heuristics).

done.

>
> > +transformations. Work as whole program optimization, i.e. require
> > +@option{-fwhole-program} and @option{-combine} flags.
>
> The transformation works only in whole program mode, so it requires
> @option{-fwhole-program} and @option{-combine} to be enabled.

done.

>
> > Cold structures
> > +can remain intact through
> > +@option{--param struct-reorg-cold-struct-ratio=@var{value}} option.
>
> I'm not sure what you meant to say here.  Perhaps "Structures considered
> "cold" by the transformation are not affected (see @option{--param
> struct-reorg-cold-struct-ratio=@var{value}})."

done.

>
>
> > +
> > +With this flag, the program debug info reflects a new structure
layout.
> > +
> >  @item -fipa-pta
> >  @opindex fipa-pta
> >  Perform interprocedural pointer analysis.
> > @@ -6624,6 +6638,13 @@ of bytes in instantiated fields to the n
> >  structure exceeds this parameter, then block copies are not used.
The.
> >  default is 75.
> >
> > +@item struct-reorg-cold-struct-ratio
> > +The threshold ratio between current and hotest structure counts
>
> s/hotest/hottest/

done.

>
> > +used by @option{-fipa-struct-reorg}. We say that if the ratio of
> > +the current structure count, calculated by profiling, to the hotest
>
> What is "current structure count"?

I rephrased it without "current structure count", using
"structure frequency".

>
> s/hotest/hottest/

done.

>
> > +structure count in the program is less than this parameter, then
> > +structure reorganization is not applied. The default is 10.
> > +
>
>
> Diego.

Any further comments?

Ok for mainline?

Olga

2007-12-09  Olga Golovanevsky  <olga@il.ibm.com>

      * doc/invoke.texi (Optimize Options): Document new -fipa-struct-reorg
      option and struct-reorg-cold-struct-ratio parameter.

Index: invoke.texi
===================================================================
--- invoke.texi   (revision 130578)
+++ invoke.texi   (working copy)
@@ -329,13 +329,13 @@ Objective-C and Objective-C++ Dialects}.
 -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
+-fipa-struct-reorg -fipa-type-escape -fivopts -fkeep-inline-functions @gol
+-fkeep-static-consts -fmerge-all-constants -fmerge-constants @gol
+-fmodulo-sched -fmodulo-sched-allow-regmoves -fmove-loop-invariants @gol
+-fmudflap -fmudflapir -fmudflapth -fno-branch-count-reg @gol
+-fno-default-inline -fno-defer-pop -fno-function-cse @gol
+-fno-guess-branch-probability -fno-inline -fno-math-errno -fno-peephole
@gol
+-fno-peephole2 -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
@@ -5711,6 +5711,20 @@ Discover which static variables do not e
 compilation unit.
 Enabled by default at @option{-O} and higher.

+@item -fipa-struct-reorg
+@opindex fipa-struct-reorg
+Perform structure reorganization optimization, that change C-like
structures
+layout in order to better utilize spatial locality.  This transformation
is
+effective for programs containing arrays of structures.  Available in two
+compilation modes: profile-based (enabled with @option
{-fprofile-generate})
+or static (which uses built-in heuristics).  Require @option
{-fipa-type-escape}
+to provide the safety of this transformation.  It works only in whole
program
+mode, so it requires @option{-fwhole-program} and @option{-combine} to be
+enabled.  Structures considered @samp{cold} by this transformation are not
+effected (see @option{--param struct-reorg-cold-struct-ratio=@var
{value}}).
+
+With this flag, the program debug info reflects a new structure
layout.}}).
+
 @item -fipa-pta
 @opindex fipa-pta
 Perform interprocedural pointer analysis.
@@ -6624,6 +6638,15 @@ of bytes in instantiated fields to the n
 structure exceeds this parameter, then block copies are not used.
The.}}).
 default is 75.

+@item struct-reorg-cold-struct-ratio
+The threshold ratio (as a percentage) between a structure frequency
+and the frequiency of the hottest structure in the program.  This
parameter
+is used by struct-reorg optimization enabaled by @option
{-fipa-struct-reorg.
+We say that if the ratio of a structure frequency, calculated by
profiling,
+to the hottest structure frequency in the program is less than this
+parameter, then structure reorganization is not applied to this
structure.,
+The default is 10.
+
 @item max-crossjump-edges
 The maximum number of incoming edges to consider for crossjumping.
 The algorithm used by @option{-fcrossjumping} is @math{O(N^2)} in.