From: Michal Jires <mjires@suse.cz>
Date: Thu, 29 Jan 2026 14:07:49 +0000 (+0100)
Subject: doc: Explain flto-toplevel-asm-heuristics
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=bf9abf065e96a825564cda0bcc427eb849ecc3b5;p=thirdparty%2Fgcc.git

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 ac86a2e1484..5e481126069 100644
--- 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 82fceeee9d9..58254b82b0e 100644
--- 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