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