Bug 32003 - Undocumented -fdump-tree options
Summary: Undocumented -fdump-tree options
Status: RESOLVED FIXED
Alias: None
Product: gcc
Classification: Unclassified
Component: middle-end (show other bugs)
Version: 4.3.0
: P3 normal
Target Milestone: ---
Assignee: Martin Sebor
URL:
Keywords: documentation, patch
Depends on:
Blocks:
 
Reported: 2007-05-19 18:40 UTC by H.J. Lu
Modified: 2017-02-15 20:13 UTC (History)
3 users (show)

See Also:
Host:
Target:
Build:
Known to work:
Known to fail: 4.3.0, 4.5.3, 4.8.3, 4.9.3, 5.3.0, 6.1.0
Last reconfirmed: 2016-05-05 00:00:00


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description H.J. Lu 2007-05-19 18:40:34 UTC
Those 2 options:

  {"stmtaddr", TDF_STMTADDR},
  {"memsyms", TDF_MEMSYMS},

aren't documented.
Comment 1 Andrew Pinski 2012-01-28 02:56:50 UTC
{"memsyms", TDF_MEMSYMS},
Is now just the same as vops.

stmtaddr just prints out the actually address of the gimple/tree.  

Confirmed.
Comment 2 Martin Sebor 2016-05-05 17:41:25 UTC
The -fdump-tree-objsz is also undocumented.

I tried to get a comprehensive list of all undocumented tree dumps.  Here's what I came up with for GCC 6.1.  It looks like the vast majority of them are, in fact, undocumented.

ipa-afdo
ipa-build_ssa_passes
ipa-cdtor
ipa-chkp_cleanup
ipa-chkp_ecleanup
ipa-chkp_passes
ipa-chkp_versioning
ipa-comdats
ipa-cp
ipa-devirt
ipa-dispachercalls
ipa-emutls
ipa-free-inline-summary
ipa-hsa
ipa-icf
ipa-increase_alignment
ipa-inline
ipa-ipa_oacc
ipa-ipa_oacc_kernels
ipa-opt_local_passes
ipa-profile
ipa-profile_estimate
ipa-pta1
ipa-pure-const
ipa-simdclone
ipa-single-use
ipa-static-var
ipa-targetclone
ipa-tmipa
ipa-visibility
ipa-whole-program
statistics
aprefetch
asan0
asan1
bswap
ccp1
cdce
cddce1
ch1
chkp
chkpopt
ch_vect
copyprop1
cplxlower0
cplxlower1
crited1
cselim
cunroll
cunrolli
dce1
dom1
dse1
ealias
early_optimizations
eh
ehcleanup1
ehdisp
ehopt
einline
eipa_sra
esra
fab1
feedback_fnsplit
fix_loops
fixup_cfg1
fnsplit
forwprop1
fre1
graphite
graphite0
hsagen
ifcombine
ifcvt
inline_param1
isolate-paths
ivcanon
ivopts
laddress
ldist
lim1
local-pure-const1
loop
loopdone
loopinit
lower
lower_vaarg
mergephi1
no_loop
nothrow
oacc_kernels
objsz1
ompexp
ompexpssa1
omplower
omptargetlink
parloops1
pcom
phicprop1
phiopt1
phiprop
profile_estimate
reassoc1
recip
release_ssa
resx
retslot
sancov1
sancov_O0
sanopt
sccp
simduid1
sincos
slp1
slsr
split-paths
stdarg
strlen
switchconv
tailc
tailr1
tmedge
tmlower
tmmark
tmmemopt
tracer
tsan0
tsan1
ubsan
uncprop1
uninit1
unswitch
veclower
veclower21
vrp1
vtable-verify
widening_mul
Comment 3 Marek Polacek 2016-05-05 17:47:42 UTC
I don't see much value in documenting those.  It seems to me that we should simply document that the format is -fdump-{tree,ipa,rtl}-<PASS>[-<DETAILS>].
Comment 4 Martin Sebor 2016-05-05 19:25:36 UTC
With most of the documentation for each option consisting of "the file name is made by appending .xxx to the source file name" I agree that in its current form and state of completion the documentation isn't very useful.

I also suspect that providing descriptions for the currently undocumented options and saying much more than what's in the boilerplate blurb above is unlikely.

I like the idea of providing a generic description instead, as long is it makes it easy to derive the option names.  I had to figure out by trial and error that the name of the option controlling the Object Size Checking dumps is -fdump-tree-objsz (by using -fdump-tree-all, looking at the suffix of the two dump files, and appending it to -fdump-tree-).  But after some experimenting and poking around in the manual I realize there's a better way to do it:

1) Run GCC with -fdump-passes and look for the pass code (e.g., objsz for Object Size Checking).
2) Append the pass code to the -fdump-tree- (or -fdump-rtl-) option to enable the dump.
3) Use the pass code to find the name of the dump file created by GCC for the pass (unless overridden).

So maybe this would be sufficient documentation for all the options.  The one thing missing is a description of what each of those passes actually does.  For some it's fairly obvious but for others not so much.  Maybe a brief description could be added to GCC's -fdump-passes output to help figure that out (e.g., under -fdump-passes=verbose if we want to keep the current output unchanged).

How does this sound?
Comment 5 sandra 2017-01-09 04:35:13 UTC
Given how bloated the GCC user manual is already (it takes almost 20 pages just to *list* all the options), I'd prefer trimming all the dump-related option documentation to something short and generic with a pointer to the GCC internals manual for a full list of the pass names and what they do.  Ordinary users have little reason to use these options, and understanding the dump output requires some familiarity with GCC internals anyway.
Comment 6 Martin Sebor 2017-01-09 17:08:57 UTC
That sounds good to me.  Unless someone beats me to it, I can see about making those changes in stage 4 after I'm done with all my stage 3 work.
Comment 7 Martin Sebor 2017-02-02 01:58:47 UTC
Patch posted for review:
https://gcc.gnu.org/ml/gcc-patches/2017-02/msg00104.html
Comment 8 Martin Sebor 2017-02-02 20:58:09 UTC
Author: msebor
Date: Thu Feb  2 20:57:37 2017
New Revision: 245136

URL: https://gcc.gnu.org/viewcvs?rev=245136&root=gcc&view=rev
Log:
PR middle-end/32003 - Undocumented -fdump-tree options

gcc/ChangeLog:
       * doc/invoke.texi (-fdump-rtl-): Remove pass-specific options from
       index.
       (-fdump-tree-@var): Add to index and document how to come up
       with pass-specific option and dump file names.
       (-fdump-passes): Clarify where to look for output.

Modified:
    trunk/gcc/ChangeLog
    trunk/gcc/doc/invoke.texi
Comment 9 Martin Sebor 2017-02-02 20:58:27 UTC
Fixed in r245136.
Comment 10 Martin Sebor 2017-02-15 20:13:43 UTC
Author: msebor
Date: Wed Feb 15 20:13:11 2017
New Revision: 245493

URL: https://gcc.gnu.org/viewcvs?rev=245493&root=gcc&view=rev
Log:
2017-02-15  Martin Sebor  <msebor@redhat.com>

	PR middle-end/32003
	* doc/invoke.texi (-fdump-final-insns): Replace option accidentally
	removed in a prior commit.

Modified:
    trunk/gcc/ChangeLog
    trunk/gcc/doc/invoke.texi