1 @c Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007, 2008
2 @c Free Software Foundation, Inc.
3 @c This is part of the GAS manual.
4 @c For copying conditions, see the file as.texinfo.
10 @chapter Xtensa Dependent Features
13 @node Machine Dependencies
14 @chapter Xtensa Dependent Features
17 @cindex Xtensa architecture
18 This chapter covers features of the @sc{gnu} assembler that are specific
19 to the Xtensa architecture. For details about the Xtensa instruction
20 set, please consult the @cite{Xtensa Instruction Set Architecture (ISA)
24 * Xtensa Options:: Command-line Options.
25 * Xtensa Syntax:: Assembler Syntax for Xtensa Processors.
26 * Xtensa Optimizations:: Assembler Optimizations.
27 * Xtensa Relaxation:: Other Automatic Transformations.
28 * Xtensa Directives:: Directives for Xtensa Processors.
32 @section Command Line Options
37 @item --text-section-literals | --no-text-section-literals
38 @kindex --text-section-literals
39 @kindex --no-text-section-literals
40 Control the treatment of literal pools. The default is
41 @samp{--no-@-text-@-section-@-literals}, which places literals in
42 separate sections in the output file. This allows the literal pool to be
43 placed in a data RAM/ROM. With @samp{--text-@-section-@-literals}, the
44 literals are interspersed in the text section in order to keep them as
45 close as possible to their references. This may be necessary for large
46 assembly files, where the literals would otherwise be out of range of the
47 @code{L32R} instructions in the text section. These options only affect
48 literals referenced via PC-relative @code{L32R} instructions; literals
49 for absolute mode @code{L32R} instructions are handled separately.
50 @xref{Literal Directive, ,literal}.
52 @item --absolute-literals | --no-absolute-literals
53 @kindex --absolute-literals
54 @kindex --no-absolute-literals
55 Indicate to the assembler whether @code{L32R} instructions use absolute
56 or PC-relative addressing. If the processor includes the absolute
57 addressing option, the default is to use absolute @code{L32R}
58 relocations. Otherwise, only the PC-relative @code{L32R} relocations
61 @item --target-align | --no-target-align
62 @kindex --target-align
63 @kindex --no-target-align
64 Enable or disable automatic alignment to reduce branch penalties at some
65 expense in code size. @xref{Xtensa Automatic Alignment, ,Automatic
66 Instruction Alignment}. This optimization is enabled by default. Note
67 that the assembler will always align instructions like @code{LOOP} that
68 have fixed alignment requirements.
70 @item --longcalls | --no-longcalls
72 @kindex --no-longcalls
73 Enable or disable transformation of call instructions to allow calls
74 across a greater range of addresses. @xref{Xtensa Call Relaxation,
75 ,Function Call Relaxation}. This option should be used when call
76 targets can potentially be out of range. It may degrade both code size
77 and performance, but the linker can generally optimize away the
78 unnecessary overhead when a call ends up within range. The default is
79 @samp{--no-@-longcalls}.
81 @item --transform | --no-transform
83 @kindex --no-transform
84 Enable or disable all assembler transformations of Xtensa instructions,
85 including both relaxation and optimization. The default is
86 @samp{--transform}; @samp{--no-transform} should only be used in the
87 rare cases when the instructions must be exactly as specified in the
88 assembly source. Using @samp{--no-transform} causes out of range
89 instruction operands to be errors.
91 @item --rename-section @var{oldname}=@var{newname}
92 @kindex --rename-section
93 Rename the @var{oldname} section to @var{newname}. This option can be used
94 multiple times to rename multiple sections.
100 @section Assembler Syntax
101 @cindex syntax, Xtensa assembler
102 @cindex Xtensa assembler syntax
105 Block comments are delimited by @samp{/*} and @samp{*/}. End of line
106 comments may be introduced with either @samp{#} or @samp{//}.
108 Instructions consist of a leading opcode or macro name followed by
109 whitespace and an optional comma-separated list of operands:
112 @var{opcode} [@var{operand}, @dots{}]
115 Instructions must be separated by a newline or semicolon.
117 FLIX instructions, which bundle multiple opcodes together in a single
118 instruction, are specified by enclosing the bundled opcodes inside
125 @var{opcode0} [@var{operands}]
127 @var{opcode1} [@var{operands}]
129 @var{opcode2} [@var{operands}]
135 The opcodes in a FLIX instruction are listed in the same order as the
136 corresponding instruction slots in the TIE format declaration.
137 Directives and labels are not allowed inside the braces of a FLIX
138 instruction. A particular TIE format name can optionally be specified
139 immediately after the opening brace, but this is usually unnecessary.
140 The assembler will automatically search for a format that can encode the
141 specified opcodes, so the format name need only be specified in rare
142 cases where there is more than one applicable format and where it
143 matters which of those formats is used. A FLIX instruction can also be
144 specified on a single line by separating the opcodes with semicolons:
147 @{ [@var{format};] @var{opcode0} [@var{operands}]; @var{opcode1} [@var{operands}]; @var{opcode2} [@var{operands}]; @dots{} @}
150 If an opcode can only be encoded in a FLIX instruction but is not
151 specified as part of a FLIX bundle, the assembler will choose the
152 smallest format where the opcode can be encoded and
153 will fill unused instruction slots with no-ops.
156 * Xtensa Opcodes:: Opcode Naming Conventions.
157 * Xtensa Registers:: Register Naming.
161 @subsection Opcode Names
162 @cindex Xtensa opcode names
163 @cindex opcode names, Xtensa
165 See the @cite{Xtensa Instruction Set Architecture (ISA) Reference
166 Manual} for a complete list of opcodes and descriptions of their
169 @cindex _ opcode prefix
170 If an opcode name is prefixed with an underscore character (@samp{_}),
171 @command{@value{AS}} will not transform that instruction in any way. The
172 underscore prefix disables both optimization (@pxref{Xtensa
173 Optimizations, ,Xtensa Optimizations}) and relaxation (@pxref{Xtensa
174 Relaxation, ,Xtensa Relaxation}) for that particular instruction. Only
175 use the underscore prefix when it is essential to select the exact
176 opcode produced by the assembler. Using this feature unnecessarily
177 makes the code less efficient by disabling assembler optimization and
178 less flexible by disabling relaxation.
180 Note that this special handling of underscore prefixes only applies to
181 Xtensa opcodes, not to either built-in macros or user-defined macros.
182 When an underscore prefix is used with a macro (e.g., @code{_MOV}), it
183 refers to a different macro. The assembler generally provides built-in
184 macros both with and without the underscore prefix, where the underscore
185 versions behave as if the underscore carries through to the instructions
186 in the macros. For example, @code{_MOV} may expand to @code{_MOV.N}@.
188 The underscore prefix only applies to individual instructions, not to
189 series of instructions. For example, if a series of instructions have
190 underscore prefixes, the assembler will not transform the individual
191 instructions, but it may insert other instructions between them (e.g.,
192 to align a @code{LOOP} instruction). To prevent the assembler from
193 modifying a series of instructions as a whole, use the
194 @code{no-transform} directive. @xref{Transform Directive, ,transform}.
196 @node Xtensa Registers
197 @subsection Register Names
198 @cindex Xtensa register names
199 @cindex register names, Xtensa
202 The assembly syntax for a register file entry is the ``short'' name for
203 a TIE register file followed by the index into that register file. For
204 example, the general-purpose @code{AR} register file has a short name of
205 @code{a}, so these registers are named @code{a0}@dots{}@code{a15}.
206 As a special feature, @code{sp} is also supported as a synonym for
207 @code{a1}. Additional registers may be added by processor configuration
208 options and by designer-defined TIE extensions. An initial @samp{$}
209 character is optional in all register names.
211 @node Xtensa Optimizations
212 @section Xtensa Optimizations
213 @cindex optimizations
215 The optimizations currently supported by @command{@value{AS}} are
216 generation of density instructions where appropriate and automatic
217 branch target alignment.
220 * Density Instructions:: Using Density Instructions.
221 * Xtensa Automatic Alignment:: Automatic Instruction Alignment.
224 @node Density Instructions
225 @subsection Using Density Instructions
226 @cindex density instructions
228 The Xtensa instruction set has a code density option that provides
229 16-bit versions of some of the most commonly used opcodes. Use of these
230 opcodes can significantly reduce code size. When possible, the
231 assembler automatically translates instructions from the core
232 Xtensa instruction set into equivalent instructions from the Xtensa code
233 density option. This translation can be disabled by using underscore
234 prefixes (@pxref{Xtensa Opcodes, ,Opcode Names}), by using the
235 @samp{--no-transform} command-line option (@pxref{Xtensa Options, ,Command
236 Line Options}), or by using the @code{no-transform} directive
237 (@pxref{Transform Directive, ,transform}).
239 It is a good idea @emph{not} to use the density instructions directly.
240 The assembler will automatically select dense instructions where
241 possible. If you later need to use an Xtensa processor without the code
242 density option, the same assembly code will then work without modification.
244 @node Xtensa Automatic Alignment
245 @subsection Automatic Instruction Alignment
246 @cindex alignment of @code{LOOP} instructions
247 @cindex alignment of branch targets
248 @cindex @code{LOOP} instructions, alignment
249 @cindex branch target alignment
251 The Xtensa assembler will automatically align certain instructions, both
252 to optimize performance and to satisfy architectural requirements.
254 As an optimization to improve performance, the assembler attempts to
255 align branch targets so they do not cross instruction fetch boundaries.
256 (Xtensa processors can be configured with either 32-bit or 64-bit
257 instruction fetch widths.) An
258 instruction immediately following a call is treated as a branch target
259 in this context, because it will be the target of a return from the
260 call. This alignment has the potential to reduce branch penalties at
261 some expense in code size.
262 This optimization is enabled by default. You can disable it with the
263 @samp{--no-target-@-align} command-line option (@pxref{Xtensa Options,
264 ,Command Line Options}).
266 The target alignment optimization is done without adding instructions
267 that could increase the execution time of the program. If there are
268 density instructions in the code preceding a target, the assembler can
269 change the target alignment by widening some of those instructions to
270 the equivalent 24-bit instructions. Extra bytes of padding can be
271 inserted immediately following unconditional jump and return
273 This approach is usually successful in aligning many, but not all,
276 The @code{LOOP} family of instructions must be aligned such that the
277 first instruction in the loop body does not cross an instruction fetch
278 boundary (e.g., with a 32-bit fetch width, a @code{LOOP} instruction
279 must be on either a 1 or 2 mod 4 byte boundary). The assembler knows
280 about this restriction and inserts the minimal number of 2 or 3 byte
281 no-op instructions to satisfy it. When no-op instructions are added,
282 any label immediately preceding the original loop will be moved in order
283 to refer to the loop instruction, not the newly generated no-op
284 instruction. To preserve binary compatibility across processors with
285 different fetch widths, the assembler conservatively assumes a 32-bit
286 fetch width when aligning @code{LOOP} instructions (except if the first
287 instruction in the loop is a 64-bit instruction).
289 Previous versions of the assembler automatically aligned @code{ENTRY}
290 instructions to 4-byte boundaries, but that alignment is now the
291 programmer's responsibility.
293 @node Xtensa Relaxation
294 @section Xtensa Relaxation
297 When an instruction operand is outside the range allowed for that
298 particular instruction field, @command{@value{AS}} can transform the code
299 to use a functionally-equivalent instruction or sequence of
300 instructions. This process is known as @dfn{relaxation}. This is
301 typically done for branch instructions because the distance of the
302 branch targets is not known until assembly-time. The Xtensa assembler
303 offers branch relaxation and also extends this concept to function
304 calls, @code{MOVI} instructions and other instructions with immediate
308 * Xtensa Branch Relaxation:: Relaxation of Branches.
309 * Xtensa Call Relaxation:: Relaxation of Function Calls.
310 * Xtensa Immediate Relaxation:: Relaxation of other Immediate Fields.
313 @node Xtensa Branch Relaxation
314 @subsection Conditional Branch Relaxation
315 @cindex relaxation of branch instructions
316 @cindex branch instructions, relaxation
318 When the target of a branch is too far away from the branch itself,
319 i.e., when the offset from the branch to the target is too large to fit
320 in the immediate field of the branch instruction, it may be necessary to
321 replace the branch with a branch around a jump. For example,
337 (The @code{BNEZ.N} instruction would be used in this example only if the
338 density option is available. Otherwise, @code{BNEZ} would be used.)
340 This relaxation works well because the unconditional jump instruction
341 has a much larger offset range than the various conditional branches.
342 However, an error will occur if a branch target is beyond the range of a
343 jump instruction. @command{@value{AS}} cannot relax unconditional jumps.
344 Similarly, an error will occur if the original input contains an
345 unconditional jump to a target that is out of range.
347 Branch relaxation is enabled by default. It can be disabled by using
348 underscore prefixes (@pxref{Xtensa Opcodes, ,Opcode Names}), the
349 @samp{--no-transform} command-line option (@pxref{Xtensa Options,
350 ,Command Line Options}), or the @code{no-transform} directive
351 (@pxref{Transform Directive, ,transform}).
353 @node Xtensa Call Relaxation
354 @subsection Function Call Relaxation
355 @cindex relaxation of call instructions
356 @cindex call instructions, relaxation
358 Function calls may require relaxation because the Xtensa immediate call
359 instructions (@code{CALL0}, @code{CALL4}, @code{CALL8} and
360 @code{CALL12}) provide a PC-relative offset of only 512 Kbytes in either
361 direction. For larger programs, it may be necessary to use indirect
362 calls (@code{CALLX0}, @code{CALLX4}, @code{CALLX8} and @code{CALLX12})
363 where the target address is specified in a register. The Xtensa
364 assembler can automatically relax immediate call instructions into
365 indirect call instructions. This relaxation is done by loading the
366 address of the called function into the callee's return address register
367 and then using a @code{CALLX} instruction. So, for example:
383 Because the addresses of targets of function calls are not generally
384 known until link-time, the assembler must assume the worst and relax all
385 the calls to functions in other source files, not just those that really
386 will be out of range. The linker can recognize calls that were
387 unnecessarily relaxed, and it will remove the overhead introduced by the
388 assembler for those cases where direct calls are sufficient.
390 Call relaxation is disabled by default because it can have a negative
391 effect on both code size and performance, although the linker can
392 usually eliminate the unnecessary overhead. If a program is too large
393 and some of the calls are out of range, function call relaxation can be
394 enabled using the @samp{--longcalls} command-line option or the
395 @code{longcalls} directive (@pxref{Longcalls Directive, ,longcalls}).
397 @node Xtensa Immediate Relaxation
398 @subsection Other Immediate Field Relaxation
399 @cindex immediate fields, relaxation
400 @cindex relaxation of immediate fields
402 The assembler normally performs the following other relaxations. They
403 can be disabled by using underscore prefixes (@pxref{Xtensa Opcodes,
404 ,Opcode Names}), the @samp{--no-transform} command-line option
405 (@pxref{Xtensa Options, ,Command Line Options}), or the
406 @code{no-transform} directive (@pxref{Transform Directive, ,transform}).
408 @cindex @code{MOVI} instructions, relaxation
409 @cindex relaxation of @code{MOVI} instructions
410 The @code{MOVI} machine instruction can only materialize values in the
411 range from -2048 to 2047. Values outside this range are best
412 materialized with @code{L32R} instructions. Thus:
418 is assembled into the following machine code:
427 @cindex @code{L8UI} instructions, relaxation
428 @cindex @code{L16SI} instructions, relaxation
429 @cindex @code{L16UI} instructions, relaxation
430 @cindex @code{L32I} instructions, relaxation
431 @cindex relaxation of @code{L8UI} instructions
432 @cindex relaxation of @code{L16SI} instructions
433 @cindex relaxation of @code{L16UI} instructions
434 @cindex relaxation of @code{L32I} instructions
435 The @code{L8UI} machine instruction can only be used with immediate
436 offsets in the range from 0 to 255. The @code{L16SI} and @code{L16UI}
437 machine instructions can only be used with offsets from 0 to 510. The
438 @code{L32I} machine instruction can only be used with offsets from 0 to
439 1020. A load offset outside these ranges can be materialized with
440 an @code{L32R} instruction if the destination register of the load
441 is different than the source address register. For example:
461 If the load destination and source address register are the same, an
462 out-of-range offset causes an error.
464 @cindex @code{ADDI} instructions, relaxation
465 @cindex relaxation of @code{ADDI} instructions
466 The Xtensa @code{ADDI} instruction only allows immediate operands in the
467 range from -128 to 127. There are a number of alternate instruction
468 sequences for the @code{ADDI} operation. First, if the
469 immediate is 0, the @code{ADDI} will be turned into a @code{MOV.N}
470 instruction (or the equivalent @code{OR} instruction if the code density
471 option is not available). If the @code{ADDI} immediate is outside of
472 the range -128 to 127, but inside the range -32896 to 32639, an
473 @code{ADDMI} instruction or @code{ADDMI}/@code{ADDI} sequence will be
474 used. Finally, if the immediate is outside of this range and a free
475 register is available, an @code{L32R}/@code{ADD} sequence will be used
476 with a literal allocated from the literal pool.
491 is assembled into the following:
507 @node Xtensa Directives
509 @cindex Xtensa directives
510 @cindex directives, Xtensa
512 The Xtensa assembler supports a region-based directive syntax:
516 .begin @var{directive} [@var{options}]
522 All the Xtensa-specific directives that apply to a region of code use
525 The directive applies to code between the @code{.begin} and the
526 @code{.end}. The state of the option after the @code{.end} reverts to
527 what it was before the @code{.begin}.
528 A nested @code{.begin}/@code{.end} region can further
529 change the state of the directive without having to be aware of its
530 outer state. For example, consider:
546 The @code{ADD} opcodes at @code{L} and @code{N} in the outer
547 @code{no-transform} region both result in @code{ADD} machine instructions,
548 but the assembler selects an @code{ADD.N} instruction for the
549 @code{ADD} at @code{M} in the inner @code{transform} region.
551 The advantage of this style is that it works well inside macros which can
552 preserve the context of their callers.
554 The following directives are available:
556 * Schedule Directive:: Enable instruction scheduling.
557 * Longcalls Directive:: Use Indirect Calls for Greater Range.
558 * Transform Directive:: Disable All Assembler Transformations.
559 * Literal Directive:: Intermix Literals with Instructions.
560 * Literal Position Directive:: Specify Inline Literal Pool Locations.
561 * Literal Prefix Directive:: Specify Literal Section Name Prefix.
562 * Absolute Literals Directive:: Control PC-Relative vs. Absolute Literals.
565 @node Schedule Directive
567 @cindex @code{schedule} directive
568 @cindex @code{no-schedule} directive
570 The @code{schedule} directive is recognized only for compatibility with
571 Tensilica's assembler.
580 This directive is ignored and has no effect on @command{@value{AS}}.
582 @node Longcalls Directive
583 @subsection longcalls
584 @cindex @code{longcalls} directive
585 @cindex @code{no-longcalls} directive
587 The @code{longcalls} directive enables or disables function call
588 relaxation. @xref{Xtensa Call Relaxation, ,Function Call Relaxation}.
592 .begin [no-]longcalls
597 Call relaxation is disabled by default unless the @samp{--longcalls}
598 command-line option is specified. The @code{longcalls} directive
599 overrides the default determined by the command-line options.
601 @node Transform Directive
602 @subsection transform
603 @cindex @code{transform} directive
604 @cindex @code{no-transform} directive
606 This directive enables or disables all assembler transformation,
607 including relaxation (@pxref{Xtensa Relaxation, ,Xtensa Relaxation}) and
608 optimization (@pxref{Xtensa Optimizations, ,Xtensa Optimizations}).
612 .begin [no-]transform
617 Transformations are enabled by default unless the @samp{--no-transform}
618 option is used. The @code{transform} directive overrides the default
619 determined by the command-line options. An underscore opcode prefix,
620 disabling transformation of that opcode, always takes precedence over
621 both directives and command-line flags.
623 @node Literal Directive
625 @cindex @code{literal} directive
627 The @code{.literal} directive is used to define literal pool data, i.e.,
628 read-only 32-bit data accessed via @code{L32R} instructions.
631 .literal @var{label}, @var{value}[, @var{value}@dots{}]
634 This directive is similar to the standard @code{.word} directive, except
635 that the actual location of the literal data is determined by the
636 assembler and linker, not by the position of the @code{.literal}
637 directive. Using this directive gives the assembler freedom to locate
638 the literal data in the most appropriate place and possibly to combine
639 identical literals. For example, the code:
649 can be used to load a pointer to the symbol @code{sym} into register
650 @code{a4}. The value of @code{sym} will not be placed between the
651 @code{ENTRY} and @code{L32R} instructions; instead, the assembler puts
652 the data in a literal pool.
654 Literal pools are placed by default in separate literal sections;
655 however, when using the @samp{--text-@-section-@-literals}
656 option (@pxref{Xtensa Options, ,Command Line Options}), the literal
657 pools for PC-relative mode @code{L32R} instructions
658 are placed in the current section.@footnote{Literals for the
659 @code{.init} and @code{.fini} sections are always placed in separate
660 sections, even when @samp{--text-@-section-@-literals} is enabled.}
661 These text section literal
662 pools are created automatically before @code{ENTRY} instructions and
663 manually after @samp{.literal_position} directives (@pxref{Literal
664 Position Directive, ,literal_position}). If there are no preceding
665 @code{ENTRY} instructions, explicit @code{.literal_position} directives
666 must be used to place the text section literal pools; otherwise,
667 @command{@value{AS}} will report an error.
669 When literals are placed in separate sections, the literal section names
670 are derived from the names of the sections where the literals are
671 defined. The base literal section names are @code{.literal} for
672 PC-relative mode @code{L32R} instructions and @code{.lit4} for absolute
673 mode @code{L32R} instructions (@pxref{Absolute Literals Directive,
674 ,absolute-literals}). These base names are used for literals defined in
675 the default @code{.text} section. For literals defined in other
676 sections or within the scope of a @code{literal_prefix} directive
677 (@pxref{Literal Prefix Directive, ,literal_prefix}), the following rules
678 determine the literal section name:
682 If the current section is a member of a section group, the literal
683 section name includes the group name as a suffix to the base
684 @code{.literal} or @code{.lit4} name, with a period to separate the base
685 name and group name. The literal section is also made a member of the
689 If the current section name (or @code{literal_prefix} value) begins with
690 ``@code{.gnu.linkonce.@var{kind}.}'', the literal section name is formed
691 by replacing ``@code{.@var{kind}}'' with the base @code{.literal} or
692 @code{.lit4} name. For example, for literals defined in a section named
693 @code{.gnu.linkonce.t.func}, the literal section will be
694 @code{.gnu.linkonce.literal.func} or @code{.gnu.linkonce.lit4.func}.
697 If the current section name (or @code{literal_prefix} value) ends with
698 @code{.text}, the literal section name is formed by replacing that
699 suffix with the base @code{.literal} or @code{.lit4} name. For example,
700 for literals defined in a section named @code{.iram0.text}, the literal
701 section will be @code{.iram0.literal} or @code{.iram0.lit4}.
704 If none of the preceding conditions apply, the literal section name is
705 formed by adding the base @code{.literal} or @code{.lit4} name as a
706 suffix to the current section name (or @code{literal_prefix} value).
709 @node Literal Position Directive
710 @subsection literal_position
711 @cindex @code{literal_position} directive
713 When using @samp{--text-@-section-@-literals} to place literals inline
714 in the section being assembled, the @code{.literal_position} directive
715 can be used to mark a potential location for a literal pool.
721 The @code{.literal_position} directive is ignored when the
722 @samp{--text-@-section-@-literals} option is not used or when
723 @code{L32R} instructions use the absolute addressing mode.
725 The assembler will automatically place text section literal pools
726 before @code{ENTRY} instructions, so the @code{.literal_position}
727 directive is only needed to specify some other location for a literal
728 pool. You may need to add an explicit jump instruction to skip over an
731 For example, an interrupt vector does not begin with an @code{ENTRY}
732 instruction so the assembler will be unable to automatically find a good
733 place to put a literal pool. Moreover, the code for the interrupt
734 vector must be at a specific starting address, so the literal pool
735 cannot come before the start of the code. The literal pool for the
736 vector must be explicitly positioned in the middle of the vector (before
737 any uses of the literals, due to the negative offsets used by
738 PC-relative @code{L32R} instructions). The @code{.literal_position}
739 directive can be used to do this. In the following code, the literal
740 for @samp{M} will automatically be aligned correctly and is placed after
741 the unconditional jump.
757 @node Literal Prefix Directive
758 @subsection literal_prefix
759 @cindex @code{literal_prefix} directive
761 The @code{literal_prefix} directive allows you to override the default
762 literal section names, which are derived from the names of the sections
763 where the literals are defined.
767 .begin literal_prefix [@var{name}]
772 For literals defined within the delimited region, the literal section
773 names are derived from the @var{name} argument instead of the name of
774 the current section. The rules used to derive the literal section names
775 do not change. @xref{Literal Directive, ,literal}. If the @var{name}
776 argument is omitted, the literal sections revert to the defaults. This
777 directive has no effect when using the
778 @samp{--text-@-section-@-literals} option (@pxref{Xtensa Options,
779 ,Command Line Options}).
781 @node Absolute Literals Directive
782 @subsection absolute-literals
783 @cindex @code{absolute-literals} directive
784 @cindex @code{no-absolute-literals} directive
786 The @code{absolute-@-literals} and @code{no-@-absolute-@-literals}
787 directives control the absolute vs.@: PC-relative mode for @code{L32R}
788 instructions. These are relevant only for Xtensa configurations that
789 include the absolute addressing option for @code{L32R} instructions.
793 .begin [no-]absolute-literals
794 .end [no-]absolute-literals
798 These directives do not change the @code{L32R} mode---they only cause
799 the assembler to emit the appropriate kind of relocation for @code{L32R}
800 instructions and to place the literal values in the appropriate section.
801 To change the @code{L32R} mode, the program must write the
802 @code{LITBASE} special register. It is the programmer's responsibility
803 to keep track of the mode and indicate to the assembler which mode is
804 used in each region of code.
806 If the Xtensa configuration includes the absolute @code{L32R} addressing
807 option, the default is to assume absolute @code{L32R} addressing unless
808 the @samp{--no-@-absolute-@-literals} command-line option is specified.
809 Otherwise, the default is to assume PC-relative @code{L32R} addressing.
810 The @code{absolute-@-literals} directive can then be used to override
811 the default determined by the command-line options.