741 lines
28 KiB
Plaintext
741 lines
28 KiB
Plaintext
@c Copyright (C) 2002 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 --density | --no-density
|
|
@kindex --density
|
|
@kindex --no-density
|
|
@cindex Xtensa density option
|
|
@cindex density option, Xtensa
|
|
Enable or disable use of the Xtensa code density option (16-bit
|
|
instructions). @xref{Density Instructions, ,Using Density
|
|
Instructions}. If the processor is configured with the density option,
|
|
this is enabled by default; otherwise, it is always disabled.
|
|
|
|
@item --relax | --no-relax
|
|
@kindex --relax
|
|
@kindex --no-relax
|
|
Enable or disable relaxation of instructions with immediate operands
|
|
that are outside the legal range for the instructions. @xref{Xtensa
|
|
Relaxation, ,Xtensa Relaxation}. The default is @samp{--relax} and this
|
|
default should almost always be used. If relaxation is disabled with
|
|
@samp{--no-relax}, instruction operands that are out of range will cause
|
|
errors. Note: In the current implementation, these options also control
|
|
whether assembler optimizations are performed, making these options
|
|
equivalent to @samp{--generics} and @samp{--no-generics}.
|
|
|
|
@item --generics | --no-generics
|
|
@kindex --generics
|
|
@kindex --no-generics
|
|
Enable or disable all assembler transformations of Xtensa instructions,
|
|
including both relaxation and optimization. The default is
|
|
@samp{--generics}; @samp{--no-generics} should only be used in the rare
|
|
cases when the instructions must be exactly as specified in the assembly
|
|
source.
|
|
@c The @samp{--no-generics} option is like @samp{--no-relax}
|
|
@c except that it also disables assembler optimizations (@pxref{Xtensa
|
|
@c Optimizations}).
|
|
As with @samp{--no-relax}, using @samp{--no-generics}
|
|
causes out of range instruction operands to be errors.
|
|
|
|
@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, and it also allows the linker to combine literal
|
|
pools from separate object files to remove redundant literals and
|
|
improve code size. 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.
|
|
|
|
@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, but it degrades both code size
|
|
and performance. The default is @samp{--no-@-longcalls}.
|
|
@end table
|
|
|
|
@node Xtensa Syntax
|
|
@section Assembler Syntax
|
|
@cindex syntax, Xtensa assembler
|
|
@cindex Xtensa assembler 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.
|
|
|
|
@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, Xtenxa
|
|
|
|
See the @cite{Xtensa Instruction Set Architecture (ISA) Reference
|
|
Manual} for a complete list of opcodes and descriptions of their
|
|
semantics.
|
|
|
|
@cindex generic opcodes
|
|
@cindex specific opcodes
|
|
@cindex _ opcode prefix
|
|
The Xtensa assembler distinguishes between @dfn{generic} and
|
|
@dfn{specific} opcodes. Specific opcodes correspond directly to Xtensa
|
|
machine instructions. Prefixing an opcode with an underscore character
|
|
(@samp{_}) identifies it as a specific opcode. Opcodes without a
|
|
leading underscore are generic, which means the assembler is required to
|
|
preserve their semantics but may not translate them directly to the
|
|
specific opcodes with the same names. Instead, the assembler may
|
|
optimize a generic opcode and select a better instruction to use in its
|
|
place (@pxref{Xtensa Optimizations, ,Xtensa Optimizations}), or the
|
|
assembler may relax the instruction to handle operands that are out of
|
|
range for the corresponding specific opcode (@pxref{Xtensa Relaxation,
|
|
,Xtensa Relaxation}).
|
|
|
|
Only use specific opcodes when it is essential to select
|
|
the exact machine instructions produced by the assembler.
|
|
Using specific opcodes unnecessarily only 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{_NOP}), 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{_NOP} expands to @code{_OR a1,a1,a1}.
|
|
|
|
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-generics} directive. @xref{Generics Directive, ,generics}.
|
|
|
|
@node Xtensa Registers
|
|
@subsection Register Names
|
|
@cindex Xtensa register names
|
|
@cindex register names, Xtensa
|
|
@cindex sp register
|
|
|
|
An initial @samp{$} character is optional in all register names.
|
|
General purpose registers are named @samp{a0}@dots{}@samp{a15}. Additional
|
|
registers may be added by processor configuration options. In
|
|
particular, the @sc{mac16} option adds a @sc{mr} register bank. Its
|
|
registers are named @samp{m0}@dots{}@samp{m3}.
|
|
|
|
As a special feature, @samp{sp} is also supported as a synonym for
|
|
@samp{a1}.
|
|
|
|
@node Xtensa Optimizations
|
|
@section Xtensa Optimizations
|
|
@cindex optimizations
|
|
|
|
The optimizations currently supported by @code{@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 generic instructions from the core
|
|
Xtensa instruction set into equivalent instructions from the Xtensa code
|
|
density option. This translation can be disabled by using specific
|
|
opcodes (@pxref{Xtensa Opcodes, ,Opcode Names}), by using the
|
|
@samp{--no-density} command-line option (@pxref{Xtensa Options, ,Command
|
|
Line Options}), or by using the @code{no-density} directive
|
|
(@pxref{Density Directive, ,density}).
|
|
|
|
It is a good idea @emph{not} to use the density instuctions directly.
|
|
The assembler will automatically select dense instructions where
|
|
possible. If you later need to avoid using the code density option, you
|
|
can disable it in the assembler without having to modify the code.
|
|
|
|
@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.
|
|
|
|
When the @code{--target-@-align} command-line option is enabled
|
|
(@pxref{Xtensa Options, ,Command Line Options}), the assembler attempts
|
|
to widen density instructions preceding a branch target so that the
|
|
target instruction does not cross a 4-byte boundary. Similarly, the
|
|
assembler also attempts to align each instruction following a call
|
|
instruction. If there are not enough preceding safe density
|
|
instructions to align a target, no widening will be performed. 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.
|
|
|
|
The @code{LOOP} family of instructions must be aligned 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.
|
|
|
|
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, @code{@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.)
|
|
|
|
@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, but it can only partially remove the overhead
|
|
introduced by the assembler.
|
|
|
|
Call relaxation has a negative effect
|
|
on both code size and performance, so this relaxation is disabled by
|
|
default. 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
|
|
|
|
@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
|
|
materalized 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 generic @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-density
|
|
L: add a0, a1, a2
|
|
.begin density
|
|
M: add a0, a1, a2
|
|
.end density
|
|
N: add a0, a1, a2
|
|
.end no-density
|
|
@end smallexample
|
|
|
|
The generic @code{ADD} opcodes at @code{L} and @code{N} in the outer
|
|
@code{no-density} region both result in @code{ADD} machine instructions,
|
|
but the assembler selects an @code{ADD.N} instruction for the generic
|
|
@code{ADD} at @code{M} in the inner @code{density} region.
|
|
|
|
The advantage of this style is that it works well inside macros which can
|
|
preserve the context of their callers.
|
|
|
|
@cindex precedence of directives
|
|
@cindex directives, precedence
|
|
When command-line options and assembler directives are used at the same
|
|
time and conflict, the one that overrides a default behavior takes
|
|
precedence over one that is the same as the default. For example, if
|
|
the code density option is available, the default is to select density
|
|
instructions whenever possible. So, if the above is assembled with the
|
|
@samp{--no-density} flag, which overrides the default, all the generic
|
|
@code{ADD} instructions result in @code{ADD} machine instructions. If
|
|
assembled with the @samp{--density} flag, which is already the default,
|
|
the @code{no-density} directive takes precedence and only one of
|
|
the generic @code{ADD} instructions is optimized to be a @code{ADD.N}
|
|
machine instruction. An underscore prefix identifying a specific opcode
|
|
always takes precedence over directives and command-line flags.
|
|
|
|
The following directives are available:
|
|
@menu
|
|
* Density Directive:: Disable Use of Density Instructions.
|
|
* Relax Directive:: Disable Assembler Relaxation.
|
|
* Longcalls Directive:: Use Indirect Calls for Greater Range.
|
|
* Generics 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.
|
|
* Freeregs Directive:: List Registers Available for Assembler Use.
|
|
* Frame Directive:: Describe a stack frame.
|
|
@end menu
|
|
|
|
@node Density Directive
|
|
@subsection density
|
|
@cindex @code{density} directive
|
|
@cindex @code{no-density} directive
|
|
|
|
The @code{density} and @code{no-density} directives enable or disable
|
|
optimization of generic instructions into density instructions within
|
|
the region. @xref{Density Instructions, ,Using Density Instructions}.
|
|
|
|
@smallexample
|
|
.begin [no-]density
|
|
.end [no-]density
|
|
@end smallexample
|
|
|
|
This optimization is enabled by default unless the Xtensa configuration
|
|
does not support the code density option or the @samp{--no-density}
|
|
command-line option was specified.
|
|
|
|
@node Relax Directive
|
|
@subsection relax
|
|
@cindex @code{relax} directive
|
|
@cindex @code{no-relax} directive
|
|
|
|
The @code{relax} directive enables or disables relaxation
|
|
within the region. @xref{Xtensa Relaxation, ,Xtensa Relaxation}.
|
|
Note: In the current implementation, these directives also control
|
|
whether assembler optimizations are performed, making them equivalent to
|
|
the @code{generics} and @code{no-generics} directives.
|
|
|
|
@smallexample
|
|
.begin [no-]relax
|
|
.end [no-]relax
|
|
@end smallexample
|
|
|
|
Relaxation is enabled by default unless the @samp{--no-relax}
|
|
command-line option was specified.
|
|
|
|
@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.
|
|
|
|
@node Generics Directive
|
|
@subsection generics
|
|
@cindex @code{generics} directive
|
|
@cindex @code{no-generics} 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-]generics
|
|
.end [no-]generics
|
|
@end smallexample
|
|
|
|
Disabling generics is roughly equivalent to adding an underscore prefix
|
|
to every opcode within the region, so that every opcode is treated as a
|
|
specific opcode. @xref{Xtensa Opcodes, ,Opcode Names}. In the current
|
|
implementation of @code{@value{AS}}, built-in macros are also disabled
|
|
within a @code{no-generics} region.
|
|
|
|
@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.
|
|
|
|
By default literal pools are placed in a separate 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 or @code{.literal_position} directives, the assembler will
|
|
print a warning and place the literal pool at the beginning of the
|
|
current section. In such cases, explicit @code{.literal_position}
|
|
directives should be used to place the literal pools.
|
|
|
|
@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.
|
|
|
|
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, of course). 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
|
|
|
|
For the code inside the delimited region, the assembler puts literals in
|
|
the section @code{@var{name}.literal}. If this section does not yet
|
|
exist, the assembler creates it. The @var{name} parameter is
|
|
optional. If @var{name} is not specified, the literal prefix is set to
|
|
the ``default'' for the file. This default is usually @code{.literal}
|
|
but can be changed with the @samp{--rename-section} command-line
|
|
argument.
|
|
|
|
@node Freeregs Directive
|
|
@subsection freeregs
|
|
@cindex @code{freeregs} directive
|
|
|
|
This directive tells the assembler that the given registers are unused
|
|
in the region.
|
|
|
|
@smallexample
|
|
.begin freeregs @var{ri}[,@var{ri}@dots{}]
|
|
.end freeregs
|
|
@end smallexample
|
|
|
|
This allows the assembler to use these registers for relaxations or
|
|
optimizations. (They are actually only for relaxations at present, but
|
|
the possibility of optimizations exists in the future.)
|
|
|
|
Nested @code{freeregs} directives can be used to add additional registers
|
|
to the list of those available to the assembler. For example:
|
|
|
|
@smallexample
|
|
.begin freeregs a3, a4
|
|
.begin freeregs a5
|
|
@end smallexample
|
|
|
|
has the effect of declaring @code{a3}, @code{a4}, and @code{a5} all free.
|
|
|
|
@node Frame Directive
|
|
@subsection frame
|
|
@cindex @code{frame} directive
|
|
|
|
This directive tells the assembler to emit information to allow the
|
|
debugger to locate a function's stack frame. The syntax is:
|
|
|
|
@smallexample
|
|
.frame @var{reg}, @var{size}
|
|
@end smallexample
|
|
|
|
where @var{reg} is the register used to hold the frame pointer (usually
|
|
the same as the stack pointer) and @var{size} is the size in bytes of
|
|
the stack frame. The @code{.frame} directive is typically placed
|
|
immediately after the @code{ENTRY} instruction for a function.
|
|
|
|
In almost all circumstances, this information just duplicates the
|
|
information given in the function's @code{ENTRY} instruction; however,
|
|
there are two cases where this is not true:
|
|
|
|
@enumerate
|
|
@item
|
|
The size of the stack frame is too big to fit in the immediate field
|
|
of the @code{ENTRY} instruction.
|
|
|
|
@item
|
|
The frame pointer is different than the stack pointer, as with functions
|
|
that call @code{alloca}.
|
|
@end enumerate
|
|
|
|
@c Local Variables:
|
|
@c fill-column: 72
|
|
@c End:
|