| 1 | @c Copyright (C) 2002 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 | @ifset GENERIC |
| 6 | @page |
| 7 | @node Xtensa-Dependent |
| 8 | @chapter Xtensa Dependent Features |
| 9 | @end ifset |
| 10 | @ifclear GENERIC |
| 11 | @node Machine Dependencies |
| 12 | @chapter Xtensa Dependent Features |
| 13 | @end ifclear |
| 14 | |
| 15 | @cindex Xtensa architecture |
| 16 | This chapter covers features of the @sc{gnu} assembler that are specific |
| 17 | to the Xtensa architecture. For details about the Xtensa instruction |
| 18 | set, please consult the @cite{Xtensa Instruction Set Architecture (ISA) |
| 19 | Reference Manual}. |
| 20 | |
| 21 | @menu |
| 22 | * Xtensa Options:: Command-line Options. |
| 23 | * Xtensa Syntax:: Assembler Syntax for Xtensa Processors. |
| 24 | * Xtensa Optimizations:: Assembler Optimizations. |
| 25 | * Xtensa Relaxation:: Other Automatic Transformations. |
| 26 | * Xtensa Directives:: Directives for Xtensa Processors. |
| 27 | @end menu |
| 28 | |
| 29 | @node Xtensa Options |
| 30 | @section Command Line Options |
| 31 | |
| 32 | The Xtensa version of the @sc{gnu} assembler supports these |
| 33 | special options: |
| 34 | |
| 35 | @table @code |
| 36 | @item --density | --no-density |
| 37 | @kindex --density |
| 38 | @kindex --no-density |
| 39 | @cindex Xtensa density option |
| 40 | @cindex density option, Xtensa |
| 41 | Enable or disable use of the Xtensa code density option (16-bit |
| 42 | instructions). @xref{Density Instructions, ,Using Density |
| 43 | Instructions}. If the processor is configured with the density option, |
| 44 | this is enabled by default; otherwise, it is always disabled. |
| 45 | |
| 46 | @item --relax | --no-relax |
| 47 | @kindex --relax |
| 48 | @kindex --no-relax |
| 49 | Enable or disable relaxation of instructions with immediate operands |
| 50 | that are outside the legal range for the instructions. @xref{Xtensa |
| 51 | Relaxation, ,Xtensa Relaxation}. The default is @samp{--relax} and this |
| 52 | default should almost always be used. If relaxation is disabled with |
| 53 | @samp{--no-relax}, instruction operands that are out of range will cause |
| 54 | errors. Note: In the current implementation, these options also control |
| 55 | whether assembler optimizations are performed, making these options |
| 56 | equivalent to @samp{--generics} and @samp{--no-generics}. |
| 57 | |
| 58 | @item --generics | --no-generics |
| 59 | @kindex --generics |
| 60 | @kindex --no-generics |
| 61 | Enable or disable all assembler transformations of Xtensa instructions, |
| 62 | including both relaxation and optimization. The default is |
| 63 | @samp{--generics}; @samp{--no-generics} should only be used in the rare |
| 64 | cases when the instructions must be exactly as specified in the assembly |
| 65 | source. |
| 66 | @c The @samp{--no-generics} option is like @samp{--no-relax} |
| 67 | @c except that it also disables assembler optimizations (@pxref{Xtensa |
| 68 | @c Optimizations}). |
| 69 | As with @samp{--no-relax}, using @samp{--no-generics} |
| 70 | causes out of range instruction operands to be errors. |
| 71 | |
| 72 | @item --text-section-literals | --no-text-section-literals |
| 73 | @kindex --text-section-literals |
| 74 | @kindex --no-text-section-literals |
| 75 | Control the treatment of literal pools. The default is |
| 76 | @samp{--no-@-text-@-section-@-literals}, which places literals in a |
| 77 | separate section in the output file. This allows the literal pool to be |
| 78 | placed in a data RAM/ROM, and it also allows the linker to combine literal |
| 79 | pools from separate object files to remove redundant literals and |
| 80 | improve code size. With @samp{--text-@-section-@-literals}, the |
| 81 | literals are interspersed in the text section in order to keep them as |
| 82 | close as possible to their references. This may be necessary for large |
| 83 | assembly files. |
| 84 | |
| 85 | @item --target-align | --no-target-align |
| 86 | @kindex --target-align |
| 87 | @kindex --no-target-align |
| 88 | Enable or disable automatic alignment to reduce branch penalties at some |
| 89 | expense in code size. @xref{Xtensa Automatic Alignment, ,Automatic |
| 90 | Instruction Alignment}. This optimization is enabled by default. Note |
| 91 | that the assembler will always align instructions like @code{LOOP} that |
| 92 | have fixed alignment requirements. |
| 93 | |
| 94 | @item --longcalls | --no-longcalls |
| 95 | @kindex --longcalls |
| 96 | @kindex --no-longcalls |
| 97 | Enable or disable transformation of call instructions to allow calls |
| 98 | across a greater range of addresses. @xref{Xtensa Call Relaxation, |
| 99 | ,Function Call Relaxation}. This option should be used when call |
| 100 | targets can potentially be out of range, but it degrades both code size |
| 101 | and performance. The default is @samp{--no-@-longcalls}. |
| 102 | @end table |
| 103 | |
| 104 | @node Xtensa Syntax |
| 105 | @section Assembler Syntax |
| 106 | @cindex syntax, Xtensa assembler |
| 107 | @cindex Xtensa assembler syntax |
| 108 | |
| 109 | Block comments are delimited by @samp{/*} and @samp{*/}. End of line |
| 110 | comments may be introduced with either @samp{#} or @samp{//}. |
| 111 | |
| 112 | Instructions consist of a leading opcode or macro name followed by |
| 113 | whitespace and an optional comma-separated list of operands: |
| 114 | |
| 115 | @smallexample |
| 116 | @var{opcode} [@var{operand},@dots{}] |
| 117 | @end smallexample |
| 118 | |
| 119 | Instructions must be separated by a newline or semicolon. |
| 120 | |
| 121 | @menu |
| 122 | * Xtensa Opcodes:: Opcode Naming Conventions. |
| 123 | * Xtensa Registers:: Register Naming. |
| 124 | @end menu |
| 125 | |
| 126 | @node Xtensa Opcodes |
| 127 | @subsection Opcode Names |
| 128 | @cindex Xtensa opcode names |
| 129 | @cindex opcode names, Xtenxa |
| 130 | |
| 131 | See the @cite{Xtensa Instruction Set Architecture (ISA) Reference |
| 132 | Manual} for a complete list of opcodes and descriptions of their |
| 133 | semantics. |
| 134 | |
| 135 | @cindex generic opcodes |
| 136 | @cindex specific opcodes |
| 137 | @cindex _ opcode prefix |
| 138 | The Xtensa assembler distinguishes between @dfn{generic} and |
| 139 | @dfn{specific} opcodes. Specific opcodes correspond directly to Xtensa |
| 140 | machine instructions. Prefixing an opcode with an underscore character |
| 141 | (@samp{_}) identifies it as a specific opcode. Opcodes without a |
| 142 | leading underscore are generic, which means the assembler is required to |
| 143 | preserve their semantics but may not translate them directly to the |
| 144 | specific opcodes with the same names. Instead, the assembler may |
| 145 | optimize a generic opcode and select a better instruction to use in its |
| 146 | place (@pxref{Xtensa Optimizations, ,Xtensa Optimizations}), or the |
| 147 | assembler may relax the instruction to handle operands that are out of |
| 148 | range for the corresponding specific opcode (@pxref{Xtensa Relaxation, |
| 149 | ,Xtensa Relaxation}). |
| 150 | |
| 151 | Only use specific opcodes when it is essential to select |
| 152 | the exact machine instructions produced by the assembler. |
| 153 | Using specific opcodes unnecessarily only makes the code less |
| 154 | efficient, by disabling assembler optimization, and less flexible, by |
| 155 | disabling relaxation. |
| 156 | |
| 157 | Note that this special handling of underscore prefixes only applies to |
| 158 | Xtensa opcodes, not to either built-in macros or user-defined macros. |
| 159 | When an underscore prefix is used with a macro (e.g., @code{_NOP}), it |
| 160 | refers to a different macro. The assembler generally provides built-in |
| 161 | macros both with and without the underscore prefix, where the underscore |
| 162 | versions behave as if the underscore carries through to the instructions |
| 163 | in the macros. For example, @code{_NOP} expands to @code{_OR a1,a1,a1}. |
| 164 | |
| 165 | The underscore prefix only applies to individual instructions, not to |
| 166 | series of instructions. For example, if a series of instructions have |
| 167 | underscore prefixes, the assembler will not transform the individual |
| 168 | instructions, but it may insert other instructions between them (e.g., |
| 169 | to align a @code{LOOP} instruction). To prevent the assembler from |
| 170 | modifying a series of instructions as a whole, use the |
| 171 | @code{no-generics} directive. @xref{Generics Directive, ,generics}. |
| 172 | |
| 173 | @node Xtensa Registers |
| 174 | @subsection Register Names |
| 175 | @cindex Xtensa register names |
| 176 | @cindex register names, Xtensa |
| 177 | @cindex sp register |
| 178 | |
| 179 | An initial @samp{$} character is optional in all register names. |
| 180 | General purpose registers are named @samp{a0}@dots{}@samp{a15}. Additional |
| 181 | registers may be added by processor configuration options. In |
| 182 | particular, the @sc{mac16} option adds a @sc{mr} register bank. Its |
| 183 | registers are named @samp{m0}@dots{}@samp{m3}. |
| 184 | |
| 185 | As a special feature, @samp{sp} is also supported as a synonym for |
| 186 | @samp{a1}. |
| 187 | |
| 188 | @node Xtensa Optimizations |
| 189 | @section Xtensa Optimizations |
| 190 | @cindex optimizations |
| 191 | |
| 192 | The optimizations currently supported by @code{@value{AS}} are |
| 193 | generation of density instructions where appropriate and automatic |
| 194 | branch target alignment. |
| 195 | |
| 196 | @menu |
| 197 | * Density Instructions:: Using Density Instructions. |
| 198 | * Xtensa Automatic Alignment:: Automatic Instruction Alignment. |
| 199 | @end menu |
| 200 | |
| 201 | @node Density Instructions |
| 202 | @subsection Using Density Instructions |
| 203 | @cindex density instructions |
| 204 | |
| 205 | The Xtensa instruction set has a code density option that provides |
| 206 | 16-bit versions of some of the most commonly used opcodes. Use of these |
| 207 | opcodes can significantly reduce code size. When possible, the |
| 208 | assembler automatically translates generic instructions from the core |
| 209 | Xtensa instruction set into equivalent instructions from the Xtensa code |
| 210 | density option. This translation can be disabled by using specific |
| 211 | opcodes (@pxref{Xtensa Opcodes, ,Opcode Names}), by using the |
| 212 | @samp{--no-density} command-line option (@pxref{Xtensa Options, ,Command |
| 213 | Line Options}), or by using the @code{no-density} directive |
| 214 | (@pxref{Density Directive, ,density}). |
| 215 | |
| 216 | It is a good idea @emph{not} to use the density instructions directly. |
| 217 | The assembler will automatically select dense instructions where |
| 218 | possible. If you later need to avoid using the code density option, you |
| 219 | can disable it in the assembler without having to modify the code. |
| 220 | |
| 221 | @node Xtensa Automatic Alignment |
| 222 | @subsection Automatic Instruction Alignment |
| 223 | @cindex alignment of @code{LOOP} instructions |
| 224 | @cindex alignment of @code{ENTRY} instructions |
| 225 | @cindex alignment of branch targets |
| 226 | @cindex @code{LOOP} instructions, alignment |
| 227 | @cindex @code{ENTRY} instructions, alignment |
| 228 | @cindex branch target alignment |
| 229 | |
| 230 | The Xtensa assembler will automatically align certain instructions, both |
| 231 | to optimize performance and to satisfy architectural requirements. |
| 232 | |
| 233 | When the @code{--target-@-align} command-line option is enabled |
| 234 | (@pxref{Xtensa Options, ,Command Line Options}), the assembler attempts |
| 235 | to widen density instructions preceding a branch target so that the |
| 236 | target instruction does not cross a 4-byte boundary. Similarly, the |
| 237 | assembler also attempts to align each instruction following a call |
| 238 | instruction. If there are not enough preceding safe density |
| 239 | instructions to align a target, no widening will be performed. This |
| 240 | alignment has the potential to reduce branch penalties at some expense |
| 241 | in code size. The assembler will not attempt to align labels with the |
| 242 | prefixes @code{.Ln} and @code{.LM}, since these labels are used for |
| 243 | debugging information and are not typically branch targets. |
| 244 | |
| 245 | The @code{LOOP} family of instructions must be aligned on either a 1 or |
| 246 | 2 mod 4 byte boundary. The assembler knows about this restriction and |
| 247 | inserts the minimal number of 2 or 3 byte no-op instructions |
| 248 | to satisfy it. When no-op instructions are added, any label immediately |
| 249 | preceding the original loop will be moved in order to refer to the loop |
| 250 | instruction, not the newly generated no-op instruction. |
| 251 | |
| 252 | Similarly, the @code{ENTRY} instruction must be aligned on a 0 mod 4 |
| 253 | byte boundary. The assembler satisfies this requirement by inserting |
| 254 | zero bytes when required. In addition, labels immediately preceding the |
| 255 | @code{ENTRY} instruction will be moved to the newly aligned instruction |
| 256 | location. |
| 257 | |
| 258 | @node Xtensa Relaxation |
| 259 | @section Xtensa Relaxation |
| 260 | @cindex relaxation |
| 261 | |
| 262 | When an instruction operand is outside the range allowed for that |
| 263 | particular instruction field, @code{@value{AS}} can transform the code |
| 264 | to use a functionally-equivalent instruction or sequence of |
| 265 | instructions. This process is known as @dfn{relaxation}. This is |
| 266 | typically done for branch instructions because the distance of the |
| 267 | branch targets is not known until assembly-time. The Xtensa assembler |
| 268 | offers branch relaxation and also extends this concept to function |
| 269 | calls, @code{MOVI} instructions and other instructions with immediate |
| 270 | fields. |
| 271 | |
| 272 | @menu |
| 273 | * Xtensa Branch Relaxation:: Relaxation of Branches. |
| 274 | * Xtensa Call Relaxation:: Relaxation of Function Calls. |
| 275 | * Xtensa Immediate Relaxation:: Relaxation of other Immediate Fields. |
| 276 | @end menu |
| 277 | |
| 278 | @node Xtensa Branch Relaxation |
| 279 | @subsection Conditional Branch Relaxation |
| 280 | @cindex relaxation of branch instructions |
| 281 | @cindex branch instructions, relaxation |
| 282 | |
| 283 | When the target of a branch is too far away from the branch itself, |
| 284 | i.e., when the offset from the branch to the target is too large to fit |
| 285 | in the immediate field of the branch instruction, it may be necessary to |
| 286 | replace the branch with a branch around a jump. For example, |
| 287 | |
| 288 | @smallexample |
| 289 | beqz a2, L |
| 290 | @end smallexample |
| 291 | |
| 292 | may result in: |
| 293 | |
| 294 | @smallexample |
| 295 | bnez.n a2, M |
| 296 | j L |
| 297 | M: |
| 298 | @end smallexample |
| 299 | |
| 300 | (The @code{BNEZ.N} instruction would be used in this example only if the |
| 301 | density option is available. Otherwise, @code{BNEZ} would be used.) |
| 302 | |
| 303 | @node Xtensa Call Relaxation |
| 304 | @subsection Function Call Relaxation |
| 305 | @cindex relaxation of call instructions |
| 306 | @cindex call instructions, relaxation |
| 307 | |
| 308 | Function calls may require relaxation because the Xtensa immediate call |
| 309 | instructions (@code{CALL0}, @code{CALL4}, @code{CALL8} and |
| 310 | @code{CALL12}) provide a PC-relative offset of only 512 Kbytes in either |
| 311 | direction. For larger programs, it may be necessary to use indirect |
| 312 | calls (@code{CALLX0}, @code{CALLX4}, @code{CALLX8} and @code{CALLX12}) |
| 313 | where the target address is specified in a register. The Xtensa |
| 314 | assembler can automatically relax immediate call instructions into |
| 315 | indirect call instructions. This relaxation is done by loading the |
| 316 | address of the called function into the callee's return address register |
| 317 | and then using a @code{CALLX} instruction. So, for example: |
| 318 | |
| 319 | @smallexample |
| 320 | call8 func |
| 321 | @end smallexample |
| 322 | |
| 323 | might be relaxed to: |
| 324 | |
| 325 | @smallexample |
| 326 | .literal .L1, func |
| 327 | l32r a8, .L1 |
| 328 | callx8 a8 |
| 329 | @end smallexample |
| 330 | |
| 331 | Because the addresses of targets of function calls are not generally |
| 332 | known until link-time, the assembler must assume the worst and relax all |
| 333 | the calls to functions in other source files, not just those that really |
| 334 | will be out of range. The linker can recognize calls that were |
| 335 | unnecessarily relaxed, but it can only partially remove the overhead |
| 336 | introduced by the assembler. |
| 337 | |
| 338 | Call relaxation has a negative effect |
| 339 | on both code size and performance, so this relaxation is disabled by |
| 340 | default. If a program is too large and some of the calls are out of |
| 341 | range, function call relaxation can be enabled using the |
| 342 | @samp{--longcalls} command-line option or the @code{longcalls} directive |
| 343 | (@pxref{Longcalls Directive, ,longcalls}). |
| 344 | |
| 345 | @node Xtensa Immediate Relaxation |
| 346 | @subsection Other Immediate Field Relaxation |
| 347 | @cindex immediate fields, relaxation |
| 348 | @cindex relaxation of immediate fields |
| 349 | |
| 350 | @cindex @code{MOVI} instructions, relaxation |
| 351 | @cindex relaxation of @code{MOVI} instructions |
| 352 | The @code{MOVI} machine instruction can only materialize values in the |
| 353 | range from -2048 to 2047. Values outside this range are best |
| 354 | materialized with @code{L32R} instructions. Thus: |
| 355 | |
| 356 | @smallexample |
| 357 | movi a0, 100000 |
| 358 | @end smallexample |
| 359 | |
| 360 | is assembled into the following machine code: |
| 361 | |
| 362 | @smallexample |
| 363 | .literal .L1, 100000 |
| 364 | l32r a0, .L1 |
| 365 | @end smallexample |
| 366 | |
| 367 | @cindex @code{L8UI} instructions, relaxation |
| 368 | @cindex @code{L16SI} instructions, relaxation |
| 369 | @cindex @code{L16UI} instructions, relaxation |
| 370 | @cindex @code{L32I} instructions, relaxation |
| 371 | @cindex relaxation of @code{L8UI} instructions |
| 372 | @cindex relaxation of @code{L16SI} instructions |
| 373 | @cindex relaxation of @code{L16UI} instructions |
| 374 | @cindex relaxation of @code{L32I} instructions |
| 375 | The @code{L8UI} machine instruction can only be used with immediate |
| 376 | offsets in the range from 0 to 255. The @code{L16SI} and @code{L16UI} |
| 377 | machine instructions can only be used with offsets from 0 to 510. The |
| 378 | @code{L32I} machine instruction can only be used with offsets from 0 to |
| 379 | 1020. A load offset outside these ranges can be materalized with |
| 380 | an @code{L32R} instruction if the destination register of the load |
| 381 | is different than the source address register. For example: |
| 382 | |
| 383 | @smallexample |
| 384 | l32i a1, a0, 2040 |
| 385 | @end smallexample |
| 386 | |
| 387 | is translated to: |
| 388 | |
| 389 | @smallexample |
| 390 | .literal .L1, 2040 |
| 391 | l32r a1, .L1 |
| 392 | addi a1, a0, a1 |
| 393 | l32i a1, a1, 0 |
| 394 | @end smallexample |
| 395 | |
| 396 | @noindent |
| 397 | If the load destination and source address register are the same, an |
| 398 | out-of-range offset causes an error. |
| 399 | |
| 400 | @cindex @code{ADDI} instructions, relaxation |
| 401 | @cindex relaxation of @code{ADDI} instructions |
| 402 | The Xtensa @code{ADDI} instruction only allows immediate operands in the |
| 403 | range from -128 to 127. There are a number of alternate instruction |
| 404 | sequences for the generic @code{ADDI} operation. First, if the |
| 405 | immediate is 0, the @code{ADDI} will be turned into a @code{MOV.N} |
| 406 | instruction (or the equivalent @code{OR} instruction if the code density |
| 407 | option is not available). If the @code{ADDI} immediate is outside of |
| 408 | the range -128 to 127, but inside the range -32896 to 32639, an |
| 409 | @code{ADDMI} instruction or @code{ADDMI}/@code{ADDI} sequence will be |
| 410 | used. Finally, if the immediate is outside of this range and a free |
| 411 | register is available, an @code{L32R}/@code{ADD} sequence will be used |
| 412 | with a literal allocated from the literal pool. |
| 413 | |
| 414 | For example: |
| 415 | |
| 416 | @smallexample |
| 417 | addi a5, a6, 0 |
| 418 | addi a5, a6, 512 |
| 419 | addi a5, a6, 513 |
| 420 | addi a5, a6, 50000 |
| 421 | @end smallexample |
| 422 | |
| 423 | is assembled into the following: |
| 424 | |
| 425 | @smallexample |
| 426 | .literal .L1, 50000 |
| 427 | mov.n a5, a6 |
| 428 | addmi a5, a6, 0x200 |
| 429 | addmi a5, a6, 0x200 |
| 430 | addi a5, a5, 1 |
| 431 | l32r a5, .L1 |
| 432 | add a5, a6, a5 |
| 433 | @end smallexample |
| 434 | |
| 435 | @node Xtensa Directives |
| 436 | @section Directives |
| 437 | @cindex Xtensa directives |
| 438 | @cindex directives, Xtensa |
| 439 | |
| 440 | The Xtensa assember supports a region-based directive syntax: |
| 441 | |
| 442 | @smallexample |
| 443 | .begin @var{directive} [@var{options}] |
| 444 | @dots{} |
| 445 | .end @var{directive} |
| 446 | @end smallexample |
| 447 | |
| 448 | All the Xtensa-specific directives that apply to a region of code use |
| 449 | this syntax. |
| 450 | |
| 451 | The directive applies to code between the @code{.begin} and the |
| 452 | @code{.end}. The state of the option after the @code{.end} reverts to |
| 453 | what it was before the @code{.begin}. |
| 454 | A nested @code{.begin}/@code{.end} region can further |
| 455 | change the state of the directive without having to be aware of its |
| 456 | outer state. For example, consider: |
| 457 | |
| 458 | @smallexample |
| 459 | .begin no-density |
| 460 | L: add a0, a1, a2 |
| 461 | .begin density |
| 462 | M: add a0, a1, a2 |
| 463 | .end density |
| 464 | N: add a0, a1, a2 |
| 465 | .end no-density |
| 466 | @end smallexample |
| 467 | |
| 468 | The generic @code{ADD} opcodes at @code{L} and @code{N} in the outer |
| 469 | @code{no-density} region both result in @code{ADD} machine instructions, |
| 470 | but the assembler selects an @code{ADD.N} instruction for the generic |
| 471 | @code{ADD} at @code{M} in the inner @code{density} region. |
| 472 | |
| 473 | The advantage of this style is that it works well inside macros which can |
| 474 | preserve the context of their callers. |
| 475 | |
| 476 | @cindex precedence of directives |
| 477 | @cindex directives, precedence |
| 478 | When command-line options and assembler directives are used at the same |
| 479 | time and conflict, the one that overrides a default behavior takes |
| 480 | precedence over one that is the same as the default. For example, if |
| 481 | the code density option is available, the default is to select density |
| 482 | instructions whenever possible. So, if the above is assembled with the |
| 483 | @samp{--no-density} flag, which overrides the default, all the generic |
| 484 | @code{ADD} instructions result in @code{ADD} machine instructions. If |
| 485 | assembled with the @samp{--density} flag, which is already the default, |
| 486 | the @code{no-density} directive takes precedence and only one of |
| 487 | the generic @code{ADD} instructions is optimized to be a @code{ADD.N} |
| 488 | machine instruction. An underscore prefix identifying a specific opcode |
| 489 | always takes precedence over directives and command-line flags. |
| 490 | |
| 491 | The following directives are available: |
| 492 | @menu |
| 493 | * Density Directive:: Disable Use of Density Instructions. |
| 494 | * Relax Directive:: Disable Assembler Relaxation. |
| 495 | * Longcalls Directive:: Use Indirect Calls for Greater Range. |
| 496 | * Generics Directive:: Disable All Assembler Transformations. |
| 497 | * Literal Directive:: Intermix Literals with Instructions. |
| 498 | * Literal Position Directive:: Specify Inline Literal Pool Locations. |
| 499 | * Literal Prefix Directive:: Specify Literal Section Name Prefix. |
| 500 | * Freeregs Directive:: List Registers Available for Assembler Use. |
| 501 | * Frame Directive:: Describe a stack frame. |
| 502 | @end menu |
| 503 | |
| 504 | @node Density Directive |
| 505 | @subsection density |
| 506 | @cindex @code{density} directive |
| 507 | @cindex @code{no-density} directive |
| 508 | |
| 509 | The @code{density} and @code{no-density} directives enable or disable |
| 510 | optimization of generic instructions into density instructions within |
| 511 | the region. @xref{Density Instructions, ,Using Density Instructions}. |
| 512 | |
| 513 | @smallexample |
| 514 | .begin [no-]density |
| 515 | .end [no-]density |
| 516 | @end smallexample |
| 517 | |
| 518 | This optimization is enabled by default unless the Xtensa configuration |
| 519 | does not support the code density option or the @samp{--no-density} |
| 520 | command-line option was specified. |
| 521 | |
| 522 | @node Relax Directive |
| 523 | @subsection relax |
| 524 | @cindex @code{relax} directive |
| 525 | @cindex @code{no-relax} directive |
| 526 | |
| 527 | The @code{relax} directive enables or disables relaxation |
| 528 | within the region. @xref{Xtensa Relaxation, ,Xtensa Relaxation}. |
| 529 | Note: In the current implementation, these directives also control |
| 530 | whether assembler optimizations are performed, making them equivalent to |
| 531 | the @code{generics} and @code{no-generics} directives. |
| 532 | |
| 533 | @smallexample |
| 534 | .begin [no-]relax |
| 535 | .end [no-]relax |
| 536 | @end smallexample |
| 537 | |
| 538 | Relaxation is enabled by default unless the @samp{--no-relax} |
| 539 | command-line option was specified. |
| 540 | |
| 541 | @node Longcalls Directive |
| 542 | @subsection longcalls |
| 543 | @cindex @code{longcalls} directive |
| 544 | @cindex @code{no-longcalls} directive |
| 545 | |
| 546 | The @code{longcalls} directive enables or disables function call |
| 547 | relaxation. @xref{Xtensa Call Relaxation, ,Function Call Relaxation}. |
| 548 | |
| 549 | @smallexample |
| 550 | .begin [no-]longcalls |
| 551 | .end [no-]longcalls |
| 552 | @end smallexample |
| 553 | |
| 554 | Call relaxation is disabled by default unless the @samp{--longcalls} |
| 555 | command-line option is specified. |
| 556 | |
| 557 | @node Generics Directive |
| 558 | @subsection generics |
| 559 | @cindex @code{generics} directive |
| 560 | @cindex @code{no-generics} directive |
| 561 | |
| 562 | This directive enables or disables all assembler transformation, |
| 563 | including relaxation (@pxref{Xtensa Relaxation, ,Xtensa Relaxation}) and |
| 564 | optimization (@pxref{Xtensa Optimizations, ,Xtensa Optimizations}). |
| 565 | |
| 566 | @smallexample |
| 567 | .begin [no-]generics |
| 568 | .end [no-]generics |
| 569 | @end smallexample |
| 570 | |
| 571 | Disabling generics is roughly equivalent to adding an underscore prefix |
| 572 | to every opcode within the region, so that every opcode is treated as a |
| 573 | specific opcode. @xref{Xtensa Opcodes, ,Opcode Names}. In the current |
| 574 | implementation of @code{@value{AS}}, built-in macros are also disabled |
| 575 | within a @code{no-generics} region. |
| 576 | |
| 577 | @node Literal Directive |
| 578 | @subsection literal |
| 579 | @cindex @code{literal} directive |
| 580 | |
| 581 | The @code{.literal} directive is used to define literal pool data, i.e., |
| 582 | read-only 32-bit data accessed via @code{L32R} instructions. |
| 583 | |
| 584 | @smallexample |
| 585 | .literal @var{label}, @var{value}[, @var{value}@dots{}] |
| 586 | @end smallexample |
| 587 | |
| 588 | This directive is similar to the standard @code{.word} directive, except |
| 589 | that the actual location of the literal data is determined by the |
| 590 | assembler and linker, not by the position of the @code{.literal} |
| 591 | directive. Using this directive gives the assembler freedom to locate |
| 592 | the literal data in the most appropriate place and possibly to combine |
| 593 | identical literals. For example, the code: |
| 594 | |
| 595 | @smallexample |
| 596 | entry sp, 40 |
| 597 | .literal .L1, sym |
| 598 | l32r a4, .L1 |
| 599 | @end smallexample |
| 600 | |
| 601 | can be used to load a pointer to the symbol @code{sym} into register |
| 602 | @code{a4}. The value of @code{sym} will not be placed between the |
| 603 | @code{ENTRY} and @code{L32R} instructions; instead, the assembler puts |
| 604 | the data in a literal pool. |
| 605 | |
| 606 | By default literal pools are placed in a separate section; however, when |
| 607 | using the @samp{--text-@-section-@-literals} option (@pxref{Xtensa |
| 608 | Options, ,Command Line Options}), the literal pools are placed in the |
| 609 | current section. These text section literal pools are created |
| 610 | automatically before @code{ENTRY} instructions and manually after |
| 611 | @samp{.literal_position} directives (@pxref{Literal Position Directive, |
| 612 | ,literal_position}). If there are no preceding @code{ENTRY} |
| 613 | instructions or @code{.literal_position} directives, the assembler will |
| 614 | print a warning and place the literal pool at the beginning of the |
| 615 | current section. In such cases, explicit @code{.literal_position} |
| 616 | directives should be used to place the literal pools. |
| 617 | |
| 618 | @node Literal Position Directive |
| 619 | @subsection literal_position |
| 620 | @cindex @code{literal_position} directive |
| 621 | |
| 622 | When using @samp{--text-@-section-@-literals} to place literals inline |
| 623 | in the section being assembled, the @code{.literal_position} directive |
| 624 | can be used to mark a potential location for a literal pool. |
| 625 | |
| 626 | @smallexample |
| 627 | .literal_position |
| 628 | @end smallexample |
| 629 | |
| 630 | The @code{.literal_position} directive is ignored when the |
| 631 | @samp{--text-@-section-@-literals} option is not used. |
| 632 | |
| 633 | The assembler will automatically place text section literal pools |
| 634 | before @code{ENTRY} instructions, so the @code{.literal_position} |
| 635 | directive is only needed to specify some other location for a literal |
| 636 | pool. You may need to add an explicit jump instruction to skip over an |
| 637 | inline literal pool. |
| 638 | |
| 639 | For example, an interrupt vector does not begin with an @code{ENTRY} |
| 640 | instruction so the assembler will be unable to automatically find a good |
| 641 | place to put a literal pool. Moreover, the code for the interrupt |
| 642 | vector must be at a specific starting address, so the literal pool |
| 643 | cannot come before the start of the code. The literal pool for the |
| 644 | vector must be explicitly positioned in the middle of the vector (before |
| 645 | any uses of the literals, of course). The @code{.literal_position} |
| 646 | directive can be used to do this. In the following code, the literal |
| 647 | for @samp{M} will automatically be aligned correctly and is placed after |
| 648 | the unconditional jump. |
| 649 | |
| 650 | @smallexample |
| 651 | .global M |
| 652 | code_start: |
| 653 | j continue |
| 654 | .literal_position |
| 655 | .align 4 |
| 656 | continue: |
| 657 | movi a4, M |
| 658 | @end smallexample |
| 659 | |
| 660 | @node Literal Prefix Directive |
| 661 | @subsection literal_prefix |
| 662 | @cindex @code{literal_prefix} directive |
| 663 | |
| 664 | The @code{literal_prefix} directive allows you to specify different |
| 665 | sections to hold literals from different portions of an assembly file. |
| 666 | With this directive, a single assembly file can be used to generate code |
| 667 | into multiple sections, including literals generated by the assembler. |
| 668 | |
| 669 | @smallexample |
| 670 | .begin literal_prefix [@var{name}] |
| 671 | .end literal_prefix |
| 672 | @end smallexample |
| 673 | |
| 674 | For the code inside the delimited region, the assembler puts literals in |
| 675 | the section @code{@var{name}.literal}. If this section does not yet |
| 676 | exist, the assembler creates it. The @var{name} parameter is |
| 677 | optional. If @var{name} is not specified, the literal prefix is set to |
| 678 | the ``default'' for the file. This default is usually @code{.literal} |
| 679 | but can be changed with the @samp{--rename-section} command-line |
| 680 | argument. |
| 681 | |
| 682 | @node Freeregs Directive |
| 683 | @subsection freeregs |
| 684 | @cindex @code{freeregs} directive |
| 685 | |
| 686 | This directive tells the assembler that the given registers are unused |
| 687 | in the region. |
| 688 | |
| 689 | @smallexample |
| 690 | .begin freeregs @var{ri}[,@var{ri}@dots{}] |
| 691 | .end freeregs |
| 692 | @end smallexample |
| 693 | |
| 694 | This allows the assembler to use these registers for relaxations or |
| 695 | optimizations. (They are actually only for relaxations at present, but |
| 696 | the possibility of optimizations exists in the future.) |
| 697 | |
| 698 | Nested @code{freeregs} directives can be used to add additional registers |
| 699 | to the list of those available to the assembler. For example: |
| 700 | |
| 701 | @smallexample |
| 702 | .begin freeregs a3, a4 |
| 703 | .begin freeregs a5 |
| 704 | @end smallexample |
| 705 | |
| 706 | has the effect of declaring @code{a3}, @code{a4}, and @code{a5} all free. |
| 707 | |
| 708 | @node Frame Directive |
| 709 | @subsection frame |
| 710 | @cindex @code{frame} directive |
| 711 | |
| 712 | This directive tells the assembler to emit information to allow the |
| 713 | debugger to locate a function's stack frame. The syntax is: |
| 714 | |
| 715 | @smallexample |
| 716 | .frame @var{reg}, @var{size} |
| 717 | @end smallexample |
| 718 | |
| 719 | where @var{reg} is the register used to hold the frame pointer (usually |
| 720 | the same as the stack pointer) and @var{size} is the size in bytes of |
| 721 | the stack frame. The @code{.frame} directive is typically placed |
| 722 | immediately after the @code{ENTRY} instruction for a function. |
| 723 | |
| 724 | In almost all circumstances, this information just duplicates the |
| 725 | information given in the function's @code{ENTRY} instruction; however, |
| 726 | there are two cases where this is not true: |
| 727 | |
| 728 | @enumerate |
| 729 | @item |
| 730 | The size of the stack frame is too big to fit in the immediate field |
| 731 | of the @code{ENTRY} instruction. |
| 732 | |
| 733 | @item |
| 734 | The frame pointer is different than the stack pointer, as with functions |
| 735 | that call @code{alloca}. |
| 736 | @end enumerate |
| 737 | |
| 738 | @c Local Variables: |
| 739 | @c fill-column: 72 |
| 740 | @c End: |