-@c Copyright (C) 2002, 2004 Free Software Foundation, Inc.
+@c Copyright (C) 2002-2019 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
@end menu
@node Xtensa Options
-@section Command Line 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
Control the treatment of literal pools. The default is
-@samp{--no-@-text-@-section-@-literals}, which places literals in a
-separate section in the output file. This allows the literal pool to be
+@samp{--no-@-text-@-section-@-literals}, which places literals in
+separate sections in the output file. This allows the literal pool to be
placed in a data RAM/ROM. With @samp{--text-@-section-@-literals}, the
literals are interspersed in the text section in order to keep them as
close as possible to their references. This may be necessary for large
assembly files, where the literals would otherwise be out of range of the
-@code{L32R} instructions in the text section. These options only affect
+@code{L32R} instructions in the text section. Literals are grouped into
+pools following @code{.literal_position} directives or preceding
+@code{ENTRY} instructions. These options only affect literals referenced
+via PC-relative @code{L32R} instructions; literals for absolute mode
+@code{L32R} instructions are handled separately.
+@xref{Literal Directive, ,literal}.
+
+@item --auto-litpools | --no-auto-litpools
+@kindex --auto-litpools
+@kindex --no-auto-litpools
+Control the treatment of literal pools. The default is
+@samp{--no-@-auto-@-litpools}, which in the absence of
+@samp{--text-@-section-@-literals} places literals in separate sections
+in the output file. This allows the literal pool to be placed in a data
+RAM/ROM. With @samp{--auto-@-litpools}, the literals are interspersed
+in the text section in order to keep them as close as possible to their
+references, explicit @code{.literal_position} directives are not
+required. This may be necessary for very large functions, where single
+literal pool at the beginning of the function may not be reachable by
+@code{L32R} instructions at the end. These options only affect
literals referenced via PC-relative @code{L32R} instructions; literals
for absolute mode @code{L32R} instructions are handled separately.
+When used together with @samp{--text-@-section-@-literals},
+@samp{--auto-@-litpools} takes precedence.
+@xref{Literal Directive, ,literal}.
@item --absolute-literals | --no-absolute-literals
@kindex --absolute-literals
rare cases when the instructions must be exactly as specified in the
assembly source. Using @samp{--no-transform} causes out of range
instruction operands to be errors.
+
+@item --rename-section @var{oldname}=@var{newname}
+@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}).
+,Command-line Options}).
The target alignment optimization is done without adding instructions
that could increase the execution time of the program. If there are
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
Branch relaxation is enabled by default. It can be disabled by using
underscore prefixes (@pxref{Xtensa Opcodes, ,Opcode Names}), the
@samp{--no-transform} command-line option (@pxref{Xtensa Options,
-,Command Line Options}), or the @code{no-transform} directive
+,Command-line Options}), or the @code{no-transform} directive
(@pxref{Transform Directive, ,transform}).
@node Xtensa Call Relaxation
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 assembler 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
The assembler normally performs the following other relaxations. They
can be disabled by using underscore prefixes (@pxref{Xtensa Opcodes,
,Opcode Names}), the @samp{--no-transform} command-line option
-(@pxref{Xtensa Options, ,Command Line Options}), or the
+(@pxref{Xtensa Options, ,Command-line Options}), or the
@code{no-transform} directive (@pxref{Transform Directive, ,transform}).
@cindex @code{MOVI} instructions, 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
offsets in the range from 0 to 255. The @code{L16SI} and @code{L16UI}
machine instructions can only be used with offsets from 0 to 510. The
@code{L32I} machine instruction can only be used with offsets from 0 to
-1020. A load offset outside these ranges can be materalized with
+1020. A load offset outside these ranges can be materialized with
an @code{L32R} instruction if the destination register of the load
is different than the source address register. For example:
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
@cindex Xtensa directives
@cindex directives, Xtensa
-The Xtensa assember supports a region-based directive syntax:
+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
* Literal Position Directive:: Specify Inline Literal Pool Locations.
* Literal Prefix Directive:: Specify Literal Section Name Prefix.
* Absolute Literals Directive:: Control PC-Relative vs. Absolute Literals.
-* Frame Directive:: Describe a stack frame.
@end menu
@node Schedule Directive
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
@code{ENTRY} and @code{L32R} instructions; instead, the assembler puts
the data in a literal pool.
-Literal pools for absolute mode @code{L32R} instructions
-(@pxref{Absolute Literals Directive}) are placed in a seperate
-@code{.lit4} section. By default literal pools for PC-relative mode
-@code{L32R} instructions are placed in a separate @code{.literal}
-section; however, when using the @samp{--text-@-section-@-literals}
-option (@pxref{Xtensa Options, ,Command Line Options}), the literal
-pools are placed in the current section. These text section literal
+Literal pools are placed by default in separate literal sections;
+however, when using the @samp{--text-@-section-@-literals}
+option (@pxref{Xtensa Options, ,Command-line Options}), the literal
+pools for PC-relative mode @code{L32R} instructions
+are placed in the current section.@footnote{Literals for the
+@code{.init} and @code{.fini} sections are always placed in separate
+sections, even when @samp{--text-@-section-@-literals} is enabled.}
+These text section literal
pools are created automatically before @code{ENTRY} instructions and
manually after @samp{.literal_position} directives (@pxref{Literal
Position Directive, ,literal_position}). If there are no preceding
must be used to place the text section literal pools; otherwise,
@command{@value{AS}} will report an error.
+When literals are placed in separate sections, the literal section names
+are derived from the names of the sections where the literals are
+defined. The base literal section names are @code{.literal} for
+PC-relative mode @code{L32R} instructions and @code{.lit4} for absolute
+mode @code{L32R} instructions (@pxref{Absolute Literals Directive,
+,absolute-literals}). These base names are used for literals defined in
+the default @code{.text} section. For literals defined in other
+sections or within the scope of a @code{literal_prefix} directive
+(@pxref{Literal Prefix Directive, ,literal_prefix}), the following rules
+determine the literal section name:
+
+@enumerate
+@item
+If the current section is a member of a section group, the literal
+section name includes the group name as a suffix to the base
+@code{.literal} or @code{.lit4} name, with a period to separate the base
+name and group name. The literal section is also made a member of the
+group.
+
+@item
+If the current section name (or @code{literal_prefix} value) begins with
+``@code{.gnu.linkonce.@var{kind}.}'', the literal section name is formed
+by replacing ``@code{.@var{kind}}'' with the base @code{.literal} or
+@code{.lit4} name. For example, for literals defined in a section named
+@code{.gnu.linkonce.t.func}, the literal section will be
+@code{.gnu.linkonce.literal.func} or @code{.gnu.linkonce.lit4.func}.
+
+@item
+If the current section name (or @code{literal_prefix} value) ends with
+@code{.text}, the literal section name is formed by replacing that
+suffix with the base @code{.literal} or @code{.lit4} name. For example,
+for literals defined in a section named @code{.iram0.text}, the literal
+section will be @code{.iram0.literal} or @code{.iram0.lit4}.
+
+@item
+If none of the preceding conditions apply, the literal section name is
+formed by adding the base @code{.literal} or @code{.lit4} name as a
+suffix to the current section name (or @code{literal_prefix} value).
+@end enumerate
+
@node Literal Position Directive
@subsection literal_position
@cindex @code{literal_position} directive
@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
@subsection literal_prefix
@cindex @code{literal_prefix} directive
-The @code{literal_prefix} directive allows you to specify different
-sections to hold literals from different portions of an assembly file.
-With this directive, a single assembly file can be used to generate code
-into multiple sections, including literals generated by the assembler.
+The @code{literal_prefix} directive allows you to override the default
+literal section names, which are derived from the names of the sections
+where the literals are defined.
@smallexample
+@group
.begin literal_prefix [@var{name}]
.end literal_prefix
+@end group
@end smallexample
-By default the assembler places literal pools in sections separate from
-the instructions, using the default literal section names of
-@code{.literal} for PC-relative mode @code{L32R} instructions and
-@code{.lit4} for absolute mode @code{L32R} instructions (@pxref{Absolute
-Literals Directive}). The @code{literal_prefix} directive causes
-different literal sections to be used for the code inside the delimited
-region. The new literal sections are determined by including @var{name}
-as a prefix to the default literal section names. If the @var{name}
+For literals defined within the delimited region, the literal section
+names are derived from the @var{name} argument instead of the name of
+the current section. The rules used to derive the literal section names
+do not change. @xref{Literal Directive, ,literal}. If the @var{name}
argument is omitted, the literal sections revert to the defaults. This
directive has no effect when using the
@samp{--text-@-section-@-literals} option (@pxref{Xtensa Options,
-,Command Line Options}).
-
-Except for two special cases, the assembler determines the new literal
-sections by simply prepending @var{name} to the default section names,
-resulting in @code{@var{name}.literal} and @code{@var{name}.lit4}
-sections. The @code{literal_prefix} directive is often used with the
-name of the current text section as the prefix argument. To facilitate
-this usage, the assembler uses special case rules when it recognizes
-@var{name} as a text section name. First, if @var{name} ends with
-@code{.text}, that suffix is not included in the literal section name.
-For example, if @var{name} is @code{.iram0.text}, then the literal
-sections will be @code{.iram0.literal} and @code{.iram0.lit4}. Second,
-if @var{name} begins with @code{.gnu.linkonce.t.}, then the literal
-section names are formed by replacing the @code{.t} substring with
-@code{.literal} and @code{.lit4}. For example, if @var{name} is
-@code{.gnu.linkonce.t.func}, the literal sections will be
-@code{.gnu.linkonce.literal.func} and @code{.gnu.linkonce.lit4.func}.
+,Command-line Options}).
@node Absolute Literals Directive
@subsection absolute-literals
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
The @code{absolute-@-literals} directive can then be used to override
the default determined by the command-line options.
-@node Frame Directive
-@subsection frame
-@cindex @code{frame} directive
-
-This directive tells the assembler to emit information to allow the
-debugger to locate a function's stack frame. The syntax is:
-
-@smallexample
- .frame @var{reg}, @var{size}
-@end smallexample
-
-where @var{reg} is the register used to hold the frame pointer (usually
-the same as the stack pointer) and @var{size} is the size in bytes of
-the stack frame. The @code{.frame} directive is typically placed
-near the @code{ENTRY} instruction for a function.
-
-In many circumstances, this information just duplicates the
-information given in the function's @code{ENTRY} instruction; however,
-there are two cases where this is not true:
-
-@enumerate
-@item
-The size of the stack frame is too big to fit in the immediate field
-of the @code{ENTRY} instruction.
-
-@item
-The frame pointer is different than the stack pointer, as with functions
-that call @code{alloca}.
-@end enumerate
-
@c Local Variables:
@c fill-column: 72
@c End:
projects / deliverable / binutils-gdb.git / blobdiff