Xtensa Dependent Features
*************************

This chapter covers features of the GNU assembler that are specific to the Xtensa architecture.  For details about the Xtensa instruction set, please consult the Xtensa Instruction Set Architecture (ISA) Reference Manual.

Command Line Options
====================

The Xtensa version of the GNU assembler supports these special options:

--text-section-literals | --no-text-section-literals
     Control the treatment of literal pools.  The default is --no-text-section-literals, which places literals in separate sections in the output file.  This allows the literal pool to be placed in a data RAM/ROM.  With --text-section-literals, the literals are interspersed in the text section in order to keep them as close as possible to their references.  This may be necessary for large assembly files, where the literals would otherwise be out of range of the L32R instructions in the text section.  These options only affect literals referenced via PC-relative L32R instructions; literals for absolute mode L32R instructions are handled separately. See literal.

--absolute-literals | --no-absolute-literals
     Indicate to the assembler whether L32R instructions use absolute or PC-relative addressing.  If the processor includes the absolute addressing option, the default is to use absolute L32R relocations.  Otherwise, only the PC-relative L32R relocations can be used.

--target-align | --no-target-align
     Enable or disable automatic alignment to reduce branch penalties at some expense in code size.  See Automatic Instruction Alignment.  This optimization is enabled by default.  Note that the assembler will always align instructions like LOOP that have fixed alignment requirements.

--longcalls | --no-longcalls
     Enable or disable transformation of call instructions to allow calls across a greater range of addresses.  See Function Call Relaxation.  This option should be used when call targets can potentially be out of range.  It may degrade both code size and performance, but the linker can generally optimize away the unnecessary overhead when a call ends up within range.  The default is --no-longcalls.

--transform | --no-transform
     Enable or disable all assembler transformations of Xtensa instructions, including both relaxation and optimization.  The default is --transform; --no-transform should only be used in the rare cases when the instructions must be exactly as specified in the assembly source.  Using --no-transform causes out of range instruction operands to be errors.

--rename-section OLDNAME=NEWNAME
     Rename the OLDNAME section to NEWNAME.  This option can be used multiple times to rename multiple sections.

Assembler Syntax
================

Block comments are delimited by /* and */.  End of line comments may be introduced with either # or //.

Instructions consist of a leading opcode or macro name followed by whitespace and an optional comma-separated list of operands:

     OPCODE [OPERAND, ...]

Instructions must be separated by a newline or semicolon.

FLIX instructions, which bundle multiple opcodes together in a single instruction, are specified by enclosing the bundled opcodes inside braces:

     {
     [FORMAT]
     OPCODE0 [OPERANDS]

     OPCODE1 [OPERANDS]

     OPCODE2 [OPERANDS]
     ...
     }

The opcodes in a FLIX instruction are listed in the same order as the corresponding instruction slots in the TIE format declaration. Directives and labels are not allowed inside the braces of a FLIX instruction.  A particular TIE format name can optionally be specified immediately after the opening brace, but this is usually unnecessary. The assembler will automatically search for a format that can encode the specified opcodes, so the format name need only be specified in rare cases where there is more than one applicable format and where it matters which of those formats is used.  A FLIX instruction can also be specified on a single line by separating the opcodes with semicolons:

     { [FORMAT;] OPCODE0 [OPERANDS]; OPCODE1 [OPERANDS]; OPCODE2 [OPERANDS]; ... }

If an opcode can only be encoded in a FLIX instruction but is not specified as part of a FLIX bundle, the assembler will choose the smallest format where the opcode can be encoded and will fill unused instruction slots with no-ops.

Opcode Names
------------

See the Xtensa Instruction Set Architecture (ISA) Reference Manual for a complete list of opcodes and descriptions of their semantics.

If an opcode name is prefixed with an underscore character (_), AS will not transform that instruction in any way.  The underscore prefix disables both optimization (see Xtensa Optimizations) and relaxation (see Xtensa Relaxation) for that particular instruction.  Only use the underscore prefix when it is essential to select the exact opcode produced by the assembler.  Using this feature unnecessarily makes the code less efficient by disabling assembler optimization and less flexible by disabling relaxation.

Note that this special handling of underscore prefixes only applies to Xtensa opcodes, not to either built-in macros or user-defined macros. When an underscore prefix is used with a macro (e.g., _MOV), it refers to a different macro.  The assembler generally provides built-in macros both with and without the underscore prefix, where the underscore versions behave as if the underscore carries through to the instructions in the macros.  For example, _MOV may expand to _MOV.N.

The underscore prefix only applies to individual instructions, not to series of instructions.  For example, if a series of instructions have underscore prefixes, the assembler will not transform the individual instructions, but it may insert other instructions between them (e.g., to align a LOOP instruction).  To prevent the assembler from modifying a series of instructions as a whole, use the no-transform directive.  See transform.

Register Names
--------------

The assembly syntax for a register file entry is the ``short'' name for a TIE register file followed by the index into that register file.  For example, the general-purpose AR register file has a short name of a, so these registers are named a0...a15. As a special feature, sp is also supported as a synonym for a1.  Additional registers may be added by processor configuration options and by designer-defined TIE extensions.  An initial $ character is optional in all register names.

Xtensa Optimizations
====================

The optimizations currently supported by AS are generation of density instructions where appropriate and automatic branch target alignment.

Using Density Instructions
--------------------------

The Xtensa instruction set has a code density option that provides 16-bit versions of some of the most commonly used opcodes.  Use of these opcodes can significantly reduce code size.  When possible, the assembler automatically translates instructions from the core Xtensa instruction set into equivalent instructions from the Xtensa code density option.  This translation can be disabled by using underscore prefixes (see Opcode Names), by using the --no-transform command-line option (see Command Line Options), or by using the no-transform directive (see transform).

It is a good idea not to use the density instructions directly. The assembler will automatically select dense instructions where possible.  If you later need to use an Xtensa processor without the code density option, the same assembly code will then work without modification.

Automatic Instruction Alignment
-------------------------------

The Xtensa assembler will automatically align certain instructions, both to optimize performance and to satisfy architectural requirements.

As an optimization to improve performance, the assembler attempts to align branch targets so they do not cross instruction fetch boundaries. (Xtensa processors can be configured with either 32-bit or 64-bit instruction fetch widths.)  An instruction immediately following a call is treated as a branch target in this context, because it will be the target of a return from the call.  This alignment has the potential to reduce branch penalties at some expense in code size. This optimization is enabled by default.  You can disable it with the --no-target-align command-line option (see Command Line Options).

The target alignment optimization is done without adding instructions that could increase the execution time of the program.  If there are density instructions in the code preceding a target, the assembler can change the target alignment by widening some of those instructions to the equivalent 24-bit instructions.  Extra bytes of padding can be inserted immediately following unconditional jump and return instructions. This approach is usually successful in aligning many, but not all, branch targets.

The LOOP family of instructions must be aligned such that the first instruction in the loop body does not cross an instruction fetch boundary (e.g., with a 32-bit fetch width, a LOOP instruction must be on either a 1 or 2 mod 4 byte boundary).  The assembler knows about this restriction and inserts the minimal number of 2 or 3 byte no-op instructions to satisfy it.  When no-op instructions are added, any label immediately preceding the original loop will be moved in order to refer to the loop instruction, not the newly generated no-op instruction.  To preserve binary compatibility across processors with different fetch widths, the assembler conservatively assumes a 32-bit fetch width when aligning LOOP instructions (except if the first instruction in the loop is a 64-bit instruction).

Previous versions of the assembler automatically aligned ENTRY instructions to 4-byte boundaries, but that alignment is now the programmer's responsibility.

Xtensa Relaxation
=================

When an instruction operand is outside the range allowed for that particular instruction field, AS can transform the code to use a functionally-equivalent instruction or sequence of instructions.  This process is known as relaxation.  This is typically done for branch instructions because the distance of the branch targets is not known until assembly-time.  The Xtensa assembler offers branch relaxation and also extends this concept to function calls, MOVI instructions and other instructions with immediate fields.

Conditional Branch Relaxation
-----------------------------

When the target of a branch is too far away from the branch itself, i.e., when the offset from the branch to the target is too large to fit in the immediate field of the branch instruction, it may be necessary to replace the branch with a branch around a jump.  For example,

         beqz    a2, L

may result in:

         bnez.n  a2, M
         j L
     M:

(The BNEZ.N instruction would be used in this example only if the density option is available.  Otherwise, BNEZ would be used.)

This relaxation works well because the unconditional jump instruction has a much larger offset range than the various conditional branches. However, an error will occur if a branch target is beyond the range of a jump instruction.  AS cannot relax unconditional jumps. Similarly, an error will occur if the original input contains an unconditional jump to a target that is out of range.

Branch relaxation is enabled by default.  It can be disabled by using underscore prefixes (see Opcode Names), the --no-transform command-line option (see Command Line Options), or the no-transform directive (see transform).

Function Call Relaxation
------------------------

Function calls may require relaxation because the Xtensa immediate call instructions (CALL0, CALL4, CALL8 and CALL12) provide a PC-relative offset of only 512 Kbytes in either direction.  For larger programs, it may be necessary to use indirect calls (CALLX0, CALLX4, CALLX8 and CALLX12) where the target address is specified in a register.  The Xtensa assembler can automatically relax immediate call instructions into indirect call instructions.  This relaxation is done by loading the address of the called function into the callee's return address register and then using a CALLX instruction.  So, for example:

         call8 func

might be relaxed to:

         .literal .L1, func
         l32r    a8, .L1
         callx8  a8

Because the addresses of targets of function calls are not generally known until link-time, the assembler must assume the worst and relax all the calls to functions in other source files, not just those that really will be out of range.  The linker can recognize calls that were unnecessarily relaxed, and it will remove the overhead introduced by the assembler for those cases where direct calls are sufficient.

Call relaxation is disabled by default because it can have a negative effect on both code size and performance, although the linker can usually eliminate the unnecessary overhead.  If a program is too large and some of the calls are out of range, function call relaxation can be enabled using the --longcalls command-line option or the longcalls directive (see longcalls).

Other Immediate Field Relaxation
--------------------------------

The assembler normally performs the following other relaxations.  They can be disabled by using underscore prefixes (see Opcode Names), the --no-transform command-line option (see Command Line Options), or the no-transform directive (see transform).

The MOVI machine instruction can only materialize values in the range from -2048 to 2047.  Values outside this range are best materialized with L32R instructions.  Thus:

         movi a0, 100000

is assembled into the following machine code:

         .literal .L1, 100000
         l32r a0, .L1

The L8UI machine instruction can only be used with immediate offsets in the range from 0 to 255. The L16SI and L16UI machine instructions can only be used with offsets from 0 to 510.  The L32I machine instruction can only be used with offsets from 0 to 1020.  A load offset outside these ranges can be materialized with an L32R instruction if the destination register of the load is different than the source address register.  For example:

         l32i a1, a0, 2040

is translated to:

         .literal .L1, 2040
         l32r a1, .L1

         add a1, a0, a1
         l32i a1, a1, 0

If the load destination and source address register are the same, an out-of-range offset causes an error.

The Xtensa ADDI instruction only allows immediate operands in the range from -128 to 127.  There are a number of alternate instruction sequences for the ADDI operation.  First, if the immediate is 0, the ADDI will be turned into a MOV.N instruction (or the equivalent OR instruction if the code density option is not available).  If the ADDI immediate is outside of the range -128 to 127, but inside the range -32896 to 32639, an ADDMI instruction or ADDMI/ADDI sequence will be used.  Finally, if the immediate is outside of this range and a free register is available, an L32R/ADD sequence will be used with a literal allocated from the literal pool.

For example:

         addi    a5, a6, 0
         addi    a5, a6, 512

         addi    a5, a6, 513
         addi    a5, a6, 50000

is assembled into the following:

         .literal .L1, 50000
         mov.n   a5, a6

         addmi   a5, a6, 0x200
         addmi   a5, a6, 0x200
         addi    a5, a5, 1

         l32r    a5, .L1
         add     a5, a6, a5

Directives
==========

The Xtensa assembler supports a region-based directive syntax:

         .begin DIRECTIVE [OPTIONS]
         ...
         .end DIRECTIVE

All the Xtensa-specific directives that apply to a region of code use this syntax.

The directive applies to code between the .begin and the .end.  The state of the option after the .end reverts to what it was before the .begin. A nested .begin/.end region can further change the state of the directive without having to be aware of its outer state.  For example, consider:

         .begin no-transform
     L:  add a0, a1, a2

         .begin transform
     M:  add a0, a1, a2
         .end transform

     N:  add a0, a1, a2
         .end no-transform

The ADD opcodes at L and N in the outer no-transform region both result in ADD machine instructions, but the assembler selects an ADD.N instruction for the ADD at M in the inner transform region.

The advantage of this style is that it works well inside macros which can preserve the context of their callers.

The following directives are available:

schedule
--------

The schedule directive is recognized only for compatibility with Tensilica's assembler.

         .begin [no-]schedule
         .end [no-]schedule

This directive is ignored and has no effect on AS.

longcalls
---------

The longcalls directive enables or disables function call relaxation.  See Function Call Relaxation.

         .begin [no-]longcalls
         .end [no-]longcalls

Call relaxation is disabled by default unless the --longcalls command-line option is specified.  The longcalls directive overrides the default determined by the command-line options.

transform
---------

This directive enables or disables all assembler transformation, including relaxation (see Xtensa Relaxation) and optimization (see Xtensa Optimizations).

         .begin [no-]transform
         .end [no-]transform

Transformations are enabled by default unless the --no-transform option is used.  The transform directive overrides the default determined by the command-line options.  An underscore opcode prefix, disabling transformation of that opcode, always takes precedence over both directives and command-line flags.

literal
-------

The .literal directive is used to define literal pool data, i.e., read-only 32-bit data accessed via L32R instructions.

         .literal LABEL, VALUE[, VALUE...]

This directive is similar to the standard .word directive, except that the actual location of the literal data is determined by the assembler and linker, not by the position of the .literal directive.  Using this directive gives the assembler freedom to locate the literal data in the most appropriate place and possibly to combine identical literals.  For example, the code:

         entry sp, 40
         .literal .L1, sym
         l32r    a4, .L1

can be used to load a pointer to the symbol sym into register a4.  The value of sym will not be placed between the ENTRY and L32R instructions; instead, the assembler puts the data in a literal pool.

Literal pools are placed by default in separate literal sections; however, when using the --text-section-literals option (see Command Line Options), the literal pools for PC-relative mode L32R instructions are placed in the current section. (Literals for the .init and .fini sections are always placed in separate sections, even when --text-section-literals is enabled.) These text section literal pools are created automatically before ENTRY instructions and manually after .literal_position directives (see literal_position).  If there are no preceding ENTRY instructions, explicit .literal_position directives must be used to place the text section literal pools; otherwise, AS will report an error.

When literals are placed in separate sections, the literal section names are derived from the names of the sections where the literals are defined.  The base literal section names are .literal for PC-relative mode L32R instructions and .lit4 for absolute mode L32R instructions (see absolute-literals).  These base names are used for literals defined in the default .text section.  For literals defined in other sections or within the scope of a literal_prefix directive (see literal_prefix), the following rules determine the literal section name:

 1. If the current section is a member of a section group, the literal section name includes the group name as a suffix to the base .literal or .lit4 name, with a period to separate the base name and group name.  The literal section is also made a member of the group.

 2. If the current section name (or literal_prefix value) begins with ``.gnu.linkonce.KIND.'', the literal section name is formed by replacing ``.KIND'' with the base .literal or .lit4 name.  For example, for literals defined in a section named .gnu.linkonce.t.func, the literal section will be .gnu.linkonce.literal.func or .gnu.linkonce.lit4.func.

 3. If the current section name (or literal_prefix value) ends with .text, the literal section name is formed by replacing that suffix with the base .literal or .lit4 name.  For example, for literals defined in a section named .iram0.text, the literal section will be .iram0.literal or .iram0.lit4.

 4. If none of the preceding conditions apply, the literal section name is formed by adding the base .literal or .lit4 name as a suffix to the current section name (or literal_prefix value).

literal_position
----------------

When using --text-section-literals to place literals inline in the section being assembled, the .literal_position directive can be used to mark a potential location for a literal pool.

         .literal_position

The .literal_position directive is ignored when the --text-section-literals option is not used or when L32R instructions use the absolute addressing mode.

The assembler will automatically place text section literal pools before ENTRY instructions, so the .literal_position directive is only needed to specify some other location for a literal pool.  You may need to add an explicit jump instruction to skip over an inline literal pool.

For example, an interrupt vector does not begin with an ENTRY instruction so the assembler will be unable to automatically find a good place to put a literal pool.  Moreover, the code for the interrupt vector must be at a specific starting address, so the literal pool cannot come before the start of the code.  The literal pool for the vector must be explicitly positioned in the middle of the vector (before any uses of the literals, due to the negative offsets used by PC-relative L32R instructions).  The .literal_position directive can be used to do this.  In the following code, the literal for M will automatically be aligned correctly and is placed after the unconditional jump.

         .global M
     code_start:

         j continue
         .literal_position
         .align 4

     continue:
         movi    a4, M

literal_prefix
--------------

The literal_prefix directive allows you to override the default literal section names, which are derived from the names of the sections where the literals are defined.

         .begin literal_prefix [NAME]
         .end literal_prefix

For literals defined within the delimited region, the literal section names are derived from the NAME argument instead of the name of the current section.  The rules used to derive the literal section names do not change.  See literal.  If the NAME argument is omitted, the literal sections revert to the defaults.  This directive has no effect when using the --text-section-literals option (see Command Line Options).

absolute-literals
-----------------

The absolute-literals and no-absolute-literals directives control the absolute vs. PC-relative mode for L32R instructions.  These are relevant only for Xtensa configurations that include the absolute addressing option for L32R instructions.

         .begin [no-]absolute-literals
         .end [no-]absolute-literals

These directives do not change the L32R mode---they only cause the assembler to emit the appropriate kind of relocation for L32R instructions and to place the literal values in the appropriate section. To change the L32R mode, the program must write the LITBASE special register.  It is the programmer's responsibility to keep track of the mode and indicate to the assembler which mode is used in each region of code.

If the Xtensa configuration includes the absolute L32R addressing option, the default is to assume absolute L32R addressing unless the --no-absolute-literals command-line option is specified. Otherwise, the default is to assume PC-relative L32R addressing. The absolute-literals directive can then be used to override the default determined by the command-line options.