Merge branch 'vendor/GCC44'
[dragonfly.git] / contrib / binutils-2.22 / gas / doc / c-xtensa.texi
1 @c Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2011
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.
5 @c
6 @c man end
7 @ifset GENERIC
8 @page
9 @node Xtensa-Dependent
10 @chapter Xtensa Dependent Features
11 @end ifset
12 @ifclear GENERIC
13 @node Machine Dependencies
14 @chapter Xtensa Dependent Features
15 @end ifclear
16
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)
21 Reference Manual}.
22
23 @menu
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.
29 @end menu
30
31 @node Xtensa Options
32 @section Command Line Options
33
34 @c man begin OPTIONS
35 @table @gcctabopt
36
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}.
51
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
59 can be used.
60
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.
69
70 @item --longcalls | --no-longcalls
71 @kindex --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}.
80
81 @item --transform | --no-transform
82 @kindex --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.
90
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.
95 @end table
96
97 @c man end
98
99 @node Xtensa Syntax
100 @section Assembler Syntax
101 @cindex syntax, Xtensa assembler
102 @cindex Xtensa assembler syntax
103 @cindex FLIX syntax
104
105 Block comments are delimited by @samp{/*} and @samp{*/}.  End of line
106 comments may be introduced with either @samp{#} or @samp{//}.
107
108 If a @samp{#} appears as the first character of a line then the whole
109 line is treated as a comment, but in this case the line could also be
110 a logical line number directive (@pxref{Comments}) or a preprocessor
111 control command (@pxref{Preprocessing}).
112
113 Instructions consist of a leading opcode or macro name followed by
114 whitespace and an optional comma-separated list of operands:
115
116 @smallexample
117 @var{opcode} [@var{operand}, @dots{}]
118 @end smallexample
119
120 Instructions must be separated by a newline or semicolon (@samp{;}).
121
122 FLIX instructions, which bundle multiple opcodes together in a single
123 instruction, are specified by enclosing the bundled opcodes inside
124 braces:
125
126 @smallexample
127 @group
128 @{
129 [@var{format}]
130 @var{opcode0} [@var{operands}]
131 @end group
132 @var{opcode1} [@var{operands}]
133 @group
134 @var{opcode2} [@var{operands}]
135 @dots{}
136 @}
137 @end group
138 @end smallexample
139
140 The opcodes in a FLIX instruction are listed in the same order as the
141 corresponding instruction slots in the TIE format declaration.
142 Directives and labels are not allowed inside the braces of a FLIX
143 instruction.  A particular TIE format name can optionally be specified
144 immediately after the opening brace, but this is usually unnecessary.
145 The assembler will automatically search for a format that can encode the
146 specified opcodes, so the format name need only be specified in rare
147 cases where there is more than one applicable format and where it
148 matters which of those formats is used.  A FLIX instruction can also be
149 specified on a single line by separating the opcodes with semicolons:
150
151 @smallexample
152 @{ [@var{format};] @var{opcode0} [@var{operands}]; @var{opcode1} [@var{operands}]; @var{opcode2} [@var{operands}]; @dots{} @}
153 @end smallexample
154
155 If an opcode can only be encoded in a FLIX instruction but is not
156 specified as part of a FLIX bundle, the assembler will choose the
157 smallest format where the opcode can be encoded and
158 will fill unused instruction slots with no-ops.
159
160 @menu
161 * Xtensa Opcodes::              Opcode Naming Conventions.
162 * Xtensa Registers::            Register Naming.
163 @end menu
164
165 @node Xtensa Opcodes
166 @subsection Opcode Names
167 @cindex Xtensa opcode names
168 @cindex opcode names, Xtensa
169
170 See the @cite{Xtensa Instruction Set Architecture (ISA) Reference
171 Manual} for a complete list of opcodes and descriptions of their
172 semantics.
173
174 @cindex _ opcode prefix
175 If an opcode name is prefixed with an underscore character (@samp{_}),
176 @command{@value{AS}} will not transform that instruction in any way.  The
177 underscore prefix disables both optimization (@pxref{Xtensa
178 Optimizations, ,Xtensa Optimizations}) and relaxation (@pxref{Xtensa
179 Relaxation, ,Xtensa Relaxation}) for that particular instruction.  Only
180 use the underscore prefix when it is essential to select the exact
181 opcode produced by the assembler.  Using this feature unnecessarily
182 makes the code less efficient by disabling assembler optimization and
183 less flexible by disabling relaxation.
184
185 Note that this special handling of underscore prefixes only applies to
186 Xtensa opcodes, not to either built-in macros or user-defined macros.
187 When an underscore prefix is used with a macro (e.g., @code{_MOV}), it
188 refers to a different macro.  The assembler generally provides built-in
189 macros both with and without the underscore prefix, where the underscore
190 versions behave as if the underscore carries through to the instructions
191 in the macros.  For example, @code{_MOV} may expand to @code{_MOV.N}@.
192
193 The underscore prefix only applies to individual instructions, not to
194 series of instructions.  For example, if a series of instructions have
195 underscore prefixes, the assembler will not transform the individual
196 instructions, but it may insert other instructions between them (e.g.,
197 to align a @code{LOOP} instruction).  To prevent the assembler from
198 modifying a series of instructions as a whole, use the
199 @code{no-transform} directive.  @xref{Transform Directive, ,transform}.
200
201 @node Xtensa Registers
202 @subsection Register Names
203 @cindex Xtensa register names
204 @cindex register names, Xtensa
205 @cindex sp register
206
207 The assembly syntax for a register file entry is the ``short'' name for
208 a TIE register file followed by the index into that register file.  For
209 example, the general-purpose @code{AR} register file has a short name of
210 @code{a}, so these registers are named @code{a0}@dots{}@code{a15}.
211 As a special feature, @code{sp} is also supported as a synonym for
212 @code{a1}.  Additional registers may be added by processor configuration
213 options and by designer-defined TIE extensions.  An initial @samp{$}
214 character is optional in all register names.
215
216 @node Xtensa Optimizations
217 @section Xtensa Optimizations
218 @cindex optimizations
219
220 The optimizations currently supported by @command{@value{AS}} are
221 generation of density instructions where appropriate and automatic
222 branch target alignment.
223
224 @menu
225 * Density Instructions::        Using Density Instructions.
226 * Xtensa Automatic Alignment::  Automatic Instruction Alignment.
227 @end menu
228
229 @node Density Instructions
230 @subsection Using Density Instructions
231 @cindex density instructions
232
233 The Xtensa instruction set has a code density option that provides
234 16-bit versions of some of the most commonly used opcodes.  Use of these
235 opcodes can significantly reduce code size.  When possible, the
236 assembler automatically translates instructions from the core
237 Xtensa instruction set into equivalent instructions from the Xtensa code
238 density option.  This translation can be disabled by using underscore
239 prefixes (@pxref{Xtensa Opcodes, ,Opcode Names}), by using the
240 @samp{--no-transform} command-line option (@pxref{Xtensa Options, ,Command
241 Line Options}), or by using the @code{no-transform} directive
242 (@pxref{Transform Directive, ,transform}).
243
244 It is a good idea @emph{not} to use the density instructions directly.
245 The assembler will automatically select dense instructions where
246 possible.  If you later need to use an Xtensa processor without the code
247 density option, the same assembly code will then work without modification.
248
249 @node Xtensa Automatic Alignment
250 @subsection Automatic Instruction Alignment
251 @cindex alignment of @code{LOOP} instructions
252 @cindex alignment of branch targets
253 @cindex @code{LOOP} instructions, alignment
254 @cindex branch target alignment
255
256 The Xtensa assembler will automatically align certain instructions, both
257 to optimize performance and to satisfy architectural requirements.
258
259 As an optimization to improve performance, the assembler attempts to
260 align branch targets so they do not cross instruction fetch boundaries.
261 (Xtensa processors can be configured with either 32-bit or 64-bit
262 instruction fetch widths.)  An
263 instruction immediately following a call is treated as a branch target
264 in this context, because it will be the target of a return from the
265 call.  This alignment has the potential to reduce branch penalties at
266 some expense in code size.
267 This optimization is enabled by default.  You can disable it with the
268 @samp{--no-target-@-align} command-line option (@pxref{Xtensa Options,
269 ,Command Line Options}).
270
271 The target alignment optimization is done without adding instructions
272 that could increase the execution time of the program.  If there are
273 density instructions in the code preceding a target, the assembler can
274 change the target alignment by widening some of those instructions to
275 the equivalent 24-bit instructions.  Extra bytes of padding can be
276 inserted immediately following unconditional jump and return
277 instructions.
278 This approach is usually successful in aligning many, but not all,
279 branch targets.
280
281 The @code{LOOP} family of instructions must be aligned such that the
282 first instruction in the loop body does not cross an instruction fetch
283 boundary (e.g., with a 32-bit fetch width, a @code{LOOP} instruction
284 must be on either a 1 or 2 mod 4 byte boundary).  The assembler knows
285 about this restriction and inserts the minimal number of 2 or 3 byte
286 no-op instructions to satisfy it.  When no-op instructions are added,
287 any label immediately preceding the original loop will be moved in order
288 to refer to the loop instruction, not the newly generated no-op
289 instruction.  To preserve binary compatibility across processors with
290 different fetch widths, the assembler conservatively assumes a 32-bit
291 fetch width when aligning @code{LOOP} instructions (except if the first
292 instruction in the loop is a 64-bit instruction).
293
294 Previous versions of the assembler automatically aligned @code{ENTRY}
295 instructions to 4-byte boundaries, but that alignment is now the
296 programmer's responsibility.
297
298 @node Xtensa Relaxation
299 @section Xtensa Relaxation
300 @cindex relaxation
301
302 When an instruction operand is outside the range allowed for that
303 particular instruction field, @command{@value{AS}} can transform the code
304 to use a functionally-equivalent instruction or sequence of
305 instructions.  This process is known as @dfn{relaxation}.  This is
306 typically done for branch instructions because the distance of the
307 branch targets is not known until assembly-time.  The Xtensa assembler
308 offers branch relaxation and also extends this concept to function
309 calls, @code{MOVI} instructions and other instructions with immediate
310 fields.
311
312 @menu
313 * Xtensa Branch Relaxation::        Relaxation of Branches.
314 * Xtensa Call Relaxation::          Relaxation of Function Calls.
315 * Xtensa Immediate Relaxation::     Relaxation of other Immediate Fields.
316 @end menu
317
318 @node Xtensa Branch Relaxation
319 @subsection Conditional Branch Relaxation
320 @cindex relaxation of branch instructions
321 @cindex branch instructions, relaxation
322
323 When the target of a branch is too far away from the branch itself,
324 i.e., when the offset from the branch to the target is too large to fit
325 in the immediate field of the branch instruction, it may be necessary to
326 replace the branch with a branch around a jump.  For example,
327
328 @smallexample
329     beqz    a2, L
330 @end smallexample
331
332 may result in:
333
334 @smallexample
335 @group
336     bnez.n  a2, M
337     j L
338 M:
339 @end group
340 @end smallexample
341
342 (The @code{BNEZ.N} instruction would be used in this example only if the
343 density option is available.  Otherwise, @code{BNEZ} would be used.)
344
345 This relaxation works well because the unconditional jump instruction
346 has a much larger offset range than the various conditional branches.
347 However, an error will occur if a branch target is beyond the range of a
348 jump instruction.  @command{@value{AS}} cannot relax unconditional jumps.
349 Similarly, an error will occur if the original input contains an
350 unconditional jump to a target that is out of range.
351
352 Branch relaxation is enabled by default.  It can be disabled by using
353 underscore prefixes (@pxref{Xtensa Opcodes, ,Opcode Names}), the
354 @samp{--no-transform} command-line option (@pxref{Xtensa Options,
355 ,Command Line Options}), or the @code{no-transform} directive
356 (@pxref{Transform Directive, ,transform}).
357
358 @node Xtensa Call Relaxation
359 @subsection Function Call Relaxation
360 @cindex relaxation of call instructions
361 @cindex call instructions, relaxation
362
363 Function calls may require relaxation because the Xtensa immediate call
364 instructions (@code{CALL0}, @code{CALL4}, @code{CALL8} and
365 @code{CALL12}) provide a PC-relative offset of only 512 Kbytes in either
366 direction.  For larger programs, it may be necessary to use indirect
367 calls (@code{CALLX0}, @code{CALLX4}, @code{CALLX8} and @code{CALLX12})
368 where the target address is specified in a register.  The Xtensa
369 assembler can automatically relax immediate call instructions into
370 indirect call instructions.  This relaxation is done by loading the
371 address of the called function into the callee's return address register
372 and then using a @code{CALLX} instruction.  So, for example:
373
374 @smallexample
375     call8 func
376 @end smallexample
377
378 might be relaxed to:
379
380 @smallexample
381 @group
382     .literal .L1, func
383     l32r    a8, .L1
384     callx8  a8
385 @end group
386 @end smallexample
387
388 Because the addresses of targets of function calls are not generally
389 known until link-time, the assembler must assume the worst and relax all
390 the calls to functions in other source files, not just those that really
391 will be out of range.  The linker can recognize calls that were
392 unnecessarily relaxed, and it will remove the overhead introduced by the
393 assembler for those cases where direct calls are sufficient.
394
395 Call relaxation is disabled by default because it can have a negative
396 effect on both code size and performance, although the linker can
397 usually eliminate the unnecessary overhead.  If a program is too large
398 and some of the calls are out of range, function call relaxation can be
399 enabled using the @samp{--longcalls} command-line option or the
400 @code{longcalls} directive (@pxref{Longcalls Directive, ,longcalls}).
401
402 @node Xtensa Immediate Relaxation
403 @subsection Other Immediate Field Relaxation
404 @cindex immediate fields, relaxation
405 @cindex relaxation of immediate fields
406
407 The assembler normally performs the following other relaxations.  They
408 can be disabled by using underscore prefixes (@pxref{Xtensa Opcodes,
409 ,Opcode Names}), the @samp{--no-transform} command-line option
410 (@pxref{Xtensa Options, ,Command Line Options}), or the
411 @code{no-transform} directive (@pxref{Transform Directive, ,transform}).
412
413 @cindex @code{MOVI} instructions, relaxation
414 @cindex relaxation of @code{MOVI} instructions
415 The @code{MOVI} machine instruction can only materialize values in the
416 range from -2048 to 2047.  Values outside this range are best
417 materialized with @code{L32R} instructions.  Thus:
418
419 @smallexample
420     movi a0, 100000
421 @end smallexample
422
423 is assembled into the following machine code:
424
425 @smallexample
426 @group
427     .literal .L1, 100000
428     l32r a0, .L1
429 @end group
430 @end smallexample
431
432 @cindex @code{L8UI} instructions, relaxation
433 @cindex @code{L16SI} instructions, relaxation
434 @cindex @code{L16UI} instructions, relaxation
435 @cindex @code{L32I} instructions, relaxation
436 @cindex relaxation of @code{L8UI} instructions
437 @cindex relaxation of @code{L16SI} instructions
438 @cindex relaxation of @code{L16UI} instructions
439 @cindex relaxation of @code{L32I} instructions
440 The @code{L8UI} machine instruction can only be used with immediate
441 offsets in the range from 0 to 255. The @code{L16SI} and @code{L16UI}
442 machine instructions can only be used with offsets from 0 to 510.  The
443 @code{L32I} machine instruction can only be used with offsets from 0 to
444 1020.  A load offset outside these ranges can be materialized with
445 an @code{L32R} instruction if the destination register of the load
446 is different than the source address register.  For example:
447
448 @smallexample
449     l32i a1, a0, 2040
450 @end smallexample
451
452 is translated to:
453
454 @smallexample
455 @group
456     .literal .L1, 2040
457     l32r a1, .L1
458 @end group
459 @group
460     add a1, a0, a1
461     l32i a1, a1, 0
462 @end group
463 @end smallexample
464
465 @noindent
466 If the load destination and source address register are the same, an
467 out-of-range offset causes an error.
468
469 @cindex @code{ADDI} instructions, relaxation
470 @cindex relaxation of @code{ADDI} instructions
471 The Xtensa @code{ADDI} instruction only allows immediate operands in the
472 range from -128 to 127.  There are a number of alternate instruction
473 sequences for the @code{ADDI} operation.  First, if the
474 immediate is 0, the @code{ADDI} will be turned into a @code{MOV.N}
475 instruction (or the equivalent @code{OR} instruction if the code density
476 option is not available).  If the @code{ADDI} immediate is outside of
477 the range -128 to 127, but inside the range -32896 to 32639, an
478 @code{ADDMI} instruction or @code{ADDMI}/@code{ADDI} sequence will be
479 used.  Finally, if the immediate is outside of this range and a free
480 register is available, an @code{L32R}/@code{ADD} sequence will be used
481 with a literal allocated from the literal pool.
482
483 For example:
484
485 @smallexample
486 @group
487     addi    a5, a6, 0
488     addi    a5, a6, 512
489 @end group
490 @group
491     addi    a5, a6, 513
492     addi    a5, a6, 50000
493 @end group
494 @end smallexample
495
496 is assembled into the following:
497
498 @smallexample
499 @group
500     .literal .L1, 50000
501     mov.n   a5, a6
502 @end group
503     addmi   a5, a6, 0x200
504     addmi   a5, a6, 0x200
505     addi    a5, a5, 1
506 @group
507     l32r    a5, .L1
508     add     a5, a6, a5
509 @end group
510 @end smallexample
511
512 @node Xtensa Directives
513 @section Directives
514 @cindex Xtensa directives
515 @cindex directives, Xtensa
516
517 The Xtensa assembler supports a region-based directive syntax:
518
519 @smallexample
520 @group
521     .begin @var{directive} [@var{options}]
522     @dots{}
523     .end @var{directive}
524 @end group
525 @end smallexample
526
527 All the Xtensa-specific directives that apply to a region of code use
528 this syntax.
529
530 The directive applies to code between the @code{.begin} and the
531 @code{.end}.  The state of the option after the @code{.end} reverts to
532 what it was before the @code{.begin}.
533 A nested @code{.begin}/@code{.end} region can further
534 change the state of the directive without having to be aware of its
535 outer state.  For example, consider:
536
537 @smallexample
538 @group
539     .begin no-transform
540 L:  add a0, a1, a2
541 @end group
542     .begin transform
543 M:  add a0, a1, a2
544     .end transform
545 @group
546 N:  add a0, a1, a2
547     .end no-transform
548 @end group
549 @end smallexample
550
551 The @code{ADD} opcodes at @code{L} and @code{N} in the outer
552 @code{no-transform} region both result in @code{ADD} machine instructions,
553 but the assembler selects an @code{ADD.N} instruction for the
554 @code{ADD} at @code{M} in the inner @code{transform} region.
555
556 The advantage of this style is that it works well inside macros which can
557 preserve the context of their callers.
558
559 The following directives are available:
560 @menu
561 * Schedule Directive::         Enable instruction scheduling.
562 * Longcalls Directive::        Use Indirect Calls for Greater Range.
563 * Transform Directive::        Disable All Assembler Transformations.
564 * Literal Directive::          Intermix Literals with Instructions.
565 * Literal Position Directive:: Specify Inline Literal Pool Locations.
566 * Literal Prefix Directive::   Specify Literal Section Name Prefix.
567 * Absolute Literals Directive:: Control PC-Relative vs. Absolute Literals.
568 @end menu
569
570 @node Schedule Directive
571 @subsection schedule
572 @cindex @code{schedule} directive
573 @cindex @code{no-schedule} directive
574
575 The @code{schedule} directive is recognized only for compatibility with
576 Tensilica's assembler.
577
578 @smallexample
579 @group
580     .begin [no-]schedule
581     .end [no-]schedule
582 @end group
583 @end smallexample
584
585 This directive is ignored and has no effect on @command{@value{AS}}.
586
587 @node Longcalls Directive
588 @subsection longcalls
589 @cindex @code{longcalls} directive
590 @cindex @code{no-longcalls} directive
591
592 The @code{longcalls} directive enables or disables function call
593 relaxation.  @xref{Xtensa Call Relaxation, ,Function Call Relaxation}.
594
595 @smallexample
596 @group
597     .begin [no-]longcalls
598     .end [no-]longcalls
599 @end group
600 @end smallexample
601
602 Call relaxation is disabled by default unless the @samp{--longcalls}
603 command-line option is specified.  The @code{longcalls} directive
604 overrides the default determined by the command-line options.
605
606 @node Transform Directive
607 @subsection transform
608 @cindex @code{transform} directive
609 @cindex @code{no-transform} directive
610
611 This directive enables or disables all assembler transformation,
612 including relaxation (@pxref{Xtensa Relaxation, ,Xtensa Relaxation}) and
613 optimization (@pxref{Xtensa Optimizations, ,Xtensa Optimizations}).
614
615 @smallexample
616 @group
617     .begin [no-]transform
618     .end [no-]transform
619 @end group
620 @end smallexample
621
622 Transformations are enabled by default unless the @samp{--no-transform}
623 option is used.  The @code{transform} directive overrides the default
624 determined by the command-line options.  An underscore opcode prefix,
625 disabling transformation of that opcode, always takes precedence over
626 both directives and command-line flags.
627
628 @node Literal Directive
629 @subsection literal
630 @cindex @code{literal} directive
631
632 The @code{.literal} directive is used to define literal pool data, i.e., 
633 read-only 32-bit data accessed via @code{L32R} instructions.
634
635 @smallexample
636     .literal @var{label}, @var{value}[, @var{value}@dots{}]
637 @end smallexample
638
639 This directive is similar to the standard @code{.word} directive, except
640 that the actual location of the literal data is determined by the
641 assembler and linker, not by the position of the @code{.literal}
642 directive.  Using this directive gives the assembler freedom to locate
643 the literal data in the most appropriate place and possibly to combine
644 identical literals.  For example, the code:
645
646 @smallexample
647 @group
648     entry sp, 40
649     .literal .L1, sym
650     l32r    a4, .L1
651 @end group
652 @end smallexample
653
654 can be used to load a pointer to the symbol @code{sym} into register
655 @code{a4}.  The value of @code{sym} will not be placed between the
656 @code{ENTRY} and @code{L32R} instructions; instead, the assembler puts
657 the data in a literal pool.
658
659 Literal pools are placed by default in separate literal sections;
660 however, when using the @samp{--text-@-section-@-literals}
661 option (@pxref{Xtensa Options, ,Command Line Options}), the literal
662 pools for PC-relative mode @code{L32R} instructions
663 are placed in the current section.@footnote{Literals for the
664 @code{.init} and @code{.fini} sections are always placed in separate
665 sections, even when @samp{--text-@-section-@-literals} is enabled.}
666 These text section literal
667 pools are created automatically before @code{ENTRY} instructions and
668 manually after @samp{.literal_position} directives (@pxref{Literal
669 Position Directive, ,literal_position}).  If there are no preceding
670 @code{ENTRY} instructions, explicit @code{.literal_position} directives
671 must be used to place the text section literal pools; otherwise,
672 @command{@value{AS}} will report an error.
673
674 When literals are placed in separate sections, the literal section names
675 are derived from the names of the sections where the literals are
676 defined.  The base literal section names are @code{.literal} for
677 PC-relative mode @code{L32R} instructions and @code{.lit4} for absolute
678 mode @code{L32R} instructions (@pxref{Absolute Literals Directive,
679 ,absolute-literals}).  These base names are used for literals defined in
680 the default @code{.text} section.  For literals defined in other
681 sections or within the scope of a @code{literal_prefix} directive
682 (@pxref{Literal Prefix Directive, ,literal_prefix}), the following rules
683 determine the literal section name:
684
685 @enumerate
686 @item
687 If the current section is a member of a section group, the literal
688 section name includes the group name as a suffix to the base
689 @code{.literal} or @code{.lit4} name, with a period to separate the base
690 name and group name.  The literal section is also made a member of the
691 group.
692
693 @item
694 If the current section name (or @code{literal_prefix} value) begins with
695 ``@code{.gnu.linkonce.@var{kind}.}'', the literal section name is formed
696 by replacing ``@code{.@var{kind}}'' with the base @code{.literal} or
697 @code{.lit4} name.  For example, for literals defined in a section named
698 @code{.gnu.linkonce.t.func}, the literal section will be
699 @code{.gnu.linkonce.literal.func} or @code{.gnu.linkonce.lit4.func}.
700
701 @item
702 If the current section name (or @code{literal_prefix} value) ends with
703 @code{.text}, the literal section name is formed by replacing that
704 suffix with the base @code{.literal} or @code{.lit4} name.  For example,
705 for literals defined in a section named @code{.iram0.text}, the literal
706 section will be @code{.iram0.literal} or @code{.iram0.lit4}.
707
708 @item
709 If none of the preceding conditions apply, the literal section name is
710 formed by adding the base @code{.literal} or @code{.lit4} name as a
711 suffix to the current section name (or @code{literal_prefix} value).
712 @end enumerate
713
714 @node Literal Position Directive
715 @subsection literal_position
716 @cindex @code{literal_position} directive
717
718 When using @samp{--text-@-section-@-literals} to place literals inline
719 in the section being assembled, the @code{.literal_position} directive
720 can be used to mark a potential location for a literal pool.
721
722 @smallexample
723     .literal_position
724 @end smallexample
725
726 The @code{.literal_position} directive is ignored when the
727 @samp{--text-@-section-@-literals} option is not used or when
728 @code{L32R} instructions use the absolute addressing mode.
729
730 The assembler will automatically place text section literal pools 
731 before @code{ENTRY} instructions, so the @code{.literal_position}
732 directive is only needed to specify some other location for a literal
733 pool.  You may need to add an explicit jump instruction to skip over an
734 inline literal pool.
735
736 For example, an interrupt vector does not begin with an @code{ENTRY}
737 instruction so the assembler will be unable to automatically find a good
738 place to put a literal pool.  Moreover, the code for the interrupt
739 vector must be at a specific starting address, so the literal pool
740 cannot come before the start of the code.  The literal pool for the
741 vector must be explicitly positioned in the middle of the vector (before
742 any uses of the literals, due to the negative offsets used by
743 PC-relative @code{L32R} instructions).  The @code{.literal_position}
744 directive can be used to do this.  In the following code, the literal
745 for @samp{M} will automatically be aligned correctly and is placed after
746 the unconditional jump.
747
748 @smallexample
749 @group
750     .global M
751 code_start:
752 @end group
753     j continue
754     .literal_position
755     .align 4
756 @group
757 continue:
758     movi    a4, M
759 @end group
760 @end smallexample
761
762 @node Literal Prefix Directive
763 @subsection literal_prefix
764 @cindex @code{literal_prefix} directive
765
766 The @code{literal_prefix} directive allows you to override the default
767 literal section names, which are derived from the names of the sections
768 where the literals are defined.
769
770 @smallexample
771 @group
772     .begin literal_prefix [@var{name}]
773     .end literal_prefix
774 @end group
775 @end smallexample
776
777 For literals defined within the delimited region, the literal section
778 names are derived from the @var{name} argument instead of the name of
779 the current section.  The rules used to derive the literal section names
780 do not change.  @xref{Literal Directive, ,literal}.  If the @var{name}
781 argument is omitted, the literal sections revert to the defaults.  This
782 directive has no effect when using the
783 @samp{--text-@-section-@-literals} option (@pxref{Xtensa Options,
784 ,Command Line Options}).
785
786 @node Absolute Literals Directive
787 @subsection absolute-literals
788 @cindex @code{absolute-literals} directive
789 @cindex @code{no-absolute-literals} directive
790
791 The @code{absolute-@-literals} and @code{no-@-absolute-@-literals}
792 directives control the absolute vs.@: PC-relative mode for @code{L32R}
793 instructions.  These are relevant only for Xtensa configurations that
794 include the absolute addressing option for @code{L32R} instructions.
795
796 @smallexample
797 @group
798     .begin [no-]absolute-literals
799     .end [no-]absolute-literals
800 @end group
801 @end smallexample
802
803 These directives do not change the @code{L32R} mode---they only cause
804 the assembler to emit the appropriate kind of relocation for @code{L32R}
805 instructions and to place the literal values in the appropriate section.
806 To change the @code{L32R} mode, the program must write the
807 @code{LITBASE} special register.  It is the programmer's responsibility
808 to keep track of the mode and indicate to the assembler which mode is
809 used in each region of code.
810
811 If the Xtensa configuration includes the absolute @code{L32R} addressing
812 option, the default is to assume absolute @code{L32R} addressing unless
813 the @samp{--no-@-absolute-@-literals} command-line option is specified.
814 Otherwise, the default is to assume PC-relative @code{L32R} addressing.
815 The @code{absolute-@-literals} directive can then be used to override
816 the default determined by the command-line options.
817
818 @c Local Variables:
819 @c fill-column: 72
820 @c End: