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