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