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

[Segher Boessenkool <segher@kernel.crashing.org>]

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