DOC PATCH: about dump file numbering

Hello All,

I (and also Pierre Vittet, a GCC MELT user) find a bit confusing the
numbering of dump files with -fdump* options.

Concretely the gcc/testsuite/melt/topengpu-1.c file of the GCC MELT
branch, when run with -fdump-tree-all, gives a lot of dump files,
named...

topengpu-1.c.013t.cfg
topengpu-1.c.014t.inline_param1
topengpu-1.c.015i.visibility
topengpu-1.c.016i.early_local_cleanups
topengpu-1.c.018t.ssa
topengpu-1.c.019t.veclower
topengpu-1.c.020t.einline
topengpu-1.c.021t.early_optimizations
topengpu-1.c.022t.copyrename1
topengpu-1.c.023t.ccp1
#### ..... etc .......
topengpu-1.c.130t.dse2
topengpu-1.c.131t.forwprop4
topengpu-1.c.132t.phiopt3
topengpu-1.c.133t.fab
topengpu-1.c.134t.widening_mul
topengpu-1.c.135t.tailc
topengpu-1.c.136t.copyrename4
topengpu-1.c.137t.uncprop
topengpu-1.c.138t.local-pure-const2
topengpu-1.c.142t.nrv
topengpu-1.c.144t.optimized
topengpu-1.c.224t.statistics
topengpu-1.c.225i.meltopengpu_detect 

This last numbering is confusing (at least to Pierre & to
me). Actually, the numbering is given by static_pass_number and is not
related to the dynamic ordering of passes execution.

I would like to document that a bit better, perhaps by the following
*untested* documentation patch.
##################
############### gcc/ChangeLog entry
2010-11-24  Basile Starynkevitch  <basile@starynkevitch.net>

	* doc/invoke.texi (Options for Debugging Your Program or GCC):
	Explain static numbering of dump files.

################

Now, my english not good, and perhaps the explanation could be better.

Comments and/or "Ok with changes" are welcome.

Cheers.

On Wed, Nov 24, 2010 at 08:31, Basile Starynkevitch
<basile@starynkevitch.net> wrote:

> This last numbering is confusing (at least to Pierre & to
> me). Actually, the numbering is given by static_pass_number and is not
> related to the dynamic ordering of passes execution.

Right.

> @@ -4968,7 +4968,10 @@ Says to make debugging dumps during compilation at
>  @var{letters}.  This is used for debugging the RTL-based passes of the
>  compiler.  The file names for most of the dumps are made by appending
>  a pass number and a word to the @var{dumpname}, and the files are
> -created in the directory of the output file.  @var{dumpname} is
> +created in the directory of the output file.  The pass number is not
> +related to the dynamic order of execution of passes, hence a pass
> +installed by a plugin could have a number above 200 even if it
> +executed quite early.  @var{dumpname} is

How about: "Note that the pass number is computed statically as passes
get registered into the pass manager.  Thus the numbering is not
related to the dynamic order of execution of passes.  In particular, a
pass installed by a plugin could have a number over 200 even if it
executed quite early."

> 2010-11-24  Basile Starynkevitch  <basile@starynkevitch.net>
>
>        * doc/invoke.texi (Options for Debugging Your Program or GCC):
>        Explain static numbering of dump files.

OK with the above nits.


Diego.

On Wed, Nov 24, 2010 at 08:38:11AM -0500, Diego Novillo wrote:
> On Wed, Nov 24, 2010 at 08:31, Basile Starynkevitch
> <basile@starynkevitch.net> wrote:
> 
> > This last numbering is confusing (at least to Pierre & to
> > me). Actually, the numbering is given by static_pass_number and is not
> > related to the dynamic ordering of passes execution.
> 
> How about: "Note that the pass number is computed statically as passes
> get registered into the pass manager.  Thus the numbering is not
> related to the dynamic order of execution of passes.  In particular, a
> pass installed by a plugin could have a number over 200 even if it
> executed quite early."

> 
> OK with the above nits.


Thanks Diego. I committed that in Committed revision 167114.

Cheers.

On Nov 24, 2010, at 5:38 AM, Diego Novillo wrote:
> How about: "Note that the pass number is computed statically as passes
> get registered into the pass manager.  Thus the numbering is not
> related to the dynamic order of execution of passes.  In particular, a
> pass installed by a plugin could have a number over 200 even if it
> executed quite early."

Ick.  How about renumbering them in dynamic order of execution?  I could imagine trying to track down a problem and being misled by this.

On Thu, 25 Nov 2010 09:37:50 -0800
Mike Stump <mikestump@comcast.net> wrote:

> On Nov 24, 2010, at 5:38 AM, Diego Novillo wrote:
> > How about: "Note that the pass number is computed statically as passes
> > get registered into the pass manager.  Thus the numbering is not
> > related to the dynamic order of execution of passes.  In particular, a
> > pass installed by a plugin could have a number over 200 even if it
> > executed quite early."
> 
> Ick.  How about renumbering them in dynamic order of execution?  
> I could imagine trying to track down a problem and being misled by this.

I would be delighted if that was implemented, but I have no idea of how to do that.

My patch documented only a [quite sad] current state of GCC.

Cheers.