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