[RFC] Come up with ipa passes introduction in gccint documentation

[RFC] Come up with ipa passes introduction in gccint documentation

[Xiong Hu Luo]

There is no ipa passes introduction in gccint now, is it nessessary to
add this part as both GIMPLE passes and RTL passes breif intruduction
already exit in Chapter 9 "Passes and Files of the Compiler" but no
section for ipa passes?
If it's OK, this is just a framework, lots of words need be filled into
each item.

ChangeLog:
	* doc/lto.texi (IPA): Reference to the IPA passes.
	* doc/passes.texi (Tree SSA passes): Add node IPA passes.
---
 gcc/doc/lto.texi    |  6 ++---
 gcc/doc/passes.texi | 62 +++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 65 insertions(+), 3 deletions(-)

diff --git a/gcc/doc/lto.texi b/gcc/doc/lto.texi
index 771e8278e50..ae48e617ea1 100644
--- a/gcc/doc/lto.texi
+++ b/gcc/doc/lto.texi
@@ -350,8 +350,9 @@ while the @emph{Read summary}, @emph{Execute}, and
 @end itemize
 
 To simplify development, the GCC pass manager differentiates
-between normal inter-procedural passes and small inter-procedural
-passes.  A @emph{small inter-procedural pass}
+between normal inter-procedural passes @pxref{All regular ipa passes}
+and small inter-procedural passes@pxref{All small ipa passes}
+& @pxref{All late ipa passes}. A @emph{small inter-procedural pass}
 (@code{SIMPLE_IPA_PASS}) is a pass that does
 everything at once and thus it cannot be executed during WPA in
 WHOPR mode.  It defines only the @emph{Execute} stage and during
@@ -362,7 +363,6 @@ object files.  The simple inter-procedural passes can also be used
 for easier prototyping and development of a new inter-procedural
 pass.
 
-
 @subsection Virtual clones
 
 One of the main challenges of introducing the WHOPR compilation
diff --git a/gcc/doc/passes.texi b/gcc/doc/passes.texi
index 6edb9a0bfb7..0b6cf73469c 100644
--- a/gcc/doc/passes.texi
+++ b/gcc/doc/passes.texi
@@ -21,6 +21,7 @@ where near complete.
 * Gimplification pass::  The bits are turned into something we can optimize.
 * Pass manager::         Sequencing the optimization passes.
 * Tree SSA passes::      Optimizations on a high-level representation.
+* IPA passes::           Optimizations on scope of intra-procedual.
 * RTL passes::           Optimizations on a low-level representation.
 * Optimization info::    Dumping optimization information from passes.
 @end menu
@@ -651,6 +652,67 @@ registers don't need to be saved.  This pass is located in
 
 @end itemize
 
+@node IPA passes
+@section IPA passes
+@cindex ipa passes
+The following briefly describes the IPA optimization
+passes including all small ipa passes, all regular ipa passes and all
+late ipa passes.
+
+@node All small ipa passes
+@subsection All small ipa passes
+@cindex all small ipa passes
+
+@itemize @bullet
+@item ipa free lang data
+@item ipa function and variable visibility
+@item ipa remove symbols
+@item ipa oacc
+@item ipa pta
+@item ipa oacc kernels
+@item target clone
+@item ipa auto profile
+@item ipa tree profile
+@item ipa free fn summary
+@item ipa increase alignment
+@item ipa tm
+@item ipa lower emutls
+@end itemize
+
+@node All regular ipa passes
+@subsection All regular ipa passes
+@cindex all regular ipa passes
+
+@itemize @bullet
+@item ipa whole program visiblity
+@item ipa profile
+@item ipa icf
+@item ipa devirt
+@item ipa cp
+@item ipa cdtor merge
+@item ipa hsa
+@item ipa fn summary
+@item ipa inline
+@item ipa pure const
+@item ipa free fn summary
+@item ipa reference
+@item ipa single use
+@item ipa comdats
+@end itemize
+
+@node All late ipa passes
+@subsection All late ipa passes
+@cindex all late ipa passes
+All late ipa passes are also simple IPA passes executed after
+the regular passes.  In WHOPR mode the passes are executed after
+partitioning and thus see just parts of the compiled unit.
+
+@itemize @bullet
+@item pass materialize all clones
+@item pass ipa pta
+@item pass omp simd clone
+@end itemize
+
 @node RTL passes
 @section RTL passes
 
-- 
2.21.0.777.g83232e3864

Re: [RFC] Come up with ipa passes introduction in gccint documentation

[Segher Boessenkool]

Hi!

Just some editorial comments...  The idea of the patch is fine IMHO.
(I am not maintainer of this, take all my comments for what they are).

On Sun, Sep 29, 2019 at 02:56:37AM -0500, Xiong Hu Luo wrote:
>  To simplify development, the GCC pass manager differentiates
> -between normal inter-procedural passes and small inter-procedural
> -passes.  A @emph{small inter-procedural pass}
> +between normal inter-procedural passes @pxref{All regular ipa passes}
> +and small inter-procedural passes@pxref{All small ipa passes}
> +& @pxref{All late ipa passes}. A @emph{small inter-procedural pass}
>  (@code{SIMPLE_IPA_PASS}) is a pass that does

To simplify development, the GCC pass manager differentiates
between normal inter-procedural passes @pxref{All regular IPA passes},
simple inter-procedural passes@pxref{All simple IPA passes},
and late inter-procedural passes @pxref{All late IPA passes}.
A @emph{simple inter-procedural pass}
(@code{SIMPLE_IPA_PASS}) is a pass that does

Don't use "&", write out the word.  IPA is an abbreviation, not a word,
so it should be written in all caps.  Enumerations are written like this,
that, and something else.  Is there a reason you used "small" instead of
"simple"?

> diff --git a/gcc/doc/passes.texi b/gcc/doc/passes.texi
> index 6edb9a0bfb7..0b6cf73469c 100644
> --- a/gcc/doc/passes.texi
> +++ b/gcc/doc/passes.texi
> @@ -21,6 +21,7 @@ where near complete.
>  * Gimplification pass::  The bits are turned into something we can optimize.
>  * Pass manager::         Sequencing the optimization passes.
>  * Tree SSA passes::      Optimizations on a high-level representation.
> +* IPA passes::           Optimizations on scope of intra-procedual.
>  * RTL passes::           Optimizations on a low-level representation.

I'd just say "Intra-procedural optimizations."  And maybe order this
differntly?  IPA, SSA, RTL, the same order as they run, and this also
keeps the "high/low-level representation" together, which reads a bit
better.

The rest should be worked out a bit more, but looks promising.

Did you test this with both "make info" and "make pdf" (and checked the
result of those of course :-) )?

Thanks,


Segher

Re: [RFC] Come up with ipa passes introduction in gccint documentation

[luoxhu]

Hi Segher,

On 2019/9/30 00:17, Segher Boessenkool wrote:
> Hi!
> 
> Just some editorial comments...  The idea of the patch is fine IMHO.
> (I am not maintainer of this, take all my comments for what they are).
> 
> On Sun, Sep 29, 2019 at 02:56:37AM -0500, Xiong Hu Luo wrote:
>>   To simplify development, the GCC pass manager differentiates
>> -between normal inter-procedural passes and small inter-procedural
>> -passes.  A @emph{small inter-procedural pass}
>> +between normal inter-procedural passes @pxref{All regular ipa passes}
>> +and small inter-procedural passes@pxref{All small ipa passes}
>> +& @pxref{All late ipa passes}. A @emph{small inter-procedural pass}
>>   (@code{SIMPLE_IPA_PASS}) is a pass that does
> 
> To simplify development, the GCC pass manager differentiates
> between normal inter-procedural passes @pxref{All regular IPA passes},
> simple inter-procedural passes@pxref{All simple IPA passes},
> and late inter-procedural passes @pxref{All late IPA passes}.
> A @emph{simple inter-procedural pass}
> (@code{SIMPLE_IPA_PASS}) is a pass that does
> 
> Don't use "&", write out the word.  IPA is an abbreviation, not a word,
> so it should be written in all caps.  Enumerations are written like this,
> that, and something else.  Is there a reason you used "small" instead of
> "simple"?

The updated output will be as below in gccint.pdf, references are valid to jump over
(suppose should be the same in info?):


To simplify development, the GCC pass manager differentiates between normal interprocedural
passes see Section 9.4.2 [All regular IPA passes], page 127, small inter-procedural
passes see Section 9.4.1 [All small IPA passes], page 127 and late inter-procedural passes see
Section 9.4.3 [All late IPA passes], page 128. A small inter-procedural pass (SIMPLE_IPA_
PASS) is a pass that does everything at once and thus it cannot be executed during WPA
in WHOPR mode. It defines only the Execute stage and during this stage it accesses and
modifies the function bodies. Such passes are useful for optimization at LGEN or LTRANS
time and are used, for example, to implement early optimization before writing object files.
The simple inter-procedural passes can also be used for easier prototyping and development
of a new inter-procedural pass.

And:

9.4 IPA passes
The following briefly describes the IPA optimization passes including all small IPA passes,
all regular IPA passes and all late IPA passes.
9.4.1 All small IPA passes
\x0f \x0fipa free lang data
\x0f ipa function and variable visibility
\x0f ipa remove symbols
....


The reason for "small" is in passes.def, it is used as 
INSERT_PASSES_AFTER (all_small_ipa_passes).  And in cgraphunit.c:
ipa_passes (void)
{
... 
  execute_ipa_pass_list (passes->all_small_ipa_passes);
...
}

So is it OK to use small here?

Thanks and welcome for other inputs.
One more thing to worry about is my poor English and I am not familiar with all the
30+ IPA passes so not easy to extract exact explanations for them. 

Xiong Hu
BR

> 
>> diff --git a/gcc/doc/passes.texi b/gcc/doc/passes.texi
>> index 6edb9a0bfb7..0b6cf73469c 100644
>> --- a/gcc/doc/passes.texi
>> +++ b/gcc/doc/passes.texi
>> @@ -21,6 +21,7 @@ where near complete.
>>   * Gimplification pass::  The bits are turned into something we can optimize.
>>   * Pass manager::         Sequencing the optimization passes.
>>   * Tree SSA passes::      Optimizations on a high-level representation.
>> +* IPA passes::           Optimizations on scope of intra-procedual.
>>   * RTL passes::           Optimizations on a low-level representation.
> 
> I'd just say "Intra-procedural optimizations."  And maybe order this
> differntly?  IPA, SSA, RTL, the same order as they run, and this also
> keeps the "high/low-level representation" together, which reads a bit
> better.
> 
> The rest should be worked out a bit more, but looks promising.
> 
> Did you test this with both "make info" and "make pdf" (and checked the
> result of those of course :-) )?
> 
> Thanks,
> 
> 
> Segher
> 

Re: [RFC] Come up with ipa passes introduction in gccint documentation

[Martin Jambor]

Hi,

I agree that we should have a chapter on IPA passes in gccint, just
please note that...

On Sun, Sep 29 2019, Xiong Hu Luo wrote:
> There is no ipa passes introduction in gccint now, is it nessessary to
> add this part as both GIMPLE passes and RTL passes breif intruduction
> already exit in Chapter 9 "Passes and Files of the Compiler" but no
> section for ipa passes?
> If it's OK, this is just a framework, lots of words need be filled into
> each item.
>
> ChangeLog:
> 	* doc/lto.texi (IPA): Reference to the IPA passes.
> 	* doc/passes.texi (Tree SSA passes): Add node IPA passes.
> ---
>  gcc/doc/lto.texi    |  6 ++---
>  gcc/doc/passes.texi | 62 +++++++++++++++++++++++++++++++++++++++++++++
>  2 files changed, 65 insertions(+), 3 deletions(-)
>

...

> diff --git a/gcc/doc/passes.texi b/gcc/doc/passes.texi
> index 6edb9a0bfb7..0b6cf73469c 100644
> --- a/gcc/doc/passes.texi
> +++ b/gcc/doc/passes.texi
> @@ -21,6 +21,7 @@ where near complete.
>  * Gimplification pass::  The bits are turned into something we can optimize.
>  * Pass manager::         Sequencing the optimization passes.
>  * Tree SSA passes::      Optimizations on a high-level representation.
> +* IPA passes::           Optimizations on scope of intra-procedual.

...IPA stands for inter (not intra!) procedural analysis.

Martin

Re: [RFC] Come up with ipa passes introduction in gccint documentation

[Segher Boessenkool]

Hi!

On Mon, Sep 30, 2019 at 09:47:13AM +0800, luoxhu wrote:
> On 2019/9/30 00:17, Segher Boessenkool wrote:
> The updated output will be as below in gccint.pdf, references are valid to jump over
> (suppose should be the same in info?):

> > Did you test this with both "make info" and "make pdf" (and checked the
> > result of those of course :-) )?

The reason I ask is, there often are little mistakes (in markup for example)
that are obvious in either rendered output or in the info reader (but not
(always) in both).  Not just the content, also the way things are laid out,
and what makes a link to what, etc.

> To simplify development, the GCC pass manager differentiates between normal interprocedural
> passes see Section 9.4.2 [All regular IPA passes], page 127, small inter-procedural
> passes see Section 9.4.1 [All small IPA passes], page 127 and late inter-procedural passes see
> Section 9.4.3 [All late IPA passes], page 128. A small inter-procedural pass (SIMPLE_IPA_

It is weird to have a different order here than the order of the actual
sections, for example.

> The reason for "small" is in passes.def, it is used as 
> INSERT_PASSES_AFTER (all_small_ipa_passes).  And in cgraphunit.c:
> ipa_passes (void)
> {
> ... 
>   execute_ipa_pass_list (passes->all_small_ipa_passes);
> ...
> }
> 
> So is it OK to use small here?

I don't mind if it is "small" or "simple", but we probably should use the
same name everywhere in the manual (or, if we use both names, explain that
they are the same thing).

There are many cases where the internal name (in the GCC source code, in
pass names, etc.) is different from the external name (in the manuals, in
option names, etc.)  It is hard to decide what to use in the internals
manual then :-)  Maybe the internal name should just be changed?

> One more thing to worry about is my poor English

It's perfectly good enough that we understand what you are saying :-)

> and I am not familiar with all the
> 30+ IPA passes so not easy to extract exact explanations for them. 

Yeah...  It's a good start to just have stubs for them, I guess?  Makes
it obvious things need to be filled out, so hopefully people will :-)


Segher

Re: [PATCH] Come up with ipa passes introduction in gccint documentation

[luoxhu]

Hi,

This is the formal documentation patch for IPA passes.  Thanks.


None of the IPA passes are documented in passes.texi.  This patch adds
a section IPA passes just before GIMPLE passes and RTL passes in
Chapter 9 "Passes and Files of the Compiler".  Also, a short description
for each IPA pass is provided.
gccint.pdf can be produced without errors.

ChangeLog:
	PR middle-end/26241
	* doc/lto.texi (IPA): Reference to the IPA passes.
	* doc/passes.texi (Pass manager): Add node IPA passes and
	  description for each IPA pass.
---
 gcc/doc/lto.texi    |   7 +-
 gcc/doc/passes.texi | 241 ++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 245 insertions(+), 3 deletions(-)

diff --git a/gcc/doc/lto.texi b/gcc/doc/lto.texi
index 771e8278e50..1afb6eb4a98 100644
--- a/gcc/doc/lto.texi
+++ b/gcc/doc/lto.texi
@@ -350,8 +350,10 @@ while the @emph{Read summary}, @emph{Execute}, and
 @end itemize
 
 To simplify development, the GCC pass manager differentiates
-between normal inter-procedural passes and small inter-procedural
-passes.  A @emph{small inter-procedural pass}
+between normal inter-procedural passes (@pxref{All regular IPA passes}),
+small inter-procedural passes (@pxref{All small IPA passes})
+and late inter-procedural passes (@pxref{All late IPA passes}).
+A @emph{small inter-procedural pass}
 (@code{SIMPLE_IPA_PASS}) is a pass that does
 everything at once and thus it cannot be executed during WPA in
 WHOPR mode.  It defines only the @emph{Execute} stage and during
@@ -362,7 +364,6 @@ object files.  The simple inter-procedural passes can also be used
 for easier prototyping and development of a new inter-procedural
 pass.
 
-
 @subsection Virtual clones
 
 One of the main challenges of introducing the WHOPR compilation
diff --git a/gcc/doc/passes.texi b/gcc/doc/passes.texi
index 6edb9a0bfb7..3f9106d60c3 100644
--- a/gcc/doc/passes.texi
+++ b/gcc/doc/passes.texi
@@ -20,6 +20,7 @@ where near complete.
 * Parsing pass::         The language front end turns text into bits.
 * Gimplification pass::  The bits are turned into something we can optimize.
 * Pass manager::         Sequencing the optimization passes.
+* IPA passes::           Inter-procedural optimizations.
 * Tree SSA passes::      Optimizations on a high-level representation.
 * RTL passes::           Optimizations on a low-level representation.
 * Optimization info::    Dumping optimization information from passes.
@@ -178,6 +179,246 @@ TODO: describe the global variables set up by the pass manager,
 and a brief description of how a new pass should use it.
 I need to look at what info RTL passes use first@enddots{}
 
+@node IPA passes
+@section IPA passes
+@cindex IPA passes
+The following briefly describes the IPA optimization passes including
+all small IPA passes, all regular IPA passes and all late IPA passes.
+
+@node All small IPA passes
+@subsection All small IPA passes
+@cindex all small ipa passes
+A small IPA pass is a pass derived from @code{simple_ipa_opt_pass}
+that does everything at once and thus it cannot be executed during WPA
+in WHOPR mode.  It defines only the @emph{Execute} stage and during this
+stage it accesses and modifies the function bodies.  No @code{generate_summary}
+@code{read_summary} or @code{write_summary} hooks defined.
+
+@itemize @bullet
+@item IPA free lang data
+
+This pass free resources that are used by FE but are not needed once
+they are done.  It is located in @file{tree.c} and is described by
+@code{pass_ipa_free_lang_data}.
+
+@item IPA function and variable visibility
+
+This is a local function pass handling visibilities of all symbols.  This
+happens before LTO streaming so in particular -fwhole-program should be ignored
+at this level.  It is located in @file{ipa-visibility.c} and is described by
+@code{pass_ipa_function_and_variable_visibility}.
+
+@item IPA remove symbols
+
+This pass performs reachability analysis and reclaim all unreachable nodes.
+It is located in @file{passes.c} and is described by
+@code{pass_ipa_remove_symbols}.
+
+@item IPA oacc
+
+It is located in @file{tree-ssa-loop.c} and is described by
+@code{pass_ipa_oacc}.
+
+@item IPA pta
+
+This is a tree based points-to analysis pass. The idea behind this analyzer
+is to generate set constraints from the program, then solve the resulting
+constraints in order to generate the points-to sets.  It is located in 
+@file{tree-ssa-structalias.c} and is described by @code{pass_ipa_pta}.
+
+@item IPA oacc kernels
+
+This pass is for processing oacc kernels.  It is located in @file{tree-ssa-loop.c}
+and is described by @code{pass_ipa_oacc_kernels}.
+
+@item Target clone
+
+This is a pass for parsing functions with multiple target attributes.
+It is located in @file{multiple_target.c} and is described by
+@code{pass_target_clone}.
+
+@item IPA auto profile
+
+This pass uses AutoFDO profile to annotate the control flow graph.
+It is located in @file{auto-profile.c} and is described by
+@code{pass_ipa_auto_profile}.
+
+@item IPA tree profile
+
+This pass do profiling for all functions in the callgraph. It calculates branch
+probabilities and basic block execution counts. It is located
+in @file{tree-profile.c} and is described by @code{pass_ipa_tree_profile}.
+
+@item IPA free fn summary
+
+This pass is a small ipa pass when argument @code{small_p} is true.
+It releases inline function summaries and call summaries.
+It is located in @file{ipa-fnsummary.c} and is described by
+@code{pass_ipa_free_free_fn_summary}.
+
+@item IPA increase alignment
+
+This pass could increase the alignment of all global arrays
+for vectorization. It is located in @file{tree-vectorizer.c}
+and is described by @code{pass_ipa_increase_alignment}.
+
+@item IPA tm
+
+This pass is for transactional memory support.
+It is located in @file{trans-mem.c} and is described by
+@code{pass_ipa_tm}.
+
+@item IPA lower emutls
+
+This pass could lower thread-local storage (TLS) operations
+to emulation functions with some run-time support in libgcc.
+It is located in @file{tree-emutls.c} and is described by
+@code{pass_ipa_lower_emutls}.
+
+@end itemize
+
+@node All regular IPA passes
+@subsection All regular IPA passes
+@cindex All regular ipa passes
+A regular IPA pass is a pass derived from @code{ipa_opt_pass_d}
+that is executed in WHOPR compilation. They may have summary hooks
+implemented in any LGEN, WPA or LTRANS stage(@pxref{IPA}).
+
+@itemize @bullet
+@item IPA whole program visiblity
+
+This pass brings functions local at LTO time with -fwhole-program.
+It is located in @file{ipa-visibility.c} and is described by
+@code{pass_ipa_whole_program_visibility}.
+
+@item IPA profile
+
+The IPA profile pass propagates frequencies across the call graph
+based on profile.  It is located in @file{ipa-profile.c} and is described by
+@code{pass_ipa_profile}.
+
+@item IPA icf
+
+This is the inter-procedural identical code folding pass for functions and
+read-only variables. The goal of this transformation is to discover functions
+and read-only variables which do have exactly the same semantics.  It is
+located in @file{ipa-icf.c} and is described by @code{pass_ipa_icf}.
+
+@item IPA devirt
+
+This pass do the devirtualization based on type inheritance graph.
+When polymorphic call has only one likely target in the unit,
+turn it into a speculative call. It is located in @file{ipa-devirt.c}
+and is described by @code{pass_ipa_devirt}.
+
+@item IPA cp
+
+This is the inter-procedural constant propagation pass.  The goal of this
+transformation is to discover functions which are always invoked with some
+arguments with the same known constant values and modify the functions, do
+partial specialization and propagates types. It is located in @file{ipa-cp.c}
+and is described by @code{pass_ipa_cp}.
+
+@item IPA sra
+
+This is the inter-procedural scalar replacement of aggregates pass.  IPA-SRA is
+an inter-procedural pass that removes unused function return values, removes
+unused function parameters.  It can also replace an aggregate parameter by a
+set of other parameters representing part of the original, turning those passed
+by reference into new ones which pass the value directly.  It is located in
+@file{ipa-sra.c} and is described by @code{pass_ipa_sra}.
+
+@item IPA cdtor merge
+
+This pass looks for constructors and destructors and produce function calling
+them.  This is needed for targets not supporting ctors or dtors.
+It is located in @file{ipa.c} and is described by @code{pass_ipa_cdtor_merge}.
+
+@item IPA hsa
+
+Inter-procedural HSA pass is responsible for creation of HSA clones.
+For all these HSA clones, emit HSAIL instructions and pass processing
+is terminated.  It is located in @file{ipa-hsa.c} and is described by
+@code{pass_ipa_hsa}.
+
+@item IPA fn summary
+
+This is function summary pass for analysis of function bodies. Each function
+will collect body size, function execution time function frame size data and
+call statement size, time and how often the parameters change for each call.
+It is located in @file{ipa-fnsummary.c} and is described by
+@code{pass_ipa_fn_summary}.
+
+@item IPA inline
+
+IPA inline pass is the real inliner able to handle inlining with whole program
+knowledge. Small functions are inlined by greedy algorithm ordering all
+inlinable cgraph edges by their badness; Unreachable functions are removed
+from callgraph; Functions called once and not exported from the unit are
+inlined.  It is located in @file{ipa-inline.c} and is described by
+@code{pass_ipa_inline}.
+
+@item IPA pure const
+
+This pass marks functions as being either const (TREE_READONLY) or
+pure (DECL_PURE_P).  It produces the global information and computes
+pure/const attributes by performing a transitive closure on the callgraph
+information that was produced by generate_summary.  It is located in
+@file{ipa-pure-const.c} and is described by @code{pass_ipa_pure_const}.
+
+@item IPA free fn summary
+
+This pass is a regular ipa pass when argument @code{small_p} is false.
+It releases inline function summaries and call summaries.
+It is located in @file{ipa-fnsummary.c} and is described by
+@code{pass_ipa_free_fn_summary}.
+
+@item IPA reference
+
+This pass gathers information about how variables whose scope is
+confined to the compilation unit are used.  It is located in
+@file{ipa-reference.c} and is described by @code{pass_ipa_reference}.
+
+@item IPA single use
+
+This pass checks whether variable is used by single function.
+It is located in @file{ipa.c} and is described by
+@code{pass_ipa_single_use}.
+
+@item IPA comdats
+
+This is a simple pass that looks for static symbols that are used
+exclusively by symbol within one comdat group. It is located in
+@file{ipa-comdats.c} and is described by @code{pass_ipa_comdats}.
+
+@end itemize
+
+@node All late IPA passes
+@subsection All late IPA passes
+@cindex all late ipa passes
+All late IPA passes are also simple IPA passes executed after
+the regular passes.  In WHOPR mode the passes are executed after
+partitioning and thus see just parts of the compiled unit.
+
+@itemize @bullet
+@item Materialize all clones
+
+Once all functions from compilation unit are in memory, produce all clones
+and update all calls.  It is located in @file{ipa.c} and is described by
+@code{pass_materialize_all_clones}.
+
+@item IPA pta
+Same as pta in small IPA passes.
+
+@item OpenMP simd clone
+
+This is the OpenMP constructs' SIMD clone pass.  If the function in NODE
+is tagged as an elemental SIMD function, create the appropriate SIMD clones.
+It is located in @file{omp-simd-clone.c} and is described by
+@code{pass_omp_simd_clone}.
+
+@end itemize
+
 @node Tree SSA passes
 @section Tree SSA passes
 
-- 
2.21.0.777.g83232e3864

Re: [PATCH] Come up with ipa passes introduction in gccint documentation

[Sandra Loosemore]

On 10/8/19 2:52 AM, luoxhu wrote:
> Hi,
> 
> This is the formal documentation patch for IPA passes.  Thanks.
> 
> 
> None of the IPA passes are documented in passes.texi.  This patch adds
> a section IPA passes just before GIMPLE passes and RTL passes in
> Chapter 9 "Passes and Files of the Compiler".  Also, a short description
> for each IPA pass is provided.
> gccint.pdf can be produced without errors.
> 
> ChangeLog:
> 	PR middle-end/26241
> 	* doc/lto.texi (IPA): Reference to the IPA passes.
> 	* doc/passes.texi (Pass manager): Add node IPA passes and
> 	  description for each IPA pass.

Thanks for submitting this documentation patch!  The content looks 
helpful to me, but I see that it has quite a few grammar bugs (I 
understand how hard English is even for native speakers....), plus some 
issues like indexing, cross-referencing, use of jargon without defining 
it, etc.  I think it would be more efficient for me to take over 
polishing the text some more than to mark it up for you to fix, but I'd 
like to give others a few days to comment on technical content first.

-Sandra

Re: [PATCH] Come up with ipa passes introduction in gccint documentation

[Richard Biener]

On Tue, Oct 8, 2019 at 10:06 PM Sandra Loosemore
<sandra@codesourcery.com> wrote:
>
> On 10/8/19 2:52 AM, luoxhu wrote:
> > Hi,
> >
> > This is the formal documentation patch for IPA passes.  Thanks.
> >
> >
> > None of the IPA passes are documented in passes.texi.  This patch adds
> > a section IPA passes just before GIMPLE passes and RTL passes in
> > Chapter 9 "Passes and Files of the Compiler".  Also, a short description
> > for each IPA pass is provided.
> > gccint.pdf can be produced without errors.
> >
> > ChangeLog:
> >       PR middle-end/26241
> >       * doc/lto.texi (IPA): Reference to the IPA passes.
> >       * doc/passes.texi (Pass manager): Add node IPA passes and
> >         description for each IPA pass.
>
> Thanks for submitting this documentation patch!  The content looks
> helpful to me, but I see that it has quite a few grammar bugs (I
> understand how hard English is even for native speakers....), plus some
> issues like indexing, cross-referencing, use of jargon without defining
> it, etc.  I think it would be more efficient for me to take over
> polishing the text some more than to mark it up for you to fix, but I'd
> like to give others a few days to comment on technical content first.

I think the contents are OK for a first try, so please go ahead polishing
and commit.  We can then improve the content as followup (I'm making
a note for myself to not forget).

Thanks,
Richard.

> -Sandra

Re: [PATCH] Come up with ipa passes introduction in gccint documentation

[Jan Hubicka]

> On Tue, Oct 8, 2019 at 10:06 PM Sandra Loosemore
> <sandra@codesourcery.com> wrote:
> >
> > On 10/8/19 2:52 AM, luoxhu wrote:
> > > Hi,
> > >
> > > This is the formal documentation patch for IPA passes.  Thanks.
> > >
> > >
> > > None of the IPA passes are documented in passes.texi.  This patch adds
> > > a section IPA passes just before GIMPLE passes and RTL passes in
> > > Chapter 9 "Passes and Files of the Compiler".  Also, a short description
> > > for each IPA pass is provided.
> > > gccint.pdf can be produced without errors.
> > >
> > > ChangeLog:
> > >       PR middle-end/26241
> > >       * doc/lto.texi (IPA): Reference to the IPA passes.
> > >       * doc/passes.texi (Pass manager): Add node IPA passes and
> > >         description for each IPA pass.
> >
> > Thanks for submitting this documentation patch!  The content looks
> > helpful to me, but I see that it has quite a few grammar bugs (I
> > understand how hard English is even for native speakers....), plus some
> > issues like indexing, cross-referencing, use of jargon without defining
> > it, etc.  I think it would be more efficient for me to take over
> > polishing the text some more than to mark it up for you to fix, but I'd
> > like to give others a few days to comment on technical content first.
> 
> I think the contents are OK for a first try, so please go ahead polishing
> and commit.  We can then improve the content as followup (I'm making
> a note for myself to not forget).

I will add some extra info once patch is in :)

Thanks for working on this!
Honza
> 
> Thanks,
> Richard.
> 
> > -Sandra

Re: [PATCH] Come up with ipa passes introduction in gccint documentation

[Sandra Loosemore]

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

On 10/9/19 1:20 AM, Jan Hubicka wrote:
>> On Tue, Oct 8, 2019 at 10:06 PM Sandra Loosemore
>> <sandra@codesourcery.com> wrote:
>>>
>>> On 10/8/19 2:52 AM, luoxhu wrote:
>>>> Hi,
>>>>
>>>> This is the formal documentation patch for IPA passes.  Thanks.
>>>>
>>>>
>>>> None of the IPA passes are documented in passes.texi.  This patch adds
>>>> a section IPA passes just before GIMPLE passes and RTL passes in
>>>> Chapter 9 "Passes and Files of the Compiler".  Also, a short description
>>>> for each IPA pass is provided.
>>>> gccint.pdf can be produced without errors.
>>>>
>>>> ChangeLog:
>>>>        PR middle-end/26241
>>>>        * doc/lto.texi (IPA): Reference to the IPA passes.
>>>>        * doc/passes.texi (Pass manager): Add node IPA passes and
>>>>          description for each IPA pass.
>>>
>>> Thanks for submitting this documentation patch!  The content looks
>>> helpful to me, but I see that it has quite a few grammar bugs (I
>>> understand how hard English is even for native speakers....), plus some
>>> issues like indexing, cross-referencing, use of jargon without defining
>>> it, etc.  I think it would be more efficient for me to take over
>>> polishing the text some more than to mark it up for you to fix, but I'd
>>> like to give others a few days to comment on technical content first.
>>
>> I think the contents are OK for a first try, so please go ahead polishing
>> and commit.  We can then improve the content as followup (I'm making
>> a note for myself to not forget).
> 
> I will add some extra info once patch is in :)
> 
> Thanks for working on this!

I've checked in the attached version of the patch.  I filled in a few 
more details myself, mainly explaining the jargon etc.

BTW, I've been thinking my stage 3 documentation project for this year 
will be doing some general cleanup on the internals manual.  Up until 
now I've been focusing on the user documentation on the theory that we 
have many more users than implementors, but the internals manual needs 
some TLC too.  I saw the poor quality of our internal documentation came 
up at Cauldron too.  :-(

-Sandra

[-- Attachment #2: ipa-docs.log --]
[-- Type: text/x-log, Size: 272 bytes --]

2019-10-10  Xiong Hu Luo  <luoxhu@linux.ibm.com>
	    Sandra Loosemore  <sandra@codesourcery.com>

	gcc/

	PR middle-end/26241
	* doc/lto.texi (IPA): Reference to the IPA passes.
	* doc/passes.texi (Pass manager): Add node IPA passes and
	  description for each IPA pass.

[-- Attachment #3: ipa-docs.patch --]
[-- Type: text/x-patch, Size: 12231 bytes --]

Index: gcc/doc/lto.texi
===================================================================
--- gcc/doc/lto.texi	(revision 276773)
+++ gcc/doc/lto.texi	(working copy)
@@ -350,10 +350,11 @@ while the @emph{Read summary}, @emph{Exe
 @end itemize
 
 To simplify development, the GCC pass manager differentiates
-between normal inter-procedural passes and small inter-procedural
-passes.  A @emph{small inter-procedural pass}
-(@code{SIMPLE_IPA_PASS}) is a pass that does
-everything at once and thus it cannot be executed during WPA in
+between normal inter-procedural passes (@pxref{Regular IPA passes}),
+small inter-procedural passes (@pxref{Small IPA passes})
+and late inter-procedural passes (@pxref{Late IPA passes}).
+A small or late IPA pass (@code{SIMPLE_IPA_PASS}) does
+everything at once and thus cannot be executed during WPA in
 WHOPR mode.  It defines only the @emph{Execute} stage and during
 this stage it accesses and modifies the function bodies.  Such
 passes are useful for optimization at LGEN or LTRANS time and are
Index: gcc/doc/passes.texi
===================================================================
--- gcc/doc/passes.texi	(revision 276773)
+++ gcc/doc/passes.texi	(working copy)
@@ -20,6 +20,7 @@ where near complete.
 * Parsing pass::         The language front end turns text into bits.
 * Gimplification pass::  The bits are turned into something we can optimize.
 * Pass manager::         Sequencing the optimization passes.
+* IPA passes::           Inter-procedural optimizations.
 * Tree SSA passes::      Optimizations on a high-level representation.
 * RTL passes::           Optimizations on a low-level representation.
 * Optimization info::    Dumping optimization information from passes.
@@ -178,6 +179,277 @@ TODO: describe the global variables set
 and a brief description of how a new pass should use it.
 I need to look at what info RTL passes use first@enddots{}
 
+@node IPA passes
+@section Inter-procedural optimization passes
+@cindex IPA passes
+@cindex inter-procedural optimization passes
+
+The inter-procedural optimization (IPA) passes use call graph
+information to perform transformations across function boundaries.
+IPA is a critical part of link-time optimization (LTO) and
+whole-program (WHOPR) optimization, and these passes are structured
+with the needs of LTO and WHOPR in mind by dividing their operations
+into stages.  For detailed discussion of the LTO/WHOPR IPA pass stages
+and interfaces, see @ref{IPA}.
+
+The following briefly describes the inter-procedural optimization (IPA)
+passes, which are split into small IPA passes, regular IPA passes,
+and late IPA passes, according to the LTO/WHOPR processing model.
+
+@menu
+* Small IPA passes::
+* Regular IPA passes::
+* Late IPA passes::
+@end menu
+
+@node Small IPA passes
+@subsection Small IPA passes
+@cindex small IPA passes
+A small IPA pass is a pass derived from @code{simple_ipa_opt_pass}.
+As described in @ref{IPA}, it does everything at once and 
+defines only the @emph{Execute} stage.  During this
+stage it accesses and modifies the function bodies.
+No @code{generate_summary}, @code{read_summary}, or @code{write_summary}
+hooks are defined.
+
+@itemize @bullet
+@item IPA free lang data
+
+This pass frees resources that are used by the front end but are
+not needed once it is done.  It is located in @file{tree.c} and is described by
+@code{pass_ipa_free_lang_data}.
+
+@item IPA function and variable visibility
+
+This is a local function pass handling visibilities of all symbols.  This
+happens before LTO streaming, so @option{-fwhole-program} should be ignored
+at this level.  It is located in @file{ipa-visibility.c} and is described by
+@code{pass_ipa_function_and_variable_visibility}.
+
+@item IPA remove symbols
+
+This pass performs reachability analysis and reclaims all unreachable nodes.
+It is located in @file{passes.c} and is described by
+@code{pass_ipa_remove_symbols}.
+
+@item IPA OpenACC
+
+This is a pass group for OpenACC processing.  It is located in
+@file{tree-ssa-loop.c} and is described by @code{pass_ipa_oacc}.
+
+@item IPA points-to analysis
+
+This is a tree-based points-to analysis pass. The idea behind this analyzer
+is to generate set constraints from the program, then solve the resulting
+constraints in order to generate the points-to sets.  It is located in 
+@file{tree-ssa-structalias.c} and is described by @code{pass_ipa_pta}.
+
+@item IPA OpenACC kernels
+
+This is a pass group for processing OpenACC kernels regions.  It is a
+subpass of the IPA OpenACC pass group that runs on offloaded functions
+containing OpenACC kernels loops.  It is located in
+@file{tree-ssa-loop.c} and is described by
+@code{pass_ipa_oacc_kernels}.
+
+@item Target clone
+
+This is a pass for parsing functions with multiple target attributes.
+It is located in @file{multiple_target.c} and is described by
+@code{pass_target_clone}.
+
+@item IPA auto profile
+
+This pass uses AutoFDO profiling data to annotate the control flow graph.
+It is located in @file{auto-profile.c} and is described by
+@code{pass_ipa_auto_profile}.
+
+@item IPA tree profile
+
+This pass does profiling for all functions in the call graph. 
+It calculates branch
+probabilities and basic block execution counts. It is located
+in @file{tree-profile.c} and is described by @code{pass_ipa_tree_profile}.
+
+@item IPA free function summary
+
+This pass is a small IPA pass when argument @code{small_p} is true.
+It releases inline function summaries and call summaries.
+It is located in @file{ipa-fnsummary.c} and is described by
+@code{pass_ipa_free_free_fn_summary}.
+
+@item IPA increase alignment
+
+This pass increases the alignment of global arrays to improve
+vectorization. It is located in @file{tree-vectorizer.c}
+and is described by @code{pass_ipa_increase_alignment}.
+
+@item IPA transactional memory
+
+This pass is for transactional memory support.
+It is located in @file{trans-mem.c} and is described by
+@code{pass_ipa_tm}.
+
+@item IPA lower emulated TLS
+
+This pass lowers thread-local storage (TLS) operations
+to emulation functions provided by libgcc.
+It is located in @file{tree-emutls.c} and is described by
+@code{pass_ipa_lower_emutls}.
+
+@end itemize
+
+@node Regular IPA passes
+@subsection Regular IPA passes
+@cindex regular IPA passes
+
+A regular IPA pass is a pass derived from @code{ipa_opt_pass_d} that
+is executed in WHOPR compilation. Regular IPA passes may have summary
+hooks implemented in any of the LGEN, WPA or LTRANS stages (@pxref{IPA}).
+
+@itemize @bullet
+@item IPA whole program visibility
+
+This pass performs various optimizations involving symbol visibility
+with @option{-fwhole-program}, including symbol privatization,
+discovering local functions, and dismantling comdat groups.  It is
+located in @file{ipa-visibility.c} and is described by
+@code{pass_ipa_whole_program_visibility}.
+
+@item IPA profile
+
+The IPA profile pass propagates profiling frequencies across the call
+graph.  It is located in @file{ipa-profile.c} and is described by
+@code{pass_ipa_profile}.
+
+@item IPA identical code folding
+
+This is the inter-procedural identical code folding pass.
+The goal of this transformation is to discover functions
+and read-only variables that have exactly the same semantics.  It is
+located in @file{ipa-icf.c} and is described by @code{pass_ipa_icf}.
+
+@item IPA devirtualization
+
+This pass performs speculative devirtualization based on the type
+inheritance graph.  When a polymorphic call has only one likely target
+in the unit, it is turned into a speculative call. It is located in
+@file{ipa-devirt.c} and is described by @code{pass_ipa_devirt}.
+
+@item IPA constant propagation
+
+The goal of this pass is to discover functions that are always invoked
+with some arguments with the same known constant values and to modify
+the functions accordingly.  It can also do partial specialization and
+type-based devirtualization.  It is located in @file{ipa-cp.c} and is
+described by @code{pass_ipa_cp}.
+
+@item IPA scalar replacement of aggregates
+
+This pass can replace an aggregate parameter with a set of other parameters
+representing part of the original, turning those passed by reference
+into new ones which pass the value directly.  It also removes unused
+function return values and unused function parameters.  This pass is
+located in @file{ipa-sra.c} and is described by @code{pass_ipa_sra}.
+
+@item IPA constructor/destructor merge
+
+This pass merges multiple constructors and destructors for static
+objects into single functions.  It's only run at LTO time unless the
+target doesn't support constructors and destructors natively.  The
+pass is located in @file{ipa.c} and is described by
+@code{pass_ipa_cdtor_merge}.
+
+@item IPA HSA
+
+This pass is part of the GCC support for HSA (Heterogeneous System
+Architecture) accelerators.  It is responsible for creation of HSA
+clones and emitting HSAIL instructions for them.  It is located in
+@file{ipa-hsa.c} and is described by @code{pass_ipa_hsa}.
+
+@item IPA function summary
+
+This pass provides function analysis for inter-procedural passes.
+It collects estimates of function body size, execution time, and frame
+size for each function.  It also estimates information about function
+calls: call statement size, time and how often the parameters change
+for each call.  It is located in @file{ipa-fnsummary.c} and is
+described by @code{pass_ipa_fn_summary}.
+
+@item IPA inline
+
+The IPA inline pass handles function inlining with whole-program
+knowledge. Small functions that are candidates for inlining are
+ordered in increasing badness, bounded by unit growth parameters.
+Unreachable functions are removed from the call graph.  Functions called
+once and not exported from the unit are inlined.  This pass is located in
+@file{ipa-inline.c} and is described by @code{pass_ipa_inline}.
+
+@item IPA pure/const analysis
+
+This pass marks functions as being either const (@code{TREE_READONLY}) or
+pure (@code{DECL_PURE_P}).  The per-function information is produced
+by @code{pure_const_generate_summary}, then the global information is computed
+by performing a transitive closure over the call graph.   It is located in
+@file{ipa-pure-const.c} and is described by @code{pass_ipa_pure_const}.
+
+@item IPA free function summary
+
+This pass is a regular IPA pass when argument @code{small_p} is false.
+It releases inline function summaries and call summaries.
+It is located in @file{ipa-fnsummary.c} and is described by
+@code{pass_ipa_free_fn_summary}.
+
+@item IPA reference
+
+This pass gathers information about how variables whose scope is
+confined to the compilation unit are used.  It is located in
+@file{ipa-reference.c} and is described by @code{pass_ipa_reference}.
+
+@item IPA single use
+
+This pass checks whether variables are used by a single function.
+It is located in @file{ipa.c} and is described by
+@code{pass_ipa_single_use}.
+
+@item IPA comdats
+
+This pass looks for static symbols that are used exclusively
+within one comdat group, and moves them into that comdat group. It is
+located in @file{ipa-comdats.c} and is described by
+@code{pass_ipa_comdats}.
+
+@end itemize
+
+@node Late IPA passes
+@subsection Late IPA passes
+@cindex late IPA passes
+
+Late IPA passes are simple IPA passes executed after
+the regular passes.  In WHOPR mode the passes are executed after
+partitioning and thus see just parts of the compiled unit.
+
+@itemize @bullet
+@item Materialize all clones
+
+Once all functions from compilation unit are in memory, produce all clones
+and update all calls.  It is located in @file{ipa.c} and is described by
+@code{pass_materialize_all_clones}.
+
+@item IPA points-to analysis
+
+Points-to analysis; this is the same as the points-to-analysis pass
+run with the small IPA passes (@pxref{Small IPA passes}).
+
+@item OpenMP simd clone
+
+This is the OpenMP constructs' SIMD clone pass.  It creates the appropriate
+SIMD clones for functions tagged as elemental SIMD functions.
+It is located in @file{omp-simd-clone.c} and is described by
+@code{pass_omp_simd_clone}.
+
+@end itemize
+
 @node Tree SSA passes
 @section Tree SSA passes