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