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