1 @c Copyright (C) 2002-2014 Free Software Foundation, Inc.
2 @c This is part of the GAS manual.
3 @c For copying conditions, see the file as.texinfo.
9 @chapter Xtensa Dependent Features
12 @node Machine Dependencies
13 @chapter Xtensa Dependent Features
16 @cindex Xtensa architecture
17 This chapter covers features of the @sc{gnu} assembler that are specific
18 to the Xtensa architecture. For details about the Xtensa instruction
19 set, please consult the @cite{Xtensa Instruction Set Architecture (ISA)
23 * Xtensa Options:: Command-line Options.
24 * Xtensa Syntax:: Assembler Syntax for Xtensa Processors.
25 * Xtensa Optimizations:: Assembler Optimizations.
26 * Xtensa Relaxation:: Other Automatic Transformations.
27 * Xtensa Directives:: Directives for Xtensa Processors.
31 @section Command Line Options
36 @item --text-section-literals | --no-text-section-literals
37 @kindex --text-section-literals
38 @kindex --no-text-section-literals
39 Control the treatment of literal pools. The default is
40 @samp{--no-@-text-@-section-@-literals}, which places literals in
41 separate sections in the output file. This allows the literal pool to be
42 placed in a data RAM/ROM. With @samp{--text-@-section-@-literals}, the
43 literals are interspersed in the text section in order to keep them as
44 close as possible to their references. This may be necessary for large
45 assembly files, where the literals would otherwise be out of range of the
46 @code{L32R} instructions in the text section. These options only affect
47 literals referenced via PC-relative @code{L32R} instructions; literals
48 for absolute mode @code{L32R} instructions are handled separately.
49 @xref{Literal Directive, ,literal}.
51 @item --absolute-literals | --no-absolute-literals
52 @kindex --absolute-literals
53 @kindex --no-absolute-literals
54 Indicate to the assembler whether @code{L32R} instructions use absolute
55 or PC-relative addressing. If the processor includes the absolute
56 addressing option, the default is to use absolute @code{L32R}
57 relocations. Otherwise, only the PC-relative @code{L32R} relocations
60 @item --target-align | --no-target-align
61 @kindex --target-align
62 @kindex --no-target-align
63 Enable or disable automatic alignment to reduce branch penalties at some
64 expense in code size. @xref{Xtensa Automatic Alignment, ,Automatic
65 Instruction Alignment}. This optimization is enabled by default. Note
66 that the assembler will always align instructions like @code{LOOP} that
67 have fixed alignment requirements.
69 @item --longcalls | --no-longcalls
71 @kindex --no-longcalls
72 Enable or disable transformation of call instructions to allow calls
73 across a greater range of addresses. @xref{Xtensa Call Relaxation,
74 ,Function Call Relaxation}. This option should be used when call
75 targets can potentially be out of range. It may degrade both code size
76 and performance, but the linker can generally optimize away the
77 unnecessary overhead when a call ends up within range. The default is
78 @samp{--no-@-longcalls}.
80 @item --transform | --no-transform
82 @kindex --no-transform
83 Enable or disable all assembler transformations of Xtensa instructions,
84 including both relaxation and optimization. The default is
85 @samp{--transform}; @samp{--no-transform} should only be used in the
86 rare cases when the instructions must be exactly as specified in the
87 assembly source. Using @samp{--no-transform} causes out of range
88 instruction operands to be errors.
90 @item --rename-section @var{oldname}=@var{newname}
91 @kindex --rename-section
92 Rename the @var{oldname} section to @var{newname}. This option can be used
93 multiple times to rename multiple sections.
95 @item --trampolines | --no-trampolines
97 @kindex --no-trampolines
98 Enable or disable transformation of jump instructions to allow jumps
99 across a greater range of addresses. @xref{Xtensa Jump Relaxation,
100 ,Jump Trampolines}. This option should be used when jump targets can
101 potentially be out of range. In the absence of such jumps this option
102 does not affect code size or performance. The default is
103 @samp{--trampolines}.
109 @section Assembler Syntax
110 @cindex syntax, Xtensa assembler
111 @cindex Xtensa assembler syntax
114 Block comments are delimited by @samp{/*} and @samp{*/}. End of line
115 comments may be introduced with either @samp{#} or @samp{//}.
117 If a @samp{#} appears as the first character of a line then the whole
118 line is treated as a comment, but in this case the line could also be
119 a logical line number directive (@pxref{Comments}) or a preprocessor
120 control command (@pxref{Preprocessing}).
122 Instructions consist of a leading opcode or macro name followed by
123 whitespace and an optional comma-separated list of operands:
126 @var{opcode} [@var{operand}, @dots{}]
129 Instructions must be separated by a newline or semicolon (@samp{;}).
131 FLIX instructions, which bundle multiple opcodes together in a single
132 instruction, are specified by enclosing the bundled opcodes inside
139 @var{opcode0} [@var{operands}]
141 @var{opcode1} [@var{operands}]
143 @var{opcode2} [@var{operands}]
149 The opcodes in a FLIX instruction are listed in the same order as the
150 corresponding instruction slots in the TIE format declaration.
151 Directives and labels are not allowed inside the braces of a FLIX
152 instruction. A particular TIE format name can optionally be specified
153 immediately after the opening brace, but this is usually unnecessary.
154 The assembler will automatically search for a format that can encode the
155 specified opcodes, so the format name need only be specified in rare
156 cases where there is more than one applicable format and where it
157 matters which of those formats is used. A FLIX instruction can also be
158 specified on a single line by separating the opcodes with semicolons:
161 @{ [@var{format};] @var{opcode0} [@var{operands}]; @var{opcode1} [@var{operands}]; @var{opcode2} [@var{operands}]; @dots{} @}
164 If an opcode can only be encoded in a FLIX instruction but is not
165 specified as part of a FLIX bundle, the assembler will choose the
166 smallest format where the opcode can be encoded and
167 will fill unused instruction slots with no-ops.
170 * Xtensa Opcodes:: Opcode Naming Conventions.
171 * Xtensa Registers:: Register Naming.
175 @subsection Opcode Names
176 @cindex Xtensa opcode names
177 @cindex opcode names, Xtensa
179 See the @cite{Xtensa Instruction Set Architecture (ISA) Reference
180 Manual} for a complete list of opcodes and descriptions of their
183 @cindex _ opcode prefix
184 If an opcode name is prefixed with an underscore character (@samp{_}),
185 @command{@value{AS}} will not transform that instruction in any way. The
186 underscore prefix disables both optimization (@pxref{Xtensa
187 Optimizations, ,Xtensa Optimizations}) and relaxation (@pxref{Xtensa
188 Relaxation, ,Xtensa Relaxation}) for that particular instruction. Only
189 use the underscore prefix when it is essential to select the exact
190 opcode produced by the assembler. Using this feature unnecessarily
191 makes the code less efficient by disabling assembler optimization and
192 less flexible by disabling relaxation.
194 Note that this special handling of underscore prefixes only applies to
195 Xtensa opcodes, not to either built-in macros or user-defined macros.
196 When an underscore prefix is used with a macro (e.g., @code{_MOV}), it
197 refers to a different macro. The assembler generally provides built-in
198 macros both with and without the underscore prefix, where the underscore
199 versions behave as if the underscore carries through to the instructions
200 in the macros. For example, @code{_MOV} may expand to @code{_MOV.N}@.
202 The underscore prefix only applies to individual instructions, not to
203 series of instructions. For example, if a series of instructions have
204 underscore prefixes, the assembler will not transform the individual
205 instructions, but it may insert other instructions between them (e.g.,
206 to align a @code{LOOP} instruction). To prevent the assembler from
207 modifying a series of instructions as a whole, use the
208 @code{no-transform} directive. @xref{Transform Directive, ,transform}.
210 @node Xtensa Registers
211 @subsection Register Names
212 @cindex Xtensa register names
213 @cindex register names, Xtensa
216 The assembly syntax for a register file entry is the ``short'' name for
217 a TIE register file followed by the index into that register file. For
218 example, the general-purpose @code{AR} register file has a short name of
219 @code{a}, so these registers are named @code{a0}@dots{}@code{a15}.
220 As a special feature, @code{sp} is also supported as a synonym for
221 @code{a1}. Additional registers may be added by processor configuration
222 options and by designer-defined TIE extensions. An initial @samp{$}
223 character is optional in all register names.
225 @node Xtensa Optimizations
226 @section Xtensa Optimizations
227 @cindex optimizations
229 The optimizations currently supported by @command{@value{AS}} are
230 generation of density instructions where appropriate and automatic
231 branch target alignment.
234 * Density Instructions:: Using Density Instructions.
235 * Xtensa Automatic Alignment:: Automatic Instruction Alignment.
238 @node Density Instructions
239 @subsection Using Density Instructions
240 @cindex density instructions
242 The Xtensa instruction set has a code density option that provides
243 16-bit versions of some of the most commonly used opcodes. Use of these
244 opcodes can significantly reduce code size. When possible, the
245 assembler automatically translates instructions from the core
246 Xtensa instruction set into equivalent instructions from the Xtensa code
247 density option. This translation can be disabled by using underscore
248 prefixes (@pxref{Xtensa Opcodes, ,Opcode Names}), by using the
249 @samp{--no-transform} command-line option (@pxref{Xtensa Options, ,Command
250 Line Options}), or by using the @code{no-transform} directive
251 (@pxref{Transform Directive, ,transform}).
253 It is a good idea @emph{not} to use the density instructions directly.
254 The assembler will automatically select dense instructions where
255 possible. If you later need to use an Xtensa processor without the code
256 density option, the same assembly code will then work without modification.
258 @node Xtensa Automatic Alignment
259 @subsection Automatic Instruction Alignment
260 @cindex alignment of @code{LOOP} instructions
261 @cindex alignment of branch targets
262 @cindex @code{LOOP} instructions, alignment
263 @cindex branch target alignment
265 The Xtensa assembler will automatically align certain instructions, both
266 to optimize performance and to satisfy architectural requirements.
268 As an optimization to improve performance, the assembler attempts to
269 align branch targets so they do not cross instruction fetch boundaries.
270 (Xtensa processors can be configured with either 32-bit or 64-bit
271 instruction fetch widths.) An
272 instruction immediately following a call is treated as a branch target
273 in this context, because it will be the target of a return from the
274 call. This alignment has the potential to reduce branch penalties at
275 some expense in code size.
276 This optimization is enabled by default. You can disable it with the
277 @samp{--no-target-@-align} command-line option (@pxref{Xtensa Options,
278 ,Command Line Options}).
280 The target alignment optimization is done without adding instructions
281 that could increase the execution time of the program. If there are
282 density instructions in the code preceding a target, the assembler can
283 change the target alignment by widening some of those instructions to
284 the equivalent 24-bit instructions. Extra bytes of padding can be
285 inserted immediately following unconditional jump and return
287 This approach is usually successful in aligning many, but not all,
290 The @code{LOOP} family of instructions must be aligned such that the
291 first instruction in the loop body does not cross an instruction fetch
292 boundary (e.g., with a 32-bit fetch width, a @code{LOOP} instruction
293 must be on either a 1 or 2 mod 4 byte boundary). The assembler knows
294 about this restriction and inserts the minimal number of 2 or 3 byte
295 no-op instructions to satisfy it. When no-op instructions are added,
296 any label immediately preceding the original loop will be moved in order
297 to refer to the loop instruction, not the newly generated no-op
298 instruction. To preserve binary compatibility across processors with
299 different fetch widths, the assembler conservatively assumes a 32-bit
300 fetch width when aligning @code{LOOP} instructions (except if the first
301 instruction in the loop is a 64-bit instruction).
303 Previous versions of the assembler automatically aligned @code{ENTRY}
304 instructions to 4-byte boundaries, but that alignment is now the
305 programmer's responsibility.
307 @node Xtensa Relaxation
308 @section Xtensa Relaxation
311 When an instruction operand is outside the range allowed for that
312 particular instruction field, @command{@value{AS}} can transform the code
313 to use a functionally-equivalent instruction or sequence of
314 instructions. This process is known as @dfn{relaxation}. This is
315 typically done for branch instructions because the distance of the
316 branch targets is not known until assembly-time. The Xtensa assembler
317 offers branch relaxation and also extends this concept to function
318 calls, @code{MOVI} instructions and other instructions with immediate
322 * Xtensa Branch Relaxation:: Relaxation of Branches.
323 * Xtensa Call Relaxation:: Relaxation of Function Calls.
324 * Xtensa Jump Relaxation:: Relaxation of Jumps.
325 * Xtensa Immediate Relaxation:: Relaxation of other Immediate Fields.
328 @node Xtensa Branch Relaxation
329 @subsection Conditional Branch Relaxation
330 @cindex relaxation of branch instructions
331 @cindex branch instructions, relaxation
333 When the target of a branch is too far away from the branch itself,
334 i.e., when the offset from the branch to the target is too large to fit
335 in the immediate field of the branch instruction, it may be necessary to
336 replace the branch with a branch around a jump. For example,
352 (The @code{BNEZ.N} instruction would be used in this example only if the
353 density option is available. Otherwise, @code{BNEZ} would be used.)
355 This relaxation works well because the unconditional jump instruction
356 has a much larger offset range than the various conditional branches.
357 However, an error will occur if a branch target is beyond the range of a
358 jump instruction. @command{@value{AS}} cannot relax unconditional jumps.
359 Similarly, an error will occur if the original input contains an
360 unconditional jump to a target that is out of range.
362 Branch relaxation is enabled by default. It can be disabled by using
363 underscore prefixes (@pxref{Xtensa Opcodes, ,Opcode Names}), the
364 @samp{--no-transform} command-line option (@pxref{Xtensa Options,
365 ,Command Line Options}), or the @code{no-transform} directive
366 (@pxref{Transform Directive, ,transform}).
368 @node Xtensa Call Relaxation
369 @subsection Function Call Relaxation
370 @cindex relaxation of call instructions
371 @cindex call instructions, relaxation
373 Function calls may require relaxation because the Xtensa immediate call
374 instructions (@code{CALL0}, @code{CALL4}, @code{CALL8} and
375 @code{CALL12}) provide a PC-relative offset of only 512 Kbytes in either
376 direction. For larger programs, it may be necessary to use indirect
377 calls (@code{CALLX0}, @code{CALLX4}, @code{CALLX8} and @code{CALLX12})
378 where the target address is specified in a register. The Xtensa
379 assembler can automatically relax immediate call instructions into
380 indirect call instructions. This relaxation is done by loading the
381 address of the called function into the callee's return address register
382 and then using a @code{CALLX} instruction. So, for example:
398 Because the addresses of targets of function calls are not generally
399 known until link-time, the assembler must assume the worst and relax all
400 the calls to functions in other source files, not just those that really
401 will be out of range. The linker can recognize calls that were
402 unnecessarily relaxed, and it will remove the overhead introduced by the
403 assembler for those cases where direct calls are sufficient.
405 Call relaxation is disabled by default because it can have a negative
406 effect on both code size and performance, although the linker can
407 usually eliminate the unnecessary overhead. If a program is too large
408 and some of the calls are out of range, function call relaxation can be
409 enabled using the @samp{--longcalls} command-line option or the
410 @code{longcalls} directive (@pxref{Longcalls Directive, ,longcalls}).
412 @node Xtensa Jump Relaxation
413 @subsection Jump Relaxation
414 @cindex relaxation of jump instructions
415 @cindex jump instructions, relaxation
417 Jump instruction may require relaxation because the Xtensa jump instruction
418 (@code{J}) provide a PC-relative offset of only 128 Kbytes in either
419 direction. One option is to use jump long (@code{J.L}) instruction, which
420 depending on jump distance may be assembled as jump (@code{J}) or indirect
421 jump (@code{JX}). However it needs a free register. When there's no spare
422 register it is possible to plant intermediate jump sites (trampolines)
423 between the jump instruction and its target. These sites may be located in
424 areas unreachable by normal code execution flow, in that case they only
425 contain intermediate jumps, or they may be inserted in the middle of code
426 block, in which case there's an additional jump from the beginning of the
427 trampoline to the instruction past its end. So, for example:
481 The Xtensa assempler uses trampolines with jump around only when it cannot
482 find suitable unreachable trampoline. There may be multiple trampolines
483 between the jump instruction and its target.
485 This relaxation does not apply to jumps to undefined symbols, assuming they
486 will reach their targets once resolved.
488 Jump relaxation is enabled by default because it does not affect code size
489 or performance while the code itself is small. This relaxation may be
490 disabled completely with @samp{--no-trampolines} or @samp{--no-transform}
491 command-line options (@pxref{Xtensa Options, ,Command Line Options}).
493 @node Xtensa Immediate Relaxation
494 @subsection Other Immediate Field Relaxation
495 @cindex immediate fields, relaxation
496 @cindex relaxation of immediate fields
498 The assembler normally performs the following other relaxations. They
499 can be disabled by using underscore prefixes (@pxref{Xtensa Opcodes,
500 ,Opcode Names}), the @samp{--no-transform} command-line option
501 (@pxref{Xtensa Options, ,Command Line Options}), or the
502 @code{no-transform} directive (@pxref{Transform Directive, ,transform}).
504 @cindex @code{MOVI} instructions, relaxation
505 @cindex relaxation of @code{MOVI} instructions
506 The @code{MOVI} machine instruction can only materialize values in the
507 range from -2048 to 2047. Values outside this range are best
508 materialized with @code{L32R} instructions. Thus:
514 is assembled into the following machine code:
523 @cindex @code{L8UI} instructions, relaxation
524 @cindex @code{L16SI} instructions, relaxation
525 @cindex @code{L16UI} instructions, relaxation
526 @cindex @code{L32I} instructions, relaxation
527 @cindex relaxation of @code{L8UI} instructions
528 @cindex relaxation of @code{L16SI} instructions
529 @cindex relaxation of @code{L16UI} instructions
530 @cindex relaxation of @code{L32I} instructions
531 The @code{L8UI} machine instruction can only be used with immediate
532 offsets in the range from 0 to 255. The @code{L16SI} and @code{L16UI}
533 machine instructions can only be used with offsets from 0 to 510. The
534 @code{L32I} machine instruction can only be used with offsets from 0 to
535 1020. A load offset outside these ranges can be materialized with
536 an @code{L32R} instruction if the destination register of the load
537 is different than the source address register. For example:
557 If the load destination and source address register are the same, an
558 out-of-range offset causes an error.
560 @cindex @code{ADDI} instructions, relaxation
561 @cindex relaxation of @code{ADDI} instructions
562 The Xtensa @code{ADDI} instruction only allows immediate operands in the
563 range from -128 to 127. There are a number of alternate instruction
564 sequences for the @code{ADDI} operation. First, if the
565 immediate is 0, the @code{ADDI} will be turned into a @code{MOV.N}
566 instruction (or the equivalent @code{OR} instruction if the code density
567 option is not available). If the @code{ADDI} immediate is outside of
568 the range -128 to 127, but inside the range -32896 to 32639, an
569 @code{ADDMI} instruction or @code{ADDMI}/@code{ADDI} sequence will be
570 used. Finally, if the immediate is outside of this range and a free
571 register is available, an @code{L32R}/@code{ADD} sequence will be used
572 with a literal allocated from the literal pool.
587 is assembled into the following:
603 @node Xtensa Directives
605 @cindex Xtensa directives
606 @cindex directives, Xtensa
608 The Xtensa assembler supports a region-based directive syntax:
612 .begin @var{directive} [@var{options}]
618 All the Xtensa-specific directives that apply to a region of code use
621 The directive applies to code between the @code{.begin} and the
622 @code{.end}. The state of the option after the @code{.end} reverts to
623 what it was before the @code{.begin}.
624 A nested @code{.begin}/@code{.end} region can further
625 change the state of the directive without having to be aware of its
626 outer state. For example, consider:
642 The @code{ADD} opcodes at @code{L} and @code{N} in the outer
643 @code{no-transform} region both result in @code{ADD} machine instructions,
644 but the assembler selects an @code{ADD.N} instruction for the
645 @code{ADD} at @code{M} in the inner @code{transform} region.
647 The advantage of this style is that it works well inside macros which can
648 preserve the context of their callers.
650 The following directives are available:
652 * Schedule Directive:: Enable instruction scheduling.
653 * Longcalls Directive:: Use Indirect Calls for Greater Range.
654 * Transform Directive:: Disable All Assembler Transformations.
655 * Literal Directive:: Intermix Literals with Instructions.
656 * Literal Position Directive:: Specify Inline Literal Pool Locations.
657 * Literal Prefix Directive:: Specify Literal Section Name Prefix.
658 * Absolute Literals Directive:: Control PC-Relative vs. Absolute Literals.
661 @node Schedule Directive
663 @cindex @code{schedule} directive
664 @cindex @code{no-schedule} directive
666 The @code{schedule} directive is recognized only for compatibility with
667 Tensilica's assembler.
676 This directive is ignored and has no effect on @command{@value{AS}}.
678 @node Longcalls Directive
679 @subsection longcalls
680 @cindex @code{longcalls} directive
681 @cindex @code{no-longcalls} directive
683 The @code{longcalls} directive enables or disables function call
684 relaxation. @xref{Xtensa Call Relaxation, ,Function Call Relaxation}.
688 .begin [no-]longcalls
693 Call relaxation is disabled by default unless the @samp{--longcalls}
694 command-line option is specified. The @code{longcalls} directive
695 overrides the default determined by the command-line options.
697 @node Transform Directive
698 @subsection transform
699 @cindex @code{transform} directive
700 @cindex @code{no-transform} directive
702 This directive enables or disables all assembler transformation,
703 including relaxation (@pxref{Xtensa Relaxation, ,Xtensa Relaxation}) and
704 optimization (@pxref{Xtensa Optimizations, ,Xtensa Optimizations}).
708 .begin [no-]transform
713 Transformations are enabled by default unless the @samp{--no-transform}
714 option is used. The @code{transform} directive overrides the default
715 determined by the command-line options. An underscore opcode prefix,
716 disabling transformation of that opcode, always takes precedence over
717 both directives and command-line flags.
719 @node Literal Directive
721 @cindex @code{literal} directive
723 The @code{.literal} directive is used to define literal pool data, i.e.,
724 read-only 32-bit data accessed via @code{L32R} instructions.
727 .literal @var{label}, @var{value}[, @var{value}@dots{}]
730 This directive is similar to the standard @code{.word} directive, except
731 that the actual location of the literal data is determined by the
732 assembler and linker, not by the position of the @code{.literal}
733 directive. Using this directive gives the assembler freedom to locate
734 the literal data in the most appropriate place and possibly to combine
735 identical literals. For example, the code:
745 can be used to load a pointer to the symbol @code{sym} into register
746 @code{a4}. The value of @code{sym} will not be placed between the
747 @code{ENTRY} and @code{L32R} instructions; instead, the assembler puts
748 the data in a literal pool.
750 Literal pools are placed by default in separate literal sections;
751 however, when using the @samp{--text-@-section-@-literals}
752 option (@pxref{Xtensa Options, ,Command Line Options}), the literal
753 pools for PC-relative mode @code{L32R} instructions
754 are placed in the current section.@footnote{Literals for the
755 @code{.init} and @code{.fini} sections are always placed in separate
756 sections, even when @samp{--text-@-section-@-literals} is enabled.}
757 These text section literal
758 pools are created automatically before @code{ENTRY} instructions and
759 manually after @samp{.literal_position} directives (@pxref{Literal
760 Position Directive, ,literal_position}). If there are no preceding
761 @code{ENTRY} instructions, explicit @code{.literal_position} directives
762 must be used to place the text section literal pools; otherwise,
763 @command{@value{AS}} will report an error.
765 When literals are placed in separate sections, the literal section names
766 are derived from the names of the sections where the literals are
767 defined. The base literal section names are @code{.literal} for
768 PC-relative mode @code{L32R} instructions and @code{.lit4} for absolute
769 mode @code{L32R} instructions (@pxref{Absolute Literals Directive,
770 ,absolute-literals}). These base names are used for literals defined in
771 the default @code{.text} section. For literals defined in other
772 sections or within the scope of a @code{literal_prefix} directive
773 (@pxref{Literal Prefix Directive, ,literal_prefix}), the following rules
774 determine the literal section name:
778 If the current section is a member of a section group, the literal
779 section name includes the group name as a suffix to the base
780 @code{.literal} or @code{.lit4} name, with a period to separate the base
781 name and group name. The literal section is also made a member of the
785 If the current section name (or @code{literal_prefix} value) begins with
786 ``@code{.gnu.linkonce.@var{kind}.}'', the literal section name is formed
787 by replacing ``@code{.@var{kind}}'' with the base @code{.literal} or
788 @code{.lit4} name. For example, for literals defined in a section named
789 @code{.gnu.linkonce.t.func}, the literal section will be
790 @code{.gnu.linkonce.literal.func} or @code{.gnu.linkonce.lit4.func}.
793 If the current section name (or @code{literal_prefix} value) ends with
794 @code{.text}, the literal section name is formed by replacing that
795 suffix with the base @code{.literal} or @code{.lit4} name. For example,
796 for literals defined in a section named @code{.iram0.text}, the literal
797 section will be @code{.iram0.literal} or @code{.iram0.lit4}.
800 If none of the preceding conditions apply, the literal section name is
801 formed by adding the base @code{.literal} or @code{.lit4} name as a
802 suffix to the current section name (or @code{literal_prefix} value).
805 @node Literal Position Directive
806 @subsection literal_position
807 @cindex @code{literal_position} directive
809 When using @samp{--text-@-section-@-literals} to place literals inline
810 in the section being assembled, the @code{.literal_position} directive
811 can be used to mark a potential location for a literal pool.
817 The @code{.literal_position} directive is ignored when the
818 @samp{--text-@-section-@-literals} option is not used or when
819 @code{L32R} instructions use the absolute addressing mode.
821 The assembler will automatically place text section literal pools
822 before @code{ENTRY} instructions, so the @code{.literal_position}
823 directive is only needed to specify some other location for a literal
824 pool. You may need to add an explicit jump instruction to skip over an
827 For example, an interrupt vector does not begin with an @code{ENTRY}
828 instruction so the assembler will be unable to automatically find a good
829 place to put a literal pool. Moreover, the code for the interrupt
830 vector must be at a specific starting address, so the literal pool
831 cannot come before the start of the code. The literal pool for the
832 vector must be explicitly positioned in the middle of the vector (before
833 any uses of the literals, due to the negative offsets used by
834 PC-relative @code{L32R} instructions). The @code{.literal_position}
835 directive can be used to do this. In the following code, the literal
836 for @samp{M} will automatically be aligned correctly and is placed after
837 the unconditional jump.
853 @node Literal Prefix Directive
854 @subsection literal_prefix
855 @cindex @code{literal_prefix} directive
857 The @code{literal_prefix} directive allows you to override the default
858 literal section names, which are derived from the names of the sections
859 where the literals are defined.
863 .begin literal_prefix [@var{name}]
868 For literals defined within the delimited region, the literal section
869 names are derived from the @var{name} argument instead of the name of
870 the current section. The rules used to derive the literal section names
871 do not change. @xref{Literal Directive, ,literal}. If the @var{name}
872 argument is omitted, the literal sections revert to the defaults. This
873 directive has no effect when using the
874 @samp{--text-@-section-@-literals} option (@pxref{Xtensa Options,
875 ,Command Line Options}).
877 @node Absolute Literals Directive
878 @subsection absolute-literals
879 @cindex @code{absolute-literals} directive
880 @cindex @code{no-absolute-literals} directive
882 The @code{absolute-@-literals} and @code{no-@-absolute-@-literals}
883 directives control the absolute vs.@: PC-relative mode for @code{L32R}
884 instructions. These are relevant only for Xtensa configurations that
885 include the absolute addressing option for @code{L32R} instructions.
889 .begin [no-]absolute-literals
890 .end [no-]absolute-literals
894 These directives do not change the @code{L32R} mode---they only cause
895 the assembler to emit the appropriate kind of relocation for @code{L32R}
896 instructions and to place the literal values in the appropriate section.
897 To change the @code{L32R} mode, the program must write the
898 @code{LITBASE} special register. It is the programmer's responsibility
899 to keep track of the mode and indicate to the assembler which mode is
900 used in each region of code.
902 If the Xtensa configuration includes the absolute @code{L32R} addressing
903 option, the default is to assume absolute @code{L32R} addressing unless
904 the @samp{--no-@-absolute-@-literals} command-line option is specified.
905 Otherwise, the default is to assume PC-relative @code{L32R} addressing.
906 The @code{absolute-@-literals} directive can then be used to override
907 the default determined by the command-line options.