diff mbox

[DOC] Enhance documentation of -fipa-ra option.

Message ID 6d36d56b-40d8-e24d-bd4b-7248e17564f0@suse.cz
State New
Headers show

Commit Message

Martin Liška July 19, 2016, 12:45 p.m. UTC 
On 07/13/2016 07:04 PM, Alexander Monakov wrote:
>> --- a/gcc/doc/invoke.texi
>> +++ b/gcc/doc/invoke.texi
>> @@ -7260,7 +7260,9 @@ any called function.  In that case it is not necessary to save and restore
>>  them around calls.  This is only possible if called functions are part of
>>  same compilation unit as current function and they are compiled before it.
>>  
>> -Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
>> +Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}, however the option
>> +is disabled if profiler is active (@option{-p}, @option{-pg} or
> 
> I think this should say "if generated code will be instrumented for profiling"
> (or "is instrumented") instead of "if profiler is active".  Internal comments
> can be fuzzy, but user-facing documentation should be more rigorous.
> 
>> +@option{-fprofile})
> 
> Right now option -fprofile is not documented, so it's probably not ok to
> mention it here (I realize it won't be so if you document it as an alias).
> 
>> or a port does not emit prologue and epilogue as RTL.
> 
> May I suggest "or if callee's register usage cannot be known exactly (this
> happens on targets that do not expose prologues and epilogues in RTL)"?
> 
> (well, this is still not 100% helpful to the user because they can't easily know
> which targets do, but still a bit of an improvement)
> 
> Thanks for bringing this forward!  The bit about profiling is especially not
> obvious and nice to have documented.
> 
> Alexander
> 

Hi Alexander.

Thank you very much for the suggestions, I've basically followed all nits you
spotted. I also noticed that there is actually one more alias of -p and that's
-profile. That comes from >20 years old commit:

commit f3a30d9b5452e89b4700b857df7caa448c956489
Author: kenner <kenner@138bc75d-0d04-0410-961f-82ee72b054a4>
Date:   Mon Jan 15 13:28:30 1996 +0000

    (LIB_SPEC): Remove %{mieee-fp:-lieee}.
    Use -lc_p for -profile.
    (CC1_SPEC): New macro.
    
    
    git-svn-id: svn+ssh://gcc.gnu.org/svn/gcc/trunk@10984 138bc75d-0d04-0410-961f-82ee72b054a4

So I decided to also mention this alias.

Thoughts?

Martin

Comments

Andreas Schwab July 19, 2016, 1:02 p.m. UTC | #1 
Martin Liška <mliska@suse.cz> writes:

> Thank you very much for the suggestions, I've basically followed all nits you
> spotted. I also noticed that there is actually one more alias of -p and that's
> -profile. That comes from >20 years old commit:

-profile is not the same as -p, as the former also adds -lc_p.

Andreas.
Alexander Monakov July 19, 2016, 1:46 p.m. UTC | #2 
> So I decided to also mention this alias.
> 
> Thoughts?

I'd like the new ipa-ra text to go in, but perhaps you should consider leaving
out option aliases out of this patch, especially given that it's non-trivial, as
Andreas' comment has shown.

(I'd say it's rather confusing that -fprofile is quite different from
-fprofile-generate; I doubt it's worthwhile to document this alias at all, but I
won't argue much either way)

Thanks.
Alexander
diff mbox

Patch

From 2108f584b35331912a0dfa4fc30131c223c6844c Mon Sep 17 00:00:00 2001
From: marxin <mliska@suse.cz>
Date: Wed, 13 Jul 2016 18:25:09 +0200
Subject: [PATCH] Enhance documentation of -fipa-ra option.

gcc/ChangeLog:

2016-07-13  Martin Liska  <mliska@suse.cz>

	* doc/invoke.texi (-fipa-ra): Document when the option is
	disabled. Fix a typo.
	(profile): Document it as an alias.
	(fprofile): Likewise.
---
 gcc/doc/invoke.texi | 21 ++++++++++++++++++---
 1 file changed, 18 insertions(+), 3 deletions(-)

diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
index 9a4db38..47d69c8 100644
--- a/gcc/doc/invoke.texi
+++ b/gcc/doc/invoke.texi
@@ -422,7 +422,8 @@  Objective-C and Objective-C++ Dialects}.
 
 @item Program Instrumentation Options
 @xref{Instrumentation Options,,Program Instrumentation Options}.
-@gccoptlist{-p  -pg  -fprofile-arcs --coverage -ftest-coverage @gol
+@gccoptlist{-p -profile -fprofile -pg -fprofile-arcs --coverage @gol
+-ftest-coverage @gol
 -fprofile-dir=@var{path} -fprofile-generate -fprofile-generate=@var{path} @gol
 -fsanitize=@var{style} -fsanitize-recover -fsanitize-recover=@var{style} @gol
 -fasan-shadow-offset=@var{number} -fsanitize-sections=@var{s1},@var{s2},... @gol
@@ -7260,7 +7261,11 @@  any called function.  In that case it is not necessary to save and restore
 them around calls.  This is only possible if called functions are part of
 same compilation unit as current function and they are compiled before it.
 
-Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
+Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}, however the option
+is disabled if generated code will be instrumented for profiling
+(@option{-p}, @option{-profile}, @option{-fprofile} or @option{-pg})
+or if callee's register usage cannot be known exactly (this happens on targets
+that do not expose prologues and epilogues in RTL).
 
 @item -fconserve-stack
 @opindex fconserve-stack
@@ -7280,7 +7285,7 @@  Perform code hoisting.  Code hoisting tries to move the
 evaluation of expressions executed on all paths to the function exit
 as early as possible.  This is especially useful as a code size
 optimization, but it often helps for code speed as well.
-This flag is enabled by defailt at @option{-O2} and higher.
+This flag is enabled by default at @option{-O2} and higher.
 
 @item -ftree-pre
 @opindex ftree-pre
@@ -9804,6 +9809,16 @@  analysis program @command{prof}.  You must use this option when compiling
 the source files you want data about, and you must also use it when
 linking.
 
+@cindex @command{prof}
+@item -profile
+@opindex profile
+Alias of @option{-p}.
+
+@cindex @command{prof}
+@item -fprofile
+@opindex fprofile
+Alias of @option{-p}.
+
 @cindex @command{gprof}
 @item -pg
 @opindex pg
-- 
2.9.0