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

[luoxhu <luoxhu at linux dot ibm dot com>]

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
 ipa free lang data
 ipa function and variable visibility
 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
>