Merge branch 'vendor/GCC50'
[dragonfly.git] / contrib / binutils-2.25 / gas / doc / c-xtensa.texi
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.
4 @c
5 @c man end
6 @ifset GENERIC
7 @page
8 @node Xtensa-Dependent
9 @chapter Xtensa Dependent Features
10 @end ifset
11 @ifclear GENERIC
12 @node Machine Dependencies
13 @chapter Xtensa Dependent Features
14 @end ifclear
15
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)
20 Reference Manual}.
21
22 @menu
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.
28 @end menu
29
30 @node Xtensa Options
31 @section Command Line Options
32
33 @c man begin OPTIONS
34 @table @gcctabopt
35
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}.
50
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
58 can be used.
59
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.
68
69 @item --longcalls | --no-longcalls
70 @kindex --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}.
79
80 @item --transform | --no-transform
81 @kindex --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.
89
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.
94
95 @item --trampolines | --no-trampolines
96 @kindex --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}.
104 @end table
105
106 @c man end
107
108 @node Xtensa Syntax
109 @section Assembler Syntax
110 @cindex syntax, Xtensa assembler
111 @cindex Xtensa assembler syntax
112 @cindex FLIX syntax
113
114 Block comments are delimited by @samp{/*} and @samp{*/}.  End of line
115 comments may be introduced with either @samp{#} or @samp{//}.
116
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}).
121
122 Instructions consist of a leading opcode or macro name followed by
123 whitespace and an optional comma-separated list of operands:
124
125 @smallexample
126 @var{opcode} [@var{operand}, @dots{}]
127 @end smallexample
128
129 Instructions must be separated by a newline or semicolon (@samp{;}).
130
131 FLIX instructions, which bundle multiple opcodes together in a single
132 instruction, are specified by enclosing the bundled opcodes inside
133 braces:
134
135 @smallexample
136 @group
137 @{
138 [@var{format}]
139 @var{opcode0} [@var{operands}]
140 @end group
141 @var{opcode1} [@var{operands}]
142 @group
143 @var{opcode2} [@var{operands}]
144 @dots{}
145 @}
146 @end group
147 @end smallexample
148
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:
159
160 @smallexample
161 @{ [@var{format};] @var{opcode0} [@var{operands}]; @var{opcode1} [@var{operands}]; @var{opcode2} [@var{operands}]; @dots{} @}
162 @end smallexample
163
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.
168
169 @menu
170 * Xtensa Opcodes::              Opcode Naming Conventions.
171 * Xtensa Registers::            Register Naming.
172 @end menu
173
174 @node Xtensa Opcodes
175 @subsection Opcode Names
176 @cindex Xtensa opcode names
177 @cindex opcode names, Xtensa
178
179 See the @cite{Xtensa Instruction Set Architecture (ISA) Reference
180 Manual} for a complete list of opcodes and descriptions of their
181 semantics.
182
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.
193
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}@.
201
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}.
209
210 @node Xtensa Registers
211 @subsection Register Names
212 @cindex Xtensa register names
213 @cindex register names, Xtensa
214 @cindex sp register
215
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.
224
225 @node Xtensa Optimizations
226 @section Xtensa Optimizations
227 @cindex optimizations
228
229 The optimizations currently supported by @command{@value{AS}} are
230 generation of density instructions where appropriate and automatic
231 branch target alignment.
232
233 @menu
234 * Density Instructions::        Using Density Instructions.
235 * Xtensa Automatic Alignment::  Automatic Instruction Alignment.
236 @end menu
237
238 @node Density Instructions
239 @subsection Using Density Instructions
240 @cindex density instructions
241
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}).
252
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.
257
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
264
265 The Xtensa assembler will automatically align certain instructions, both
266 to optimize performance and to satisfy architectural requirements.
267
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}).
279
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
286 instructions.
287 This approach is usually successful in aligning many, but not all,
288 branch targets.
289
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).
302
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.
306
307 @node Xtensa Relaxation
308 @section Xtensa Relaxation
309 @cindex relaxation
310
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
319 fields.
320
321 @menu
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.
326 @end menu
327
328 @node Xtensa Branch Relaxation
329 @subsection Conditional Branch Relaxation
330 @cindex relaxation of branch instructions
331 @cindex branch instructions, relaxation
332
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,
337
338 @smallexample
339     beqz    a2, L
340 @end smallexample
341
342 may result in:
343
344 @smallexample
345 @group
346     bnez.n  a2, M
347     j L
348 M:
349 @end group
350 @end smallexample
351
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.)
354
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.
361
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}).
367
368 @node Xtensa Call Relaxation
369 @subsection Function Call Relaxation
370 @cindex relaxation of call instructions
371 @cindex call instructions, relaxation
372
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:
383
384 @smallexample
385     call8 func
386 @end smallexample
387
388 might be relaxed to:
389
390 @smallexample
391 @group
392     .literal .L1, func
393     l32r    a8, .L1
394     callx8  a8
395 @end group
396 @end smallexample
397
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.
404
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}).
411
412 @node Xtensa Jump Relaxation
413 @subsection Jump Relaxation
414 @cindex relaxation of jump instructions
415 @cindex jump instructions, relaxation
416
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:
428
429 @smallexample
430 @group
431     j 1f
432     ...
433     retw
434     ...
435     mov a10, a2
436     call8 func
437     ...
438 1:
439     ...
440 @end group
441 @end smallexample
442
443 might be relaxed to:
444
445 @smallexample
446 @group
447     j .L0_TR_1
448     ...
449     retw
450 .L0_TR_1:
451     j 1f
452     ...
453     mov a10, a2
454     call8 func
455     ...
456 1:
457     ...
458 @end group
459 @end smallexample
460
461 or to:
462
463 @smallexample
464 @group
465     j .L0_TR_1
466     ...
467     retw
468     ...
469     mov a10, a2
470     j .L0_TR_0
471 .L0_TR_1:
472     j 1f
473 .L0_TR_0:
474     call8 func
475     ...
476 1:
477     ...
478 @end group
479 @end smallexample
480
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.
484
485 This relaxation does not apply to jumps to undefined symbols, assuming they
486 will reach their targets once resolved.
487
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}).
492
493 @node Xtensa Immediate Relaxation
494 @subsection Other Immediate Field Relaxation
495 @cindex immediate fields, relaxation
496 @cindex relaxation of immediate fields
497
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}).
503
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:
509
510 @smallexample
511     movi a0, 100000
512 @end smallexample
513
514 is assembled into the following machine code:
515
516 @smallexample
517 @group
518     .literal .L1, 100000
519     l32r a0, .L1
520 @end group
521 @end smallexample
522
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:
538
539 @smallexample
540     l32i a1, a0, 2040
541 @end smallexample
542
543 is translated to:
544
545 @smallexample
546 @group
547     .literal .L1, 2040
548     l32r a1, .L1
549 @end group
550 @group
551     add a1, a0, a1
552     l32i a1, a1, 0
553 @end group
554 @end smallexample
555
556 @noindent
557 If the load destination and source address register are the same, an
558 out-of-range offset causes an error.
559
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.
573
574 For example:
575
576 @smallexample
577 @group
578     addi    a5, a6, 0
579     addi    a5, a6, 512
580 @end group
581 @group
582     addi    a5, a6, 513
583     addi    a5, a6, 50000
584 @end group
585 @end smallexample
586
587 is assembled into the following:
588
589 @smallexample
590 @group
591     .literal .L1, 50000
592     mov.n   a5, a6
593 @end group
594     addmi   a5, a6, 0x200
595     addmi   a5, a6, 0x200
596     addi    a5, a5, 1
597 @group
598     l32r    a5, .L1
599     add     a5, a6, a5
600 @end group
601 @end smallexample
602
603 @node Xtensa Directives
604 @section Directives
605 @cindex Xtensa directives
606 @cindex directives, Xtensa
607
608 The Xtensa assembler supports a region-based directive syntax:
609
610 @smallexample
611 @group
612     .begin @var{directive} [@var{options}]
613     @dots{}
614     .end @var{directive}
615 @end group
616 @end smallexample
617
618 All the Xtensa-specific directives that apply to a region of code use
619 this syntax.
620
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:
627
628 @smallexample
629 @group
630     .begin no-transform
631 L:  add a0, a1, a2
632 @end group
633     .begin transform
634 M:  add a0, a1, a2
635     .end transform
636 @group
637 N:  add a0, a1, a2
638     .end no-transform
639 @end group
640 @end smallexample
641
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.
646
647 The advantage of this style is that it works well inside macros which can
648 preserve the context of their callers.
649
650 The following directives are available:
651 @menu
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.
659 @end menu
660
661 @node Schedule Directive
662 @subsection schedule
663 @cindex @code{schedule} directive
664 @cindex @code{no-schedule} directive
665
666 The @code{schedule} directive is recognized only for compatibility with
667 Tensilica's assembler.
668
669 @smallexample
670 @group
671     .begin [no-]schedule
672     .end [no-]schedule
673 @end group
674 @end smallexample
675
676 This directive is ignored and has no effect on @command{@value{AS}}.
677
678 @node Longcalls Directive
679 @subsection longcalls
680 @cindex @code{longcalls} directive
681 @cindex @code{no-longcalls} directive
682
683 The @code{longcalls} directive enables or disables function call
684 relaxation.  @xref{Xtensa Call Relaxation, ,Function Call Relaxation}.
685
686 @smallexample
687 @group
688     .begin [no-]longcalls
689     .end [no-]longcalls
690 @end group
691 @end smallexample
692
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.
696
697 @node Transform Directive
698 @subsection transform
699 @cindex @code{transform} directive
700 @cindex @code{no-transform} directive
701
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}).
705
706 @smallexample
707 @group
708     .begin [no-]transform
709     .end [no-]transform
710 @end group
711 @end smallexample
712
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.
718
719 @node Literal Directive
720 @subsection literal
721 @cindex @code{literal} directive
722
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.
725
726 @smallexample
727     .literal @var{label}, @var{value}[, @var{value}@dots{}]
728 @end smallexample
729
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:
736
737 @smallexample
738 @group
739     entry sp, 40
740     .literal .L1, sym
741     l32r    a4, .L1
742 @end group
743 @end smallexample
744
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.
749
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.
764
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:
775
776 @enumerate
777 @item
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
782 group.
783
784 @item
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}.
791
792 @item
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}.
798
799 @item
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).
803 @end enumerate
804
805 @node Literal Position Directive
806 @subsection literal_position
807 @cindex @code{literal_position} directive
808
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.
812
813 @smallexample
814     .literal_position
815 @end smallexample
816
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.
820
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
825 inline literal pool.
826
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.
838
839 @smallexample
840 @group
841     .global M
842 code_start:
843 @end group
844     j continue
845     .literal_position
846     .align 4
847 @group
848 continue:
849     movi    a4, M
850 @end group
851 @end smallexample
852
853 @node Literal Prefix Directive
854 @subsection literal_prefix
855 @cindex @code{literal_prefix} directive
856
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.
860
861 @smallexample
862 @group
863     .begin literal_prefix [@var{name}]
864     .end literal_prefix
865 @end group
866 @end smallexample
867
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}).
876
877 @node Absolute Literals Directive
878 @subsection absolute-literals
879 @cindex @code{absolute-literals} directive
880 @cindex @code{no-absolute-literals} directive
881
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.
886
887 @smallexample
888 @group
889     .begin [no-]absolute-literals
890     .end [no-]absolute-literals
891 @end group
892 @end smallexample
893
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.
901
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.
908
909 @c Local Variables:
910 @c fill-column: 72
911 @c End: