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
