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