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