[pushed] AVR: Update linker stubs <-> relaxing relations in docs
Commit Message
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.
Applied to trunk.
Johann
--
gcc/
* doc/invoke.texi (AVR Options): Update documentation of linker
stubs relation to linker relaxation.
@@ -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.