Subversion Repositories open8_urisc

@c Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2011

@c Free Software Foundation, Inc.

@c This is part of the GAS manual.

@c For copying conditions, see the file as.texinfo.

@c

@c man end

@ifset GENERIC

@page

@node Xtensa-Dependent

@chapter Xtensa Dependent Features

@end ifset

@ifclear GENERIC

@node Machine Dependencies

@chapter Xtensa Dependent Features

@end ifclear

@cindex Xtensa architecture

This chapter covers features of the @sc{gnu} assembler that are specific

to the Xtensa architecture.  For details about the Xtensa instruction

set, please consult the @cite{Xtensa Instruction Set Architecture (ISA)

Reference Manual}.

@menu

* Xtensa Options::              Command-line Options.

* Xtensa Syntax::               Assembler Syntax for Xtensa Processors.

* Xtensa Optimizations::        Assembler Optimizations.

* Xtensa Relaxation::           Other Automatic Transformations.

* Xtensa Directives::           Directives for Xtensa Processors.

@end menu

@node Xtensa Options

@section Command Line Options

@c man begin OPTIONS

@table @gcctabopt

@item --text-section-literals | --no-text-section-literals

@kindex --text-section-literals

@kindex --no-text-section-literals

Control the treatment of literal pools.  The default is

@samp{--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 @samp{--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

@code{L32R} instructions in the text section.  These options only affect

literals referenced via PC-relative @code{L32R} instructions; literals

for absolute mode @code{L32R} instructions are handled separately.

@xref{Literal Directive, ,literal}.

@item --absolute-literals | --no-absolute-literals

@kindex --absolute-literals

@kindex --no-absolute-literals

Indicate to the assembler whether @code{L32R} instructions use absolute

or PC-relative addressing.  If the processor includes the absolute

addressing option, the default is to use absolute @code{L32R}

relocations.  Otherwise, only the PC-relative @code{L32R} relocations

can be used.

@item --target-align | --no-target-align

@kindex --target-align

@kindex --no-target-align

Enable or disable automatic alignment to reduce branch penalties at some

expense in code size.  @xref{Xtensa Automatic Alignment, ,Automatic

Instruction Alignment}.  This optimization is enabled by default.  Note

that the assembler will always align instructions like @code{LOOP} that

have fixed alignment requirements.

@item --longcalls | --no-longcalls

@kindex --longcalls

@kindex --no-longcalls

Enable or disable transformation of call instructions to allow calls

across a greater range of addresses.  @xref{Xtensa Call Relaxation,

,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

@samp{--no-@-longcalls}.

@item --transform | --no-transform

@kindex --transform

@kindex --no-transform

Enable or disable all assembler transformations of Xtensa instructions,

including both relaxation and optimization.  The default is

@samp{--transform}; @samp{--no-transform} should only be used in the

rare cases when the instructions must be exactly as specified in the

assembly source.  Using @samp{--no-transform} causes out of range

instruction operands to be errors.

@item --rename-section @var{oldname}=@var{newname}

@kindex --rename-section

Rename the @var{oldname} section to @var{newname}.  This option can be used

multiple times to rename multiple sections.

@end table

@c man end

@node Xtensa Syntax

@section Assembler Syntax

@cindex syntax, Xtensa assembler

@cindex Xtensa assembler syntax

@cindex FLIX syntax

Block comments are delimited by @samp{/*} and @samp{*/}.  End of line

comments may be introduced with either @samp{#} or @samp{//}.

If a @samp{#} appears as the first character of a line then the whole

line is treated as a comment, but in this case the line could also be

a logical line number directive (@pxref{Comments}) or a preprocessor

control command (@pxref{Preprocessing}).

Instructions consist of a leading opcode or macro name followed by

whitespace and an optional comma-separated list of operands:

@smallexample

@var{opcode} [@var{operand}, @dots{}]

@end smallexample

Instructions must be separated by a newline or semicolon (@samp{;}).

FLIX instructions, which bundle multiple opcodes together in a single

instruction, are specified by enclosing the bundled opcodes inside

braces:

@smallexample

@group

@{

[@var{format}]

@var{opcode0} [@var{operands}]

@end group

@var{opcode1} [@var{operands}]

@group

@var{opcode2} [@var{operands}]

@dots{}

@}

@end group

@end smallexample

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:

@smallexample

@{ [@var{format};] @var{opcode0} [@var{operands}]; @var{opcode1} [@var{operands}]; @var{opcode2} [@var{operands}]; @dots{} @}

@end smallexample

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.

@menu

* Xtensa Opcodes::              Opcode Naming Conventions.

* Xtensa Registers::            Register Naming.

@end menu

@node Xtensa Opcodes

@subsection Opcode Names

@cindex Xtensa opcode names

@cindex opcode names, Xtensa

See the @cite{Xtensa Instruction Set Architecture (ISA) Reference

Manual} for a complete list of opcodes and descriptions of their

semantics.

@cindex _ opcode prefix

If an opcode name is prefixed with an underscore character (@samp{_}),

@command{@value{AS}} will not transform that instruction in any way.  The

underscore prefix disables both optimization (@pxref{Xtensa

Optimizations, ,Xtensa Optimizations}) and relaxation (@pxref{Xtensa

Relaxation, ,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., @code{_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, @code{_MOV} may expand to @code{_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 @code{LOOP} instruction).  To prevent the assembler from

modifying a series of instructions as a whole, use the

@code{no-transform} directive.  @xref{Transform Directive, ,transform}.

@node Xtensa Registers

@subsection Register Names

@cindex Xtensa register names

@cindex register names, Xtensa

@cindex sp register

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 @code{AR} register file has a short name of

@code{a}, so these registers are named @code{a0}@dots{}@code{a15}.

As a special feature, @code{sp} is also supported as a synonym for

@code{a1}.  Additional registers may be added by processor configuration

options and by designer-defined TIE extensions.  An initial @samp{$}

character is optional in all register names.

@node Xtensa Optimizations

@section Xtensa Optimizations

@cindex optimizations

The optimizations currently supported by @command{@value{AS}} are

generation of density instructions where appropriate and automatic

branch target alignment.

@menu

* Density Instructions::        Using Density Instructions.

* Xtensa Automatic Alignment::  Automatic Instruction Alignment.

@end menu

@node Density Instructions

@subsection Using Density Instructions

@cindex 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 (@pxref{Xtensa Opcodes, ,Opcode Names}), by using the

@samp{--no-transform} command-line option (@pxref{Xtensa Options, ,Command

Line Options}), or by using the @code{no-transform} directive

(@pxref{Transform Directive, ,transform}).

It is a good idea @emph{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.

@node Xtensa Automatic Alignment

@subsection Automatic Instruction Alignment

@cindex alignment of @code{LOOP} instructions

@cindex alignment of branch targets

@cindex @code{LOOP} instructions, alignment

@cindex branch target 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

@samp{--no-target-@-align} command-line option (@pxref{Xtensa Options,

,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 @code{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 @code{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 @code{LOOP} instructions (except if the first

instruction in the loop is a 64-bit instruction).

Previous versions of the assembler automatically aligned @code{ENTRY}

instructions to 4-byte boundaries, but that alignment is now the

programmer's responsibility.

@node Xtensa Relaxation

@section Xtensa Relaxation

@cindex relaxation

When an instruction operand is outside the range allowed for that

particular instruction field, @command{@value{AS}} can transform the code

to use a functionally-equivalent instruction or sequence of

instructions.  This process is known as @dfn{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, @code{MOVI} instructions and other instructions with immediate

fields.

@menu

* Xtensa Branch Relaxation::        Relaxation of Branches.

* Xtensa Call Relaxation::          Relaxation of Function Calls.

* Xtensa Immediate Relaxation::     Relaxation of other Immediate Fields.

@end menu

@node Xtensa Branch Relaxation

@subsection Conditional Branch Relaxation

@cindex relaxation of branch instructions

@cindex branch instructions, 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,

@smallexample

    beqz    a2, L

@end smallexample

may result in:

@smallexample

@group

    bnez.n  a2, M

    j L

M:

@end group

@end smallexample

(The @code{BNEZ.N} instruction would be used in this example only if the

density option is available.  Otherwise, @code{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.  @command{@value{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 (@pxref{Xtensa Opcodes, ,Opcode Names}), the

@samp{--no-transform} command-line option (@pxref{Xtensa Options,

,Command Line Options}), or the @code{no-transform} directive

(@pxref{Transform Directive, ,transform}).

@node Xtensa Call Relaxation

@subsection Function Call Relaxation

@cindex relaxation of call instructions

@cindex call instructions, relaxation

Function calls may require relaxation because the Xtensa immediate call

instructions (@code{CALL0}, @code{CALL4}, @code{CALL8} and

@code{CALL12}) provide a PC-relative offset of only 512 Kbytes in either

direction.  For larger programs, it may be necessary to use indirect

calls (@code{CALLX0}, @code{CALLX4}, @code{CALLX8} and @code{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 @code{CALLX} instruction.  So, for example:

@smallexample

    call8 func

@end smallexample

might be relaxed to:

@smallexample

@group

    .literal .L1, func

    l32r    a8, .L1

    callx8  a8

@end group

@end smallexample

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 @samp{--longcalls} command-line option or the

@code{longcalls} directive (@pxref{Longcalls Directive, ,longcalls}).

@node Xtensa Immediate Relaxation

@subsection Other Immediate Field Relaxation

@cindex immediate fields, relaxation

@cindex relaxation of immediate fields

The assembler normally performs the following other relaxations.  They

can be disabled by using underscore prefixes (@pxref{Xtensa Opcodes,

,Opcode Names}), the @samp{--no-transform} command-line option

(@pxref{Xtensa Options, ,Command Line Options}), or the

@code{no-transform} directive (@pxref{Transform Directive, ,transform}).

@cindex @code{MOVI} instructions, relaxation

@cindex relaxation of @code{MOVI} instructions

The @code{MOVI} machine instruction can only materialize values in the

range from -2048 to 2047.  Values outside this range are best

materialized with @code{L32R} instructions.  Thus:

@smallexample

    movi a0, 100000

@end smallexample

is assembled into the following machine code:

@smallexample

@group

    .literal .L1, 100000

    l32r a0, .L1

@end group

@end smallexample

@cindex @code{L8UI} instructions, relaxation

@cindex @code{L16SI} instructions, relaxation

@cindex @code{L16UI} instructions, relaxation

@cindex @code{L32I} instructions, relaxation

@cindex relaxation of @code{L8UI} instructions

@cindex relaxation of @code{L16SI} instructions

@cindex relaxation of @code{L16UI} instructions

@cindex relaxation of @code{L32I} instructions

The @code{L8UI} machine instruction can only be used with immediate

offsets in the range from 0 to 255. The @code{L16SI} and @code{L16UI}

machine instructions can only be used with offsets from 0 to 510.  The

@code{L32I} machine instruction can only be used with offsets from 0 to

1020.  A load offset outside these ranges can be materialized with

an @code{L32R} instruction if the destination register of the load

is different than the source address register.  For example:

@smallexample

    l32i a1, a0, 2040

@end smallexample

is translated to:

@smallexample

@group

    .literal .L1, 2040

    l32r a1, .L1

@end group

@group

    add a1, a0, a1

    l32i a1, a1, 0

@end group

@end smallexample

@noindent

If the load destination and source address register are the same, an

out-of-range offset causes an error.

@cindex @code{ADDI} instructions, relaxation

@cindex relaxation of @code{ADDI} instructions

The Xtensa @code{ADDI} instruction only allows immediate operands in the

range from -128 to 127.  There are a number of alternate instruction

sequences for the @code{ADDI} operation.  First, if the

immediate is 0, the @code{ADDI} will be turned into a @code{MOV.N}

instruction (or the equivalent @code{OR} instruction if the code density

option is not available).  If the @code{ADDI} immediate is outside of

the range -128 to 127, but inside the range -32896 to 32639, an

@code{ADDMI} instruction or @code{ADDMI}/@code{ADDI} sequence will be

used.  Finally, if the immediate is outside of this range and a free

register is available, an @code{L32R}/@code{ADD} sequence will be used

with a literal allocated from the literal pool.

For example:

@smallexample

@group

    addi    a5, a6, 0

    addi    a5, a6, 512

@end group

@group

    addi    a5, a6, 513

    addi    a5, a6, 50000

@end group

@end smallexample

is assembled into the following:

@smallexample

@group

    .literal .L1, 50000

    mov.n   a5, a6

@end group

    addmi   a5, a6, 0x200

    addmi   a5, a6, 0x200

    addi    a5, a5, 1

@group

    l32r    a5, .L1

    add     a5, a6, a5

@end group

@end smallexample

@node Xtensa Directives

@section Directives

@cindex Xtensa directives

@cindex directives, Xtensa

The Xtensa assembler supports a region-based directive syntax:

@smallexample

@group

    .begin @var{directive} [@var{options}]

    @dots{}

    .end @var{directive}

@end group

@end smallexample

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

this syntax.

The directive applies to code between the @code{.begin} and the

@code{.end}.  The state of the option after the @code{.end} reverts to

what it was before the @code{.begin}.

A nested @code{.begin}/@code{.end} region can further

change the state of the directive without having to be aware of its

outer state.  For example, consider:

@smallexample

@group

    .begin no-transform

L:  add a0, a1, a2

@end group

    .begin transform

M:  add a0, a1, a2

    .end transform

@group

N:  add a0, a1, a2

    .end no-transform

@end group

@end smallexample

The @code{ADD} opcodes at @code{L} and @code{N} in the outer

@code{no-transform} region both result in @code{ADD} machine instructions,

but the assembler selects an @code{ADD.N} instruction for the

@code{ADD} at @code{M} in the inner @code{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:

@menu

* Schedule Directive::         Enable instruction scheduling.

* Longcalls Directive::        Use Indirect Calls for Greater Range.

* Transform Directive::        Disable All Assembler Transformations.

* Literal Directive::          Intermix Literals with Instructions.

* Literal Position Directive:: Specify Inline Literal Pool Locations.

* Literal Prefix Directive::   Specify Literal Section Name Prefix.

* Absolute Literals Directive:: Control PC-Relative vs. Absolute Literals.

@end menu

@node Schedule Directive

@subsection schedule

@cindex @code{schedule} directive

@cindex @code{no-schedule} directive

The @code{schedule} directive is recognized only for compatibility with

Tensilica's assembler.

@smallexample

@group

    .begin [no-]schedule

    .end [no-]schedule

@end group

@end smallexample

This directive is ignored and has no effect on @command{@value{AS}}.

@node Longcalls Directive

@subsection longcalls

@cindex @code{longcalls} directive

@cindex @code{no-longcalls} directive

The @code{longcalls} directive enables or disables function call

relaxation.  @xref{Xtensa Call Relaxation, ,Function Call Relaxation}.

@smallexample

@group

    .begin [no-]longcalls

    .end [no-]longcalls

@end group

@end smallexample

Call relaxation is disabled by default unless the @samp{--longcalls}

command-line option is specified.  The @code{longcalls} directive

overrides the default determined by the command-line options.

@node Transform Directive

@subsection transform

@cindex @code{transform} directive

@cindex @code{no-transform} directive

This directive enables or disables all assembler transformation,

including relaxation (@pxref{Xtensa Relaxation, ,Xtensa Relaxation}) and

optimization (@pxref{Xtensa Optimizations, ,Xtensa Optimizations}).

@smallexample

@group

    .begin [no-]transform

    .end [no-]transform

@end group

@end smallexample

Transformations are enabled by default unless the @samp{--no-transform}

option is used.  The @code{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.

@node Literal Directive

@subsection literal

@cindex @code{literal} directive

The @code{.literal} directive is used to define literal pool data, i.e.,

read-only 32-bit data accessed via @code{L32R} instructions.

@smallexample

    .literal @var{label}, @var{value}[, @var{value}@dots{}]

@end smallexample

This directive is similar to the standard @code{.word} directive, except

that the actual location of the literal data is determined by the

assembler and linker, not by the position of the @code{.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:

@smallexample

@group

    entry sp, 40

    .literal .L1, sym

    l32r    a4, .L1

@end group

@end smallexample

can be used to load a pointer to the symbol @code{sym} into register

@code{a4}.  The value of @code{sym} will not be placed between the

@code{ENTRY} and @code{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 @samp{--text-@-section-@-literals}

option (@pxref{Xtensa Options, ,Command Line Options}), the literal

pools for PC-relative mode @code{L32R} instructions

are placed in the current section.@footnote{Literals for the

@code{.init} and @code{.fini} sections are always placed in separate

sections, even when @samp{--text-@-section-@-literals} is enabled.}

These text section literal

pools are created automatically before @code{ENTRY} instructions and

manually after @samp{.literal_position} directives (@pxref{Literal

Position Directive, ,literal_position}).  If there are no preceding

@code{ENTRY} instructions, explicit @code{.literal_position} directives

must be used to place the text section literal pools; otherwise,

@command{@value{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 @code{.literal} for

PC-relative mode @code{L32R} instructions and @code{.lit4} for absolute

mode @code{L32R} instructions (@pxref{Absolute Literals Directive,

,absolute-literals}).  These base names are used for literals defined in

the default @code{.text} section.  For literals defined in other

sections or within the scope of a @code{literal_prefix} directive

(@pxref{Literal Prefix Directive, ,literal_prefix}), the following rules

determine the literal section name:

@enumerate

@item

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

@code{.literal} or @code{.lit4} name, with a period to separate the base

name and group name.  The literal section is also made a member of the

group.

@item

If the current section name (or @code{literal_prefix} value) begins with

``@code{.gnu.linkonce.@var{kind}.}'', the literal section name is formed

by replacing ``@code{.@var{kind}}'' with the base @code{.literal} or

@code{.lit4} name.  For example, for literals defined in a section named

@code{.gnu.linkonce.t.func}, the literal section will be

@code{.gnu.linkonce.literal.func} or @code{.gnu.linkonce.lit4.func}.

@item

If the current section name (or @code{literal_prefix} value) ends with

@code{.text}, the literal section name is formed by replacing that

suffix with the base @code{.literal} or @code{.lit4} name.  For example,

for literals defined in a section named @code{.iram0.text}, the literal

section will be @code{.iram0.literal} or @code{.iram0.lit4}.

@item

If none of the preceding conditions apply, the literal section name is

formed by adding the base @code{.literal} or @code{.lit4} name as a

suffix to the current section name (or @code{literal_prefix} value).

@end enumerate

@node Literal Position Directive

@subsection literal_position

@cindex @code{literal_position} directive

When using @samp{--text-@-section-@-literals} to place literals inline

in the section being assembled, the @code{.literal_position} directive

can be used to mark a potential location for a literal pool.

@smallexample

    .literal_position

@end smallexample

The @code{.literal_position} directive is ignored when the

@samp{--text-@-section-@-literals} option is not used or when

@code{L32R} instructions use the absolute addressing mode.

The assembler will automatically place text section literal pools

before @code{ENTRY} instructions, so the @code{.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 @code{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 @code{L32R} instructions).  The @code{.literal_position}

directive can be used to do this.  In the following code, the literal

for @samp{M} will automatically be aligned correctly and is placed after

the unconditional jump.

@smallexample

@group

    .global M

code_start:

@end group

    j continue

    .literal_position

    .align 4

@group

continue:

    movi    a4, M

@end group

@end smallexample

@node Literal Prefix Directive

@subsection literal_prefix

@cindex @code{literal_prefix} directive

The @code{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.

@smallexample

@group

    .begin literal_prefix [@var{name}]

    .end literal_prefix

@end group

@end smallexample

For literals defined within the delimited region, the literal section

names are derived from the @var{name} argument instead of the name of

the current section.  The rules used to derive the literal section names

do not change.  @xref{Literal Directive, ,literal}.  If the @var{name}

argument is omitted, the literal sections revert to the defaults.  This

directive has no effect when using the

@samp{--text-@-section-@-literals} option (@pxref{Xtensa Options,

,Command Line Options}).

@node Absolute Literals Directive

@subsection absolute-literals

@cindex @code{absolute-literals} directive

@cindex @code{no-absolute-literals} directive

The @code{absolute-@-literals} and @code{no-@-absolute-@-literals}

directives control the absolute vs.@: PC-relative mode for @code{L32R}

instructions.  These are relevant only for Xtensa configurations that

include the absolute addressing option for @code{L32R} instructions.

@smallexample

@group

    .begin [no-]absolute-literals

    .end [no-]absolute-literals

@end group

@end smallexample

These directives do not change the @code{L32R} mode---they only cause

the assembler to emit the appropriate kind of relocation for @code{L32R}

instructions and to place the literal values in the appropriate section.

To change the @code{L32R} mode, the program must write the

@code{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 @code{L32R} addressing

option, the default is to assume absolute @code{L32R} addressing unless

the @samp{--no-@-absolute-@-literals} command-line option is specified.

Otherwise, the default is to assume PC-relative @code{L32R} addressing.

The @code{absolute-@-literals} directive can then be used to override

the default determined by the command-line options.

@c Local Variables:

@c fill-column: 72

@c End: