passes description

[Basile STARYNKEVITCH]

Hello All,

I have a wish: that each (middle-end) pass [those in gcc/tree-passes.h] 
would have a small documentation describing it (in particular which 
representations, TREE, SSA, CFG, etc... are valid after the pass). A 
simple wiki page (describing each pass) would be more than enough for 
me. Or at least having each *_opt_pass described in 
http://gcc.gnu.org/onlinedocs/gccint/Tree_002dSSA-passes.html without 
exceptions (even trivial clean-up passes need a few sentences).

I have difficulty in trying to position my passes in passes.c I'm pretty 
sure not to be alone on that!

I want to use MELT to prototype a single interval static analyser (like 
the interval analysis mentioned in 
http://en.wikipedia.org/wiki/Abstract_interpretation). I believe I need 
SSA & CFG.

perhaps we might need to define, e.g, some common comment structure for 
each *_opt_pass of tree-passes.h.

What do people think?

In addition, I find difficult & unrealistic to propose a patch for that, 
because that would essentially means understand the exact role of every 
pass, and I am not able of that, and I even think that few GCC hackers 
are understanding that.

I'm suggesting at least adding detailed comments inside each *_opt_pass 
structure.

I also think that each pass should have a unique name. Remember, if a 
pass name starts with '*' it behave as if it has no name (ie no dumping 
occur). I find pitiful that some new passes are still unamed.

I presume that there are some passes which nobody understands, but I 
believe that since the gimple -> tuple transition happened recently this 
  might be false know. I suppose that there are active contributors who 
know what the pass they patched are grossly doing.

So what would be the easiest solution to get more description of each pass?

Given that passes are central to the middle end in GCC, shouldn't we 
want each of them (without exception!) be described by at least a simple 
paragraph. I'm sure that is a small effort for each pass writer (he/she 
knows what he has coded) but it is a huge effort for somebody not 
understanding them. Should we aim for some structured comments, for some 
requirements regarding documenting the pass in the doc/*texi files, in 
the wiki, ...?

See also http://gcc.gnu.org/wiki/MakingGCCEasierToLearn

regards.
-- 
Basile STARYNKEVITCH         http://starynkevitch.net/Basile/
email: basile<at>starynkevitch<dot>net mobile: +33 6 8501 2359
8, rue de la Faiencerie, 92340 Bourg La Reine, France
*** opinions {are only mines, sont seulement les miennes} ***