-@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
braces:
@smallexample
+@group
@{
[@var{format}]
@var{opcode0} [@var{operands}]
+@end group
@var{opcode1} [@var{operands}]
+@group
@var{opcode2} [@var{operands}]
@dots{}
@}
+@end group
@end smallexample
The opcodes in a FLIX instruction are listed in the same order as the
@{ [@var{format};] @var{opcode0} [@var{operands}]; @var{opcode1} [@var{operands}]; @var{opcode2} [@var{operands}]; @dots{} @}
@end smallexample
-The assembler can automatically bundle opcodes into FLIX instructions.
-It encodes the opcodes in order, one at a time,
-choosing the smallest format where each opcode can be encoded and
-filling unused instruction slots with no-ops.
+If an opcode can only be encoded in a FLIX instruction but is not
+specified as part of a FLIX bundle, the assembler will choose the
+smallest format where the opcode can be encoded and
+will fill unused instruction slots with no-ops.
@menu
* Xtensa Opcodes:: Opcode Naming Conventions.
@node Xtensa Automatic Alignment
@subsection Automatic Instruction Alignment
@cindex alignment of @code{LOOP} instructions
-@cindex alignment of @code{ENTRY} instructions
@cindex alignment of branch targets
@cindex @code{LOOP} instructions, alignment
-@cindex @code{ENTRY} instructions, alignment
@cindex branch target alignment
The Xtensa assembler will automatically align certain instructions, both
instruction immediately following a call is treated as a branch target
in this context, because it will be the target of a return from the
call. This alignment has the potential to reduce branch penalties at
-some expense in code size. The assembler will not attempt to align
-labels with the prefixes @code{.Ln} and @code{.LM}, since these labels
-are used for debugging information and are not typically branch targets.
+some expense in code size.
This optimization is enabled by default. You can disable it with the
@samp{--no-target-@-align} command-line option (@pxref{Xtensa Options,
,Command Line Options}).
fetch width when aligning @code{LOOP} instructions (except if the first
instruction in the loop is a 64-bit instruction).
-Similarly, the @code{ENTRY} instruction must be aligned on a 0 mod 4
-byte boundary. The assembler satisfies this requirement by inserting
-zero bytes when required. In addition, labels immediately preceding the
-@code{ENTRY} instruction will be moved to the newly aligned instruction
-location.
+Previous versions of the assembler automatically aligned @code{ENTRY}
+instructions to 4-byte boundaries, but that alignment is now the
+programmer's responsibility.
@node Xtensa Relaxation
@section Xtensa Relaxation
@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
may result in:
@smallexample
+@group
bnez.n a2, M
j L
M:
+@end group
@end smallexample
(The @code{BNEZ.N} instruction would be used in this example only if the
might be relaxed to:
@smallexample
+@group
.literal .L1, func
l32r a8, .L1
callx8 a8
+@end group
@end smallexample
Because the addresses of targets of function calls are not generally
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
is assembled into the following machine code:
@smallexample
+@group
.literal .L1, 100000
l32r a0, .L1
+@end group
@end smallexample
@cindex @code{L8UI} instructions, relaxation
is translated to:
@smallexample
+@group
.literal .L1, 2040
l32r a1, .L1
- addi a1, a0, a1
+@end group
+@group
+ add a1, a0, a1
l32i a1, a1, 0
+@end group
@end smallexample
@noindent
For example:
@smallexample
+@group
addi a5, a6, 0
addi a5, a6, 512
+@end group
+@group
addi a5, a6, 513
addi a5, a6, 50000
+@end group
@end smallexample
is assembled into the following:
@smallexample
+@group
.literal .L1, 50000
mov.n a5, a6
+@end group
addmi a5, a6, 0x200
addmi a5, a6, 0x200
addi a5, a5, 1
+@group
l32r a5, .L1
add a5, a6, a5
+@end group
@end smallexample
@node Xtensa Directives
The Xtensa assembler supports a region-based directive syntax:
@smallexample
+@group
.begin @var{directive} [@var{options}]
@dots{}
.end @var{directive}
+@end group
@end smallexample
All the Xtensa-specific directives that apply to a region of code use
outer state. For example, consider:
@smallexample
+@group
.begin no-transform
L: add a0, a1, a2
+@end group
.begin transform
M: add a0, a1, a2
.end transform
+@group
N: add a0, a1, a2
.end no-transform
+@end group
@end smallexample
The @code{ADD} opcodes at @code{L} and @code{N} in the outer
Tensilica's assembler.
@smallexample
+@group
.begin [no-]schedule
.end [no-]schedule
+@end group
@end smallexample
This directive is ignored and has no effect on @command{@value{AS}}.
relaxation. @xref{Xtensa Call Relaxation, ,Function Call Relaxation}.
@smallexample
+@group
.begin [no-]longcalls
.end [no-]longcalls
+@end group
@end smallexample
Call relaxation is disabled by default unless the @samp{--longcalls}
optimization (@pxref{Xtensa Optimizations, ,Xtensa Optimizations}).
@smallexample
+@group
.begin [no-]transform
.end [no-]transform
+@end group
@end smallexample
Transformations are enabled by default unless the @samp{--no-transform}
@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
identical literals. For example, the code:
@smallexample
+@group
entry sp, 40
.literal .L1, sym
l32r a4, .L1
+@end group
@end smallexample
can be used to load a pointer to the symbol @code{sym} into register
@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
the unconditional jump.
@smallexample
+@group
.global M
code_start:
+@end group
j continue
.literal_position
.align 4
+@group
continue:
movi a4, M
+@end group
@end smallexample
@node Literal Prefix Directive
where the literals are defined.
@smallexample
+@group
.begin literal_prefix [@var{name}]
.end literal_prefix
+@end group
@end smallexample
For literals defined within the delimited region, the literal section
include the absolute addressing option for @code{L32R} instructions.
@smallexample
+@group
.begin [no-]absolute-literals
.end [no-]absolute-literals
+@end group
@end smallexample
These directives do not change the @code{L32R} mode---they only cause
projects / deliverable / binutils-gdb.git / blobdiff