diff options
Diffstat (limited to 'binutils-2.17/gas/doc/c-xtensa.texi')
| -rw-r--r-- | binutils-2.17/gas/doc/c-xtensa.texi | 753 |
1 files changed, 0 insertions, 753 deletions
diff --git a/binutils-2.17/gas/doc/c-xtensa.texi b/binutils-2.17/gas/doc/c-xtensa.texi deleted file mode 100644 index 33035ad8..00000000 --- a/binutils-2.17/gas/doc/c-xtensa.texi +++ /dev/null @@ -1,753 +0,0 @@ -@c Copyright (C) 2002, 2003, 2004 Free Software Foundation, Inc. -@c This is part of the GAS manual. -@c For copying conditions, see the file as.texinfo. -@c -@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 - -The Xtensa version of the @sc{gnu} assembler supports these -special options: - -@table @code -@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 a -separate section 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. - -@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 - -@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{//}. - -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. - -FLIX instructions, which bundle multiple opcodes together in a single -instruction, are specified by enclosing the bundled opcodes inside -braces: - -@smallexample -@{ -[@var{format}] -@var{opcode0} [@var{operands}] -@var{opcode1} [@var{operands}] -@var{opcode2} [@var{operands}] -@dots{} -@} -@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 - -The assembler can automatically bundle opcodes into FLIX instructions. -It encodes the opcodes in order, one at a time, -choosing the smallest format where each opcode can be encoded and -filling 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 @code{ENTRY} instructions -@cindex alignment of branch targets -@cindex @code{LOOP} instructions, alignment -@cindex @code{ENTRY} 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. The assembler will not attempt to align -labels with the prefixes @code{.Ln} and @code{.LM}, since these labels -are used for debugging information and are not typically branch targets. -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). - -Similarly, the @code{ENTRY} instruction must be aligned on a 0 mod 4 -byte boundary. The assembler satisfies this requirement by inserting -zero bytes when required. In addition, labels immediately preceding the -@code{ENTRY} instruction will be moved to the newly aligned instruction -location. - -@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 - bnez.n a2, M - j L -M: -@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 - .literal .L1, func - l32r a8, .L1 - callx8 a8 -@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 - .literal .L1, 100000 - l32r a0, .L1 -@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 materalized 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 - .literal .L1, 2040 - l32r a1, .L1 - addi a1, a0, a1 - l32i a1, a1, 0 -@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 - addi a5, a6, 0 - addi a5, a6, 512 - addi a5, a6, 513 - addi a5, a6, 50000 -@end smallexample - -is assembled into the following: - -@smallexample - .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 -@end smallexample - -@node Xtensa Directives -@section Directives -@cindex Xtensa directives -@cindex directives, Xtensa - -The Xtensa assember supports a region-based directive syntax: - -@smallexample - .begin @var{directive} [@var{options}] - @dots{} - .end @var{directive} -@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 - .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 -@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 - .begin [no-]schedule - .end [no-]schedule -@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 - .begin [no-]longcalls - .end [no-]longcalls -@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 - .begin [no-]transform - .end [no-]transform -@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 - entry sp, 40 - .literal .L1, sym - l32r a4, .L1 -@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 for absolute mode @code{L32R} instructions -(@pxref{Absolute Literals Directive}) are placed in a separate -@code{.lit4} section. By default literal pools for PC-relative mode -@code{L32R} instructions are placed in a separate @code{.literal} -section; however, when using the @samp{--text-@-section-@-literals} -option (@pxref{Xtensa Options, ,Command Line Options}), the literal -pools are placed in the current section. 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. - -@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 - .global M -code_start: - j continue - .literal_position - .align 4 -continue: - movi a4, M -@end smallexample - -@node Literal Prefix Directive -@subsection literal_prefix -@cindex @code{literal_prefix} directive - -The @code{literal_prefix} directive allows you to specify different -sections to hold literals from different portions of an assembly file. -With this directive, a single assembly file can be used to generate code -into multiple sections, including literals generated by the assembler. - -@smallexample - .begin literal_prefix [@var{name}] - .end literal_prefix -@end smallexample - -By default the assembler places literal pools in sections separate from -the instructions, using the default literal section names of -@code{.literal} for PC-relative mode @code{L32R} instructions and -@code{.lit4} for absolute mode @code{L32R} instructions (@pxref{Absolute -Literals Directive}). The @code{literal_prefix} directive causes -different literal sections to be used for the code inside the delimited -region. The new literal sections are determined by including @var{name} -as a prefix to the default literal section names. 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}). - -Except for two special cases, the assembler determines the new literal -sections by simply prepending @var{name} to the default section names, -resulting in @code{@var{name}.literal} and @code{@var{name}.lit4} -sections. The @code{literal_prefix} directive is often used with the -name of the current text section as the prefix argument. To facilitate -this usage, the assembler uses special case rules when it recognizes -@var{name} as a text section name. First, if @var{name} ends with -@code{.text}, that suffix is not included in the literal section name. -For example, if @var{name} is @code{.iram0.text}, then the literal -sections will be @code{.iram0.literal} and @code{.iram0.lit4}. Second, -if @var{name} begins with @code{.gnu.linkonce.t.}, then the literal -section names are formed by replacing the @code{.t} substring with -@code{.literal} and @code{.lit4}. For example, if @var{name} is -@code{.gnu.linkonce.t.func}, the literal sections will be -@code{.gnu.linkonce.literal.func} and @code{.gnu.linkonce.lit4.func}. - -@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 - .begin [no-]absolute-literals - .end [no-]absolute-literals -@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: |