gas/doc/c-xtensa.texi

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