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