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