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