gas/doc/c-xtensa.texi

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