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