docs: Suggest options to improve ASAN stack traces

  I got a complaint that while Clang docs suggest options that improve
the quality of the backtraces ASAN prints (cf.
<https://clang.llvm.org/docs/AddressSanitizer.html#usage>), our docs
don't say anything to that effect.  This patch amends that with a new
paragraph.  (It deliberately doesn't mention -fno-omit-frame-pointer.)

gcc/ChangeLog:

	* doc/invoke.texi (-fsanitize=address): Suggest options to improve
	stack traces.
---
 gcc/doc/invoke.texi | 8 ++++++++
 1 file changed, 8 insertions(+)


base-commit: 3ad0f470c16d5528a5283060b007f8b419c33c92
  

* Marek Polacek via Gcc-patches:

> diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
> index 726392409b6..2de14466dd3 100644
> --- a/gcc/doc/invoke.texi
> +++ b/gcc/doc/invoke.texi
> @@ -16510,6 +16510,14 @@ The option cannot be combined with @option{-fsanitize=thread} or
>  @option{-fsanitize=hwaddress}.  Note that the only target
>  @option{-fsanitize=hwaddress} is currently supported on is AArch64.
>  
> +To get more accurate stack traces, it is possible to use options such as
> +@option{-O} (which, for instance, prevents most function inlining),
> +@option{-fno-optimize-sibling-calls} (which prevents optimizing sibling
> +and tail recursive calls), or @option{-fno-ipa-icf} (which disables Identical
> +Code Folding for functions and read-only variables).  Since multiple runs
> +of the program may yield backtraces with different addresses due to ASLR,
> +it may be desirable to turn off ASLR: @samp{setarch `uname -m` -R ./prog}.

What about -fasynchronous-unwind-tables?  It should help if ASAN ever
reports stray segmentation faults.  Whether it also helps in general
depends on whether ASAN maintains ABI around its instrumentation.

Thanks,
Florian
  

On Thu, Dec 08, 2022 at 08:25:26AM +0100, Florian Weimer wrote:
> * Marek Polacek via Gcc-patches:
> 
> > diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
> > index 726392409b6..2de14466dd3 100644
> > --- a/gcc/doc/invoke.texi
> > +++ b/gcc/doc/invoke.texi
> > @@ -16510,6 +16510,14 @@ The option cannot be combined with @option{-fsanitize=thread} or
> >  @option{-fsanitize=hwaddress}.  Note that the only target
> >  @option{-fsanitize=hwaddress} is currently supported on is AArch64.
> >  
> > +To get more accurate stack traces, it is possible to use options such as
> > +@option{-O} (which, for instance, prevents most function inlining),
> > +@option{-fno-optimize-sibling-calls} (which prevents optimizing sibling
> > +and tail recursive calls), or @option{-fno-ipa-icf} (which disables Identical
> > +Code Folding for functions and read-only variables).  Since multiple runs
> > +of the program may yield backtraces with different addresses due to ASLR,
> > +it may be desirable to turn off ASLR: @samp{setarch `uname -m` -R ./prog}.
> 
> What about -fasynchronous-unwind-tables?  It should help if ASAN ever
> reports stray segmentation faults.  Whether it also helps in general
> depends on whether ASAN maintains ABI around its instrumentation.

I'm not sure.  Someone else will have to decide if we want to mention
that option as well.

Marek
  

On Thu, Dec 08, 2022 at 09:11:54AM -0500, Marek Polacek via Gcc-patches wrote:
> On Thu, Dec 08, 2022 at 08:25:26AM +0100, Florian Weimer wrote:
> > * Marek Polacek via Gcc-patches:
> > 
> > > diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
> > > index 726392409b6..2de14466dd3 100644
> > > --- a/gcc/doc/invoke.texi
> > > +++ b/gcc/doc/invoke.texi
> > > @@ -16510,6 +16510,14 @@ The option cannot be combined with @option{-fsanitize=thread} or
> > >  @option{-fsanitize=hwaddress}.  Note that the only target
> > >  @option{-fsanitize=hwaddress} is currently supported on is AArch64.
> > >  
> > > +To get more accurate stack traces, it is possible to use options such as
> > > +@option{-O} (which, for instance, prevents most function inlining),
> > > +@option{-fno-optimize-sibling-calls} (which prevents optimizing sibling
> > > +and tail recursive calls), or @option{-fno-ipa-icf} (which disables Identical
> > > +Code Folding for functions and read-only variables).  Since multiple runs
> > > +of the program may yield backtraces with different addresses due to ASLR,
> > > +it may be desirable to turn off ASLR: @samp{setarch `uname -m` -R ./prog}.
> > 
> > What about -fasynchronous-unwind-tables?  It should help if ASAN ever
> > reports stray segmentation faults.  Whether it also helps in general
> > depends on whether ASAN maintains ABI around its instrumentation.
> 
> I'm not sure.  Someone else will have to decide if we want to mention
> that option as well.

-fasynchronous-unwind-tables is on by default on many targets, so I wouldn't
mention it:
grep asynchronous_unwind_tables common/*/*/* config/*/*
common/config/aarch64/aarch64-common.cc:    { OPT_LEVELS_ALL, OPT_fasynchronous_unwind_tables, NULL, 1 },
common/config/i386/i386-common.cc:  opts->x_flag_asynchronous_unwind_tables = 2;
common/config/loongarch/loongarch-common.cc:  { OPT_LEVELS_ALL, OPT_fasynchronous_unwind_tables, NULL, 1 },
common/config/rs6000/rs6000-common.cc:  opts->x_flag_asynchronous_unwind_tables = 1;
common/config/s390/s390-common.cc:  opts->x_flag_asynchronous_unwind_tables = 1;
config/i386/i386-options.cc:      if (opts->x_flag_asynchronous_unwind_tables == 2)
config/i386/i386-options.cc:	opts->x_flag_asynchronous_unwind_tables = !USE_IX86_FRAME_POINTER;
config/mips/mips.cc:      && !global_options_set.x_flag_asynchronous_unwind_tables)
config/mips/mips.cc:    flag_asynchronous_unwind_tables = 1;
config/rs6000/rs6000.cc:      && !OPTION_SET_P (flag_asynchronous_unwind_tables))
config/rs6000/rs6000.cc:    flag_asynchronous_unwind_tables = 1;

On the other side, the @samp{setarch `uname -m` -R ./prog} suggestion is
very Linux specific, so if we mention it at all, it should mention that
"e.g. on Linux through ..." or something similar.
I also wouldn't mention the "and read-only variables" part, that is
irrelevant for stack traces.

	Jakub