-@c Copyright (C) 2002, 2003, 2004 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
+@c man end
@ifset GENERIC
@page
@node Xtensa-Dependent
@node Xtensa Options
@section Command Line Options
-The Xtensa version of the @sc{gnu} assembler supports these
-special options:
+@c man begin OPTIONS
+@table @gcctabopt
-@table @code
@item --text-section-literals | --no-text-section-literals
@kindex --text-section-literals
@kindex --no-text-section-literals
@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
+
@node Xtensa Syntax
@section Assembler Syntax
@cindex syntax, Xtensa assembler
Block comments are delimited by @samp{/*} and @samp{*/}. End of line
comments may be introduced with either @samp{#} or @samp{//}.
+If a @samp{#} appears as the first character of a line then the whole
+line is treated as a comment, but in this case the line could also be
+a logical line number directive (@pxref{Comments}) or a preprocessor
+control command (@pxref{Preprocessing}).
+
Instructions consist of a leading opcode or macro name followed by
whitespace and an optional comma-separated list of operands:
@var{opcode} [@var{operand}, @dots{}]
@end smallexample
-Instructions must be separated by a newline or semicolon.
+Instructions must be separated by a newline or semicolon (@samp{;}).
FLIX instructions, which bundle multiple opcodes together in a single
instruction, are specified by enclosing the bundled opcodes inside
@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
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
@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
@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