mirror of
https://github.com/darlinghq/darling-gdb.git
synced 2024-12-05 02:47:05 +00:00
9456465c21
(add_section_rename): Delete. Inlined into... (build_section_rename): ...here. Use xstrdup instead of strdup. (xtensa_section_rename): Drop "const" from argument and return types. (md_show_usage): Indent to match show_usage(). * config/tc-xtensa.h: Remove XTENSA_SECTION_RENAME ifdefs. (tc_canonicalize_section_name): Define. (md_elf_section_rename): Remove unused macro. * doc/as.texinfo (Overview): Document Xtensa --rename-section option. * doc/c-xtensa.texi (Xtensa Options): Likewise. (Frame Directive): Delete.
754 lines
30 KiB
Plaintext
754 lines
30 KiB
Plaintext
@c Copyright (C) 2002, 2004 Free Software Foundation, Inc.
|
|
@c This is part of the GAS manual.
|
|
@c For copying conditions, see the file as.texinfo.
|
|
@c
|
|
@ifset GENERIC
|
|
@page
|
|
@node Xtensa-Dependent
|
|
@chapter Xtensa Dependent Features
|
|
@end ifset
|
|
@ifclear GENERIC
|
|
@node Machine Dependencies
|
|
@chapter Xtensa Dependent Features
|
|
@end ifclear
|
|
|
|
@cindex Xtensa architecture
|
|
This chapter covers features of the @sc{gnu} assembler that are specific
|
|
to the Xtensa architecture. For details about the Xtensa instruction
|
|
set, please consult the @cite{Xtensa Instruction Set Architecture (ISA)
|
|
Reference Manual}.
|
|
|
|
@menu
|
|
* Xtensa Options:: Command-line Options.
|
|
* Xtensa Syntax:: Assembler Syntax for Xtensa Processors.
|
|
* Xtensa Optimizations:: Assembler Optimizations.
|
|
* Xtensa Relaxation:: Other Automatic Transformations.
|
|
* Xtensa Directives:: Directives for Xtensa Processors.
|
|
@end menu
|
|
|
|
@node Xtensa Options
|
|
@section Command Line Options
|
|
|
|
The Xtensa version of the @sc{gnu} assembler supports these
|
|
special options:
|
|
|
|
@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
|
|
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
|
|
literals referenced via PC-relative @code{L32R} instructions; literals
|
|
for absolute mode @code{L32R} instructions are handled separately.
|
|
|
|
@item --absolute-literals | --no-absolute-literals
|
|
@kindex --absolute-literals
|
|
@kindex --no-absolute-literals
|
|
Indicate to the assembler whether @code{L32R} instructions use absolute
|
|
or PC-relative addressing. If the processor includes the absolute
|
|
addressing option, the default is to use absolute @code{L32R}
|
|
relocations. Otherwise, only the PC-relative @code{L32R} relocations
|
|
can be used.
|
|
|
|
@item --target-align | --no-target-align
|
|
@kindex --target-align
|
|
@kindex --no-target-align
|
|
Enable or disable automatic alignment to reduce branch penalties at some
|
|
expense in code size. @xref{Xtensa Automatic Alignment, ,Automatic
|
|
Instruction Alignment}. This optimization is enabled by default. Note
|
|
that the assembler will always align instructions like @code{LOOP} that
|
|
have fixed alignment requirements.
|
|
|
|
@item --longcalls | --no-longcalls
|
|
@kindex --longcalls
|
|
@kindex --no-longcalls
|
|
Enable or disable transformation of call instructions to allow calls
|
|
across a greater range of addresses. @xref{Xtensa Call Relaxation,
|
|
,Function Call Relaxation}. This option should be used when call
|
|
targets can potentially be out of range. It may degrade both code size
|
|
and performance, but the linker can generally optimize away the
|
|
unnecessary overhead when a call ends up within range. The default is
|
|
@samp{--no-@-longcalls}.
|
|
|
|
@item --transform | --no-transform
|
|
@kindex --transform
|
|
@kindex --no-transform
|
|
Enable or disable all assembler transformations of Xtensa instructions,
|
|
including both relaxation and optimization. The default is
|
|
@samp{--transform}; @samp{--no-transform} should only be used in the
|
|
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.
|
|
@end table
|
|
|
|
@node Xtensa Syntax
|
|
@section Assembler Syntax
|
|
@cindex syntax, Xtensa assembler
|
|
@cindex Xtensa assembler syntax
|
|
@cindex FLIX syntax
|
|
|
|
Block comments are delimited by @samp{/*} and @samp{*/}. End of line
|
|
comments may be introduced with either @samp{#} or @samp{//}.
|
|
|
|
Instructions consist of a leading opcode or macro name followed by
|
|
whitespace and an optional comma-separated list of operands:
|
|
|
|
@smallexample
|
|
@var{opcode} [@var{operand}, @dots{}]
|
|
@end smallexample
|
|
|
|
Instructions must be separated by a newline or semicolon.
|
|
|
|
FLIX instructions, which bundle multiple opcodes together in a single
|
|
instruction, are specified by enclosing the bundled opcodes inside
|
|
braces:
|
|
|
|
@smallexample
|
|
@{
|
|
[@var{format}]
|
|
@var{opcode0} [@var{operands}]
|
|
@var{opcode1} [@var{operands}]
|
|
@var{opcode2} [@var{operands}]
|
|
@dots{}
|
|
@}
|
|
@end smallexample
|
|
|
|
The opcodes in a FLIX instruction are listed in the same order as the
|
|
corresponding instruction slots in the TIE format declaration.
|
|
Directives and labels are not allowed inside the braces of a FLIX
|
|
instruction. A particular TIE format name can optionally be specified
|
|
immediately after the opening brace, but this is usually unnecessary.
|
|
The assembler will automatically search for a format that can encode the
|
|
specified opcodes, so the format name need only be specified in rare
|
|
cases where there is more than one applicable format and where it
|
|
matters which of those formats is used. A FLIX instruction can also be
|
|
specified on a single line by separating the opcodes with semicolons:
|
|
|
|
@smallexample
|
|
@{ [@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.
|
|
|
|
@menu
|
|
* Xtensa Opcodes:: Opcode Naming Conventions.
|
|
* Xtensa Registers:: Register Naming.
|
|
@end menu
|
|
|
|
@node Xtensa Opcodes
|
|
@subsection Opcode Names
|
|
@cindex Xtensa opcode names
|
|
@cindex opcode names, Xtensa
|
|
|
|
See the @cite{Xtensa Instruction Set Architecture (ISA) Reference
|
|
Manual} for a complete list of opcodes and descriptions of their
|
|
semantics.
|
|
|
|
@cindex _ opcode prefix
|
|
If an opcode name is prefixed with an underscore character (@samp{_}),
|
|
@command{@value{AS}} will not transform that instruction in any way. The
|
|
underscore prefix disables both optimization (@pxref{Xtensa
|
|
Optimizations, ,Xtensa Optimizations}) and relaxation (@pxref{Xtensa
|
|
Relaxation, ,Xtensa Relaxation}) for that particular instruction. Only
|
|
use the underscore prefix when it is essential to select the exact
|
|
opcode produced by the assembler. Using this feature unnecessarily
|
|
makes the code less efficient by disabling assembler optimization and
|
|
less flexible by disabling relaxation.
|
|
|
|
Note that this special handling of underscore prefixes only applies to
|
|
Xtensa opcodes, not to either built-in macros or user-defined macros.
|
|
When an underscore prefix is used with a macro (e.g., @code{_MOV}), it
|
|
refers to a different macro. The assembler generally provides built-in
|
|
macros both with and without the underscore prefix, where the underscore
|
|
versions behave as if the underscore carries through to the instructions
|
|
in the macros. For example, @code{_MOV} may expand to @code{_MOV.N}@.
|
|
|
|
The underscore prefix only applies to individual instructions, not to
|
|
series of instructions. For example, if a series of instructions have
|
|
underscore prefixes, the assembler will not transform the individual
|
|
instructions, but it may insert other instructions between them (e.g.,
|
|
to align a @code{LOOP} instruction). To prevent the assembler from
|
|
modifying a series of instructions as a whole, use the
|
|
@code{no-transform} directive. @xref{Transform Directive, ,transform}.
|
|
|
|
@node Xtensa Registers
|
|
@subsection Register Names
|
|
@cindex Xtensa register names
|
|
@cindex register names, Xtensa
|
|
@cindex sp register
|
|
|
|
The assembly syntax for a register file entry is the ``short'' name for
|
|
a TIE register file followed by the index into that register file. For
|
|
example, the general-purpose @code{AR} register file has a short name of
|
|
@code{a}, so these registers are named @code{a0}@dots{}@code{a15}.
|
|
As a special feature, @code{sp} is also supported as a synonym for
|
|
@code{a1}. Additional registers may be added by processor configuration
|
|
options and by designer-defined TIE extensions. An initial @samp{$}
|
|
character is optional in all register names.
|
|
|
|
@node Xtensa Optimizations
|
|
@section Xtensa Optimizations
|
|
@cindex optimizations
|
|
|
|
The optimizations currently supported by @command{@value{AS}} are
|
|
generation of density instructions where appropriate and automatic
|
|
branch target alignment.
|
|
|
|
@menu
|
|
* Density Instructions:: Using Density Instructions.
|
|
* Xtensa Automatic Alignment:: Automatic Instruction Alignment.
|
|
@end menu
|
|
|
|
@node Density Instructions
|
|
@subsection Using Density Instructions
|
|
@cindex density instructions
|
|
|
|
The Xtensa instruction set has a code density option that provides
|
|
16-bit versions of some of the most commonly used opcodes. Use of these
|
|
opcodes can significantly reduce code size. When possible, the
|
|
assembler automatically translates instructions from the core
|
|
Xtensa instruction set into equivalent instructions from the Xtensa code
|
|
density option. This translation can be disabled by using underscore
|
|
prefixes (@pxref{Xtensa Opcodes, ,Opcode Names}), by using the
|
|
@samp{--no-transform} command-line option (@pxref{Xtensa Options, ,Command
|
|
Line Options}), or by using the @code{no-transform} directive
|
|
(@pxref{Transform Directive, ,transform}).
|
|
|
|
It is a good idea @emph{not} to use the density instructions directly.
|
|
The assembler will automatically select dense instructions where
|
|
possible. If you later need to use an Xtensa processor without the code
|
|
density option, the same assembly code will then work without modification.
|
|
|
|
@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
|
|
to optimize performance and to satisfy architectural requirements.
|
|
|
|
As an optimization to improve performance, the assembler attempts to
|
|
align branch targets so they do not cross instruction fetch boundaries.
|
|
(Xtensa processors can be configured with either 32-bit or 64-bit
|
|
instruction fetch widths.) An
|
|
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.
|
|
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}).
|
|
|
|
The target alignment optimization is done without adding instructions
|
|
that could increase the execution time of the program. If there are
|
|
density instructions in the code preceding a target, the assembler can
|
|
change the target alignment by widening some of those instructions to
|
|
the equivalent 24-bit instructions. Extra bytes of padding can be
|
|
inserted immediately following unconditional jump and return
|
|
instructions.
|
|
This approach is usually successful in aligning many, but not all,
|
|
branch targets.
|
|
|
|
The @code{LOOP} family of instructions must be aligned such that the
|
|
first instruction in the loop body does not cross an instruction fetch
|
|
boundary (e.g., with a 32-bit fetch width, a @code{LOOP} instruction
|
|
must be on either a 1 or 2 mod 4 byte boundary). The assembler knows
|
|
about this restriction and inserts the minimal number of 2 or 3 byte
|
|
no-op instructions to satisfy it. When no-op instructions are added,
|
|
any label immediately preceding the original loop will be moved in order
|
|
to refer to the loop instruction, not the newly generated no-op
|
|
instruction. To preserve binary compatibility across processors with
|
|
different fetch widths, the assembler conservatively assumes a 32-bit
|
|
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.
|
|
|
|
@node Xtensa Relaxation
|
|
@section Xtensa Relaxation
|
|
@cindex relaxation
|
|
|
|
When an instruction operand is outside the range allowed for that
|
|
particular instruction field, @command{@value{AS}} can transform the code
|
|
to use a functionally-equivalent instruction or sequence of
|
|
instructions. This process is known as @dfn{relaxation}. This is
|
|
typically done for branch instructions because the distance of the
|
|
branch targets is not known until assembly-time. The Xtensa assembler
|
|
offers branch relaxation and also extends this concept to function
|
|
calls, @code{MOVI} instructions and other instructions with immediate
|
|
fields.
|
|
|
|
@menu
|
|
* Xtensa Branch Relaxation:: Relaxation of Branches.
|
|
* Xtensa Call Relaxation:: Relaxation of Function Calls.
|
|
* Xtensa Immediate Relaxation:: Relaxation of other Immediate Fields.
|
|
@end menu
|
|
|
|
@node Xtensa Branch Relaxation
|
|
@subsection Conditional Branch Relaxation
|
|
@cindex relaxation of branch instructions
|
|
@cindex branch instructions, relaxation
|
|
|
|
When the target of a branch is too far away from the branch itself,
|
|
i.e., when the offset from the branch to the target is too large to fit
|
|
in the immediate field of the branch instruction, it may be necessary to
|
|
replace the branch with a branch around a jump. For example,
|
|
|
|
@smallexample
|
|
beqz a2, L
|
|
@end smallexample
|
|
|
|
may result in:
|
|
|
|
@smallexample
|
|
bnez.n a2, M
|
|
j L
|
|
M:
|
|
@end smallexample
|
|
|
|
(The @code{BNEZ.N} instruction would be used in this example only if the
|
|
density option is available. Otherwise, @code{BNEZ} would be used.)
|
|
|
|
This relaxation works well because the unconditional jump instruction
|
|
has a much larger offset range than the various conditional branches.
|
|
However, an error will occur if a branch target is beyond the range of a
|
|
jump instruction. @command{@value{AS}} cannot relax unconditional jumps.
|
|
Similarly, an error will occur if the original input contains an
|
|
unconditional jump to a target that is out of range.
|
|
|
|
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
|
|
(@pxref{Transform Directive, ,transform}).
|
|
|
|
@node Xtensa Call Relaxation
|
|
@subsection Function Call Relaxation
|
|
@cindex relaxation of call instructions
|
|
@cindex call instructions, relaxation
|
|
|
|
Function calls may require relaxation because the Xtensa immediate call
|
|
instructions (@code{CALL0}, @code{CALL4}, @code{CALL8} and
|
|
@code{CALL12}) provide a PC-relative offset of only 512 Kbytes in either
|
|
direction. For larger programs, it may be necessary to use indirect
|
|
calls (@code{CALLX0}, @code{CALLX4}, @code{CALLX8} and @code{CALLX12})
|
|
where the target address is specified in a register. The Xtensa
|
|
assembler can automatically relax immediate call instructions into
|
|
indirect call instructions. This relaxation is done by loading the
|
|
address of the called function into the callee's return address register
|
|
and then using a @code{CALLX} instruction. So, for example:
|
|
|
|
@smallexample
|
|
call8 func
|
|
@end smallexample
|
|
|
|
might be relaxed to:
|
|
|
|
@smallexample
|
|
.literal .L1, func
|
|
l32r a8, .L1
|
|
callx8 a8
|
|
@end smallexample
|
|
|
|
Because the addresses of targets of function calls are not generally
|
|
known until link-time, the assembler must assume the worst and relax all
|
|
the calls to functions in other source files, not just those that really
|
|
will be out of range. The linker can recognize calls that were
|
|
unnecessarily relaxed, and it will remove the overhead introduced by the
|
|
assembler for those cases where direct calls are sufficient.
|
|
|
|
Call relaxation is disabled by default because it can have a negative
|
|
effect on both code size and performance, although the linker can
|
|
usually eliminate the unnecessary overhead. If a program is too large
|
|
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 Immediate Relaxation
|
|
@subsection Other Immediate Field Relaxation
|
|
@cindex immediate fields, relaxation
|
|
@cindex relaxation of immediate fields
|
|
|
|
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
|
|
@code{no-transform} directive (@pxref{Transform Directive, ,transform}).
|
|
|
|
@cindex @code{MOVI} instructions, relaxation
|
|
@cindex relaxation of @code{MOVI} instructions
|
|
The @code{MOVI} machine instruction can only materialize values in the
|
|
range from -2048 to 2047. Values outside this range are best
|
|
materialized with @code{L32R} instructions. Thus:
|
|
|
|
@smallexample
|
|
movi a0, 100000
|
|
@end smallexample
|
|
|
|
is assembled into the following machine code:
|
|
|
|
@smallexample
|
|
.literal .L1, 100000
|
|
l32r a0, .L1
|
|
@end smallexample
|
|
|
|
@cindex @code{L8UI} instructions, relaxation
|
|
@cindex @code{L16SI} instructions, relaxation
|
|
@cindex @code{L16UI} instructions, relaxation
|
|
@cindex @code{L32I} instructions, relaxation
|
|
@cindex relaxation of @code{L8UI} instructions
|
|
@cindex relaxation of @code{L16SI} instructions
|
|
@cindex relaxation of @code{L16UI} instructions
|
|
@cindex relaxation of @code{L32I} instructions
|
|
The @code{L8UI} machine instruction can only be used with immediate
|
|
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
|
|
an @code{L32R} instruction if the destination register of the load
|
|
is different than the source address register. For example:
|
|
|
|
@smallexample
|
|
l32i a1, a0, 2040
|
|
@end smallexample
|
|
|
|
is translated to:
|
|
|
|
@smallexample
|
|
.literal .L1, 2040
|
|
l32r a1, .L1
|
|
addi a1, a0, a1
|
|
l32i a1, a1, 0
|
|
@end smallexample
|
|
|
|
@noindent
|
|
If the load destination and source address register are the same, an
|
|
out-of-range offset causes an error.
|
|
|
|
@cindex @code{ADDI} instructions, relaxation
|
|
@cindex relaxation of @code{ADDI} instructions
|
|
The Xtensa @code{ADDI} instruction only allows immediate operands in the
|
|
range from -128 to 127. There are a number of alternate instruction
|
|
sequences for the @code{ADDI} operation. First, if the
|
|
immediate is 0, the @code{ADDI} will be turned into a @code{MOV.N}
|
|
instruction (or the equivalent @code{OR} instruction if the code density
|
|
option is not available). If the @code{ADDI} immediate is outside of
|
|
the range -128 to 127, but inside the range -32896 to 32639, an
|
|
@code{ADDMI} instruction or @code{ADDMI}/@code{ADDI} sequence will be
|
|
used. Finally, if the immediate is outside of this range and a free
|
|
register is available, an @code{L32R}/@code{ADD} sequence will be used
|
|
with a literal allocated from the literal pool.
|
|
|
|
For example:
|
|
|
|
@smallexample
|
|
addi a5, a6, 0
|
|
addi a5, a6, 512
|
|
addi a5, a6, 513
|
|
addi a5, a6, 50000
|
|
@end smallexample
|
|
|
|
is assembled into the following:
|
|
|
|
@smallexample
|
|
.literal .L1, 50000
|
|
mov.n a5, a6
|
|
addmi a5, a6, 0x200
|
|
addmi a5, a6, 0x200
|
|
addi a5, a5, 1
|
|
l32r a5, .L1
|
|
add a5, a6, a5
|
|
@end smallexample
|
|
|
|
@node Xtensa Directives
|
|
@section Directives
|
|
@cindex Xtensa directives
|
|
@cindex directives, Xtensa
|
|
|
|
The Xtensa assember supports a region-based directive syntax:
|
|
|
|
@smallexample
|
|
.begin @var{directive} [@var{options}]
|
|
@dots{}
|
|
.end @var{directive}
|
|
@end smallexample
|
|
|
|
All the Xtensa-specific directives that apply to a region of code use
|
|
this syntax.
|
|
|
|
The directive applies to code between the @code{.begin} and the
|
|
@code{.end}. The state of the option after the @code{.end} reverts to
|
|
what it was before the @code{.begin}.
|
|
A nested @code{.begin}/@code{.end} region can further
|
|
change the state of the directive without having to be aware of its
|
|
outer state. For example, consider:
|
|
|
|
@smallexample
|
|
.begin no-transform
|
|
L: add a0, a1, a2
|
|
.begin transform
|
|
M: add a0, a1, a2
|
|
.end transform
|
|
N: add a0, a1, a2
|
|
.end no-transform
|
|
@end smallexample
|
|
|
|
The @code{ADD} opcodes at @code{L} and @code{N} in the outer
|
|
@code{no-transform} region both result in @code{ADD} machine instructions,
|
|
but the assembler selects an @code{ADD.N} instruction for the
|
|
@code{ADD} at @code{M} in the inner @code{transform} region.
|
|
|
|
The advantage of this style is that it works well inside macros which can
|
|
preserve the context of their callers.
|
|
|
|
The following directives are available:
|
|
@menu
|
|
* Schedule Directive:: Enable instruction scheduling.
|
|
* Longcalls Directive:: Use Indirect Calls for Greater Range.
|
|
* Transform Directive:: Disable All Assembler Transformations.
|
|
* Literal Directive:: Intermix Literals with Instructions.
|
|
* 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.
|
|
@end menu
|
|
|
|
@node Schedule Directive
|
|
@subsection schedule
|
|
@cindex @code{schedule} directive
|
|
@cindex @code{no-schedule} directive
|
|
|
|
The @code{schedule} directive is recognized only for compatibility with
|
|
Tensilica's assembler.
|
|
|
|
@smallexample
|
|
.begin [no-]schedule
|
|
.end [no-]schedule
|
|
@end smallexample
|
|
|
|
This directive is ignored and has no effect on @command{@value{AS}}.
|
|
|
|
@node Longcalls Directive
|
|
@subsection longcalls
|
|
@cindex @code{longcalls} directive
|
|
@cindex @code{no-longcalls} directive
|
|
|
|
The @code{longcalls} directive enables or disables function call
|
|
relaxation. @xref{Xtensa Call Relaxation, ,Function Call Relaxation}.
|
|
|
|
@smallexample
|
|
.begin [no-]longcalls
|
|
.end [no-]longcalls
|
|
@end smallexample
|
|
|
|
Call relaxation is disabled by default unless the @samp{--longcalls}
|
|
command-line option is specified. The @code{longcalls} directive
|
|
overrides the default determined by the command-line options.
|
|
|
|
@node Transform Directive
|
|
@subsection transform
|
|
@cindex @code{transform} directive
|
|
@cindex @code{no-transform} directive
|
|
|
|
This directive enables or disables all assembler transformation,
|
|
including relaxation (@pxref{Xtensa Relaxation, ,Xtensa Relaxation}) and
|
|
optimization (@pxref{Xtensa Optimizations, ,Xtensa Optimizations}).
|
|
|
|
@smallexample
|
|
.begin [no-]transform
|
|
.end [no-]transform
|
|
@end smallexample
|
|
|
|
Transformations are enabled by default unless the @samp{--no-transform}
|
|
option is used. The @code{transform} directive overrides the default
|
|
determined by the command-line options. An underscore opcode prefix,
|
|
disabling transformation of that opcode, always takes precedence over
|
|
both directives and command-line flags.
|
|
|
|
@node Literal Directive
|
|
@subsection literal
|
|
@cindex @code{literal} directive
|
|
|
|
The @code{.literal} directive is used to define literal pool data, i.e.,
|
|
read-only 32-bit data accessed via @code{L32R} instructions.
|
|
|
|
@smallexample
|
|
.literal @var{label}, @var{value}[, @var{value}@dots{}]
|
|
@end smallexample
|
|
|
|
This directive is similar to the standard @code{.word} directive, except
|
|
that the actual location of the literal data is determined by the
|
|
assembler and linker, not by the position of the @code{.literal}
|
|
directive. Using this directive gives the assembler freedom to locate
|
|
the literal data in the most appropriate place and possibly to combine
|
|
identical literals. For example, the code:
|
|
|
|
@smallexample
|
|
entry sp, 40
|
|
.literal .L1, sym
|
|
l32r a4, .L1
|
|
@end smallexample
|
|
|
|
can be used to load a pointer to the symbol @code{sym} into register
|
|
@code{a4}. The value of @code{sym} will not be placed between the
|
|
@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
|
|
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
|
|
@code{ENTRY} instructions, explicit @code{.literal_position} directives
|
|
must be used to place the text section literal pools; otherwise,
|
|
@command{@value{AS}} will report an error.
|
|
|
|
@node Literal Position Directive
|
|
@subsection literal_position
|
|
@cindex @code{literal_position} directive
|
|
|
|
When using @samp{--text-@-section-@-literals} to place literals inline
|
|
in the section being assembled, the @code{.literal_position} directive
|
|
can be used to mark a potential location for a literal pool.
|
|
|
|
@smallexample
|
|
.literal_position
|
|
@end smallexample
|
|
|
|
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
|
|
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
|
|
inline literal pool.
|
|
|
|
For example, an interrupt vector does not begin with an @code{ENTRY}
|
|
instruction so the assembler will be unable to automatically find a good
|
|
place to put a literal pool. Moreover, the code for the interrupt
|
|
vector must be at a specific starting address, so the literal pool
|
|
cannot come before the start of the code. The literal pool for the
|
|
vector must be explicitly positioned in the middle of the vector (before
|
|
any uses of the literals, due to the negative offsets used by
|
|
PC-relative @code{L32R} instructions). The @code{.literal_position}
|
|
directive can be used to do this. In the following code, the literal
|
|
for @samp{M} will automatically be aligned correctly and is placed after
|
|
the unconditional jump.
|
|
|
|
@smallexample
|
|
.global M
|
|
code_start:
|
|
j continue
|
|
.literal_position
|
|
.align 4
|
|
continue:
|
|
movi a4, M
|
|
@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.
|
|
|
|
@smallexample
|
|
.begin literal_prefix [@var{name}]
|
|
.end literal_prefix
|
|
@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}
|
|
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}.
|
|
|
|
@node Absolute Literals Directive
|
|
@subsection absolute-literals
|
|
@cindex @code{absolute-literals} directive
|
|
@cindex @code{no-absolute-literals} directive
|
|
|
|
The @code{absolute-@-literals} and @code{no-@-absolute-@-literals}
|
|
directives control the absolute vs.@: PC-relative mode for @code{L32R}
|
|
instructions. These are relevant only for Xtensa configurations that
|
|
include the absolute addressing option for @code{L32R} instructions.
|
|
|
|
@smallexample
|
|
.begin [no-]absolute-literals
|
|
.end [no-]absolute-literals
|
|
@end smallexample
|
|
|
|
These directives do not change the @code{L32R} mode---they only cause
|
|
the assembler to emit the appropriate kind of relocation for @code{L32R}
|
|
instructions and to place the literal values in the appropriate section.
|
|
To change the @code{L32R} mode, the program must write the
|
|
@code{LITBASE} special register. It is the programmer's responsibility
|
|
to keep track of the mode and indicate to the assembler which mode is
|
|
used in each region of code.
|
|
|
|
If the Xtensa configuration includes the absolute @code{L32R} addressing
|
|
option, the default is to assume absolute @code{L32R} addressing unless
|
|
the @samp{--no-@-absolute-@-literals} command-line option is specified.
|
|
Otherwise, the default is to assume PC-relative @code{L32R} addressing.
|
|
The @code{absolute-@-literals} directive can then be used to override
|
|
the default determined by the command-line options.
|
|
|
|
@c Local Variables:
|
|
@c fill-column: 72
|
|
@c End:
|