doc: Explain flto-toplevel-asm-heuristics

This patch adds documentation for flto-toplevel-asm-heuristics
and mentions it in Remarks in Basic Asm.

gcc/ChangeLog:

	* doc/extend.texi: Mention flto-toplevel-asm-heuristics.
	* doc/invoke.texi: Add flto-toplevel-asm-heuristics.

diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
index ac86a2e14847ff419c51b2f5fdd199d2494b5a3c..5e481126069d6ecdb643a5bf5dcb0ce6888d2146 100644 (file)
--- a/gcc/doc/extend.texi
+++ b/gcc/doc/extend.texi
@@ -11507,6 +11507,11 @@ with extended @code{asm}.  See
 from basic asm to extended asm} for information about how to perform this
 conversion.
 
+LTO typically requires rewriting top-level basic @code{asm} statements to
+extended @code{asm}.  Otherwise you will likely encounter missing symbol
+errors by linker.  Alternatively you may use
+@option{-flto-toplevel-asm-heuristics}.
+
 The compiler copies the assembler instructions in a basic @code{asm} 
 verbatim to the assembly language output file, without 
 processing dialects or any of the @samp{%} operators that are available with

diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
index 82fceeee9d96412c8b29a539edb1957a085ead0c..58254b82b0e089a56e2030f83d2eed3c1bcf3e98 100644 (file)
--- a/gcc/doc/invoke.texi
+++ b/gcc/doc/invoke.texi
@@ -16088,9 +16088,22 @@ a default balanced compression setting is used.
 
 @opindex flto-toplevel-asm-heuristics
 @item -flto-toplevel-asm-heuristics
-Enable heuristics to recognize symbol identifiers in top-level basic asm
-(@pxref{Basic Asm}), and prevent them from being mangled or deleted during
-link-time optimization.
+Enables heuristics to find symbols used in top-level basic @code{asm}.
+This will restrict link-time optimizations that could cause renaming
+or deletion of such symbols which would result in missing symbol errors by
+linker.
+
+This flag is intended for projects that have not converted to using top-level
+extended @code{asm} (@pxref{Extended Asm}), which specify the usage directly
+without any false positives.
+
+The heuristics are simple and do not parse the assembly.
+The heuristics scan through top-level assembly for all possible identifiers;
+if an identifier is found among declared symbols, the symbol will be marked to
+restrict link-time optimizations.  Static symbols disable more optimizations.
+Identifiers followed by ':' disable more optimizations as well, because they
+might be a locally defined symbol in assembly, even when the declaration
+is marked 'extern'.
 
 @opindex fuse-linker-plugin
 @item -fuse-linker-plugin