Allow symbols in MEMORY region specification

[deliverable/binutils-gdb.git] / gas / doc / c-xtensa.texi

diff --git a/gas/doc/c-xtensa.texi b/gas/doc/c-xtensa.texi
index 67c6f15055a84c42e57e87a4bcabea3fa4608590..7019f8478ad9198c2ce74f96af2782a638661681 100644 (file)
--- a/gas/doc/c-xtensa.texi
+++ b/gas/doc/c-xtensa.texi
@@ -1,5 +1,4 @@
-@c Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2011
-@c Free Software Foundation, Inc.
+@c Copyright (C) 2002-2015 Free Software Foundation, Inc.
 @c This is part of the GAS manual.
 @c For copying conditions, see the file as.texinfo.
 @c
@@ -92,6 +91,16 @@ instruction operands to be errors.
 @kindex --rename-section
 Rename the @var{oldname} section to @var{newname}.  This option can be used
 multiple times to rename multiple sections.
+
+@item --trampolines | --no-trampolines
+@kindex --trampolines
+@kindex --no-trampolines
+Enable or disable transformation of jump instructions to allow jumps
+across a greater range of addresses.  @xref{Xtensa Jump Relaxation,
+,Jump Trampolines}.  This option should be used when jump targets can
+potentially be out of range.  In the absence of such jumps this option
+does not affect code size or performance.  The default is
+@samp{--trampolines}.
 @end table
 
 @c man end
@@ -312,6 +321,7 @@ fields.
 @menu
 * Xtensa Branch Relaxation::        Relaxation of Branches.
 * Xtensa Call Relaxation::          Relaxation of Function Calls.
+* Xtensa Jump Relaxation::          Relaxation of Jumps.
 * Xtensa Immediate Relaxation::     Relaxation of other Immediate Fields.
 @end menu
 
@@ -399,6 +409,87 @@ and some of the calls are out of range, function call relaxation can be
 enabled using the @samp{--longcalls} command-line option or the
 @code{longcalls} directive (@pxref{Longcalls Directive, ,longcalls}).
 
+@node Xtensa Jump Relaxation
+@subsection Jump Relaxation
+@cindex relaxation of jump instructions
+@cindex jump instructions, relaxation
+
+Jump instruction may require relaxation because the Xtensa jump instruction
+(@code{J}) provide a PC-relative offset of only 128 Kbytes in either
+direction.  One option is to use jump long (@code{J.L}) instruction, which
+depending on jump distance may be assembled as jump (@code{J}) or indirect
+jump (@code{JX}).  However it needs a free register.  When there's no spare
+register it is possible to plant intermediate jump sites (trampolines)
+between the jump instruction and its target.  These sites may be located in
+areas unreachable by normal code execution flow, in that case they only
+contain intermediate jumps, or they may be inserted in the middle of code
+block, in which case there's an additional jump from the beginning of the
+trampoline to the instruction past its end.  So, for example:
+
+@smallexample
+@group
+    j 1f
+    ...
+    retw
+    ...
+    mov a10, a2
+    call8 func
+    ...
+1:
+    ...
+@end group
+@end smallexample
+
+might be relaxed to:
+
+@smallexample
+@group
+    j .L0_TR_1
+    ...
+    retw
+.L0_TR_1:
+    j 1f
+    ...
+    mov a10, a2
+    call8 func
+    ...
+1:
+    ...
+@end group
+@end smallexample
+
+or to:
+
+@smallexample
+@group
+    j .L0_TR_1
+    ...
+    retw
+    ...
+    mov a10, a2
+    j .L0_TR_0
+.L0_TR_1:
+    j 1f
+.L0_TR_0:
+    call8 func
+    ...
+1:
+    ...
+@end group
+@end smallexample
+
+The Xtensa assempler uses trampolines with jump around only when it cannot
+find suitable unreachable trampoline.  There may be multiple trampolines
+between the jump instruction and its target.
+
+This relaxation does not apply to jumps to undefined symbols, assuming they
+will reach their targets once resolved.
+
+Jump relaxation is enabled by default because it does not affect code size
+or performance while the code itself is small.  This relaxation may be
+disabled completely with @samp{--no-trampolines} or @samp{--no-transform}
+command-line options (@pxref{Xtensa Options, ,Command Line Options}).
+
 @node Xtensa Immediate Relaxation
 @subsection Other Immediate Field Relaxation
 @cindex immediate fields, relaxation
@@ -629,7 +720,7 @@ both directives and command-line flags.
 @subsection literal
 @cindex @code{literal} directive
 
-The @code{.literal} directive is used to define literal pool data, i.e., 
+The @code{.literal} directive is used to define literal pool data, i.e.,
 read-only 32-bit data accessed via @code{L32R} instructions.
 
 @smallexample
@@ -727,7 +818,7 @@ The @code{.literal_position} directive is ignored when the
 @samp{--text-@-section-@-literals} option is not used or when
 @code{L32R} instructions use the absolute addressing mode.
 
-The assembler will automatically place text section literal pools 
+The assembler will automatically place text section literal pools
 before @code{ENTRY} instructions, so the @code{.literal_position}
 directive is only needed to specify some other location for a literal
 pool.  You may need to add an explicit jump instruction to skip over an