https://gcc.gnu.org/g:bf9abf065e96a825564cda0bcc427eb849ecc3b5
commit r16-7192-gbf9abf065e96a825564cda0bcc427eb849ecc3b5 Author: Michal Jires <[email protected]> Date: Thu Jan 29 15:07:49 2026 +0100 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: --- gcc/doc/extend.texi | 5 +++++ gcc/doc/invoke.texi | 19 ++++++++++++++++--- 2 files changed, 21 insertions(+), 3 deletions(-) diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi index ac86a2e14847..5e481126069d 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 82fceeee9d96..58254b82b0e0 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
