https://gcc.gnu.org/g:bdb72b81eece14ddfefc6f9e456bf3ab3791f031
commit r17-4853-gbdb72b81eece14ddfefc6f9e456bf3ab3791f031 Author: Georg-Johann Lay <[email protected]> Date: Sat Oct 3 13:30:20 2026 +0200 AVR: Update linker stubs <-> relaxing relations in docs This patch updates the AVR documentation on linker stubs and their relation to linker relaxation (-mrelax/--relax). For example, relaxation is no more needed to generate stubs. gcc/ * doc/invoke.texi (AVR Options): Update documentation of linker stubs relation to linker relaxation. Diff: --- gcc/doc/invoke.texi | 39 +++++++++++++++++++++------------------ 1 file changed, 21 insertions(+), 18 deletions(-) diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi index 41a4f3dc544e..f89b984fd25f 100644 --- a/gcc/doc/invoke.texi +++ b/gcc/doc/invoke.texi @@ -24510,7 +24510,7 @@ known before code is located. Therefore, the assembly code generated by the compiler is the same, but the instructions in the executable may differ from instructions in the assembly code. -Relaxing must be turned on if linker stubs are needed, see the +Relaxing can be used to remove unused linker stubs, see the section on @code{EIND} and linker stubs below. @opindex mprune-vectab @@ -24523,18 +24523,18 @@ Setting @option{-mprune-vectab} just adds the @option{--prune-vectab} option to the linker's command line, provided the required GNU Binutils support (@w{@uref{https://sourceware.org/PR34679,,PR34679}}) is available. Otherwise, or when relaxing is not enabled, the option has no effect. +This option makes it harder to find rogue IRQs that lack an interrupt service +routine (ISR) and whose IRQ vector is located beyond the last used one. What is not supported are jumps like @example - JMP 0x18 +JMP 0x18 @end example that target a vector table entry that is not the reset vector. Use code like @example - JMP __vectors + 0x18 +JMP __vectors + 0x18 @end example instead. -This option makes it harder to find rogue IRQs that lack an interrupt service -routine (ISR) and whose IRQ vector is located beyond the last used one. @opindex mstrict-addr-space-subsets @item -mstrict-addr-space-subsets @@ -24773,15 +24773,14 @@ prologue/epilogue. @item For indirect calls to functions and computed goto, the linker generates @emph{stubs}. Stubs are jump pads sometimes also called -@emph{trampolines}. Thus, the indirect call/jump jumps to such a stub. -The stub contains a direct jump to the desired address. +@emph{trampolines}. The indirect @code{EICALL}/@code{EIJMP} jumps to such a +stub, which contains a direct @code{JMP} to the desired address. @item -Linker relaxation must be turned on so that the linker generates -the stubs correctly in all situations. See the compiler option -@option{-mrelax} and the linker option @option{--relax}. -There are corner cases where the linker is supposed to generate stubs -but aborts without relaxation and without a helpful error message. +The @code{.trampolines} section contains unused stubs that target +locations in the same 128 KiB block like the trampolines. +Linker relaxation can be turned on to remove such unused stubs, see +the compiler option @option{-mrelax} and the linker option @option{--relax}. @item The default linker script is arranged for code with @code{EIND = 0}. @@ -24819,8 +24818,8 @@ init3_set_eind (void) The @code{__trampolines_start} symbol is defined in the linker script. @item -Stubs are generated automatically by the linker if -the following two conditions are met: +Stubs are generated automatically by the linker when +the following three conditions are met: @itemize @minus @item The address of a label is taken by means of the @code{gs} modifier @@ -24829,17 +24828,21 @@ the following two conditions are met: LDI r24, lo8(gs(@var{func})) LDI r25, hi8(gs(@var{func})) @end example -@item The final location of that label is in a code segment -@emph{outside} the segment where the stubs are located. +@item The AVR device has more than 128 KiB of program memory. On devices +with at most 128 KiB of program memory, the @code{gs} modifier behaves +like @code{pm}, i.e.@: it evaluates to the word address of the symbol +without generating a stub. +@item Linker relaxation if off, or the symbol has a value outside +the 128 KiB block containing the trampolines. @end itemize @item The compiler emits such @code{gs} modifiers for code labels in the following situations: @itemize @minus -@item Taking address of a function or code label. +@item Taking the address of a function or code label. @item Computed goto. -@item If prologue-save function is used, see @option{-mcall-prologues} +@item If the prologue-save function is used, see the @option{-mcall-prologues} command-line option. @item Switch/case dispatch tables. If you do not want such dispatch tables you can specify the @option{-fno-jump-tables} command-line option.
